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}