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.ldap.client.api; 021 022 023import java.io.IOException; 024 025import org.apache.directory.api.ldap.model.entry.Entry; 026import org.apache.directory.api.ldap.model.exception.LdapException; 027import org.apache.directory.api.ldap.model.message.AddRequest; 028import org.apache.directory.api.ldap.model.message.BindRequest; 029import org.apache.directory.api.ldap.model.message.CompareRequest; 030import org.apache.directory.api.ldap.model.message.DeleteRequest; 031import org.apache.directory.api.ldap.model.message.ExtendedRequest; 032import org.apache.directory.api.ldap.model.message.ModifyDnRequest; 033import org.apache.directory.api.ldap.model.message.ModifyRequest; 034import org.apache.directory.api.ldap.model.message.SearchRequest; 035import org.apache.directory.api.ldap.model.message.SearchScope; 036import org.apache.directory.api.ldap.model.name.Dn; 037import org.apache.directory.ldap.client.api.future.AddFuture; 038import org.apache.directory.ldap.client.api.future.BindFuture; 039import org.apache.directory.ldap.client.api.future.CompareFuture; 040import org.apache.directory.ldap.client.api.future.DeleteFuture; 041import org.apache.directory.ldap.client.api.future.ExtendedFuture; 042import org.apache.directory.ldap.client.api.future.ModifyDnFuture; 043import org.apache.directory.ldap.client.api.future.ModifyFuture; 044import org.apache.directory.ldap.client.api.future.SearchFuture; 045 046 047/** 048 * Root interface for all asynchronous LDAP connections. 049 * 050 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> 051 */ 052public interface LdapAsyncConnection extends LdapConnection 053{ 054 055 /** 056 * Add an entry to the server asynchronously. This is a non blocking add : 057 * the user has to get for the response from the returned Future. 058 * 059 * @param entry The entry to add 060 * @return the add operation's future 061 * @throws LdapException if some error occurred 062 */ 063 AddFuture addAsync( Entry entry ) throws LdapException; 064 065 066 /** 067 * Add an entry present in the AddRequest to the server. 068 * 069 * @param addRequest the request object containing an entry and controls(if any) 070 * @return the add operation's future 071 * @throws LdapException if some error occurred 072 */ 073 AddFuture addAsync( AddRequest addRequest ) throws LdapException; 074 075 076 /** 077 * Asynchronous Bind on a server, using the LdapConnectionConfig informations. 078 * 079 * @return the bind operation's future 080 * @throws LdapException if some error occurred 081 * @throws IOException if some IO error occurred 082 */ 083 BindFuture bindAsync() throws LdapException, IOException; 084 085 086 /** 087 * Anonymous asynchronous Bind on a server. 088 * 089 * @return the bind operation's future 090 * @throws LdapException if some error occurred 091 * @throws IOException if some IO error occurred 092 */ 093 BindFuture anonymousBindAsync() throws LdapException, IOException; 094 095 096 /** 097 * Simple asynchronous Bind on a server. 098 * 099 * @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}