# HG changeset patch # User lancea # Date 1446737828 18000 # Node ID f42f1ed3be7f62de1e2555e4a6db3d5ada7c40e7 # Parent eb067bcd9414c6133f78bbd4e8d66d5bcf6611e6 8136496: Add Connection.begin/endRequest Reviewed-by: joehw, rriggs, psandoz diff -r eb067bcd9414 -r f42f1ed3be7f jdk/src/java.sql/share/classes/java/sql/Connection.java --- a/jdk/src/java.sql/share/classes/java/sql/Connection.java Thu Nov 05 10:54:05 2015 +0100 +++ b/jdk/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. + *

+ * 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. + *

+ * 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 + *

+ * 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. + *

+ * 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. + *

+ * @apiNote + * This method is to be used by Connection pooling managers. + *

+ * The pooling manager should call {@code beginRequest} on the underlying connection + * prior to returning a connection to the caller. + *

+ * The pooling manager does not need to call {@code beginRequest} if: + *

+ * @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. + *

+ * 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. + *

+ * The pooling manager should call {@code endRequest} on the underlying connection + * when the applications returns the connection back to the connection pool. + * + *

  • The connection pool caches {@code PooledConnection} objects
    • + *
  • Returns a logical connection handle when {@code getConnection} is + * called by the application
    • + *
  • The pool manager calls {@code Connection.close} on the logical connection handle + * prior to returning the {@code PooledConnection} back to the cache
    • + * + * @throws SQLException if an error occurs + * @since 1.9 + * @see beginRequest + * @see PooledConnection + */ + default void endRequest() throws SQLException { + // Default method takes no action + } } diff -r eb067bcd9414 -r f42f1ed3be7f jdk/src/java.sql/share/classes/javax/sql/PooledConnection.java --- a/jdk/src/java.sql/share/classes/javax/sql/PooledConnection.java Thu Nov 05 10:54:05 2015 +0100 +++ b/jdk/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 @@ * PooledConnection 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. - *

    + *

    + * 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}: + *

    + *

    * The physical connection is not closed until the connection pool manager * calls the PooledConnection method close. * This method is generally called to have an orderly shutdown of the server or