aries-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From timothyjw...@apache.org
Subject svn commit: r1745797 - in /aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control: ./ jdbc/ jpa/
Date Fri, 27 May 2016 18:10:18 GMT
Author: timothyjward
Date: Fri May 27 18:10:18 2016
New Revision: 1745797

URL: http://svn.apache.org/viewvc?rev=1745797&view=rev
Log:
[tx-control] Tidy up JavaDoc for Transaction Control API

Modified:
    aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/LocalResource.java
    aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/ResourceProvider.java
    aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/ScopedWorkException.java
    aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionBuilder.java
    aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionControl.java
    aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionStarter.java
    aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionStatus.java
    aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/jdbc/JDBCConnectionProviderFactory.java
    aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/jpa/JPAEntityManagerProviderFactory.java

Modified: aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/LocalResource.java
URL: http://svn.apache.org/viewvc/aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/LocalResource.java?rev=1745797&r1=1745796&r2=1745797&view=diff
==============================================================================
--- aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/LocalResource.java
(original)
+++ aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/LocalResource.java
Fri May 27 18:10:18 2016
@@ -24,14 +24,14 @@ public interface LocalResource {
 	/**
 	 * Commit the resource
 	 * 
-	 * @throws TransactionException
+	 * @throws TransactionException if an error occurs while committing,
 	 */
 	void commit() throws TransactionException;
 
 	/**
 	 * Roll back the resource
 	 * 
-	 * @throws TransactionException
+	 * @throws TransactionException if an error occurs while rolling back
 	 */
 	void rollback() throws TransactionException;
 }

Modified: aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/ResourceProvider.java
URL: http://svn.apache.org/viewvc/aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/ResourceProvider.java?rev=1745797&r1=1745796&r2=1745797&view=diff
==============================================================================
--- aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/ResourceProvider.java
(original)
+++ aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/ResourceProvider.java
Fri May 27 18:10:18 2016
@@ -16,19 +16,20 @@
 package org.osgi.service.transaction.control;
 
 /**
- * A resource provider is used to provide a transactional resource to the
+ * A resource provider is used to provide a scoped resource to the
  * application
  * 
- * @param <T>
+ * @param <T> The type of the scoped resource created by this {@link ResourceProvider}
  */
 public interface ResourceProvider<T> {
 
 	/**
-	 * Get a resource which will associate with the current transaction context
-	 * when used
+	 * Get a resource which will automatically associate with the current 
+	 * scope
 	 * 
-	 * @param txControl
-	 * @return The resource which will participate in the current transaction
+	 * @param txControl The transaction control service to associate with
+	 * @return The resource which will participate in the scopes started
+	 *         by the provided {@link TransactionControl}
 	 * @throws TransactionException if the resource cannot be registered with
 	 *             the transaction
 	 */

Modified: aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/ScopedWorkException.java
URL: http://svn.apache.org/viewvc/aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/ScopedWorkException.java?rev=1745797&r1=1745796&r2=1745797&view=diff
==============================================================================
--- aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/ScopedWorkException.java
(original)
+++ aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/ScopedWorkException.java
Fri May 27 18:10:18 2016
@@ -65,7 +65,7 @@ public class ScopedWorkException extends
 	}
 
 	/**
-	 * Throws the cause of this Exception as a RuntimeException the supplied
+	 * Throws the cause of this Exception as a RuntimeException, or as the supplied
 	 * Exception type.
 	 * <p>
 	 * Usage is of the form:
@@ -80,11 +80,19 @@ public class ScopedWorkException extends
 	 * }
 	 * </pre>
 	 * 
-	 * @param throwable
-	 * @return This method will always throw an exception
-	 * @throws T
+	 * @param throwable The exception type to throw
+	 *        
+	 * @return This method will always throw an exception, either:
+	 *           <ul>
+	 *             <li>The cause of this exception as the type &lt;T&gt;</li>
+	 *             <li>The cause of this exception as a runtime exception</li>
+	 *             <li>An IllegalArgumentException with its cause set to <code>this</code></li>
+	 *           </ul>
+	 * 
+	 * @throws T the type of exception to be thrown
+	 * @throws IllegalArgumentException if the cause is not a {@link RuntimeException} or of
type T
 	 */
