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}