001    /*
002     *  Licensed to the Apache Software Foundation (ASF) under one
003     *  or more contributor license agreements.  See the NOTICE file
004     *  distributed with this work for additional information
005     *  regarding copyright ownership.  The ASF licenses this file
006     *  to you under the Apache License, Version 2.0 (the
007     *  "License"); you may not use this file except in compliance
008     *  with the License.  You may obtain a copy of the License at
009     *  
010     *    http://www.apache.org/licenses/LICENSE-2.0
011     *  
012     *  Unless required by applicable law or agreed to in writing,
013     *  software distributed under the License is distributed on an
014     *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     *  KIND, either express or implied.  See the License for the
016     *  specific language governing permissions and limitations
017     *  under the License. 
018     *  
019     */
020    package org.apache.directory.shared.ldap.schema;
021    
022    
023    import java.io.Serializable;
024    import java.util.List;
025    import java.util.Map;
026    
027    import org.apache.directory.shared.ldap.exception.LdapException;
028    import org.apache.directory.shared.ldap.schema.registries.Registries;
029    
030    
031    /**
032     * Most schema objects have some common attributes. This class
033     * contains the minimum set of properties exposed by a SchemaObject.<br> 
034     * We have 11 types of SchemaObjects :
035     * <li> AttributeType
036     * <li> DitCOntentRule
037     * <li> DitStructureRule
038     * <li> LdapComparator (specific to ADS)
039     * <li> LdapSyntaxe
040     * <li> MatchingRule
041     * <li> MatchingRuleUse
042     * <li> NameForm
043     * <li> Normalizer (specific to ADS)
044     * <li> ObjectClass
045     * <li> SyntaxChecker (specific to ADS)
046     * <br>
047     * <br>
048     * This class provides accessors and setters for the following attributes, 
049     * which are common to all those SchemaObjects :
050     * <li>oid : The numeric OID 
051     * <li>description : The SchemaObject description
052     * <li>obsolete : Tells if the schema object is obsolete
053     * <li>extensions : The extensions, a key/Values map
054     * <li>schemaObjectType : The SchemaObject type (see upper)
055     * <li>schema : The schema the SchemaObject is associated with (it's an extension).
056     * Can be null
057     * <li>isEnabled : The SchemaObject status (it's related to the schema status)
058     * <li>isReadOnly : Tells if the SchemaObject can be modified or not
059     * <br><br>
060     * Some of those attributes are not used by some Schema elements, even if they should
061     * have been used. Here is the list :
062     * <b>name</b> : LdapSyntax, Comparator, Normalizer, SyntaxChecker
063     * <b>numericOid</b> : DitStructureRule, 
064     * <b>obsolete</b> : LdapSyntax, Comparator, Normalizer, SyntaxChecker
065     * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
066     * @version $Rev: 927122 $
067     */
068    public interface SchemaObject extends Serializable
069    {
070        /**
071         * Gets usually what is the numeric object identifier assigned to this
072         * SchemaObject. All schema objects except for MatchingRuleUses have an OID
073         * assigned specifically to then. A MatchingRuleUse's OID really is the OID
074         * of it's MatchingRule and not specific to the MatchingRuleUse. This
075         * effects how MatchingRuleUse objects are maintained by the system.
076         * 
077         * @return an OID for this SchemaObject or its MatchingRule if this
078         *         SchemaObject is a MatchingRuleUse object
079         */
080        String getOid();
081    
082    
083        /**
084         * A special method used when renaming an SchemaObject: we may have to
085         * change it's OID
086         * @param oid The new OID
087         */
088        void setOid( String oid );
089    
090    
091        /**
092         * Gets short names for this SchemaObject if any exists for it, otherwise,
093         * returns an empty list.
094         * 
095         * @return the names for this SchemaObject
096         */
097        List<String> getNames();
098    
099    
100        /**
101         * Gets the first name in the set of short names for this SchemaObject if
102         * any exists for it.
103         * 
104         * @return the first of the names for this SchemaObject or the oid
105         * if one does not exist
106         */
107        String getName();
108    
109    
110        /**
111         * Inject this SchemaObject into the given registries, updating the references to
112         * other SchemaObject
113         *
114         * @param errors The errors we got
115         * @param registries The Registries
116         */
117        void addToRegistries( List<Throwable> errors, Registries registries ) throws LdapException;
118    
119    
120        /**
121         * Remove this SchemaObject from the given registries, updating the references to
122         * other SchemaObject
123         *
124         * @param errors The errors we got
125         * @param registries The Registries
126         */
127        void removeFromRegistries( List<Throwable> errors, Registries registries ) throws LdapException;
128    
129    
130        /**
131         * Add a new name to the list of names for this SchemaObject. The name
132         * is lowercased and trimmed.
133         *  
134         * @param names The names to add
135         */
136        void addName( String... names );
137    
138    
139        /**
140         * Sets the list of names for this SchemaObject. The names are
141         * lowercased and trimmed.
142         *  
143         * @param names The list of names. Can be empty
144         */
145        void setNames( List<String> names );
146    
147    
148        /**
149         * Gets a short description about this SchemaObject.
150         * 
151         * @return a short description about this SchemaObject
152         */
153        public String getDescription();
154    
155    
156        /**
157         * Sets the SchemaObject's description
158         * 
159         * @param description The SchemaObject's description
160         */
161        public void setDescription( String description );
162    
163    
164        /**
165         * Gets the SchemaObject specification.
166         * 
167         * @return the SchemaObject specification
168         */
169        public String getSpecification();
170    
171    
172        /**
173         * Sets the SchemaObject's specification
174         * 
175         * @param specification The SchemaObject's specification
176         */
177        void setSpecification( String specification );
178    
179    
180        /**
181         * Tells if this SchemaObject is enabled.
182         *  
183         * @param schemaEnabled the associated schema status
184         * @return true if the SchemaObject is enabled, or if it depends on 
185         * an enabled schema
186         */
187        boolean isEnabled();
188    
189    
190        /**
191         * Tells if this SchemaObject is disabled.
192         *  
193         * @return true if the SchemaObject is disabled
194         */
195        boolean isDisabled();
196    
197    
198        /**
199         * Sets the SchemaObject state, either enabled or disabled.
200         * 
201         * @param enabled The current SchemaObject state
202         */
203        void setEnabled( boolean enabled );
204    
205    
206        /**
207         * Tells if this SchemaObject is ReadOnly.
208         *  
209         * @return true if the SchemaObject is not modifiable
210         */
211        boolean isReadOnly();
212    
213    
214        /**
215         * Sets the SchemaObject readOnly flag
216         * 
217         * @param enabled The current SchemaObject ReadOnly status
218         */
219        void setReadOnly( boolean isReadOnly );
220    
221    
222        /**
223         * Gets whether or not this SchemaObject has been inactivated. All
224         * SchemaObjects except Syntaxes allow for this parameter within their
225         * definition. For Syntaxes this property should always return false in
226         * which case it is never included in the description.
227         * 
228         * @return true if inactive, false if active
229         */
230        boolean isObsolete();
231    
232    
233        /**
234         * Sets the Obsolete flag.
235         * 
236         * @param obsolete The Obsolete flag state
237         */
238        void setObsolete( boolean obsolete );
239    
240    
241        /**
242         * @return The SchemaObject extensions, as a Map of [extension, values]
243         */
244        Map<String, List<String>> getExtensions();
245    
246    
247        /**
248         * Add an extension with its values
249         * @param key The extension key
250         * @param values The associated values
251         */
252        void addExtension( String key, List<String> values );
253    
254    
255        /**
256         * Add an extensions with their values. (Actually do a copy)
257         * 
258         * @param key The extension key
259         * @param values The associated values
260         */
261        void setExtensions( Map<String, List<String>> extensions );
262    
263    
264        /**
265         * The SchemaObject type :
266         * <li> AttributeType
267         * <li> DitCOntentRule
268         * <li> DitStructureRule
269         * <li> LdapComparator (specific to ADS)
270         * <li> LdapSyntaxe
271         * <li> MatchingRule
272         * <li> MatchingRuleUse
273         * <li> NameForm
274         * <li> Normalizer (specific to ADS)
275         * <li> ObjectClass
276         * <li> SyntaxChecker (specific to ADS)
277         * 
278         * @return the SchemaObject type
279         */
280        SchemaObjectType getObjectType();
281    
282    
283        /**
284         * Gets the name of the schema this SchemaObject is associated with.
285         *
286         * @return the name of the schema associated with this schemaObject
287         */
288        String getSchemaName();
289    
290    
291        /**
292         * Sets the name of the schema this SchemaObject is associated with.
293         * 
294         * @param schemaName the new schema name
295         */
296        void setSchemaName( String schemaName );
297    
298    
299        /**
300         * @see Object#hashCode()
301         */
302        int hashCode();
303    
304    
305        /**
306         * @see Object#equals(Object)
307         */
308        boolean equals( Object o1 );
309    
310    
311        /**
312         * Register the given SchemaObject into the given registries' globalOidRegistry
313         *
314         * @param schemaObject the SchemaObject we want to register
315         * @param registries The registries in which we want it to be stored
316         * @throws LdapException If the OID is invalid
317         */
318        void registerOid( SchemaObject schemaObject, Registries registries ) throws LdapException;
319    
320    
321        /**
322         * Copy the current SchemaObject on place
323         *
324         * @return The copied SchemaObject
325         */
326        SchemaObject copy();
327    
328    
329        /**
330         * Copy a SchemaObject.
331         * 
332         * @return A copy of the current SchemaObject
333         */
334        SchemaObject copy( SchemaObject original );
335    
336    
337        /**
338         * Clear the current SchemaObject : remove all the references to other objects, 
339         * and all the Maps. 
340         */
341        void clear();
342    
343    
344        /**
345         * Inject the Registries into the SchemaObject
346         *
347         * @param registries The Registries
348         */
349        void setRegistries( Registries registries );
350        
351        
352        /**
353         * Transform the SchemaObject to an immutable object
354         * TODO locked.
355         *
356         */
357        void lock();
358    }