-	public <T extends Throwable> T as(Class<T> throwable) throws T {
+	public <T extends Throwable> T as(Class<T> throwable) throws T, IllegalArgumentException
{
 		Throwable t = getCause();
 
 		if (t instanceof RuntimeException) {
@@ -100,7 +108,7 @@ public class ScopedWorkException extends
 	}
 
 	/**
-	 * Throws the cause of this Exception as a RuntimeException or one of the
+	 * Throws the cause of this Exception as a RuntimeException, or as one of the
 	 * supplied Exception types.
 	 * <p>
 	 * Usage is of the form:
@@ -115,14 +123,21 @@ public class ScopedWorkException extends
 	 * }
 	 * </pre>
 	 * 
-	 * @param a
-	 * @param b
-	 * @return This method will always throw an exception
-	 * @throws A
-	 * @throws B
+	 * @param a The first possible exception type to throw
+	 * @param b The second possible exception type to throw
+	 * @return This method will always throw an exception, either:
+	 *           <ul>
+	 *             <li>The cause of this exception as the type &lt;A&gt;</li>
+	 *             <li>The cause of this exception as the type &lt;B&gt;</li>
+	 *             <li>The cause of this exception as a runtime exception</li>
+	 *             <li>An IllegalArgumentException with its cause set to <code>this</code></li>
+	 *           </ul>
+	 * @throws A The first possible exception type to throw
+	 * @throws B The second possible exception type to throw
+	 * @throws IllegalArgumentException if the cause is not a {@link RuntimeException} or of
type A or B
 	 */
 	public <A extends Throwable, B extends Throwable> RuntimeException asOneOf(
-			Class<A> a, Class<B> b) throws A, B {
+			Class<A> a, Class<B> b) throws A, B, IllegalArgumentException {
 		Throwable t = getCause();
 
 		if (t instanceof RuntimeException) {
@@ -143,15 +158,24 @@ public class ScopedWorkException extends
 	 * supplied Exception types.
 	 * 
 	 * @see #asOneOf(Class, Class)
-	 * @param a
-	 * @param b
-	 * @param c
-	 * @return This method will always throw an exception
-	 * @throws A
-	 * @throws B
+	 * @param a The first possible exception type to throw
+	 * @param b The second possible exception type to throw
+	 * @param c The third possible exception type to throw
+	 * @return This method will always throw an exception, either:
+	 *           <ul>
+	 *             <li>The cause of this exception as the type &lt;A&gt;</li>
+	 *             <li>The cause of this exception as the type &lt;B&gt;</li>
+	 *             <li>The cause of this exception as the type &lt;C&gt;</li>
+	 *             <li>The cause of this exception as a runtime exception</li>
+	 *             <li>An IllegalArgumentException with its cause set to <code>this</code></li>
+	 *           </ul>
+	 * @throws A The first possible exception type to throw
+	 * @throws B The second possible exception type to throw
+	 * @throws C The third possible exception type to throw
+	 * @throws IllegalArgumentException if the cause is not a {@link RuntimeException} or one
of types A, B or C
 	 */
 	public <A extends Throwable, B extends Throwable, C extends Throwable> RuntimeException
asOneOf(
-			Class<A> a, Class<B> b, Class<C> c) throws A, B, C {
+			Class<A> a, Class<B> b, Class<C> c) throws A, B, C, IllegalArgumentException
{
 		Throwable t = getCause();
 
 		if (t instanceof RuntimeException) {
@@ -173,18 +197,26 @@ public class ScopedWorkException extends
 	 * supplied Exception types.
 	 * 
 	 * @see #asOneOf(Class, Class)
-	 * @param a
-	 * @param b
-	 * @param c
-	 * @param d
-	 * @return This method will always throw an exception
-	 * @throws A
-	 * @throws B
-	 * @throws C
-	 * @throws D
+	 * @param a The first possible exception type to throw
+	 * @param b The second possible exception type to throw
+	 * @param c The third possible exception type to throw
+	 * @param d The fourth possible exception type to throw
+	 * @return This method will always throw an exception, either:
+	 *           <ul>
+	 *             <li>The cause of this exception as the type &lt;A&gt;</li>
+	 *             <li>The cause of this exception as the type &lt;B&gt;</li>
+	 *             <li>The cause of this exception as the type &lt;C&gt;</li>
+	 *             <li>The cause of this exception as a runtime exception</li>
+	 *             <li>An IllegalArgumentException with its cause set to <code>this</code></li>
+	 *           </ul>
+	 * @throws A The first possible exception type to throw
+	 * @throws B The second possible exception type to throw
+	 * @throws C The third possible exception type to throw
+	 * @throws D The fourth possible exception type to throw
+	 * @throws IllegalArgumentException if the cause is not a {@link RuntimeException} or one
of types A, B, C or D
 	 */
 	public <A extends Throwable, B extends Throwable, C extends Throwable, D extends Throwable>
RuntimeException asOneOf(
-			Class<A> a, Class<B> b, Class<C> c, Class<D> d) throws A, B, C,
D {
+			Class<A> a, Class<B> b, Class<C> c, Class<D> d) throws A, B, C,
D, IllegalArgumentException {
 		Throwable t = getCause();
 
 		if (t instanceof RuntimeException) {

Modified: aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionBuilder.java
URL: http://svn.apache.org/viewvc/aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionBuilder.java?rev=1745797&r1=1745796&r2=1745797&view=diff
==============================================================================
--- aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionBuilder.java
(original)
+++ aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionBuilder.java
Fri May 27 18:10:18 2016
@@ -63,8 +63,8 @@ public abstract class TransactionBuilder
 	 * </li>
 	 * </ul>
 	 * 
-	 * @param t
-	 * @param throwables The Exception types that should trigger rollback
+	 * @param t An exception type that should trigger rollback
+	 * @param throwables further exception types that should trigger rollback
 	 * @return this builder
 	 */
 	@SafeVarargs

Modified: aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionControl.java
URL: http://svn.apache.org/viewvc/aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionControl.java?rev=1745797&r1=1745796&r2=1745797&view=diff
==============================================================================
--- aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionControl.java
(original)
+++ aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionControl.java
Fri May 27 18:10:18 2016
@@ -24,7 +24,6 @@ public interface TransactionControl exte
 	/**
 	 * Build a transaction context to surround a piece of transactional work
 	 * 
-	 * @param propagation The transaction propagation to use
 	 * @return A builder to complete the creation of the transaction
 	 */
 	TransactionBuilder build();

Modified: aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionStarter.java
URL: http://svn.apache.org/viewvc/aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionStarter.java?rev=1745797&r1=1745796&r2=1745797&view=diff
==============================================================================
--- aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionStarter.java
(original)
+++ aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionStarter.java
Fri May 27 18:10:18 2016
@@ -27,7 +27,7 @@ public interface TransactionStarter {
 	 * transaction is active then it must be started and associated with the
 	 * work and then completed after the transactional work has finished.
 	 * 
-	 * @param work
+	 * @param work The work to execute
 	 * @return The value returned by the work
 	 * @throws TransactionException if there is an error starting or completing
 	 *             the transaction
@@ -47,7 +47,7 @@ public interface TransactionStarter {
 	 * completed the new transaction must also complete and any suspended
 	 * transaction be resumed.
 	 * 
-	 * @param work
+	 * @param work The work to execute
 	 * @return The value returned by the work
 	 * @throws TransactionException if there is an error starting or completing
 	 *             the transaction
@@ -70,7 +70,7 @@ public interface TransactionStarter {
 	 * completion callback to any registered functions. This function is
 	 * suitable for final cleanup, such as closing a connection
 	 * 
-	 * @param work
+	 * @param work The work to execute
 	 * @return The value returned by the work
 	 * @throws TransactionException if there is an error starting or completing
 	 *             the transaction
@@ -92,7 +92,7 @@ public interface TransactionStarter {
 	 * completion callback to any registered functions. This function is
 	 * suitable for final cleanup, such as closing a connection
 	 * 
-	 * @param work
+	 * @param work The work to execute
 	 * @return The value returned by the work
 	 * @throws TransactionException if there is an error starting or completing
 	 *             the transaction
@@ -102,5 +102,4 @@ public interface TransactionStarter {
 	<T> T supports(Callable<T> work)
 			throws TransactionException, ScopedWorkException;
 
-
 }

Modified: aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionStatus.java
URL: http://svn.apache.org/viewvc/aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionStatus.java?rev=1745797&r1=1745796&r2=1745797&view=diff
==============================================================================
--- aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionStatus.java
(original)
+++ aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionStatus.java
Fri May 27 18:10:18 2016
@@ -20,7 +20,7 @@ package org.osgi.service.transaction.con
  * 
  * A transaction may not enter all of the states in this enum, however it will always
  * traverse the enum in ascending order. In particular if the TransactionStatus is 
- * reported as X then it will never proceed into a state Y where X.compareTo(Y) >= 0;
+ * reported as X then it will never proceed into a state Y where X.compareTo(Y) &gt;=
0;
  *
  */
 public enum TransactionStatus {

Modified: aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/jdbc/JDBCConnectionProviderFactory.java
URL: http://svn.apache.org/viewvc/aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/jdbc/JDBCConnectionProviderFactory.java?rev=1745797&r1=1745796&r2=1745797&view=diff
==============================================================================
--- aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/jdbc/JDBCConnectionProviderFactory.java
(original)
+++ aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/jdbc/JDBCConnectionProviderFactory.java
Fri May 27 18:10:18 2016
@@ -15,6 +15,7 @@
  */
 package org.osgi.service.transaction.control.jdbc;
 
+import java.sql.Connection;
 import java.sql.Driver;
 import java.util.Map;
 import java.util.Properties;
@@ -90,7 +91,7 @@ public interface JDBCConnectionProviderF
 	 * Create a private {@link JDBCConnectionProvider} using a
 	 * DataSourceFactory.
 	 * 
-	 * @param dsf
+	 * @param dsf The {@link DataSourceFactory} that provides access to the database
 	 * @param jdbcProperties The properties to pass to the
 	 *            {@link DataSourceFactory} in order to create the underlying
 	 *            {@link DataSource}
@@ -106,7 +107,7 @@ public interface JDBCConnectionProviderF
 	 * Create a private {@link JDBCConnectionProvider} using an existing
 	 * {@link DataSource}.
 	 * 
-	 * @param ds
+	 * @param ds The {@link DataSource} that provides access to the database
 	 * @param resourceProviderProperties Configuration properties to pass to the
 	 *            JDBC Resource Provider runtime
 	 * @return A {@link JDBCConnectionProvider} that can be used in transactions
@@ -118,7 +119,7 @@ public interface JDBCConnectionProviderF
 	 * Create a private {@link JDBCConnectionProvider} using an existing
 	 * {@link Driver}.
 	 * 
-	 * @param driver
+	 * @param driver The {@link Driver} that provides access to the database
 	 * @param jdbcProperties The properties to pass to the {@link Driver} in
 	 *            order to create a {@link Connection}
 	 * @param resourceProviderProperties Configuration properties to pass to the
@@ -133,7 +134,7 @@ public interface JDBCConnectionProviderF
 	 * Create a private {@link JDBCConnectionProvider} using an existing
 	 * {@link XADataSource}.
 	 * 
-	 * @param ds
+	 * @param ds The {@link XADataSource} that provides access to the database
 	 * @param resourceProviderProperties Configuration properties to pass to the
 	 *            JDBC Resource Provider runtime
 	 * @return A {@link JDBCConnectionProvider} that can be used in transactions

Modified: aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/jpa/JPAEntityManagerProviderFactory.java
URL: http://svn.apache.org/viewvc/aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/jpa/JPAEntityManagerProviderFactory.java?rev=1745797&r1=1745796&r2=1745797&view=diff
==============================================================================
--- aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/jpa/JPAEntityManagerProviderFactory.java
(original)
+++ aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control/jpa/JPAEntityManagerProviderFactory.java
Fri May 27 18:10:18 2016
@@ -61,7 +61,7 @@ public interface JPAEntityManagerProvide
 	 * Create a private {@link JPAEntityManagerProvider} using an
 	 * {@link EntityManagerFactoryBuilder}
 	 * 
-	 * @param emfb
+	 * @param emfb The {@link EntityManagerFactoryBuilder} to create JPA resources with
 	 * @param jpaProperties The properties to pass to the
 	 *            {@link EntityManagerFactoryBuilder} in order to create the
 	 *            underlying {@link EntityManagerFactory} and
@@ -79,7 +79,7 @@ public interface JPAEntityManagerProvide
 	 * Create a private {@link JPAEntityManagerProvider} using an existing
 	 * {@link EntityManagerFactory}.
 	 * 
-	 * @param emf
+	 * @param emf The {@link EntityManagerFactory} to use in the {@link JPAEntityManagerProvider}
 	 * @param resourceProviderProperties Configuration properties to pass to the
 	 *            JDBC Resource Provider runtime
 	 * @return A {@link JPAEntityManagerProvider} that can be used in



Mime
View raw message