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