1 /*
2 * The contents of this file are subject to the terms of the Common Development and
3 * Distribution License (the License). You may not use this file except in compliance with the
4 * License.
5 *
6 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
7 * specific language governing permission and limitations under the License.
8 *
9 * When distributing Covered Software, include this CDDL Header Notice in each file and include
10 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
11 * Header, with the fields enclosed by brackets [] replaced by your own identifying
12 * information: "Portions Copyright [year] [name of copyright owner]".
13 *
14 * Copyright 2012-2015 ForgeRock AS.
15 */
16
17 package org.forgerock.json.resource;
18
19 import java.io.Closeable;
20
21 import org.forgerock.util.promise.Promise;
22
23 /**
24 * A connection factory provides an interface for obtaining a connection to a
25 * JSON resource provider. Connection factories can be used to wrap other
26 * connection factories in order to provide enhanced capabilities in a manner
27 * which is transparent to the application. For example:
28 * <ul>
29 * <li>Connection pooling
30 * <li>Load balancing
31 * <li>Keep alive
32 * <li>Logging connections
33 * <li>Read-only connections
34 * </ul>
35 * An application typically obtains a connection from a connection factory,
36 * performs one or more operations, and then closes the connection. Applications
37 * should aim to close connections as soon as possible in order to avoid
38 * resource contention.
39 */
40 public interface ConnectionFactory extends Closeable {
41
42 /**
43 * Releases any resources associated with this connection factory. Depending
44 * on the implementation a factory may:
45 * <ul>
46 * <li>do nothing
47 * <li>close underlying connection factories (e.g. load-balancers)
48 * <li>close pooled connections (e.g. connection pools)
49 * <li>shutdown IO event service and related thread pools (e.g. Grizzly).
50 * </ul>
51 * Calling {@code close} on a connection factory which is already closed has
52 * no effect.
53 * <p>
54 * Applications should avoid closing connection factories while there are
55 * remaining active connections in use or connection attempts in progress.
56 *
57 * @see Resources#uncloseable(ConnectionFactory)
58 */
59 @Override
60 void close();
61
62 /**
63 * Returns a connection to the JSON resource provider associated with this
64 * connection factory. The connection returned by this method can be used
65 * immediately.
66 *
67 * @return A connection to the JSON resource provider associated with this
68 * connection factory.
69 * @throws ResourceException
70 * If the connection request failed for some reason.
71 */
72 Connection getConnection() throws ResourceException;
73
74 /**
75 * Asynchronously obtains a connection to the JSON resource provider
76 * associated with this connection factory. The returned
77 * {@code FutureResult} can be used to retrieve the completed connection.
78 *
79 * @return A future which can be used to retrieve the connection.
80 */
81 Promise<Connection, ResourceException> getConnectionAsync();
82 }