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 2011-2014 ForgeRock AS. 015 */ 016 017package org.forgerock.opendj.ldap; 018 019import org.forgerock.util.promise.Promise; 020 021/** 022 * A connection factory which maintains and re-uses a pool of connections. 023 * Connections obtained from a connection pool are returned to the connection 024 * pool when closed, although connection pool implementations may choose to 025 * physically close the connection if needed (e.g. in order to reduce the size 026 * of the pool). 027 * <p> 028 * When connection pools are no longer needed they must be explicitly closed in 029 * order to close any remaining pooled connections. 030 * <p> 031 * Since pooled connections are re-used, applications must use operations such 032 * as binds and StartTLS with extreme caution. 033 */ 034public interface ConnectionPool extends ConnectionFactory { 035 /** 036 * Releases any resources associated with this connection pool. Pooled 037 * connections will be permanently closed and this connection pool will no 038 * longer be available for use. 039 * <p> 040 * Attempts to use this connection pool after it has been closed will result 041 * in an {@code IllegalStateException}. 042 * <p> 043 * Calling {@code close} on a connection pool which is already closed has no 044 * effect. 045 */ 046 @Override 047 void close(); 048 049 /** 050 * Asynchronously obtains a connection from this connection pool, 051 * potentially opening a new connection if needed. 052 * <p> 053 * The returned {@code Promise} can be used to retrieve the pooled 054 * connection. 055 * <p> 056 * Closing the pooled connection will, depending on the connection pool 057 * implementation, return the connection to this pool without closing it. 058 * 059 * @return A promise which can be used to retrieve the pooled connection. 060 * @throws IllegalStateException 061 * If this connection pool has already been closed. 062 */ 063 @Override 064 Promise<Connection, LdapException> getConnectionAsync(); 065 066 /** 067 * Obtains a connection from this connection pool, potentially opening a new 068 * connection if needed. 069 * <p> 070 * Closing the pooled connection will, depending on the connection pool 071 * implementation, return the connection to this pool without closing it. 072 * 073 * @return A pooled connection. 074 * @throws LdapException 075 * If the connection request failed for some reason. 076 * @throws IllegalStateException 077 * If this connection pool has already been closed. 078 */ 079 @Override 080 Connection getConnection() throws LdapException; 081}