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
<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 @@ 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
<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 @@ 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
<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 @@ 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
<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) {
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) >= 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
