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.ldap.client.api; 21 22 23 import java.io.IOException; 24 25 import org.apache.directory.api.ldap.model.entry.Entry; 26 import org.apache.directory.api.ldap.model.exception.LdapException; 27 import org.apache.directory.api.ldap.model.message.AddRequest; 28 import org.apache.directory.api.ldap.model.message.BindRequest; 29 import org.apache.directory.api.ldap.model.message.CompareRequest; 30 import org.apache.directory.api.ldap.model.message.DeleteRequest; 31 import org.apache.directory.api.ldap.model.message.ExtendedRequest; 32 import org.apache.directory.api.ldap.model.message.ModifyDnRequest; 33 import org.apache.directory.api.ldap.model.message.ModifyRequest; 34 import org.apache.directory.api.ldap.model.message.SearchRequest; 35 import org.apache.directory.api.ldap.model.message.SearchScope; 36 import org.apache.directory.api.ldap.model.name.Dn; 37 import org.apache.directory.ldap.client.api.future.AddFuture; 38 import org.apache.directory.ldap.client.api.future.BindFuture; 39 import org.apache.directory.ldap.client.api.future.CompareFuture; 40 import org.apache.directory.ldap.client.api.future.DeleteFuture; 41 import org.apache.directory.ldap.client.api.future.ExtendedFuture; 42 import org.apache.directory.ldap.client.api.future.ModifyDnFuture; 43 import org.apache.directory.ldap.client.api.future.ModifyFuture; 44 import org.apache.directory.ldap.client.api.future.SearchFuture; 45 46 47 /** 48 * Root interface for all asynchronous LDAP connections. 49 * 50 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> 51 */ 52 public interface LdapAsyncConnection extends LdapConnection 53 { 54 55 /** 56 * Add an entry to the server asynchronously. This is a non blocking add : 57 * the user has to get for the response from the returned Future. 58 * 59 * @param entry The entry to add 60 * @return the add operation's future 61 * @throws LdapException if some error occurred 62 */ 63 AddFuture addAsync( Entry entry ) throws LdapException; 64 65 66 /** 67 * Add an entry present in the AddRequest to the server. 68 * 69 * @param addRequest the request object containing an entry and controls(if any) 70 * @return the add operation's future 71 * @throws LdapException if some error occurred 72 */ 73 AddFuture addAsync( AddRequest addRequest ) throws LdapException; 74 75 76 /** 77 * Asynchronous Bind on a server, using the LdapConnectionConfig informations. 78 * 79 * @return the bind operation's future 80 * @throws LdapException if some error occurred 81 * @throws IOException if some IO error occurred 82 */ 83 BindFuture bindAsync() throws LdapException, IOException; 84 85 86 /** 87 * Anonymous asynchronous Bind on a server. 88 * 89 * @return the bind operation's future 90 * @throws LdapException if some error occurred 91 * @throws IOException if some IO error occurred 92 */ 93 BindFuture anonymousBindAsync() throws LdapException, IOException; 94 95 96 /** 97 * Simple asynchronous Bind on a server. 98 * 99 * @param name The name we use to authenticate the user, it must be a valid Dn 100 * @param credentials The password, it can't be null 101 * @return the bind operation's future 102 * @throws LdapException if some error occurred 103 * @throws IOException if some IO error occurred 104 */ 105 BindFuture bindAsync( String name, String credentials ) throws LdapException, IOException; 106 107 108 /** 109 * Simple asynchronous Bind on a server. 110 * 111 * @param name The name we use to authenticate the user, it must be a valid Dn 112 * @param credentials The password, it can't be null 113 * @return the bind operation's future 114 * @throws LdapException if some error occurred 115 * @throws IOException if some IO error occurred 116 */ 117 BindFuture bindAsync( Dn name, String credentials ) throws LdapException, IOException; 118 119 120 /** 121 * Do an asynchronous bind, based on a BindRequest. 122 * 123 * @param bindRequest The BindRequest to send 124 * @return the bind operation's future 125 * @throws LdapException if some error occurred 126 * @throws IOException if some IO error occurred 127 */ 128 BindFuture bindAsync( BindRequest bindRequest ) throws LdapException, IOException; 129 130 131 /** 132 * Do an asynchronous search, on the base object, using the given filter. The 133 * SearchRequest parameters default to : 134 * <pre> 135 * Scope : ONE 136 * DerefAlias : ALWAYS 137 * SizeLimit : none 138 * TimeLimit : none 139 * TypesOnly : false 140 * Attributes : all the user's attributes. 141 * This method is blocking. 142 * </pre> 143 * 144 * @param baseDn The base for the search, it must be a valid Dn, and can't be emtpy 145 * @param filter The filter to use for this search, it can't be empty 146 * @param scope The search scope : OBJECT, ONELEVEL or SUBTREE 147 * @param attributes The attributes for this search 148 * @return the search operation's future 149 * @throws org.apache.directory.api.ldap.model.exception.LdapException if some error occurred 150 */ 151 SearchFuture searchAsync( String baseDn, String filter, SearchScope scope, String... attributes ) 152 throws LdapException; 153 154 155 /** 156 * Do an asynchronous search, on the base object, using the given filter. The 157 * SearchRequest parameters default to : 158 * <pre> 159 * Scope : ONE 160 * DerefAlias : ALWAYS 161 * SizeLimit : none 162 * TimeLimit : none 163 * TypesOnly : false 164 * Attributes : all the user's attributes. 165 * This method is blocking. 166 * </pre> 167 * 168 * @param baseDn The base for the search, it must be a valid Dn, and can't be empty 169 * @param filter The filter to use for this search, it can't be empty 170 * @param scope The search scope : OBJECT, ONELEVEL or SUBTREE 171 * @param attributes The attributes for this search 172 * @return the search operation's future 173 * @throws LdapException if some error occurred 174 */ 175 SearchFuture searchAsync( Dn baseDn, String filter, SearchScope scope, String... attributes ) 176 throws LdapException; 177 178 179 /** 180 * Do a search, on the base object, using the given filter. The 181 * SearchRequest parameters default to : 182 * <pre> 183 * Scope : ONE 184 * DerefAlias : ALWAYS 185 * SizeLimit : none 186 * TimeLimit : none 187 * TypesOnly : false 188 * Attributes : all the user's attributes. 189 * This method is blocking. 190 * </pre> 191 * 192 * @param searchRequest The search request to send to the server 193 * @return the search operation's future 194 * @throws LdapException if some error occurred 195 */ 196 SearchFuture searchAsync( SearchRequest searchRequest ) throws LdapException; 197 198 199 /** 200 * Performs an asynchronous modify operation based on the modifications present in 201 * the ModifyRequest. 202 * 203 * @param modRequest the request for modify operation 204 * @return the modify operation's future 205 * @throws LdapException in case of modify operation failure or timeout happens 206 */ 207 ModifyFuture modifyAsync( ModifyRequest modRequest ) throws LdapException; 208 209 210 /** 211 * Performs the modifyDn operation based on the given ModifyDnRequest. 212 * 213 * @param modDnRequest the request 214 * @return modifyDn operation's future 215 * @throws LdapException if some error occurred 216 */ 217 ModifyDnFuture modifyDnAsync( ModifyDnRequest modDnRequest ) throws LdapException; 218 219 220 /** 221 * Performs an asynchronous delete operation based on the delete request object. 222 * 223 * @param delRequest the delete operation's request 224 * @return delete operation's future 225 * @throws LdapException If the Dn is not valid or if the deletion failed 226 */ 227 DeleteFuture deleteAsync( DeleteRequest delRequest ) throws LdapException; 228 229 230 /** 231 * Asynchronously compares an entry's attribute's value with that of the given value 232 * 233 * @param compareRequest the CompareRequest which contains the target Dn, attribute name and value 234 * @return compare operation's future 235 * @throws LdapException if some error occurred 236 */ 237 CompareFuture compareAsync( CompareRequest compareRequest ) throws LdapException; 238 239 240 /** 241 * Asynchronously requests the server to perform an extended operation based on the given request. 242 * 243 * @param extendedRequest the object containing the details of the extended operation to be performed 244 * @return extended operation's Future 245 * @throws LdapException if some error occurred 246 */ 247 ExtendedFuture extendedAsync( ExtendedRequest extendedRequest ) throws LdapException; 248 249 250 /** 251 * Configuration of LdapNetworkConnection 252 * 253 * @return the configuration of the LDAP connection 254 */ 255 LdapConnectionConfig getConfig(); 256 }