View Javadoc
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 org.apache.directory.api.ldap.codec.api.LdapApiService;
24  import org.apache.directory.api.ldap.model.exception.LdapException;
25  
26  
27  /**
28   * A factory that creates {@link LdapConnection} objects using the provided
29   * {@link LdapConnectionConfig}.
30   * 
31   * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
32   */
33  public interface LdapConnectionFactory
34  {
35      /**
36       * Issues a bind request on the supplied connection using the name and
37       * credentials from the LdapConnectionConfg supplied to the constructor.
38       * Returns the connection supplied for chaining.
39       * 
40       * @param connection
41       *            The connection to bind with the configuration credentials.
42       * @return The connection supplied.
43       * @throws LdapException
44       *             If the bind fails.
45       */
46      public abstract LdapConnection bindConnection( LdapConnection connection ) throws LdapException;
47  
48  
49      /**
50       * Applies the following configuration settings from the
51       * LdapConnectionConfig to the supplied connection:
52       * <ul>
53       * <li>timeOut</li>
54       * <li>binaryAttributeDetector</li>
55       * </ul>
56       * This method is called by newLdapConnection, so there is no need to call
57       * this on a newly created connection. This should be used for pooling where
58       * the returned connection could have been modified by the borrower in order
59       * to ensure the next borrower gets a correctly configured connection.
60       * Returns the supplied connection for chaining.
61       * 
62       * @param connection
63       *            The connection to configure
64       * @return The supplied connection.
65       */
66      public abstract LdapConnection configureConnection( LdapConnection connection );
67  
68  
69      /**
70       * Returns the LdapApiService instance used by this factory.
71       *
72       * @return The LdapApiService instance used by this factory
73       */
74      public LdapApiService getLdapApiService();
75  
76  
77      /**
78       * Returns a newly created, configured, and authenticated connection. This
79       * method should be used by a connection pool to manufacture the pooled
80       * instances.
81       * 
82       * @return A newly created, configured, and authenticated LdapConnection.
83       * @throws LdapException
84       */
85      public abstract LdapConnection newLdapConnection() throws LdapException;
86      
87      
88      /**
89       * Returns a newly created connection, that has not been bound (bind) that
90       * otherwise respects LdapConnectionConfig supplied to the constructor. This
91       * is useful for authentication purposes where the consumer will use a bind
92       * operation.
93       * 
94       * @return A newly created and configured LdapConnection.
95       */
96      public abstract LdapConnection newUnboundLdapConnection();
97  }