You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@aries.apache.org by ti...@apache.org on 2016/05/27 18:10:18 UTC
svn commit: r1745797 - in
/aries/trunk/tx-control/tx-control-api/src/main/java/org/osgi/service/transaction/control:
./ jdbc/ jpa/
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