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.codec.api;
021
022
023import java.util.Iterator;
024
025import org.apache.directory.api.asn1.DecoderException;
026import org.apache.directory.api.asn1.EncoderException;
027import org.apache.directory.api.asn1.ber.Asn1Container;
028import org.apache.directory.api.ldap.model.message.Control;
029import org.apache.directory.api.ldap.model.message.ExtendedRequest;
030import org.apache.directory.api.ldap.model.message.ExtendedResponse;
031import org.apache.mina.filter.codec.ProtocolCodecFactory;
032
033
034/**
035 * The service interface for the LDAP codec. It gathers all the supported controls and extended operations.
036 *
037 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
038 * @version $Rev$, $Date$
039 */
040public interface LdapApiService
041{
042    /** The default codec factory */
043    String DEFAULT_PROTOCOL_CODEC_FACTORY =
044        "org.apache.directory.api.ldap.codec.protocol.mina.LdapProtocolCodecFactory";
045
046
047    // ------------------------------------------------------------------------
048    // Control Methods
049    // ------------------------------------------------------------------------
050
051    /**
052     * Returns an Iterator over the OID Strings of registered controls.
053     * 
054     * @return The registered control OID Strings
055     */
056    Iterator<String> registeredControls();
057
058
059    /**
060     * Checks if a control has been registered.
061     * 
062     * @param oid The Control OID we are looking for
063     * @return The OID of the control to check for registration
064     */
065    boolean isControlRegistered( String oid );
066
067
068    /**
069     * Registers an {@link ControlFactory} with this service.
070     * 
071     * @param factory The control factory
072     * @return The registred control factory
073     */
074    ControlFactory<?> registerControl( ControlFactory<?> factory );
075
076
077    /**
078     * Unregisters an {@link ControlFactory} with this service.
079     * 
080     * @param oid The oid of the control the factory is associated with.
081     * @return The unregistred control factory
082     */
083    ControlFactory<?> unregisterControl( String oid );
084
085
086    /**
087     * Creates a new codec control decorator of the specified type.
088     *
089     * @param oid The OID of the new control to create.
090     * @return The newly created codec control.
091     */
092    CodecControl<? extends Control> newControl( String oid );
093
094
095    /**
096     * Creates a new codec control decorator for the provided control.
097     *
098     * @param control The control the codec control is generated for.
099     * @return The newly created codec control.
100     */
101    CodecControl<? extends Control> newControl( Control control );
102
103
104    /**
105     * Creates a JNDI control from the ldap model's control.
106     *
107     * @param modelControl The model's control.
108     * @return The JNDI control.
109     * @throws EncoderException if there are problems encoding the modelControl.
110     */
111    javax.naming.ldap.Control toJndiControl( Control modelControl ) throws EncoderException;
112
113
114    /**
115     * Creates a model control from the JNDI control.
116     *
117     * @param jndiControl The JNDI control.
118     * @return The model control.
119     * @throws DecoderException if there are problems decoding the value of the JNDI control.
120     */
121    Control fromJndiControl( javax.naming.ldap.Control jndiControl ) throws DecoderException;
122
123
124    // ------------------------------------------------------------------------
125    // Extended Request Methods
126    // ------------------------------------------------------------------------
127
128    /**
129     * Returns an Iterator over the OID Strings of registered extended 
130     * requests.
131     *
132     * @return The registered extended request OID Strings
133     */
134    Iterator<String> registeredExtendedRequests();
135
136
137    /**
138     * Registers an {@link ExtendedOperationFactory} for generating extended request 
139     * response pairs.
140     * 
141     * @param factory The extended request factory
142     * @return The displaced factory if one existed for the oid
143     */
144    ExtendedOperationFactory registerExtendedRequest( ExtendedOperationFactory factory );
145
146
147    /**
148     * Unregisters an {@link ExtendedOperationFactory} for generating extended 
149     * request response pairs.
150     * 
151     * @param oid The extended request oid
152     * @return The displaced factory if one existed for the oid
153     */
154    ExtendedOperationFactory unregisterExtendedRequest( String oid );
155
156
157    /**
158     * Checks to see if an extended operation, either a standard request 
159     * response, pair or just an unsolicited response is registered.
160     *
161     * @param oid The object identifier for the extended operation
162     * @return true if registered, false if not
163     */
164    boolean isExtendedOperationRegistered( String oid );
165
166
167    // ------------------------------------------------------------------------
168    // Extended Response Methods
169    // ------------------------------------------------------------------------
170
171    /**
172     * Creates a model ExtendedResponse from the JNDI ExtendedResponse.
173     *
174     * @param jndiResponse The JNDI ExtendedResponse 
175     * @return The model ExtendedResponse
176     * @throws DecoderException if the response value cannot be decoded.
177     */
178    ExtendedResponse fromJndi( javax.naming.ldap.ExtendedResponse jndiResponse ) throws DecoderException;
179
180
181    /**
182     * Creates a JNDI {@link javax.naming.ldap.ExtendedResponse} from the model 
183     * {@link ExtendedResponse}.
184     * 
185     * @param modelResponse The extended response to convert
186     * @return A JNDI extended response
187     * @throws EncoderException If the conversion failed
188     */
189    javax.naming.ldap.ExtendedResponse toJndi( ExtendedResponse modelResponse ) throws EncoderException;
190
191
192    /**
193     * Creates a model ExtendedResponse from the JNDI ExtendedRequest.
194     *
195     * @param jndiRequest The JNDI ExtendedRequest 
196     * @return The model ExtendedRequest
197     * @throws DecoderException if the request value cannot be decoded.
198     */
199    ExtendedRequest fromJndi( javax.naming.ldap.ExtendedRequest jndiRequest ) throws DecoderException;
200
201
202    /**
203     * Creates a JNDI {@link javax.naming.ldap.ExtendedRequest} from the model 
204     * {@link ExtendedRequest}.
205     * 
206     * @param modelRequest The extended request to convert
207     * @return A JNDI extended request
208     * @throws EncoderException If the conversion failed
209     */
210    javax.naming.ldap.ExtendedRequest toJndi( ExtendedRequest modelRequest ) throws EncoderException;
211
212
213    // ------------------------------------------------------------------------
214    // Other Methods
215    // ------------------------------------------------------------------------
216
217    /**
218     * Creates a new LDAP {@link ProtocolCodecFactory}.
219     *
220     * @return the {@link ProtocolCodecFactory}
221     */
222    ProtocolCodecFactory getProtocolCodecFactory();
223
224
225    /**
226     * Registers a ProtocolCodecFactory with this LdapCodecService.
227     *
228     * @param factory The factory being registered.
229     * @return The previously set {@link ProtocolCodecFactory}, or null if 
230     * none had been set earlier.
231     */
232    ProtocolCodecFactory registerProtocolCodecFactory( ProtocolCodecFactory factory );
233
234
235    /**
236     * Creates a new MessageContainer.
237     *
238     * @return The newly created LDAP MessageContainer instance.
239     */
240    Asn1Container newMessageContainer();
241
242
243    /**
244     * Create an instance of a ExtendedResponse, knowing its OID. Inject the payload
245     * into it.
246     * 
247     * @param responseName The extendedRespose OID
248     * @param messageId The original message ID
249     * @param serializedResponse The serialized response payload
250     * @param <E> The extended response type
251     * @return The extendedResponse instance
252     * 
253     * @throws DecoderException If the payload is incorrect
254     */
255    <E extends ExtendedResponse> E newExtendedResponse( String responseName, int messageId, byte[] serializedResponse )
256        throws DecoderException;
257
258
259    /**
260     * Creates a new ExtendedRequest instance.
261     * 
262     * @param oid the extended request's object identifier
263     * @param value the encoded value of the extended request
264     * @return The new extended request
265     */
266    ExtendedRequest newExtendedRequest( String oid, byte[] value );
267
268
269    /**
270     * Decorates an extended request message, ie encapsulate it into a class that do the encoding/decoding
271     *
272     * @param decoratedMessage The extended request to decorate
273     * @return The decorated extended request
274     */
275    ExtendedRequestDecorator<?> decorate( ExtendedRequest decoratedMessage );
276
277
278    /**
279     * Decorates an extended response message, ie encapsulate it into a class that do the encoding/decoding
280     *
281     * @param decoratedMessage The extended response to decorate
282     * @return The decorated extended response
283     */
284    ExtendedResponseDecorator<?> decorate( ExtendedResponse decoratedMessage );
285}