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}