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 */
020package org.apache.directory.api.ldap.model.schema;
021
022
023import java.util.List;
024import java.util.Map;
025
026
027/**
028 * Most schema objects have some common attributes. This class
029 * contains the minimum set of properties exposed by a SchemaObject.<br>
030 * We have 11 types of SchemaObjects :
031 * <li> AttributeType
032 * <li> DitCOntentRule
033 * <li> DitStructureRule
034 * <li> LdapComparator (specific to ADS)
035 * <li> LdapSyntaxe
036 * <li> MatchingRule
037 * <li> MatchingRuleUse
038 * <li> NameForm
039 * <li> Normalizer (specific to ADS)
040 * <li> ObjectClass
041 * <li> SyntaxChecker (specific to ADS)
042 * <br>
043 * <br>
044 * This class provides accessors and setters for the following attributes,
045 * which are common to all those SchemaObjects :
046 * <li>oid : The numeric OID
047 * <li>description : The SchemaObject description
048 * <li>obsolete : Tells if the schema object is obsolete
049 * <li>extensions : The extensions, a key/Values map
050 * <li>schemaObjectType : The SchemaObject type (see upper)
051 * <li>schema : The schema the SchemaObject is associated with (it's an extension).
052 * Can be null
053 * <li>isEnabled : The SchemaObject status (it's related to the schema status)
054 * <li>isReadOnly : Tells if the SchemaObject can be modified or not
055 * <br><br>
056 * Some of those attributes are not used by some Schema elements, even if they should
057 * have been used. Here is the list :
058 * <b>name</b> : LdapSyntax, Comparator, Normalizer, SyntaxChecker
059 * <b>numericOid</b> : DitStructureRule,
060 * <b>obsolete</b> : LdapSyntax, Comparator, Normalizer, SyntaxChecker
061 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
062 */
063public interface SchemaObject
064{
065    /**
066     * Gets usually what is the numeric object identifier assigned to this
067     * SchemaObject. All schema objects except for MatchingRuleUses have an OID
068     * assigned specifically to then. A MatchingRuleUse's OID really is the OID
069     * of it's MatchingRule and not specific to the MatchingRuleUse. This
070     * effects how MatchingRuleUse objects are maintained by the system.
071     * 
072     * @return an OID for this SchemaObject or its MatchingRule if this
073     *         SchemaObject is a MatchingRuleUse object
074     */
075    String getOid();
076
077
078    /**
079     * A special method used when renaming an SchemaObject: we may have to
080     * change it's OID
081     * @param oid The new OID
082     */
083    void setOid( String oid );
084
085
086    /**
087     * Gets short names for this SchemaObject if any exists for it, otherwise,
088     * returns an empty list.
089     * 
090     * @return the names for this SchemaObject
091     */
092    List<String> getNames();
093
094
095    /**
096     * Gets the first name in the set of short names for this SchemaObject if
097     * any exists for it.
098     * 
099     * @return the first of the names for this SchemaObject or the oid
100     * if one does not exist
101     */
102    String getName();
103
104
105    /**
106     * Add a new name to the list of names for this SchemaObject. The name
107     * is lower cased and trimmed.
108     * 
109     * @param names The names to add
110     */
111    void addName( String... names );
112
113
114    /**
115     * Sets the list of names for this SchemaObject. The names are
116     * lower cased and trimmed.
117     * 
118     * @param names The list of names. Can be empty
119     */
120    void setNames( List<String> names );
121
122
123    /**
124     * Gets a short description about this SchemaObject.
125     * 
126     * @return a short description about this SchemaObject
127     */
128    String getDescription();
129
130
131    /**
132     * Sets the SchemaObject's description
133     * 
134     * @param description The SchemaObject's description
135     */
136    void setDescription( String description );
137
138
139    /**
140     * Gets the SchemaObject specification.
141     * 
142     * @return the SchemaObject specification
143     */
144    String getSpecification();
145
146
147    /**
148     * Sets the SchemaObject's specification
149     * 
150     * @param specification The SchemaObject's specification
151     */
152    void setSpecification( String specification );
153
154
155    /**
156     * Tells if this SchemaObject is enabled.
157     * 
158     * @return true if the SchemaObject is enabled, or if it depends on
159     * an enabled schema
160     */
161    boolean isEnabled();
162
163
164    /**
165     * Tells if this SchemaObject is disabled.
166     * 
167     * @return true if the SchemaObject is disabled
168     */
169    boolean isDisabled();
170
171
172    /**
173     * Sets the SchemaObject state, either enabled or disabled.
174     * 
175     * @param enabled The current SchemaObject state
176     */
177    void setEnabled( boolean enabled );
178
179
180    /**
181     * Tells if this SchemaObject is ReadOnly.
182     * 
183     * @return true if the SchemaObject is not modifiable
184     */
185    boolean isReadOnly();
186
187
188    /**
189     * Sets the SchemaObject readOnly flag
190     * 
191     * @param isReadOnly The current SchemaObject ReadOnly status
192     */
193    void setReadOnly( boolean isReadOnly );
194
195
196    /**
197     * Gets whether or not this SchemaObject has been inactivated. All
198     * SchemaObjects except Syntaxes allow for this parameter within their
199     * definition. For Syntaxes this property should always return false in
200     * which case it is never included in the description.
201     * 
202     * @return true if inactive, false if active
203     */
204    boolean isObsolete();
205
206
207    /**
208     * Sets the Obsolete flag.
209     * 
210     * @param obsolete The Obsolete flag state
211     */
212    void setObsolete( boolean obsolete );
213
214
215    /**
216     * @return The SchemaObject extensions, as a Map of [extension, values]
217     */
218    Map<String, List<String>> getExtensions();
219
220
221    /**
222     * Add an extension with its values
223     * @param key The extension key
224     * @param values The associated values
225     */
226    void addExtension( String key, String... values );
227
228
229    /**
230     * Add an extension with its values
231     * @param key The extension key
232     * @param values The associated values
233     */
234    void addExtension( String key, List<String> values );
235
236
237    /**
238     * Add an extensions with their values. (Actually do a copy)
239     * 
240     * @param extensions The extensions map
241     */
242    void setExtensions( Map<String, List<String>> extensions );
243
244
245    /**
246     * The SchemaObject type :
247     * <li> AttributeType
248     * <li> DitCOntentRule
249     * <li> DitStructureRule
250     * <li> LdapComparator (specific to ADS)
251     * <li> LdapSyntaxe
252     * <li> MatchingRule
253     * <li> MatchingRuleUse
254     * <li> NameForm
255     * <li> Normalizer (specific to ADS)
256     * <li> ObjectClass
257     * <li> SyntaxChecker (specific to ADS)
258     * 
259     * @return the SchemaObject type
260     */
261    SchemaObjectType getObjectType();
262
263
264    /**
265     * Gets the name of the schema this SchemaObject is associated with.
266     *
267     * @return the name of the schema associated with this schemaObject
268     */
269    String getSchemaName();
270
271
272    /**
273     * Sets the name of the schema this SchemaObject is associated with.
274     * 
275     * @param schemaName the new schema name
276     */
277    void setSchemaName( String schemaName );
278
279
280    /**
281     * {@inheritDoc}
282     */
283    int hashCode();
284
285
286    /**
287     * {@inheritDoc}
288     */
289    boolean equals( Object o1 );
290
291
292    /**
293     * Copy the current SchemaObject on place
294     *
295     * @return The copied SchemaObject
296     */
297    SchemaObject copy();
298
299
300    /**
301     * Copies the given schema object into this schema object.
302     *
303     * @param original the original SchemaObject
304     * @return this
305     */
306    SchemaObject copy( SchemaObject original );
307
308
309    /**
310     * Clear the current SchemaObject : remove all the references to other objects,
311     * and all the Maps.
312     */
313    void clear();
314
315
316    /**
317     * Transform the SchemaObject to an immutable object
318     * TODO locked.
319     *
320     */
321    void lock();
322}