changeset 13059:67d91e7479c1

8136496: Add Connection.begin/endRequest Reviewed-by: joehw, rriggs, psandoz
author lancea
date Thu, 05 Nov 2015 10:37:08 -0500
parents 20ccac7e0705
children a16ce5acb643
files src/java.sql/share/classes/java/sql/Connection.java src/java.sql/share/classes/javax/sql/PooledConnection.java
diffstat 2 files changed, 117 insertions(+), 3 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.sql/share/classes/java/sql/Connection.java	Thu Nov 05 10:54:05 2015 +0100
+++ b/src/java.sql/share/classes/java/sql/Connection.java	Thu Nov 05 10:37:08 2015 -0500
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2015, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -1482,4 +1482,109 @@
      * @since 1.7
      */
     int getNetworkTimeout() throws SQLException;
+
+    // JDBC 4.3
+
+     /**
+     * Hints to the driver that a request, an independent unit of work, is beginning
+     * on this connection. Each request is independent of all other requests
+     * with regard to state local to the connection either on the client or the
+     * server. Work done between {@code beginRequest}, {@code endRequest}
+     * pairs does not depend on any other work done on the connection either as
+     * part of another request or outside of any request. A request may include multiple
+     * transactions. There may be dependencies on committed database state as
+     * that is not local to the connection.
+     * <p>
+     * Local state is defined as any state associated with a Connection that is
+     * local to the current Connection either in the client or the database that
+     * is not transparently reproducible.
+     * <p>
+     * Calls to {@code beginRequest} and {@code endRequest}  are not nested.
+     * Multiple calls to {@code beginRequest} without an intervening call
+     * to {@code endRequest} is not an error. The first {@code beginRequest} call
+     * marks the start of the request and subsequent calls are treated as
+     * a no-op
+     * <p>
+     * Use of {@code beginRequest} and {@code endRequest} is optional, vendor
+     * specific and should largely be transparent. In particular
+     * implementations may detect conditions that indicate dependence on
+     * other work such as an open transaction. It is recommended though not
+     * required that implementations throw a {@code SQLException} if there is an active
+     * transaction and {@code beginRequest} is called.
+     * Using these methods may improve performance or provide other benefits.
+     * Consult your vendors documentation for additional information.
+     * <p>
+     * It is recommended to
+     * enclose each unit of work in {@code beginRequest}, {@code endRequest}
+     * pairs such that there is no open transaction at the beginning or end of
+     * the request and no dependency on local state that crosses request
+     * boundaries. Committed database state is not local.
+     *
+     * @implSpec
+     * The default implementation is a no-op.
+     * <p>
+     * @apiNote
+     * This method is to be used by Connection pooling managers.
+     * <p>
+     * The pooling manager should call {@code beginRequest} on the underlying connection
+     * prior to returning a connection to the caller.
+     * <p>
+     * The pooling manager does not need to call {@code beginRequest} if:
+     * <ul>
+     * <li>The connection pool caches {@code PooledConnection} objects</li>
+     * <li>Returns a logical connection handle when {@code getConnection} is
+     * called by the application</li>
+     * <li>The pool manager calls {@code Connection.close} on the logical connection handle
+     * prior to returning the {@code PooledConnection} back to the cache</li>
+     * </ul>
+     * @throws SQLException if an error occurs
+     * @since 1.9
+     * @see endRequest
+     * @see PooledConnection
+     */
+    default void beginRequest() throws SQLException {
+       // Default method takes no action
+    }
+
+    /**
+     * Hints to the driver that a request, an independent unit of work,
+     * has completed. Calls to {@code beginRequest}
+     * and {@code endRequest} are not nested. Multiple
+     * calls to {@code endRequest} without an intervening call to {@code beginRequest}
+     * is not an error. The first {@code endRequest} call
+     * marks the request completed and subsequent calls are treated as
+     * a no-op. If {@code endRequest} is called without an initial call to
+     * {@code beginRequest} is a no-op.
+     *<p>
+     * The exact behavior of this method is vendor specific. In particular
+     * implementations may detect conditions that indicate dependence on
+     * other work such as an open transaction. It is recommended though not
+     * required that implementations throw a {@code SQLException} if there is an active
+     * transaction and {@code endRequest} is called.
+     *
+     * @implSpec
+     * The default implementation is a no-op.
+     * @apiNote
+     *
+     * This method is to be used by Connection pooling managers.
+     * <p>
+     * The pooling manager should call {@code endRequest} on the underlying connection
+     * when the applications returns the connection back to the connection pool.
+     * <p<
+     * The pooling manager does not need to call {@code endRequest} if:
+     * <ul>
+     * <li>The connection pool caches {@code PooledConnection} objects</li>
+     * <li>Returns a logical connection handle when {@code getConnection} is
+     * called by the application</li>
+     * <li>The pool manager calls {@code Connection.close} on the logical connection handle
+     * prior to returning the {@code PooledConnection} back to the cache</li>
+     * </ul>
+     * @throws SQLException if an error occurs
+     * @since 1.9
+     * @see beginRequest
+     * @see PooledConnection
+     */
+    default void endRequest() throws SQLException {
+            // Default method takes no action
+    }
 }
--- a/src/java.sql/share/classes/javax/sql/PooledConnection.java	Thu Nov 05 10:54:05 2015 +0100
+++ b/src/java.sql/share/classes/javax/sql/PooledConnection.java	Thu Nov 05 10:37:08 2015 -0500
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2015, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -66,7 +66,16 @@
  * <code>PooledConnection</code> object to the pool of connections so that
  * it can be used again.  Thus, when an application closes its connection,
  * the underlying physical connection is recycled rather than being closed.
- * <P>
+ * <p>
+ * If the connection pool manager wraps or provides a proxy to the logical
+ * handle returned from a call to {@code PoolConnection.getConnection}, the pool
+ * manager must do
+ * one of the following when the application calls {@code Connection.close}:
+ * <ul>
+ * <li>call {@code endRequest} on the logical {@code Connection} handle
+ * <li>call {@code close} on the logical {@code Connection} handle
+ * </ul>
+ * <p>
  * The physical connection is not closed until the connection pool manager
  * calls the <code>PooledConnection</code> method <code>close</code>.
  * This method is generally called to have an orderly shutdown of the server or