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.registries;
021
022
023import java.util.Iterator;
024
025import org.apache.directory.api.ldap.model.exception.LdapException;
026import org.apache.directory.api.ldap.model.schema.SchemaObject;
027import org.apache.directory.api.ldap.model.schema.SchemaObjectType;
028
029
030/**
031 * Common schema object registry interface.
032 *
033 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
034 */
035public interface SchemaObjectRegistry<T extends SchemaObject>
036{
037    /**
038     * Checks to see if an SchemaObject exists in the registry, by its
039     * OID or name. 
040     * 
041     * @param oid the object identifier or name of the SchemaObject
042     * @return true if a SchemaObject definition exists for the oid, false
043     * otherwise
044     */
045    boolean contains( String oid );
046
047
048    /**
049     * Gets the name of the schema this schema object is associated with.
050     *
051     * @param oid the object identifier or the name
052     * @return the schema name
053     * @throws LdapException if the schema object does not exist
054     */
055    String getSchemaName( String oid ) throws LdapException;
056
057
058    /**
059     * Gets the SchemaObject associated with a given OID.
060     *
061     * @param oid The SchemaObject's OID we are looking for
062     * @return The SchemaObject, if any. Null otherwise
063     */
064    T get( String oid );
065
066
067    /**
068     * Modify all the SchemaObject using a schemaName when this name changes.
069     *
070     * @param originalSchemaName The original Schema name
071     * @param newSchemaName The new Schema name
072     * @throws LdapException if the schema object does not exist
073     */
074    void renameSchema( String originalSchemaName, String newSchemaName ) throws LdapException;
075
076
077    /**
078     * Gets an iterator over the registered schema objects in the registry.
079     *
080     * @return an Iterator of homogeneous schema objects
081     */
082    Iterator<T> iterator();
083
084
085    /**
086     * Gets an iterator over the registered schema objects'OID in the registry.
087     *
088     * @return an Iterator of OIDs
089     */
090    Iterator<String> oidsIterator();
091
092
093    /**
094     * Looks up a SchemaObject by its unique Object Identifier or by name.
095     *
096     * @param oid the object identifier or name
097     * @return the SchemaObject instance for the id
098     * @throws LdapException if the SchemaObject does not exist
099     */
100    T lookup( String oid ) throws LdapException;
101
102
103    /**
104     * Registers a new SchemaObject with this registry.
105     *
106     * @param schemaObject the SchemaObject to register
107     * @throws LdapException if the SchemaObject is already registered or
108     * the registration operation is not supported
109     */
110    void register( T schemaObject ) throws LdapException;
111
112
113    /**
114     * Removes the SchemaObject registered with this registry, using its
115     * numeric OID.
116     * 
117     * @param numericOid the numeric identifier
118     * @throws LdapException if the numeric identifier is invalid
119     */
120    T unregister( String numericOid ) throws LdapException;
121
122
123    /**
124     * Removes the SchemaObject registered with this registry.
125     * 
126     * @param schemaObject the schemaObject to unregister
127     * @throws LdapException if the schemaObject can't be unregistered is invalid
128     */
129    T unregister( T schemaObject ) throws LdapException;
130
131
132    /**
133     * Unregisters all SchemaObjects defined for a specific schema from
134     * this registry.
135     * 
136     * @param schemaName the name of the schema whose SchemaObjects will be removed from
137     */
138    void unregisterSchemaElements( String schemaName ) throws LdapException;
139
140
141    /**
142     * Gets the numericOid for a name/alias if one is associated.  To prevent
143     * lookup failures due to case variance in the name, a failure to lookup the
144     * OID, will trigger a lookup using a lower cased version of the name and 
145     * the name that failed to match will automatically be associated with the
146     * OID.
147     * 
148     * @param name The name we are looking the oid for
149     * @return The numericOID associated with this name
150     * @throws LdapException If the OID can't be found
151     */
152    String getOidByName( String name ) throws LdapException;
153
154
155    /**
156     * Copy a DefaultSchemaObjectRegistry. All the stored SchemaObject will also
157     * be copied, by the cross references will be lost.
158     * 
159     * @return SchemaObjectRegistry<T> The copied registry
160     */
161    SchemaObjectRegistry<T> copy();
162
163
164    /**
165     * @return the type
166     */
167    SchemaObjectType getType();
168
169
170    /**
171     *  @return The number of AttributeType stored
172     */
173    int size();
174
175
176    /**
177     * Clear the registry from all its content
178     */
179    void clear() throws LdapException;
180}