[tx-control] Tidy up JavaDoc for Transaction Control API
git-svn-id: https://svn.apache.org/repos/asf/aries/trunk/tx-control@1745797 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/tx-control-api/src/main/java/org/osgi/service/transaction/control/LocalResource.java b/tx-control-api/src/main/java/org/osgi/service/transaction/control/LocalResource.java
index 1230df6..f1331fd 100644
--- a/tx-control-api/src/main/java/org/osgi/service/transaction/control/LocalResource.java
+++ b/tx-control-api/src/main/java/org/osgi/service/transaction/control/LocalResource.java
@@ -24,14 +24,14 @@
/**
* 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;
}
diff --git a/tx-control-api/src/main/java/org/osgi/service/transaction/control/ResourceProvider.java b/tx-control-api/src/main/java/org/osgi/service/transaction/control/ResourceProvider.java
index 7f1e164..dba8403 100644
--- a/tx-control-api/src/main/java/org/osgi/service/transaction/control/ResourceProvider.java
+++ b/tx-control-api/src/main/java/org/osgi/service/transaction/control/ResourceProvider.java
@@ -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
*/
diff --git a/tx-control-api/src/main/java/org/osgi/service/transaction/control/ScopedWorkException.java b/tx-control-api/src/main/java/org/osgi/service/transaction/control/ScopedWorkException.java
index 9436eda..8589269 100644
--- a/tx-control-api/src/main/java/org/osgi/service/transaction/control/ScopedWorkException.java
+++ b/tx-control-api/src/main/java/org/osgi/service/transaction/control/ScopedWorkException.java
@@ -65,7 +65,7 @@
}
/**
- * 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 @@
* }
* </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 <T></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 @@
}
/**
- * 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 @@
* }
* </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 <A></li>
+ * <li>The cause of this exception as the type <B></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 @@
* 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 <A></li>
+ * <li>The cause of this exception as the type <B></li>
+ * <li>The cause of this exception as the type <C></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 @@
* 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 <A></li>
+ * <li>The cause of this exception as the type <B></li>
+ * <li>The cause of this exception as the type <C></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) {
diff --git a/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionBuilder.java b/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionBuilder.java
index df35e70..9523fc2 100644
--- a/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionBuilder.java
+++ b/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionBuilder.java
@@ -63,8 +63,8 @@
* </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
diff --git a/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionControl.java b/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionControl.java
index 012d9f1..7545e39 100644
--- a/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionControl.java
+++ b/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionControl.java
@@ -24,7 +24,6 @@
/**
* 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();
diff --git a/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionStarter.java b/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionStarter.java
index c06ff96..6a28020 100644
--- a/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionStarter.java
+++ b/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionStarter.java
@@ -27,7 +27,7 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
<T> T supports(Callable<T> work)
throws TransactionException, ScopedWorkException;
-
}
diff --git a/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionStatus.java b/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionStatus.java
index 84a506b..b0b37de 100644
--- a/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionStatus.java
+++ b/tx-control-api/src/main/java/org/osgi/service/transaction/control/TransactionStatus.java
@@ -20,7 +20,7 @@
*
* 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) >= 0;
*
*/
public enum TransactionStatus {
diff --git a/tx-control-api/src/main/java/org/osgi/service/transaction/control/jdbc/JDBCConnectionProviderFactory.java b/tx-control-api/src/main/java/org/osgi/service/transaction/control/jdbc/JDBCConnectionProviderFactory.java
index 7b169f9..89321d1 100644
--- a/tx-control-api/src/main/java/org/osgi/service/transaction/control/jdbc/JDBCConnectionProviderFactory.java
+++ b/tx-control-api/src/main/java/org/osgi/service/transaction/control/jdbc/JDBCConnectionProviderFactory.java
@@ -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 @@
* 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 @@
* 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 @@
* 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 @@
* 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
diff --git a/tx-control-api/src/main/java/org/osgi/service/transaction/control/jpa/JPAEntityManagerProviderFactory.java b/tx-control-api/src/main/java/org/osgi/service/transaction/control/jpa/JPAEntityManagerProviderFactory.java
index 5a5fa89..a50eaab 100644
--- a/tx-control-api/src/main/java/org/osgi/service/transaction/control/jpa/JPAEntityManagerProviderFactory.java
+++ b/tx-control-api/src/main/java/org/osgi/service/transaction/control/jpa/JPAEntityManagerProviderFactory.java
@@ -61,7 +61,7 @@
* 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 @@
* 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
