001/* 002 * The contents of this file are subject to the terms of the Common Development and 003 * Distribution License (the License). You may not use this file except in compliance with the 004 * License. 005 * 006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the 007 * specific language governing permission and limitations under the License. 008 * 009 * When distributing Covered Software, include this CDDL Header Notice in each file and include 010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL 011 * Header, with the fields enclosed by brackets [] replaced by your own identifying 012 * information: "Portions Copyright [year] [name of copyright owner]". 013 * 014 * Copyright 2009-2010 Sun Microsystems, Inc. 015 * Portions Copyright 2011-2014 ForgeRock AS. 016 */ 017 018package org.forgerock.opendj.ldap; 019 020import java.io.Closeable; 021 022import org.forgerock.util.promise.Promise; 023 024/** 025 * A connection factory provides an interface for obtaining a connection to a 026 * Directory Server. Connection factories can be used to wrap other connection 027 * factories in order to provide enhanced capabilities in a manner which is 028 * transparent to the application. For example: 029 * <ul> 030 * <li>Connection pooling 031 * <li>Load balancing 032 * <li>Keep alive 033 * <li>Transactional connections 034 * <li>Connections to LDIF files 035 * <li>Data transformations 036 * <li>Logging connections 037 * <li>Read-only connections 038 * <li>Pre-authenticated connections 039 * <li>Recording connections, with primitive roll-back functionality 040 * </ul> 041 * An application typically obtains a connection from a connection factory, 042 * performs one or more operations, and then closes the connection. Applications 043 * should aim to close connections as soon as possible in order to avoid 044 * resource contention. 045 */ 046public interface ConnectionFactory extends Closeable { 047 048 /** 049 * Releases any resources associated with this connection factory. Depending 050 * on the implementation a factory may: 051 * <ul> 052 * <li>do nothing 053 * <li>close underlying connection factories (e.g. load-balancers) 054 * <li>close pooled connections (e.g. connection pools) 055 * <li>shutdown IO event service and related thread pools (e.g. Grizzly). 056 * </ul> 057 * Calling {@code close} on a connection factory which is already closed has 058 * no effect. 059 * <p> 060 * Applications should avoid closing connection factories while there are 061 * remaining active connections in use or connection attempts in progress. 062 * 063 * @see Connections#uncloseable(ConnectionFactory) 064 */ 065 @Override 066 void close(); 067 068 /** 069 * Asynchronously obtains a connection to the Directory Server associated 070 * with this connection factory. The returned {@code Promise} can be used to 071 * retrieve the completed connection. 072 * 073 * @return A promise which can be used to retrieve the connection. 074 */ 075 Promise<Connection, LdapException> getConnectionAsync(); 076 077 /** 078 * Returns a connection to the Directory Server associated with this 079 * connection factory. The connection returned by this method can be used 080 * immediately. 081 * <p> 082 * If the calling thread is interrupted while waiting for the connection 083 * attempt to complete then the calling thread unblock and throw a 084 * {@link CancelledResultException} whose cause is the underlying 085 * {@link InterruptedException}. 086 * 087 * @return A connection to the Directory Server associated with this 088 * connection factory. 089 * @throws LdapException 090 * If the connection request failed for some reason. 091 */ 092 Connection getConnection() throws LdapException; 093}