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 * https://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 import java.util.Map;
25
26 import org.apache.directory.api.asn1.DecoderException;
27 import org.apache.directory.api.asn1.EncoderException;
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.directory.api.ldap.model.name.DnFactory;
32 import org.apache.mina.filter.codec.ProtocolCodecFactory;
33
34
35 /**
36 * The service interface for the LDAP codec. It gathers all the supported controls and extended operations.
37 *
38 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
39 * @version $Rev$, $Date$
40 */
41 public interface LdapApiService
42 {
43 /** The default codec factory */
44 String DEFAULT_PROTOCOL_CODEC_FACTORY =
45 "org.apache.directory.api.ldap.codec.protocol.mina.LdapProtocolCodecFactory";
46
47
48 // ------------------------------------------------------------------------
49 // Control Methods
50 // ------------------------------------------------------------------------
51
52 /**
53 * Returns an Iterator over the OID Strings of registered request controls.
54 *
55 * @return The registered control OID Strings
56 */
57 Iterator<String> registeredRequestControls();
58
59
60 /**
61 * Returns an Iterator over the OID Strings of registered response controls.
62 *
63 * @return The registered control OID Strings
64 */
65 Iterator<String> registeredResponseControls();
66
67
68 /**
69 * Checks if a control has been registered. It will check in both the
70 * request and response control maps.
71 *
72 * @param oid The Control OID we are looking for
73 * @return The OID of the control to check for registration
74 */
75 boolean isControlRegistered( String oid );
76
77
78 /**
79 * Registers an request {@link ControlFactory} with this service.
80 *
81 * @param factory The control factory
82 * @return The registered control factory
83 */
84 ControlFactory<?> registerRequestControl( ControlFactory<?> factory );
85
86
87 /**
88 * Registers an response {@link ControlFactory} with this service.
89 *
90 * @param factory The control factory
91 * @return The registered control factory
92 */
93 ControlFactory<?> registerResponseControl( ControlFactory<?> factory );
94
95
96 /**
97 * Unregisters a request {@link ControlFactory} with this service.
98 *
99 * @param oid The oid of the control the factory is associated with.
100 * @return The unregistered control factory
101 */
102 ControlFactory<?> unregisterRequestControl( String oid );
103
104
105 /**
106 * Unregisters a response {@link ControlFactory} with this service.
107 *
108 * @param oid The oid of the control the factory is associated with.
109 * @return The unregistered control factory
110 */
111 ControlFactory<?> unregisterResponseControl( String oid );
112
113
114 /**
115 * Creates a JNDI control from the ldap model's control.
116 *
117 * @param modelControl The model's control.
118 * @return The JNDI control.
119 * @throws EncoderException if there are problems encoding the modelControl.
120 */
121 javax.naming.ldap.Control toJndiControl( Control modelControl ) throws EncoderException;
122
123
124 /**
125 * Creates a model request control from the JNDI request control.
126 *
127 * @param jndiControl The JNDI control.
128 * @return The model request control.
129 * @throws DecoderException if there are problems decoding the value of the JNDI control.
130 */
131 Control fromJndiRequestControl( javax.naming.ldap.Control jndiControl ) throws DecoderException;
132
133
134 /**
135 * Creates a model response control from the JNDI response control.
136 *
137 * @param jndiControl The JNDI response control.
138 * @return The model control.
139 * @throws DecoderException if there are problems decoding the value of the JNDI control.
140 */
141 Control fromJndiResponseControl( javax.naming.ldap.Control jndiControl ) throws DecoderException;
142
143
144 /**
145 * @return the request controlFactories
146 */
147 Map<String, ControlFactory<? extends Control>> getRequestControlFactories();
148
149
150 /**
151 * @return the response controlFactories
152 */
153 Map<String, ControlFactory<? extends Control>> getResponseControlFactories();
154
155
156 // ------------------------------------------------------------------------
157 // Extended Request Methods
158 // ------------------------------------------------------------------------
159 /**
160 * Returns an Iterator over the OID Strings of registered extended
161 * requests.
162 *
163 * @return The registered extended request OID Strings
164 */
165 Iterator<String> registeredExtendedRequests();
166
167
168 /**
169 * Returns an Iterator over the OID Strings of registered extended
170 * responses.
171 *
172 * @return The registered extended response OID Strings
173 */
174 Iterator<String> registeredExtendedResponses();
175
176
177 /**
178 * Registers an {@link ExtendedOperationFactory} for generating extended request
179 * response pairs.
180 *
181 * @param factory The extended request factory
182 * @return The registered factory if one existed for the oid
183 */
184 ExtendedOperationFactory registerExtendedRequest( ExtendedOperationFactory factory );
185
186
187 /**
188 * Registers an {@link ExtendedOperationFactory} for generating extended response
189 * response pairs.
190 *
191 * @param factory The extended response factory
192 * @return The registered factory if one existed for the oid
193 */
194 ExtendedOperationFactory registerExtendedResponse( ExtendedOperationFactory factory );
195
196
197 /**
198 * Unregisters an {@link ExtendedOperationFactory} for generating extended
199 * request response pairs.
200 *
201 * @param oid The extended request oid
202 * @return The registered factory if one existed for the oid
203 */
204 ExtendedOperationFactory unregisterExtendedRequest( String oid );
205
206
207 /**
208 * Unregisters an {@link ExtendedOperationFactory} for generating extended
209 * responses.
210 *
211 * @param oid The extended response oid
212 * @return The registered factory if one existed for the oid
213 */
214 ExtendedOperationFactory unregisterExtendedResponse( String oid );
215
216
217 /**
218 * Checks to see if an extended request operation is registered.
219 *
220 * @param oid The object identifier for the extended request operation
221 * @return true if registered, false if not
222 */
223 boolean isExtendedRequestRegistered( String oid );
224
225
226 /**
227 * Checks to see if an extended response operation is registered.
228 *
229 * @param oid The object identifier for the extended response operation
230 * @return true if registered, false if not
231 */
232 boolean isExtendedResponseRegistered( String oid );
233
234
235 /**
236 * @return the extendedRequestFactories
237 */
238 Map<String, ExtendedOperationFactory> getExtendedRequestFactories();
239
240
241 /**
242 * @return the extendedResponseFactories
243 */
244 Map<String, ExtendedOperationFactory> getExtendedResponseFactories();
245
246
247 // ------------------------------------------------------------------------
248 // Intermediate Response Methods
249 // ------------------------------------------------------------------------
250
251 /**
252 * Returns an Iterator over the OID Strings of registered intermediate
253 * responses.
254 *
255 * @return The registered Intermediate response OID Strings
256 */
257 Iterator<String> registeredIntermediateResponses();
258
259
260 /**
261 * Registers an {@link IntermediateOperationFactory} for generating intermediate response
262 *
263 * @param factory The intermediate response factory
264 * @return The displaced factory if one existed for the oid
265 */
266 IntermediateOperationFactory registerIntermediateResponse( IntermediateOperationFactory factory );
267
268
269 /**
270 * Unregisters an {@link IntermediateOperationFactory} for generating intermediate
271 * response
272 *
273 * @param oid The intermediate response oid
274 * @return The displaced factory if one existed for the oid
275 */
276 IntermediateOperationFactory unregisterIntermediateResponse( String oid );
277
278
279 /**
280 * Checks to see if an intermediate response is registered.
281 *
282 * @param oid The object identifier for the intermediate response
283 * @return true if registered, false if not
284 */
285 boolean isIntermediateResponseRegistered( String oid );
286
287
288 /**
289 * @return the intermediateResponseFactories
290 */
291 Map<String, IntermediateOperationFactory> getIntermediateResponseFactories();
292
293
294 // ------------------------------------------------------------------------
295 // Extended Response Methods
296 // ------------------------------------------------------------------------
297
298 /**
299 * Creates a model ExtendedResponse from the JNDI ExtendedResponse.
300 *
301 * @param jndiResponse The JNDI ExtendedResponse
302 * @return The model ExtendedResponse
303 * @throws DecoderException if the response value cannot be decoded.
304 */
305 ExtendedResponse fromJndi( javax.naming.ldap.ExtendedResponse jndiResponse ) throws DecoderException;
306
307
308 /**
309 * Creates a JNDI {@link javax.naming.ldap.ExtendedResponse} from the model
310 * {@link ExtendedResponse}.
311 *
312 * @param modelResponse The extended response to convert
313 * @return A JNDI extended response
314 * @throws EncoderException If the conversion failed
315 */
316 javax.naming.ldap.ExtendedResponse toJndi( ExtendedResponse modelResponse ) throws EncoderException;
317
318
319 /**
320 * Creates a model ExtendedResponse from the JNDI ExtendedRequest.
321 *
322 * @param jndiRequest The JNDI ExtendedRequest
323 * @return The model ExtendedRequest
324 * @throws DecoderException if the request value cannot be decoded.
325 */
326 ExtendedRequest fromJndi( javax.naming.ldap.ExtendedRequest jndiRequest ) throws DecoderException;
327
328
329 /**
330 * Creates a JNDI {@link javax.naming.ldap.ExtendedRequest} from the model
331 * {@link ExtendedRequest}.
332 *
333 * @param modelRequest The extended request to convert
334 * @return A JNDI extended request
335 * @throws EncoderException If the conversion failed
336 */
337 javax.naming.ldap.ExtendedRequest toJndi( ExtendedRequest modelRequest ) throws EncoderException;
338
339
340 // ------------------------------------------------------------------------
341 // Other Methods
342 // ------------------------------------------------------------------------
343
344 /**
345 * Creates a new LDAP {@link ProtocolCodecFactory}.
346 *
347 * @return the {@link ProtocolCodecFactory}
348 */
349 ProtocolCodecFactory getProtocolCodecFactory();
350
351
352 /**
353 * Registers a ProtocolCodecFactory with this LdapCodecService.
354 *
355 * @param factory The factory being registered.
356 * @return The previously set {@link ProtocolCodecFactory}, or null if
357 * none had been set earlier.
358 */
359 ProtocolCodecFactory registerProtocolCodecFactory( ProtocolCodecFactory factory );
360
361
362 /**
363 * Associate a DnFactory to the service
364 * @param dnfactory The DnFactory instance
365 */
366 void setDnfactory( DnFactory dnfactory );
367
368
369 /**
370 * Get the DN Factory
371 * @return The DnFactory instance
372 */
373 DnFactory getDnFactory();
374 }