1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 *
19 */
20 package org.apache.directory.api.ldap.codec.api;
21
22
23 import java.util.Iterator;
24
25 import org.apache.directory.api.asn1.DecoderException;
26 import org.apache.directory.api.asn1.EncoderException;
27 import org.apache.directory.api.asn1.ber.Asn1Container;
28 import org.apache.directory.api.ldap.model.message.Control;
29 import org.apache.directory.api.ldap.model.message.ExtendedRequest;
30 import org.apache.directory.api.ldap.model.message.ExtendedResponse;
31 import org.apache.mina.filter.codec.ProtocolCodecFactory;
32
33
34 /**
35 * The service interface for the LDAP codec. It gathers all the supported controls and extended operations.
36 *
37 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
38 * @version $Rev$, $Date$
39 */
40 public interface LdapApiService
41 {
42 /** The default codec factory */
43 String DEFAULT_PROTOCOL_CODEC_FACTORY =
44 "org.apache.directory.api.ldap.codec.protocol.mina.LdapProtocolCodecFactory";
45
46
47 // ------------------------------------------------------------------------
48 // Control Methods
49 // ------------------------------------------------------------------------
50
51 /**
52 * Returns an Iterator over the OID Strings of registered controls.
53 *
54 * @return The registered control OID Strings
55 */
56 Iterator<String> registeredControls();
57
58
59 /**
60 * Checks if a control has been registered.
61 *
62 * @param oid The Control OID we are looking for
63 * @return The OID of the control to check for registration
64 */
65 boolean isControlRegistered( String oid );
66
67
68 /**
69 * Registers an {@link ControlFactory} with this service.
70 *
71 * @param factory The control factory
72 * @return The registred control factory
73 */
74 ControlFactory<?> registerControl( ControlFactory<?> factory );
75
76
77 /**
78 * Unregisters an {@link ControlFactory} with this service.
79 *
80 * @param oid The oid of the control the factory is associated with.
81 * @return The unregistred control factory
82 */
83 ControlFactory<?> unregisterControl( String oid );
84
85
86 /**
87 * Creates a new codec control decorator of the specified type.
88 *
89 * @param oid The OID of the new control to create.
90 * @return The newly created codec control.
91 */
92 CodecControl<? extends Control> newControl( String oid );
93
94
95 /**
96 * Creates a new codec control decorator for the provided control.
97 *
98 * @param control The control the codec control is generated for.
99 * @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 }