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.shared.ldap.codec.api; 021 022 023import java.util.Iterator; 024 025import org.apache.directory.shared.asn1.DecoderException; 026import org.apache.directory.shared.asn1.EncoderException; 027import org.apache.directory.shared.asn1.ber.Asn1Container; 028import org.apache.directory.shared.ldap.model.message.Control; 029import org.apache.directory.shared.ldap.model.message.ExtendedRequest; 030import org.apache.directory.shared.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.shared.ldap.codec.protocol.mina.LdapProtocolCodecFactory"; 044 045 // ------------------------------------------------------------------------ 046 // Control Methods 047 // ------------------------------------------------------------------------ 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 /** 126 * Returns an Iterator over the OID Strings of registered extended 127 * requests. 128 * 129 * @return The registered extended request OID Strings 130 */ 131 Iterator<String> registeredExtendedRequests(); 132 133 134 /** 135 * Registers an {@link ExtendedRequestFactory} for generating extended request 136 * response pairs. 137 * 138 * @param factory The extended request factory 139 * @return The displaced factory if one existed for the oid 140 */ 141 ExtendedRequestFactory<?,?> registerExtendedRequest( ExtendedRequestFactory<?,?> factory ); 142 143 144 /** 145 * Unregisters an {@link ExtendedRequestFactory} for generating extended 146 * request response pairs. 147 * 148 * @param oid The extended request oid 149 * @return The displaced factory if one existed for the oid 150 */ 151 ExtendedRequestFactory<?,?> unregisterExtendedRequest( String oid ); 152 153 154 /** 155 * Checks to see if an extended operation, either a standard request 156 * response, pair or just an unsolicited response is registered. 157 * 158 * @param oid The object identifier for the extended operation 159 * @return true if registered, false if not 160 */ 161 boolean isExtendedOperationRegistered( String oid ); 162 163 164 // ------------------------------------------------------------------------ 165 // Extended Response Methods 166 // ------------------------------------------------------------------------ 167 168 169 /** 170 * Returns an Iterator over the OID Strings of registered unsolicited 171 * extended responses. 172 * 173 * @return The registered unsolicited extended response OID Strings 174 */ 175 Iterator<String> registeredUnsolicitedResponses(); 176 177 178 /** 179 * Registers an {@link UnsolicitedResponseFactory} for generating extended 180 * responses sent by servers without an extended request. 181 * 182 * @param factory The unsolicited response creating factory 183 * @return The displaced factory if one existed for the oid 184 */ 185 UnsolicitedResponseFactory<?> registerUnsolicitedResponse( UnsolicitedResponseFactory<?> factory ); 186 187 188 /** 189 * Unregisters an {@link UnsolicitedResponseFactory} for generating 190 * extended responses sent by servers without an extended request. 191 * 192 * @param oid The unsolicited response oid 193 */ 194 UnsolicitedResponseFactory<?> unregisterUnsolicitedResponse( String oid ); 195 196 197 /** 198 * Creates a model ExtendedResponse from the JNDI ExtendedResponse. 199 * 200 * @param jndiResponse The JNDI ExtendedResponse 201 * @return The model ExtendedResponse 202 * @throws DecoderException if the response value cannot be decoded. 203 */ 204 ExtendedResponse fromJndi( javax.naming.ldap.ExtendedResponse jndiResponse ) throws DecoderException; 205 206 207 /** 208 * Creates a JNDI {@link javax.naming.ldap.ExtendedResponse} from the model 209 * {@link ExtendedResponse}. 210 * 211 * @param modelResponse 212 * @return 213 * @throws EncoderException 214 */ 215 javax.naming.ldap.ExtendedResponse toJndi( ExtendedResponse modelResponse ) throws EncoderException; 216 217 218 /** 219 * Creates a model ExtendedResponse from the JNDI ExtendedResponse. 220 * 221 * @param jndiResponse The JNDI ExtendedResponse 222 * @return The model ExtendedResponse 223 * @throws DecoderException if the response value cannot be decoded. 224 */ 225 ExtendedRequest<?> fromJndi( javax.naming.ldap.ExtendedRequest jndiRequest ) throws DecoderException; 226 227 228 /** 229 * Creates a JNDI {@link javax.naming.ldap.ExtendedResponse} from the model 230 * {@link ExtendedResponse}. 231 * 232 * @param modelResponse 233 * @return 234 * @throws EncoderException 235 */ 236 javax.naming.ldap.ExtendedRequest toJndi( ExtendedRequest<?> modelRequest ) throws EncoderException; 237 238 239 // ------------------------------------------------------------------------ 240 // Other Methods 241 // ------------------------------------------------------------------------ 242 243 244 /** 245 * Creates a new LDAP {@link ProtocolCodecFactory}. 246 * 247 * @return the {@link ProtocolCodecFactory} 248 */ 249 ProtocolCodecFactory getProtocolCodecFactory(); 250 251 252 /** 253 * Registers a ProtocolCodecFactory with this LdapCodecService. 254 * 255 * @param factory The factory being registered. 256 * @return The previously set {@link ProtocolCodecFactory}, or null if 257 * none had been set earlier. 258 */ 259 ProtocolCodecFactory registerProtocolCodecFactory( ProtocolCodecFactory factory ); 260 261 262 /** 263 * Creates a new MessageContainer. 264 * 265 * @TODO akarasulu - Wondering why is this not an LdapMessageContainer? 266 * @return The newly created LDAP MessageContainer instance. 267 */ 268 Asn1Container newMessageContainer(); 269 270 271 <E extends ExtendedResponse> E newExtendedResponse( ExtendedRequest<E> req, byte[] serializedResponse ) throws DecoderException; 272 273 274 /** 275 * Creates a new ExtendedRequest instance. 276 * 277 * @param oid the extended request's object identifier 278 * @param value the encoded value of the extended request 279 * @return The new extended request 280 */ 281 ExtendedRequest<?> newExtendedRequest( String oid, byte[] value ); 282 283 284 ExtendedRequestDecorator<?,?> decorate( ExtendedRequest<?> decoratedMessage ); 285 286 287 ExtendedResponseDecorator<?> decorate( ExtendedResponse decoratedMessage ); 288}