001/* 002 * CDDL HEADER START 003 * 004 * The contents of this file are subject to the terms of the 005 * Common Development and Distribution License, Version 1.0 only 006 * (the "License"). You may not use this file except in compliance 007 * with the License. 008 * 009 * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt 010 * or http://forgerock.org/license/CDDLv1.0.html. 011 * See the License for the specific language governing permissions 012 * and limitations under the License. 013 * 014 * When distributing Covered Code, include this CDDL HEADER in each 015 * file and include the License file at legal-notices/CDDLv1_0.txt. 016 * If applicable, add the following below this CDDL HEADER, with the 017 * fields enclosed by brackets "[]" replaced with your own identifying 018 * information: 019 * Portions Copyright [yyyy] [name of copyright owner] 020 * 021 * CDDL HEADER END 022 * 023 * 024 * Copyright 2011-2014 ForgeRock AS 025 */ 026 027package org.forgerock.opendj.ldap; 028 029import org.forgerock.util.promise.Promise; 030 031/** 032 * A connection factory which maintains and re-uses a pool of connections. 033 * Connections obtained from a connection pool are returned to the connection 034 * pool when closed, although connection pool implementations may choose to 035 * physically close the connection if needed (e.g. in order to reduce the size 036 * of the pool). 037 * <p> 038 * When connection pools are no longer needed they must be explicitly closed in 039 * order to close any remaining pooled connections. 040 * <p> 041 * Since pooled connections are re-used, applications must use operations such 042 * as binds and StartTLS with extreme caution. 043 */ 044public interface ConnectionPool extends ConnectionFactory { 045 /** 046 * Releases any resources associated with this connection pool. Pooled 047 * connections will be permanently closed and this connection pool will no 048 * longer be available for use. 049 * <p> 050 * Attempts to use this connection pool after it has been closed will result 051 * in an {@code IllegalStateException}. 052 * <p> 053 * Calling {@code close} on a connection pool which is already closed has no 054 * effect. 055 */ 056 @Override 057 void close(); 058 059 /** 060 * Asynchronously obtains a connection from this connection pool, 061 * potentially opening a new connection if needed. 062 * <p> 063 * The returned {@code Promise} can be used to retrieve the pooled 064 * connection. 065 * <p> 066 * Closing the pooled connection will, depending on the connection pool 067 * implementation, return the connection to this pool without closing it. 068 * 069 * @return A promise which can be used to retrieve the pooled connection. 070 * @throws IllegalStateException 071 * If this connection pool has already been closed. 072 */ 073 @Override 074 Promise<Connection, LdapException> getConnectionAsync(); 075 076 /** 077 * Obtains a connection from this connection pool, potentially opening a new 078 * connection if needed. 079 * <p> 080 * Closing the pooled connection will, depending on the connection pool 081 * implementation, return the connection to this pool without closing it. 082 * 083 * @return A pooled connection. 084 * @throws LdapException 085 * If the connection request failed for some reason. 086 * @throws IllegalStateException 087 * If this connection pool has already been closed. 088 */ 089 @Override 090 Connection getConnection() throws LdapException; 091}