[jboss-cvs] JBossAS SVN: r82194 - in projects/javaee/trunk/jboss-jca-api: src/main/javax/resource and 5 other directories.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Wed Dec 10 11:19:26 EST 2008
Author: jeff.zhang
Date: 2008-12-10 11:19:26 -0500 (Wed, 10 Dec 2008)
New Revision: 82194
Added:
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/Activation.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/AdministeredObject.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/AuthenticationMechanism.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConfigProperty.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConnectionDefinition.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConnectionDefinitions.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/Connector.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/SecurityPermission.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/TransactionSupport.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/DistributableWork.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/DistributableWorkManager.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/HintsWorkContext.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/SecurityWorkContext.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/TransactionWorkContext.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkContext.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkContextErrorCodes.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkContextLifecycleListener.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkContextProvider.java
Modified:
projects/javaee/trunk/jboss-jca-api/pom-jdk14.xml
projects/javaee/trunk/jboss-jca-api/pom.xml
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/NotSupportedException.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/Referenceable.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/ResourceException.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/Connection.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ConnectionFactory.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ConnectionMetaData.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ConnectionSpec.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/IndexedRecord.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/Interaction.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/InteractionSpec.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/LocalTransaction.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/MappedRecord.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/MessageListener.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/Record.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/RecordFactory.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ResourceAdapterMetaData.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ResourceWarning.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ResultSet.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ResultSetInfo.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/Streamable.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/package.html
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/package.html
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ActivationSpec.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ApplicationServerInternalException.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/BootstrapContext.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/CommException.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConnectionEvent.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConnectionEventListener.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConnectionManager.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConnectionRequestInfo.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/DissociatableManagedConnection.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/EISSystemException.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/IllegalStateException.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/InvalidPropertyException.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/LazyAssociatableConnectionManager.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/LazyEnlistableConnectionManager.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/LazyEnlistableManagedConnection.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/LocalTransaction.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/LocalTransactionException.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ManagedConnection.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ManagedConnectionFactory.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ManagedConnectionMetaData.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ResourceAdapter.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ResourceAdapterAssociation.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ResourceAdapterInternalException.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ResourceAllocationException.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/SecurityException.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/SharingViolationException.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/UnavailableException.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ValidatingManagedConnectionFactory.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/XATerminator.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/endpoint/MessageEndpoint.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/endpoint/MessageEndpointFactory.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/endpoint/package.html
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/package.html
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/security/GenericCredential.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/security/PasswordCredential.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/security/package.html
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/ExecutionContext.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/Work.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkAdapter.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkCompletedException.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkEvent.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkException.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkListener.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkManager.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkRejectedException.java
projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/package.html
Log:
[JBEE-8] add new JCA 1.6 api into javaee/trunk and remove 1.5 api, it based on JCA 1.6 pr-to-pub version and change *InflowContext to *WorkContext
Modified: projects/javaee/trunk/jboss-jca-api/pom-jdk14.xml
===================================================================
--- projects/javaee/trunk/jboss-jca-api/pom-jdk14.xml 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/pom-jdk14.xml 2008-12-10 16:19:26 UTC (rev 82194)
@@ -19,11 +19,11 @@
<modelVersion>4.0.0</modelVersion>
<groupId>org.jboss.javaee</groupId>
<artifactId>jboss-jca-api-jdk14</artifactId>
- <version>1.5-SNAPSHOT</version>
+ <version>1.6-SNAPSHOT</version>
<packaging>jar</packaging>
- <name>JBoss J2EE Connector Architecture 1.5 API</name>
+ <name>JBoss J2EE Connector Architecture 1.6 API</name>
<url>http://www.jboss.org</url>
- <description>The J2EE Connector Architecture 1.5 API classes</description>
+ <description>The J2EE Connector Architecture 1.6 API classes</description>
<build>
<outputDirectory>${outputDirectory}</outputDirectory>
<testOutputDirectory>${testOutputDirectory}</testOutputDirectory>
@@ -88,6 +88,11 @@
<artifactId>jboss-common-core-jdk14</artifactId>
<version>2.2.1-SNAPSHOT</version>
</dependency>
+ <dependency>
+ <groupId>org.jboss.javaee</groupId>
+ <artifactId>jboss-transaction-api</artifactId>
+ <version>1.0.1.GA</version>
+ </dependency>
</dependencies>
<properties>
Modified: projects/javaee/trunk/jboss-jca-api/pom.xml
===================================================================
--- projects/javaee/trunk/jboss-jca-api/pom.xml 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/pom.xml 2008-12-10 16:19:26 UTC (rev 82194)
@@ -8,16 +8,21 @@
<modelVersion>4.0.0</modelVersion>
<groupId>org.jboss.javaee</groupId>
<artifactId>jboss-jca-api</artifactId>
- <version>1.5.1-SNAPSHOT</version>
+ <version>1.6.0-SNAPSHOT</version>
<packaging>jar</packaging>
- <name>JBoss J2EE Connector Architecture 1.5 API</name>
+ <name>JBoss J2EE Connector Architecture 1.6 API</name>
<url>http://www.jboss.org</url>
- <description>The J2EE Connector Architecture 1.5 API classes</description>
+ <description>The J2EE Connector Architecture 1.6 API classes</description>
<dependencies>
<!-- For SerialVersion -->
<dependency>
<groupId>org.jboss</groupId>
<artifactId>jboss-common-core</artifactId>
</dependency>
+ <dependency>
+ <groupId>org.jboss.javaee</groupId>
+ <artifactId>jboss-transaction-api</artifactId>
+ <version>1.0.1.GA</version>
+ </dependency>
</dependencies>
</project>
\ No newline at end of file
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/NotSupportedException.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/NotSupportedException.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/NotSupportedException.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,65 +19,69 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
+
package javax.resource;
/**
- * A NotSupportedException is thrown to indicate that the callee (resource
- * adapter or application server for system contracts) cannot execute an
- * operation because the operation is not a supported feature. For example, if
- * the transaction support level for a resource adapter is NO_TRANSACTION, an
- * invocation of ManagedConnection.getXAResource method should throw
- * NotSupportedException exception.
+ * A <code>NotSupportedException</code> is thrown to indicate that
+ * callee (resource adapter
+ * or application server for system contracts) cannot execute an operation
+ * because the operation is not a supported feature. For example, if the
+ * transaction support level for a resource adapter is
+ * <code>NO_TRANSACTION</code>, an invocation of <code>getXAResource</code>
+ * method on a <code>ManagedConnection</code> object should throw a
+ * <code>NotSupportedException</code> exception.
+ *
+ * @version 1.0
+ * @author Rahul Sharma
+ * @author Ram Jeyaraman
*/
-public class NotSupportedException extends ResourceException
-{
- /**
- * Create a not supported exception.
- */
- public NotSupportedException()
- {
- super();
- }
- /**
- * Create a not supported exception with a reason.
- *
- * @param reason the reason
- */
- public NotSupportedException(String reason)
- {
- super(reason);
- }
+public class NotSupportedException extends javax.resource.ResourceException {
+
+ /**
+ * Constructs a new instance with null as its detail message.
+ */
+ public NotSupportedException() { super(); }
- /**
- * Create a not supported exception with a reason and an errorCode.
- *
- * @param reason the reason
- * @param errorCode the error code
- */
- public NotSupportedException(String reason, String errorCode)
- {
- super(reason, errorCode);
- }
+ /**
+ * Constructs a new instance with the specified detail message.
+ *
+ * @param message the detail message.
+ */
+ public NotSupportedException(String message) {
+ super(message);
+ }
- /**
- * Create a not supported exception with a reason and an error.
- *
- * @param reason the reason
- * @param throwable the error
- */
- public NotSupportedException(String reason, Throwable throwable)
- {
- super(reason, throwable);
- }
+ /**
+ * Constructs a new throwable with the specified cause.
+ *
+ * @param cause a chained exception of type <code>Throwable</code>.
+ */
+ public NotSupportedException(Throwable cause) {
+ super(cause);
+ }
- /**
- * Create a not supported exception with an error.
- *
- * @param throwable the error
- */
- public NotSupportedException(Throwable throwable)
- {
- super(throwable);
- }
-}
\ No newline at end of file
+ /**
+ * Constructs a new throwable with the specified detail message and cause.
+ *
+ * @param message the detail message.
+ *
+ * @param cause a chained exception of type <code>Throwable</code>.
+ */
+ public NotSupportedException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ /**
+ * Constructs a new throwable with the specified detail message and
+ * error code.
+ *
+ * @param message a description of the exception.
+ * @param errorCode a string specifying the vendor specific error code.
+ */
+ public NotSupportedException(String message, String errorCode) {
+ super(message, errorCode);
+ }
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/Referenceable.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/Referenceable.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/Referenceable.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,27 +19,38 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource;
import javax.naming.Reference;
-/**
- * The Referenceable interface extends the javax.naming.Referenceable
- * interface. It enables support for the JNDI Reference mechanism for the
- * registration of the connection factory in the JNDI name space. Note that the
- * implementation and structure of a Reference is specific to an application
- * server.
- *
- * The implementation class for a connection factory interface is required to
- * implement both the java.io.Serializable and the javax.resource.Referenceable
- * interfaces to support JNDI registration.
- */
-public interface Referenceable extends javax.naming.Referenceable
-{
- /**
- * Sets the reference instance
- *
- * @param reference the reference
- */
- void setReference(Reference reference);
-}
\ No newline at end of file
+/** The Referenceable interface extends the javax.naming.Referenceable
+ * interface. It enables support for JNDI Reference mechanism for
+ * the registration of the connection factory in the JNDI name space.
+ * Note that the implementation and structure of Reference is specific
+ * to an application server.
+ *
+ * <p>The implementation class for a connection factory interface is
+ * required to implement both java.io.Serializable and
+ * javax.resource.Referenceable interfaces to support JNDI registration.
+ *
+ * @version 0.9
+ * @author Rahul Sharma
+ *
+**/
+
+public interface Referenceable extends javax.naming.Referenceable {
+
+ /** Sets the Reference instance. This method is called by the
+ * deployment code to set the Reference that can be later
+ * returned by the getReference method (as defined in the
+ * javax.naming.Referenceable interface).
+ *
+ * @param reference A Reference instance
+ * @see javax.naming.Referenceable#getReference
+ *
+ **/
+ public
+ void setReference(Reference reference);
+
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/ResourceException.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/ResourceException.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/ResourceException.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,149 +19,147 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
-package javax.resource;
-import org.jboss.util.id.SerialVersion;
+package javax.resource;
+
/**
- * This is the root exception for the exception hierarchy defined for the
- * connector architecture.
+ * This is the root interface of the exception hierarchy defined
+ * for the Connector architecture.
*
- * A ResourceException contains three items, the first two of which are set
- * from the constructor. The first is a standard message string which is
- * accessed via the getMessage() method. The second is an errorCode which is
- * accessed via the getErrorCode() method. The third is a linked exception
- * which provides more information from a lower level in the resource manager.
- * Linked exceptions are accessed via get/setLinkedException.
+ * The ResourceException provides the following information:
+ * <UL>
+ * <LI> A resource adapter vendor specific string describing the error.
+ * This string is a standard Java exception message and is available
+ * through getMessage() method.
+ * <LI> resource adapter vendor specific error code.
+ * <LI> reference to another exception. Often a resource exception
+ * will be result of a lower level problem. If appropriate, this
+ * lower level exception can be linked to the ResourceException.
+ * Note, this has been deprecated in favor of J2SE release 1.4 exception
+ * chaining facility.
+ * </UL>
+ *
+ * @version 1.0
+ * @author Rahul Sharma
+ * @author Ram Jeyaraman
*/
-public class ResourceException extends Exception
-{
- /** @since 4.0.2 */
- static final long serialVersionUID;
- static
- {
- if (SerialVersion.version == SerialVersion.LEGACY)
- serialVersionUID = 4770679801401540475L;
- else
- serialVersionUID = 547071213627824490L;
- }
-
- /** The error code */
- private String errorCode;
- /** The linked exception */
- private Exception linkedException;
+public class ResourceException extends java.lang.Exception {
- /**
- * Create an exception with a null reason.
- */
- public ResourceException()
- {
- super();
- }
+ /** Vendor specific error code */
+ private String errorCode;
- /**
- * Create an exception with a reason.
- *
- * @param reason the reason
- */
- public ResourceException(String reason)
- {
- super(reason);
- }
+ /** reference to another exception */
+ private Exception linkedException;
- /**
- * Create an exception with a reason and an errorCode.
- *
- * @param reason the reason
- * @param errorCode the error code
- */
- public ResourceException(String reason, String errorCode)
- {
- super(reason);
- this.errorCode = errorCode;
- }
+ /**
+ * Constructs a new instance with null as its detail message.
+ */
+ public ResourceException() { super(); }
- /**
- * Create an exception with a reason and an errorCode.
- *
- * @param reason the reason
- * @param throwable the linked error
- */
- public ResourceException(String reason, Throwable throwable)
- {
- super(reason, throwable);
- }
+ /**
+ * Constructs a new instance with the specified detail message.
+ *
+ * @param message the detail message.
+ */
+ public ResourceException(String message) {
+ super(message);
+ }
- /**
- * Create an exception with a reason and an errorCode.
- *
- * @param throwable the linked error
- */
- public ResourceException(Throwable throwable)
- {
- super(throwable);
- }
+ /**
+ * Constructs a new throwable with the specified cause.
+ *
+ * @param cause a chained exception of type <code>Throwable</code>.
+ */
+ public ResourceException(Throwable cause) {
+ super(cause);
+ }
- /**
- * Get the error code.
- *
- * @return the error code
- */
- public String getErrorCode()
- {
- return errorCode;
- }
+ /**
+ * Constructs a new throwable with the specified detail message and cause.
+ *
+ * @param message the detail message.
+ *
+ * @param cause a chained exception of type <code>Throwable</code>.
+ */
+ public ResourceException(String message, Throwable cause) {
+ super(message, cause);
+ }
- /**
- * Get any linked exception.
- *
- * @return the linked exception
- */
- public Exception getLinkedException()
- {
- return linkedException;
- }
+ /**
+ * Create a new throwable with the specified message and error code.
+ *
+ * @param message a description of the exception.
+ * @param errorCode a string specifying the vendor specific error code.
+ */
+ public ResourceException(String message, String errorCode) {
+ super(message);
+ this.errorCode = errorCode;
+ }
- /**
- * Get the message composed of the reason and error code.
- *
- * @return message composed of the reason and error code.
- */
- public String getMessage()
- {
- String msg = super.getMessage();
- String ec = getErrorCode();
- if ((msg == null) && (ec == null))
- {
- return null;
- }
- if ((msg != null) && (ec != null))
- {
- return (msg + ", error code: " + ec);
- }
- return ((msg != null) ? msg : ("error code: " + ec));
- }
+ /**
+ * Set the error code.
+ *
+ * @param errorCode the error code.
+ */
+ public void setErrorCode(String errorCode) {
+ this.errorCode = errorCode;
+ }
- /**
- * Set the error code.
- *
- * @param errorCode code the error code
- */
- public void setErrorCode(String errorCode)
- {
- this.errorCode = errorCode;
- }
+ /**
+ * Get the error code.
+ *
+ * @return the error code.
+ */
+ public String getErrorCode() {
+ return this.errorCode;
+ }
- /**
- * Set a linked exception.
- *
- * @deprecated use initCause
- * @param linkedException the linked exception
- */
- public void setLinkedException(Exception linkedException)
- {
- this.linkedException = linkedException;
- initCause(linkedException);
- }
-}
\ No newline at end of file
+ /**
+ * Get the exception linked to this ResourceException
+ *
+ * @return linked Exception, null if none
+ *
+ * @deprecated J2SE release 1.4 supports a chained exception facility
+ * that allows any throwable to know about another throwable, if any,
+ * that caused it to get thrown. Refer to <code>getCause</code> and
+ * <code>initCause</code> methods of the
+ * <code>java.lang.Throwable</code> class..
+ */
+ public Exception getLinkedException() {
+ return (linkedException);
+ }
+
+ /**
+ * Add a linked Exception to this ResourceException.
+ *
+ * @param ex linked Exception
+ *
+ * @deprecated J2SE release 1.4 supports a chained exception facility
+ * that allows any throwable to know about another throwable, if any,
+ * that caused it to get thrown. Refer to <code>getCause</code> and
+ * <code>initCause</code> methods of the
+ * <code>java.lang.Throwable</code> class.
+ */
+ public void setLinkedException(Exception ex) {
+ linkedException = ex;
+ }
+
+ /**
+ * Returns a detailed message string describing this exception.
+ *
+ * @return a detailed message string.
+ */
+ public String getMessage() {
+ String msg = super.getMessage();
+ String ec = getErrorCode();
+ if ((msg == null) && (ec == null)) {
+ return null;
+ }
+ if ((msg != null) && (ec != null)) {
+ return (msg + ", error code: " + ec);
+ }
+ return ((msg != null) ? msg : ("error code: " + ec));
+ }
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/Connection.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/Connection.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/Connection.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,44 +19,101 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.cci;
import javax.resource.ResourceException;
+import javax.resource.NotSupportedException;
-/**
- * The Connection provides a handle for use by the application to access an
- * underlying physical connection.
+
+/** A Connection represents an application-level handle that is used
+ * by a client to access the underlying physical connection. The actual
+ * physical connection associated with a Connection instance is
+ * represented by a ManagedConnection instance.
+ *
+ * <p>A client gets a Connection instance by using the
+ * <code>getConnection</code> method on a <code>ConnectionFactory</code>
+ * instance. A connection can be associated with zero or more Interaction
+ * instances.
*
- * The client calls the getConnection() method on a ConnectionFactory object to
- * get a Connection.
- */
-public interface Connection
-{
- /**
- * Closes a connection
- */
- public void close() throws ResourceException;
+ * @author Rahul Sharma
+ * @version 0.8
+ * @see javax.resource.cci.ConnectionFactory
+ * @see javax.resource.cci.Interaction
+ **/
- /**
- * Creates a new interaction associated with this connection.
- */
- public Interaction createInteraction() throws ResourceException;
+public interface Connection {
+
+ /** Creates an Interaction associated with this Connection. An
+ * Interaction enables an application to execute EIS functions.
+ *
+ * @return Interaction instance
+ * @throws ResourceException Failed to create an Interaction
+ **/
+ public
+ Interaction createInteraction()
+ throws ResourceException;
- /**
- * Gets a LocalTransaction object which allows the client to manage local
- * transactions for the connection.
- */
- public LocalTransaction getLocalTransaction() throws ResourceException;
+ /** Returns an LocalTransaction instance that enables a component to
+ * demarcate resource manager local transactions on the Connection.
+ * If a resource adapter does not allow a component to demarcate
+ * local transactions on an Connection using LocalTransaction
+ * interface, then the method getLocalTransaction should throw a
+ * NotSupportedException.
+ *
+ * @return LocalTransaction instance
+ *
+ * @throws ResourceException Failed to return a LocalTransaction
+ * instance because of a resource
+ * adapter error
+ * @throws NotSupportedException Demarcation of Resource manager
+ * local transactions is not supported
+ * on this Connection
+ * @see javax.resource.cci.LocalTransaction
+ **/
- /**
- * Gets meta data for the underlying resource represented by this
- * connection.
- */
- public ConnectionMetaData getMetaData() throws ResourceException;
+ public
+ LocalTransaction getLocalTransaction() throws ResourceException;
+
+ /** Gets the information on the underlying EIS instance represented
+ * through an active connection.
+ *
+ * @return ConnectionMetaData instance representing information
+ * about the EIS instance
+ * @throws ResourceException
+ * Failed to get information about the
+ * connected EIS instance. Error can be
+ * resource adapter-internal, EIS-specific
+ * or communication related.
+ **/
+ public
+ ConnectionMetaData getMetaData() throws ResourceException;
- /**
- * Gets information on ResultSet functionality supported by the underlying
- * resource for the connection.
- */
- public ResultSetInfo getResultSetInfo() throws ResourceException;
-}
\ No newline at end of file
+ /** Gets the information on the ResultSet functionality supported by
+ * a connected EIS instance.
+ *
+ * @return ResultSetInfo instance
+ * @throws ResourceException Failed to get ResultSet related
+ * information
+ * @throws NotSupportedException ResultSet functionality is not
+ * supported
+ **/
+ public
+ ResultSetInfo getResultSetInfo() throws ResourceException;
+
+
+ /** Initiates close of the connection handle at the application level.
+ * A client should not use a closed connection to interact with
+ * an EIS.
+ *
+ * @throws ResourceException Exception thrown if close
+ * on a connection handle fails.
+ * <p>Any invalid connection close invocation--example,
+ * calling close on a connection handle that is
+ * already closed--should also throw this exception.
+ *
+ **/
+ public
+ void close() throws ResourceException;
+
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ConnectionFactory.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ConnectionFactory.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ConnectionFactory.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,47 +19,124 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.cci;
-import java.io.Serializable;
-import javax.resource.Referenceable;
+import java.io.PrintWriter;
import javax.resource.ResourceException;
+import javax.resource.NotSupportedException;
-/**
- * The ConnectionFactory provides an interface for getting a Connection from
- * the Resource adapter.
- *
- * The application retrieves a reference to the ConnectionFactory through a
- * JNDI lookup.
- *
- * ConnectionFactory extends java.io.Serializable and
- * javax.resource.Referenceable in order to support JNDI lookup.
- */
-public interface ConnectionFactory extends Serializable, Referenceable
-{
- /**
- * Gets a connection from the resource adapter. When using this method the
- * client does not pass any security information, and wants the container to
- * manage sign-on. This is called container managed sign-on.
- */
- public Connection getConnection() throws ResourceException;
- /**
- * Gets a connection from the resource adapter. When using this method the
- * client passes in the security information. This is called component
- * managed sign-on.
- */
- public Connection getConnection(ConnectionSpec properties) throws ResourceException;
+/** <code>ConnectionFactory</code> provides an interface for getting
+ * connection to an EIS instance. An implementation of ConnectionFactory
+ * interface is provided by a resource adapter.
+ *
+ * <p>Application code looks up a ConnectionFactory instance from JNDI
+ * namespace and uses it to get EIS connections.
+ *
+ * <p>An implementation class for ConnectionFactory is required to
+ * implement <code>java.io.Serializable</code> and
+ * <code>javax.resource.Referenceable</code>interfaces to support
+ * JNDI registration.
+ *
+ * @author Rahul Sharma
+ * @version 0.8
+ * @see javax.resource.cci.Connection
+ * @see javax.resource.Referenceable
+ **/
+public interface ConnectionFactory
+ extends java.io.Serializable,
+ javax.resource.Referenceable {
+
+ /** Gets a connection to an EIS instance. This getConnection variant
+ * should be used when a component wants the container to manage EIS
+ * sign-on. This case is termed container-managed sign-on. The
+ * component does not pass any security information.
+ *
+ *
+ * @return Connection instance
+ * @throws ResourceException Failed to get a connection to
+ * the EIS instance. Examples of
+ * error cases are:
+ * <UL>
+ * <LI> Invalid configuration of ManagedConnectionFactory--
+ * example: invalid server name
+ * <LI> Application server-internal error--example:
+ * connection pool related error
+ * <LI> Communication error
+ * <LI> EIS-specific error--example: EIS not active
+ * <LI> Resource adapter-internal error
+ * <LI> Security related error; example: invalid user
+ * <LI> Failure to allocate system resources
+ * </UL>
+ **/
+ public
+ Connection getConnection() throws ResourceException;
- /**
- * Gets a RecordFactory instance for use in creating Record objects.
- */
- public RecordFactory getRecordFactory() throws ResourceException;
+ /** Gets a connection to an EIS instance. A component should use
+ * the getConnection variant with javax.resource.cci.ConnectionSpec
+ * parameter, if it needs to pass any resource adapter specific
+ * security information and connection parameters. In the component-
+ * managed sign-on case, an application component passes security
+ * information (example: username, password) through the
+ * ConnectionSpec instance.
+ *
+ * <p>It is important to note that the properties passed through
+ * the getConnection method should be client-specific (example:
+ * username, password, language) and not related to the
+ * configuration of a target EIS instance (example: port number,
+ * server name). The ManagedConnectionFactory instance is configured
+ * with complete set of properties required for the creation of a
+ * connection to an EIS instance.
+ *
+ * @param properties Connection parameters and security
+ * information specified as
+ * ConnectionSpec instance
+ * @return Connection instance
+ *
+ * @throws ResourceException Failed to get a connection to
+ * the EIS instance. Examples of
+ * error cases are:
+ * <UL>
+ * <LI> Invalid specification of input parameters
+ * <LI> Invalid configuration of ManagedConnectionFactory--
+ * example: invalid server name
+ * <LI> Application server-internal error--example:
+ * connection pool related error
+ * <LI> Communication error
+ * <LI> EIS-specific error--example: EIS not active
+ * <LI> Resource adapter-internal error
+ * <LI> Security related error; example: invalid user
+ * <LI> Failure to allocate system resources
+ * </UL>
+ * @see javax.resource.cci.ConnectionSpec
+ **/
+ public
+ Connection getConnection(ConnectionSpec properties)
+ throws ResourceException;
- /**
- * Gets metadata for the resource adapter. This call does not require an
- * active connection.
- */
- public ResourceAdapterMetaData getMetaData() throws ResourceException;
-}
\ No newline at end of file
+ /** Gets a RecordFactory instance. The RecordFactory is used for
+ * the creation of generic Record instances.
+ *
+ * @return RecordFactory RecordFactory instance
+ *
+ * @throws ResourceException Failed to create a RecordFactory
+ * @throws NotSupportedException Operation not supported
+ **/
+ public
+ RecordFactory getRecordFactory() throws ResourceException;
+
+ /** Gets metadata for the Resource Adapter. Note that the metadata
+ * information is about the ResourceAdapter and not the EIS instance.
+ * An invocation of this method does not require that an active
+ * connection to an EIS instance should have been established.
+ *
+ * @return ResourceAdapterMetaData instance
+ * @throws ResourceException Failed to get metadata information
+ * about the resource adapter
+ **/
+ public
+ ResourceAdapterMetaData getMetaData() throws ResourceException;
+
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ConnectionMetaData.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ConnectionMetaData.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ConnectionMetaData.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,36 +19,53 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.cci;
+
import javax.resource.ResourceException;
-/**
- * The ConnectionMetaData provides information about the underlying resources
- * for the connection.
- */
-public interface ConnectionMetaData
-{
- /**
- * Gets the product name of the underlying resource for the connection.
- *
- * @return Product name of underlying resource.
- */
- public String getEISProductName() throws ResourceException;
+/** The interface <code>ConnectionMetaData</code> provides information
+ * about an EIS instance connected through a Connection instance. A
+ * component calls the method <code>Connection.getMetaData</code> to
+ * get a <code>ConnectionMetaData</code> instance.
+ *
+ * @version 0.8
+ * @author Rahul Sharma
+ * @see javax.resource.cci.Connection
+ * @see javax.resource.cci.ResultSetInfo
+**/
- /**
- * Gets the product version of the underlying resource for the connection.
- *
- * @return Product version name of underlying resource.
- */
- public String getEISProductVersion() throws ResourceException;
+public interface ConnectionMetaData {
- /**
- * Gets the user name for the connection to the underlying resource as known
- * to the underlying resource. This name corresponds to the principal under
- * whose context the connection was first made.
- *
- * @return Product name of underlying resource.
- */
- public String getUserName() throws ResourceException;
-}
\ No newline at end of file
+ /** Returns product name of the underlying EIS instance connected
+ * through the Connection that produced this metadata.
+ *
+ * @return Product name of the EIS instance
+ * @throws ResourceException Failed to get the information for
+ * the EIS instance
+ **/
+ public
+ String getEISProductName() throws ResourceException;
+
+ /** Returns product version of the underlying EIS instance.
+ *
+ * @return Product version of an EIS instance.
+ * @throws ResourceException Failed to get the information for
+ * the EIS instance
+ **/
+ public
+ String getEISProductVersion() throws ResourceException;
+
+ /** Returns the user name for an active connection as known to
+ * the underlying EIS instance. The name corresponds the resource
+ * principal under whose security context a connection to the
+ * EIS instance has been established.
+ *
+ * @return String representing the user name
+ * @throws ResourceException Failed to get the information for
+ * the EIS instance
+ **/
+ public
+ String getUserName() throws ResourceException;
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ConnectionSpec.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ConnectionSpec.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ConnectionSpec.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,19 +19,29 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.cci;
-/**
- * An ConnectionSpec holds connection specific properties for use by a
- * ConnectionFactory in creating a Connection.n Connection in order to execute
- * a function on the underlying resource.
- *
- * The ConnectionSpec interface should be implemented as a JavaBean in order
- * for ease of tool support.
- *
- * A standard set of properties are defined in the specification. In addition
- * an implementation may implement additional properties.
- */
-public interface ConnectionSpec
-{
-}
\ No newline at end of file
+/** ConnectionSpec is used by an application component to pass
+ * connection request-specific properties to the ConnectionFactory.
+ * getConnection method.
+ *
+ * <p>It is recommended that the ConnectionSpec interface be
+ * implemented as a JavaBean to support tools. The properties
+ * on the ConnectionSpec implementation class must be defined
+ * through the getter and setter methods pattern.
+ *
+ * <p>The CCI specification defines a set of standard properties
+ * for an ConnectionSpec. The properties are defined either on
+ * a derived interface or an implementation class of an empty
+ * ConnectionSpec interface. In addition, a resource adapter may
+ * define additional properties specific to its underlying EIS.
+ *
+ * @author Rahul Sharma
+ * @version 1.0 Public Draft 1
+ * @see javax.resource.cci.ConnectionFactory
+ **/
+
+public interface ConnectionSpec {
+
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/IndexedRecord.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/IndexedRecord.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/IndexedRecord.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,12 +19,18 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.cci;
-/**
- * The IndexedRecord interface is used for list oriented representations of the
- * Record elements.
- */
-public interface IndexedRecord extends Record, java.util.List, java.io.Serializable
-{
-}
\ No newline at end of file
+/** IndexedRecord represents an ordered collection of record elements
+ * based on the <code>java.util.List</code> interface. This interface
+ * allows a client to access elements by their integer index (position
+ * in the list) and search for elements in the List.
+ *
+ * @author Rahul Sharma
+ * @since 0.8
+**/
+public interface IndexedRecord extends Record, java.util.List,
+ java.io.Serializable {
+
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/Interaction.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/Interaction.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/Interaction.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,70 +19,144 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.cci;
import javax.resource.ResourceException;
+import javax.resource.NotSupportedException;
-/**
- * The Interaction enables a component to execute functions on the underlying
- * resource. An object implementing the Interaction interface supports two
- * execute() methods for interacting with the underlying resource.
- *
- * An Interaction is created from a Connection and maintains an association
- * with the Connection for its entire lifetime.
- * @version $Revision$
- */
-public interface Interaction
-{
- /**
- * Clears all warnings reported by this Interaction.
- *
- * @exception ResourceException Thrown if operation fails.
- */
- public void clearWarnings() throws ResourceException;
- /**
- * Closes an interaction
- *
- * @exception ResourceException Thrown if operation fails.
- */
- public void close() throws ResourceException;
+/** The <code>javax.resource.cci.Interaction</code> enables a component to
+ * execute EIS functions. An Interaction instance supports the following ways
+ * of interacting with an EIS instance:
+ * <UL>
+ * <LI><code>execute</code> method that takes an input Record, output
+ * Record and an InteractionSpec. This method executes the EIS
+ * function represented by the InteractionSpec and updates the
+ * output Record
+ * <LI><code>execute</code> method that takes an input Record and an
+ * InteractionSpec. This method implementation executes the EIS
+ * function represented by the InteractionSpec and produces the
+ * output Record as a return value.
+ * </UL>
+ * <p>An Interaction instance is created from a Connection and is required
+ * to maintain its association with the Connection instance. The close method
+ * releases all resources maintained by the resource adapter for the
+ * Interaction. The close of an Interaction instance should not close the
+ * associated Connection instance.
+ *
+ * @author Rahul Sharma
+ * @version 0.8
+ * @since 0.8
+ * @see java.sql.ResultSet
+**/
- /**
- * Executes the interaction specified by the InteractionSpec with the
- * specified input.
- *
- * @param spec Represents the target function on the underlying resource.
- * @param input Input Record @returns Record Output if successful, null if
- * not.
- * @exception ResourceException Thrown if Interaction fails.
- */
- public Record execute(InteractionSpec spec, Record input) throws ResourceException;
+public interface Interaction {
+
+ /** Closes the current Interaction and release all the resources
+ * held for this instance by the resource adapter. The close of an
+ * Interaction instance does not close the associated Connection
+ * instance. It is recommended that Interaction instances be
+ * closed explicitly to free any held resources.
+ *
+ * @throws ResourceException Failed to close the Interaction
+ * instance. Invoking close on an
+ * already closed Interaction should
+ * also throw this exception.
+ **/
+ public
+ void close() throws ResourceException;
- /**
- * Executes the interaction specified by the InteractionSpec with the
- * specified input.
- *
- * @param spec Represents the target function on the underlying resource.
- * @param input Input Record
- * @param output Output record @returns boolean True if successful, false if
- * not
- * @exception ResourceException Thrown if Interaction fails.
- */
- public boolean execute(InteractionSpec spec, Record input, Record output) throws ResourceException;
- /**
- * Gets the connection associated with this interaction.
- * @returns Connection Associated connection
- *
- */
- public Connection getConnection();
+ /** Gets the Connection associated with the Interaction.
+ *
+ * @return Connection instance associated with the Interaction
+ **/
+ public
+ Connection getConnection();
- /**
- * Gets the first warning for this interaction. @returns ResourceWarning
- * First warning.
- *
- * @exception ResourceException Thrown if operation fails.
- */
- public ResourceWarning getWarnings() throws ResourceException;
-}
\ No newline at end of file
+ /** Executes an interaction represented by the InteractionSpec.
+ * This form of invocation takes an input Record and updates
+ * the output Record.
+ *
+ * @param ispec InteractionSpec representing a target EIS
+ * data/function module
+ * @param input Input Record
+ * @param output Output Record
+ *
+ * @return true if execution of the EIS function has been
+ * successful and output Record has been updated; false
+ * otherwise
+ *
+ * @throws ResourceException Exception if execute operation
+ * fails. Examples of error cases
+ * are:
+ * <UL>
+ * <LI> Resource adapter internal, EIS-specific or
+ * communication error
+ * <LI> Invalid specification of an InteractionSpec,
+ * input or output record structure
+ * <LI> Errors in use of input or output Record
+ * <LI> Invalid connection associated with this
+ * Interaction
+ * </UL>
+ * @throws NotSupportedException Operation not supported
+ *
+ **/
+ public
+ boolean execute(InteractionSpec ispec,
+ Record input,
+ Record output) throws ResourceException;
+
+ /** Executes an interaction represented by the InteractionSpec.
+ * This form of invocation takes an input Record and returns an
+ * output Record if the execution of the Interaction has been
+ * successfull.
+ *
+ * @param ispec InteractionSpec representing a target EIS
+ * data/function module
+ * @param input Input Record
+
+ * @return output Record if execution of the EIS function has been
+ * successful; null otherwise
+ *
+ * @throws ResourceException Exception if execute operation
+ * fails. Examples of error cases
+ * are:
+ * <UL>
+ * <LI> Resource adapter internal, EIS-specific or
+ * communication error
+ * <LI> Invalid specification of an InteractionSpec
+ * or input record structure
+ * <LI> Errors in use of input Record or creation
+ * of an output Record
+ * <LI> Invalid connection associated with this
+ * Interaction
+ * </UL>
+ * @throws NotSupportedException Operation not supported
+ **/
+ public
+ Record execute(InteractionSpec ispec,
+ Record input) throws ResourceException;
+
+ /** Gets the first ResourceWarning from the chain of warnings
+ * associated with this Interaction instance.
+ *
+ * @return ResourceWarning at top of the warning chain
+ * @throws ResourceException Failed to get ResourceWarnings
+ * associated with Interaction
+ **/
+ public
+ ResourceWarning getWarnings() throws ResourceException;
+
+ /** Clears all the warning reported by this Interaction instance. After
+ * a call to this method, the method getWarnings will return null
+ * until a new warning is reported for this Interaction.
+ *
+ * @throws ResourceException Failed to clear ResourceWarnings
+ * associated with Interaction
+ **/
+ public
+ void clearWarnings() throws ResourceException;
+
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/InteractionSpec.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/InteractionSpec.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/InteractionSpec.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,35 +19,84 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.cci;
import java.io.Serializable;
-/**
- * An InteractionSpec holds properties for use by an Interaction in order to
- * execute a function on the underlying resource.
+/** An InteractionSpec holds properties for driving an Interaction
+ * with an EIS instance. An InteractionSpec is used by an Interaction
+ * to execute the specified function on an underlying EIS.
+ *
+ * <p>The CCI specification defines a set of standard properties for
+ * an InteractionSpec. An InteractionSpec implementation is not
+ * required to support a standard property if that property does
+ * not apply to its underlying EIS.
+ *
+ * <p>The InteractionSpec implementation class must provide getter and
+ * setter methods for each of its supported properties. The getter and
+ * setter methods convention should be based on the Java Beans design
+ * pattern.
*
- * There is a set of standard properties which are used to give hints to an
- * Interaction object about the requirements of a ResultSet.
- *
- * FetchSize, FetchDirection, MaxFieldSize, ResultSetType, ResultSetConcurrency
- *
- * A specific implementation may implement additional properties.
- */
-public interface InteractionSpec extends Serializable
-{
- /**
- * Execution requires only a send to the underlying resource.
- */
- public static final int SYNC_SEND = 0;
+ * <p>The standard properties are as follows:
+ * <UL>
+ * <LI>FunctionName: name of an EIS function
+ * <LI>InteractionVerb: mode of interaction with an EIS instance:
+ * SYNC_SEND, SYNC_SEND_RECEIVE, SYNC_RECEIVE
+ * <LI>ExecutionTimeout: the number of milliseconds an Interaction
+ * will wait for an EIS to execute the specified function
+ * </UL>
+ *
+ * <p>The following standard properties are used to give hints to an
+ * Interaction instance about the ResultSet requirements:
+ * <UL>
+ * <LI>FetchSize
+ * <LI>FetchDirection
+ * <LI>MaxFieldSize
+ * <LI>ResultSetType
+ * <LI>ResultSetConcurrency
+ * </UL>
+ *
+ * <p>A CCI implementation can provide additional properties beyond
+ * that described in the InteractionSpec interface. Note that the
+ * format and type of the additional properties is specific to an EIS
+ * and is outside the scope of the CCI specification.
+ *
+ * <p>It is required that the InteractionSpec interface be implemented
+ * as a JavaBean for the toolability support. The properties on the
+ * InteractionSpec implementation class should be defined through the
+ * getter and setter methods pattern. An implementation class for
+ * InteractionSpec interface is required to implement the
+ * java.io.Serializable interface.
+ *
+ * @author Rahul Sharma
+ * @version 0.8
+ * @since 0.8
+ * @see javax.resource.cci.Interaction
+**/
- /**
- * Execution requires only a send to the underlying resource.
- */
- public static final int SYNC_SEND_RECEIVE = 1;
+public interface InteractionSpec extends java.io.Serializable {
+
+ /**Interaction Verb type: The execution of an Interaction does only a
+ * send to the target EIS instance. The input record is sent to the
+ * EIS instance without any synchronous response in terms of an
+ * output Record or ResultSet.
+ */
+ public static final int SYNC_SEND = 0;
- /**
- * Execution results in a synchronous receive of the output Record
- */
- public static final int SYNC_RECEIVE = 2;
-}
\ No newline at end of file
+ /**Interaction Verb type: The execution of an Interaction sends a
+ * request to the EIS instance and receives response synchronously.
+ * The input record is sent to the EIS instance with the output
+ * received either as Record or CCIResultSet.
+ **/
+ public static final int SYNC_SEND_RECEIVE = 1;
+
+ /**The execution of an Interaction results in a synchronous
+ * receive of an output Record. An example is: a session bean gets
+ * a method invocation and it uses this SEND_RECEIVE form of
+ * interaction to retrieve messages that have been delivered to a
+ * message queue.
+ **/
+ public static final int SYNC_RECEIVE = 2;
+
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/LocalTransaction.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/LocalTransaction.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/LocalTransaction.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,32 +19,89 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.cci;
import javax.resource.ResourceException;
+/** The LocalTransaction defines a transaction demarcation interface for
+ * resource manager local transactions. Note that this interface is
+ * used for application level local transaction demarcation. The
+ * system contract level LocalTransaction interface (as defined in
+ * the <code>javax.resource.spi</code> package) is used by the container
+ * for local transaction management.
+ *
+ * <p>A local transaction is managed internal to a resource manager. There
+ * is no external transaction manager involved in the coordination of
+ * such transactions.
+ *
+ * <p>A CCI implementation can (but is not required to) implement the
+ * LocalTransaction interface. If the LocalTransaction interface is supported
+ * by a CCI implementation, then the method
+ * <code>Connection.getLocalTransaction</code> should return a
+ * LocalTransaction instance. A component can then use the
+ * returned LocalTransaction to demarcate a resource manager local transaction
+ * (associated with the Connection instance) on the underlying EIS
+ * instance.
+ *
+ * @author Rahul Sharma
+ * @since 0.8
+ * @see javax.resource.cci.Connection
+**/
-/**
- * The LocalTransaction interface is the transaction demarcation interface for
- * transactions local to the resource manager. This interface is used for
- * application level transaction demarcation, the spi.LocalTransaction
- * interface is used for transaction management within a resource adapter.
- *
- * Implementation of this interface is optional for a resource manager.
- */
-public interface LocalTransaction
-{
- /**
- * Begins a local transaction on the userlying resource.
- */
- public void begin() throws ResourceException;
+public interface LocalTransaction {
- /**
- * Commits a local transaction on the userlying resource.
- */
- public void commit() throws ResourceException;
+ /** Begins a local transaction on an EIS instance.
+ *
+ * @throws ResourceException Failed to begin a local
+ * transaction. Examples of
+ * error cases are:
+ * <UL>
+ * <LI>Resource adapter internal or EIS-specific
+ * error
+ * <LI>Connection is already participating in a
+ * local or JTA transaction
+ * </UL>
+ **/
+ public
+ void begin() throws ResourceException;
- /**
- * Rolls back a local transaction on the userlying resource.
- */
- public void rollback() throws ResourceException;
-}
\ No newline at end of file
+
+ /** Commits the current local transaction and release all locks held
+ * by the underlying EIS instance.
+ *
+ * @throws ResourceException Failed to commit a local
+ * transaction. Examples of
+ * error cases are:
+ * <UL>
+ * <LI> Resource adapter internal or EIS-specific error
+ * <LI> Violation of integrity constraints, deadlock
+ * detection, communication failure during
+ * transaction completion, or any retry requirement
+ * <LI> Connection is participating in an active JTA
+ * transaction
+ * <LI> Invalid transaction context; commit
+ * operation invoked without an active
+ * transaction context
+ * </UL>
+ **/
+ public
+ void commit() throws ResourceException;
+
+ /** Rollbacks the current resource manager local transaction.
+ *
+ * @throws ResourceException Failed to rollback a local
+ * transaction. Examples of
+ * error cases are:
+ * <UL>
+ * <LI> Resource adapter internal or EIS-specific error
+ * <LI> Connection is participating in an active JTA
+ * transaction
+ * <LI> Invalid transaction context; rollback
+ * operation invoked without an active
+ * transaction context
+ * </UL>
+
+ **/
+ public
+ void rollback() throws ResourceException;
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/MappedRecord.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/MappedRecord.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/MappedRecord.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,15 +19,18 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.cci;
-import java.io.Serializable;
-import java.util.Map;
+/** The interface <code>javax.resource.cci.MappedRecord</code> is
+ * used for key-value map based representation of record elements.
+ * The MappedRecord interface extends both <code>Record</code> and
+ * <code>java.util.Map</code>interfaces.
+ *
+ * @author Rahul Sharma
+ * @version 0.8
+**/
+public interface MappedRecord extends Record, java.util.Map,
+ java.io.Serializable {
-/**
- * The MappedRecord interface is used for key-value map based representation of
- * the Record elements.
- */
-public interface MappedRecord extends Record, Map, Serializable
-{
-}
\ No newline at end of file
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/MessageListener.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/MessageListener.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/MessageListener.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,21 +19,30 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.cci;
import javax.resource.ResourceException;
-/**
- * A request/response message listener that message driven beans may implement
- */
-public interface MessageListener
-{
- /**
- * Request response style message listener
- *
- * @param inputData the input data
- * @return the response or null
- * @throws ResourceException for any error
- */
- Record onMessage(Record inputData) throws ResourceException;
-}
\ No newline at end of file
+/**
+ * This serves as a request-response message listener type that message
+ * endpoints (message-driven beans) may implement. This allows an EIS to
+ * communicate with an endpoint using a request-response style.
+ *
+ * @author Ram Jeyaraman
+ * @version 1.0
+ */
+public interface MessageListener {
+
+ /**
+ * This method allows an EIS to call a message endpoint using a
+ * request-response style communication.
+ *
+ * @param inputData a <code>Record</code> instance.
+ *
+ * @return a <code>Record</code> instance or null.
+ *
+ * @throws ResourceException indicates an exceptional condition.
+ */
+ Record onMessage(Record inputData) throws ResourceException;
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/Record.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/Record.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/Record.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,59 +19,99 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.cci;
-import java.io.Serializable;
-/**
- * The Record interface is the base interface for representing input and output
- * for an Interaction.
- *
- * A Record can be extended in several ways:
- * <ul>
- * <li>MappedRecord based on a Map
- * <li>IndexedRecord based on a List
- * <li>ResultSet based on a java.sql.ResultSet
- * <li>Arbitrary JavaBean
- * </ul>
- *
- * Both MappedRecord and IndexedRecord support heirarchical structures of
- * Records with Records within Records.
- */
-public interface Record extends Cloneable, Serializable
-{
- /**
- * Creae a copy of this Record
- */
- public Object clone() throws CloneNotSupportedException;
+/** The <code>javax.resource.cci.Record</code> interface is the base
+ * interface for the representation of an input or output to the
+ * execute methods defined on an Interaction.
+ *
+ * <p>The Record interface can be extended to form a one of the
+ * following representations:
+ * <UL>
+ * <LI> MappedRecord: A key-value pair based collection represents
+ * a record. This interface is based on the <code>java.util.Map</code>
+ * <LI> IndexedRecord:An ordered and indexed collection represents
+ * a record. This interface is based on the <code>java.util.List</code>.
+ * <LI> JavaBean based representation of an EIS abstraction: An
+ * example is a custom record generated to represent a purchase
+ * order in an ERP system.
+ * <LI> <code>javax.resource.cci.ResultSet</code>: This interface
+ * extends both <code>java.sql.ResultSet</code> and <code>
+ * javax.resource.cci.Record</code>. A ResultSet
+ * represents tabular data.
+ * </UL>
+ *
+ * <p>A MappedRecord or IndexedRecord can contain another Record. This
+ * means that MappedRecord and IndexedRecord can be used to create
+ * a hierarchical structure of any arbitrary depth. A basic Java
+ * type is used as the leaf element of a hierarchical structure
+ * represented by a MappedRecord or IndexedRecord.
+ *
+ * @author Rahul Sharma
+ * @version 0.8
+ * @see javax.resource.cci.Interaction
+ * @see java.sql.ResultSet
+**/
+public interface Record extends java.lang.Cloneable, java.io.Serializable {
+
+ /** Gets the name of the Record.
+ *
+ * @return String representing name of the Record
+ **/
+ public
+ String getRecordName();
+
+ /** Sets the name of the Record.
+ *
+ * @param name Name of the Record
+ **/
+ public
+ void setRecordName(String name);
+
+ /** Sets a short description string for the Record. This property
+ * is used primarily by application development tools.
+ *
+ * @param description Description of the Record
+ **/
+ public
+ void setRecordShortDescription(String description);
- /**
- * Compare two Records for equality
- */
- public boolean equals(Object other);
+ /** Gets a short description string for the Record. This property
+ * is used primarily by application development tools.
+ *
+ * @return String representing a short description of the Record
+ **/
+ public
+ String getRecordShortDescription();
- /*
- * Return a hashcode for this Record
- */
- public int hashCode();
+ /** Check if this instance is equal to another Record.
+ *
+ * @return true if two instances are equal
+ **/
+ public
+ boolean equals(Object other);
- /**
- * Get the name of this Record.
- */
- public String getRecordName();
- /**
- * Set the name of this Record.
- */
- public void setRecordName(String name);
+ /** Returns the hash code for the Record instance.
+ *
+ * @return hash code
+ **/
+ public
+ int hashCode();
- /**
- * Get the short description of this Record
- */
- public String getRecordShortDescription();
+ /** Creates and returns a copy of this object. The precise
+ * meaning of "copy" may depend on the class of the object.
+ *
+ * @return a clone of this instance.
+ * @throws CloneNotSupportedException
+ * If the object's class does not support the
+ * Cloneable interface Subclasses that override the
+ * clone method can also throw this exception to
+ * indicate that an instance cannot be cloned.
+ **/
+ public
+ Object clone() throws CloneNotSupportedException;
- /**
- * Set the short description of this Record
- */
- public void setRecordShortDescription(String description);
-}
\ No newline at end of file
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/RecordFactory.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/RecordFactory.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/RecordFactory.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,25 +19,69 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.cci;
+import java.util.Map;
+import java.util.Collection;
import javax.resource.ResourceException;
+import javax.resource.NotSupportedException;
-/**
- * The RecordFactory interface is used for creating MappedRecord and
- * IndexedRecord instances.
- */
-public interface RecordFactory
-{
- /**
- * Creates a MappedRecord with the specified name. The name is used as a key
- * into the MetaData.
- */
- public MappedRecord createMappedRecord(String recordName) throws ResourceException;
- /**
- * Creates a IndexedRecord with the specified name. The name is used as a
- * key into the MetaData.
- */
- public IndexedRecord createIndexedRecord(String recordName) throws ResourceException;
-}
\ No newline at end of file
+/** The RecordFactory interface is used for creating MappedRecord and
+ * IndexedRecord instances. Note that the RecordFactory is only used
+ * for creation of generic record instances. A CCI implementation
+ * provides an implementation class for the RecordFactory interface.
+ *
+ * @author Rahul Sharma
+ * @since 0.8
+ * @see javax.resource.cci.IndexedRecord
+ * @see javax.resource.cci.MappedRecord
+**/
+public interface RecordFactory {
+
+ /** Creates a MappedRecord. The method takes the name of the record
+ * that is to be created by the RecordFactory. The name of the
+ * record acts as a pointer to the meta information (stored in
+ * the metadata repository) for a specific record type.
+ *
+ * @param recordName Name of the Record
+ * @return MappedRecord
+ * @throws ResourceException Failed to create a MappedRecord.
+ * Example error cases are:
+ *
+ * <UL>
+ * <LI> Invalid specification of record name
+ * <LI> Resource adapter internal error
+ * <LI> Failed to access metadata repository
+ * </UL>
+ * @throws NotSupportedException Operation not supported
+ *
+ **/
+ public
+ MappedRecord createMappedRecord(String recordName)
+ throws ResourceException;
+
+ /** Creates a IndexedRecord. The method takes the name of the record
+ * that is to be created by the RecordFactory. The name of the
+ * record acts as a pointer to the meta information (stored in
+ * the metadata repository) for a specific record type.
+ *
+ * @param recordName Name of the Record
+ * @return IndexedRecord
+ * @throws ResourceException Failed to create an IndexedRecord.
+ * Example error cases are:
+ *
+ * <UL>
+ * <LI> Invalid specification of record name
+ * <LI> Resource adapter internal error
+ * <LI> Failed to access metadata repository
+ * </UL>
+ * @throws NotSupportedException Operation not supported
+ **/
+ public
+ IndexedRecord createIndexedRecord(String recordName)
+ throws ResourceException;
+
+}
+
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ResourceAdapterMetaData.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ResourceAdapterMetaData.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ResourceAdapterMetaData.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,78 +19,124 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.cci;
-/**
- * The ResourceAdaptetMetaData provides information about the resource adapters
- * implementation.
- *
- * The resource adapter does not require an active connection to exist in order
- * for the client to retrieve and use this data.
- * @version $Revision$
- */
-public interface ResourceAdapterMetaData
-{
- /**
- * Gets the resource adapter's name.
- *
- * @return Resource adapter name.
- */
- public String getAdapterName();
+import javax.resource.ResourceException;
- /**
- * Gets the resource adapter's short description.
- *
- * @return Resource adapter short description.
- */
- public String getAdapterShortDescription();
+/** The interface <code>javax.resource.cci.ResourceAdapterMetaData</code>
+ * provides information about capabilities of a resource adapter
+ * implementation. Note that this interface does not provide information
+ * about an EIS instance that is connected through the resource adapter.
+ *
+ * <p>A CCI client uses a <code>ConnectionFactory.getMetaData</code> to
+ * get metadata information about the resource adapter. The
+ * <code>getMetaData</code> method does not require that an active
+ * connection to an EIS instance should have been established.
+ *
+ * <p>The ResourceAdapterMetaData can be extended to provide more
+ * information specific to a resource adapter implementation.
+ *
+ * @author Rahul Sharma
+ * @version 0.8
+ * @since 0.8
+ * @see javax.resource.cci.ConnectionFactory
+**/
- /**
- * Gets the resource adapter vendor's name.
- *
- * @return Resource adapter vendor name.
- */
- public String getAdapterVendorName();
+public interface ResourceAdapterMetaData {
- /**
- * Gets the resource adapter version.
- *
- * @return Resource adapter version.
- */
- public String getAdapterVersion();
+ /** Gets the version of the resource adapter.
+ *
+ * @return String representing version of the resource adapter
+ **/
+ public
+ String getAdapterVersion();
+
+ /** Gets the name of the vendor that has provided the resource
+ * adapter.
+ *
+ * @return String representing name of the vendor that has
+ * provided the resource adapter
+ **/
+ public
+ String getAdapterVendorName();
+
+ /** Gets a tool displayable name of the resource adapter.
+ *
+ * @return String representing the name of the resource adapter
+ **/
+ public
+ String getAdapterName();
+
+ /** Gets a tool displayable short desription of the resource
+ * adapter.
+ *
+ * @return String describing the resource adapter
+ **/
+ public
+ String getAdapterShortDescription();
- /**
- * Gets information on the InteractionSpec types supported by this resource
- * adapter.
- *
- * @return Array of InteractionSpec names supported.
- */
- public String[] getInteractionSpecsSupported();
+ /** Returns a string representation of the version of the
+ * connector architecture specification that is supported by
+ * the resource adapter.
+ *
+ * @return String representing the supported version of
+ * the connector architecture
+ **/
+ public
+ String getSpecVersion();
- /**
- * Gets the Connector specification version supported by this adapter.
- *
- * @return Connector specification version.
- */
- public String getSpecVersion();
+ /** Returns an array of fully-qualified names of InteractionSpec
+ * types supported by the CCI implementation for this resource
+ * adapter. Note that the fully-qualified class name is for
+ * the implementation class of an InteractionSpec. This method
+ * may be used by tools vendor to find information on the
+ * supported InteractionSpec types. The method should return
+ * an array of length 0 if the CCI implementation does not
+ * define specific InteractionSpec types.
+ *
+ * @return Array of fully-qualified class names of
+ * InteractionSpec classes supported by this
+ * resource adapter's CCI implementation
+ * @see javax.resource.cci.InteractionSpec
+ **/
+ public
+ String[] getInteractionSpecsSupported();
- /**
- * Returns true if the resource adapter Interaction implementation supports
- * the method boolean execute( InteractionSpec spec, Record input, Record
- * output ), otherwise returns false
- */
- public boolean supportsExecuteWithInputAndOutputRecord();
- /**
- * Returns true if the resource adapter Interaction implementation supports
- * the method boolean execute( InteractionSpec spec, Record input ),
- * otherwise returns false
- */
- public boolean supportsExecuteWithInputRecordOnly();
+ /** Returns true if the implementation class for the Interaction
+ * interface implements public boolean execute(InteractionSpec
+ * ispec, Record input, Record output) method; otherwise the
+ * method returns false.
+ *
+ * @return boolean depending on method support
+ * @see javax.resource.cci.Interaction
+ **/
+ public
+ boolean supportsExecuteWithInputAndOutputRecord();
- /**
- * Returns true if the resource adapter implementation implements the
- * LocalTransaction interface and supports local transaction demarcation.
- */
- public boolean supportsLocalTransactionDemarcation();
-}
\ No newline at end of file
+
+ /** Returns true if the implementation class for the Interaction
+ * interface implements public Record execute(InteractionSpec
+ * ispec, Record input) method; otherwise the method returns
+ * false.
+ *
+ * @return boolean depending on method support
+ * @see javax.resource.cci.Interaction
+ **/
+ public
+ boolean supportsExecuteWithInputRecordOnly();
+
+
+ /** Returns true if the resource adapter implements the LocalTransaction
+ * interface and supports local transaction demarcation on the
+ * underlying EIS instance through the LocalTransaction interface.
+ *
+ * @return true if resource adapter supports resource manager
+ * local transaction demarcation through LocalTransaction
+ * interface; false otherwise
+ * @see javax.resource.cci.LocalTransaction
+ **/
+ public
+ boolean supportsLocalTransactionDemarcation();
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ResourceWarning.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ResourceWarning.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ResourceWarning.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,78 +19,98 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.cci;
-import javax.resource.ResourceException;
-
/**
- * ResourceWarning provides information on warnings generated by the underlying
- * resource. They are chained to an Interaction object for later retrieval.
+ * A <code>ResourceWarning</code> provides information on warnings related to
+ * execution of an interaction with an EIS. Warnings are silently
+ * chained to the object whose method caused it to be reported.
+ *
+ * @see Interaction#getWarnings
*/
-public class ResourceWarning extends ResourceException
-{
- /**
- * Create a warning
- */
- public ResourceWarning()
- {
- super();
- }
+public class ResourceWarning extends javax.resource.ResourceException {
- /**
- * Create a warning with a reason.
- */
- public ResourceWarning(String reason)
- {
- super(reason);
- }
+ /**
+ * Constructs a new instance with null as its detail message.
+ */
+ public ResourceWarning() { super(); }
- /**
- * Create a warning with a reason and an errorCode.
- */
- public ResourceWarning(String reason, String errorCode)
- {
- super(reason, errorCode);
- }
+ /**
+ * Constructs a new instance with the specified detail message.
+ *
+ * @param message the detail message.
+ */
+ public ResourceWarning(String message) {
+ super(message);
+ }
- /**
- * Create a warning with a reason and an error.
- *
- * @param reason the reason
- * @param throwable the error
- */
- public ResourceWarning(String reason, Throwable throwable)
- {
- super(reason, throwable);
- }
+ /**
+ * Constructs a new throwable with the specified cause.
+ *
+ * @param cause a chained exception of type
+ * <code>Throwable</code>.
+ */
+ public ResourceWarning(Throwable cause) {
+ super(cause);
+ }
- /**
- * Create a warning with an error.
- *
- * @param throwable the error
- */
- public ResourceWarning(Throwable throwable)
- {
- super(throwable);
- }
-
- /**
- * Set a linked warning.
- *
- * @deprecated use initCause()
- */
- public void setLinkedWarning(ResourceWarning linkedWarning)
- {
- setLinkedException(linkedWarning);
- }
+ /**
+ * Constructs a new throwable with the specified detail message and cause.
+ *
+ * @param message the detail message.
+ *
+ * @param cause a chained exception of type
+ * <code>Throwable</code>.
+ */
+ public ResourceWarning(String message, Throwable cause) {
+ super(message, cause);
+ }
- /**
- * Get any linked warning.
- *
- * @deprecated use getCause()
- */
- public ResourceWarning getLinkedWarning()
- {
- return (ResourceWarning) getLinkedException();
- }
-}
\ No newline at end of file
+ /**
+ * Constructs a new throwable with the specified detail message and
+ * an error code.
+ *
+ * @param message a description of the exception.
+ * @param errorCode a string specifying the vendor specific error code.
+ */
+ public ResourceWarning(String message, String errorCode) {
+ super(message, errorCode);
+ }
+
+ /**
+ * Retrieves the warning chained to this <code>ResourceWarning</code>
+ * object.
+ *
+ * @return next <code>ResourceWarning</code> in the chain; null if none.
+ *
+ * @deprecated J2SE release 1.4 supports a chained exception facility
+ * that allows any throwable to know about another throwable, if any,
+ * that caused it to get thrown. Refer to <code>getCause</code> and
+ * <code>initCause</code> methods of the
+ * <code>java.lang.Throwable</code> class.
+ */
+ public ResourceWarning getLinkedWarning() {
+ try {
+ return ((ResourceWarning)getLinkedException());
+ }
+ catch (ClassCastException ex) {
+ return null;
+ }
+ }
+
+ /**
+ * Adds an <code>ResourceWarning</code> object to the end of the chain.
+ *
+ * @param warning <code>ResourceWarning</code> to be added to the chain.
+ *
+ * @deprecated J2SE release 1.4 supports a chained exception facility
+ * that allows any throwable to know about another throwable, if any,
+ * that caused it to get thrown. Refer to <code>getCause</code> and
+ * <code>initCause</code> methods of the
+ * <code>java.lang.Throwable</code> class.
+ */
+ public void setLinkedWarning(ResourceWarning warning) {
+ setLinkedException(warning);
+ }
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ResultSet.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ResultSet.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ResultSet.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,14 +19,20 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.cci;
-/**
- * A ResultSet represents tabular data returned from the underlying resource by
- * the execution of an interaction. The cci.ResultSet is based on the JDBC
- * result set.
- * @version $Revision$
- */
-public interface ResultSet extends Record, java.sql.ResultSet
-{
-}
\ No newline at end of file
+/** A ResultSet represents tabular data that is retrieved from an EIS
+ * instance by the execution of an Interaction.. The CCI ResultSet is
+ * based on the JDBC ResultSet.
+ *
+ * <p>Refer the CCI specification in Connectors 1.0 for detailed
+ * requirements on the implementation of a CCI ResultSet.
+ *
+ * @author Rahul Sharma
+ * @since 0.8
+ * @see java.sql.ResultSet
+**/
+public interface ResultSet extends Record, java.sql.ResultSet {
+
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ResultSetInfo.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ResultSetInfo.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/ResultSetInfo.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,74 +19,154 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.cci;
+
import javax.resource.ResourceException;
-/**
- * The interface ResultSetInfo provides information on the support for the
- * ResultSet interface by an underlying resource. A component can retrieve a
- * ResultSetInfo from a Connection instance.
+/** The interface <code>javax.resource.cci.ResultSetInfo</code> provides
+ * information on the support provided for ResultSet by a connected
+ * EIS instance. A component calls the method
+ * <code>Connection.getResultInfo</code> to get the ResultSetInfo instance.
*
- * A resource only needs to support this interface if it also supports the
- * ResultSet interface.
- */
-public interface ResultSetInfo
-{
- /**
- * Indicates whether or not a visible row delete can be detected.
- */
- public boolean deletesAreDetected(int type) throws ResourceException;
+ * <p>A CCI implementation is not required to support
+ * <code>javax.resource.cci.ResultSetInfo</code> interface. The
+ * implementation of this interface is provided only if the CCI
+ * supports the ResultSet facility.
+ *
+ * @version 0.9
+ * @author Rahul Sharma
+ * @see javax.resource.cci.Connection
+ * @see java.sql.ResultSet
+ * @see javax.resource.cci.ConnectionMetaData
+**/
- /**
- * Indicates whether or not a visible row insert can be detected.
- */
- public boolean insertsAreDetected(int type) throws ResourceException;
+public interface ResultSetInfo {
+
+ /** Indicates whether or not a visible row update can be detected
+ * by calling the method <code>ResultSet.rowUpdated</code>.
+ *
+ * @param type type of the ResultSet i.e. ResultSet.TYPE_XXX
+ * @return true if changes are detected by the result set
+ * type; false otherwise
+ * @see java.sql.ResultSet#rowUpdated
+ * @throws ResourceException Failed to get the information
+ **/
+ public
+ boolean updatesAreDetected(int type) throws ResourceException;
- /**
- * Indicates whether deletes made by others are visible.
- */
- public boolean othersDeletesAreVisible(int type) throws ResourceException;
+ /** Indicates whether or not a visible row insert can be detected
+ * by calling ResultSet.rowInserted.
+ *
+ * @param type type of the ResultSet i.e. ResultSet.TYPE_XXX
+ * @return true if changes are detected by the result set
+ * type; false otherwise
+ * @see java.sql.ResultSet#rowInserted
+ * @throws ResourceException Failed to get the information
+ **/
+ public
+ boolean insertsAreDetected(int type) throws ResourceException;
+
+ /* Indicates whether or not a visible row delete can be detected by
+ * calling ResultSet.rowDeleted. If deletesAreDetected
+ * returns false, then deleted rows are removed from the ResultSet.
+ *
+ * @param type type of the ResultSet i.e. ResultSet.TYPE_XXX
+ * @return true if changes are detected by the result set
+ * type; false otherwise
+ * @see java.sql.ResultSet#rowDeleted
+ * @throws ResourceException Failed to get the information
+ **/
+ public
+ boolean deletesAreDetected(int type) throws ResourceException;
+
+ /** Indicates whether or not a resource adapter supports a type
+ * of ResultSet.
+ *
+ * @param type type of the ResultSet i.e. ResultSet.TYPE_XXX
+ * @return true if ResultSet type supported; false otherwise
+ * @throws ResourceException Failed to get the information
+ **/
+ public
+ boolean supportsResultSetType(int type) throws ResourceException;
- /**
- * Indicates whether inserts made by others are visible.
- */
- public boolean othersInsertsAreVisible(int type) throws ResourceException;
+ /** Indicates whether or not a resource adapter supports the
+ * concurrency type in combination with the given ResultSet type/
+ *
+ * @param type type of the ResultSet i.e. ResultSet.TYPE_XXX
+ * @param concurrency ResultSet concurrency type defined in
+ * java.sql.ResultSet
+ * @return true if the specified combination supported; false otherwise
+ * @throws ResourceException Failed to get the information
+ **/
+ public
+ boolean supportsResultTypeConcurrency(int type,
+ int concurrency)
+ throws ResourceException;
- /**
- * Indicates whether updates made by others are visible.
- */
- public boolean othersUpdatesAreVisible(int type) throws ResourceException;
- /**
- * Indicates whether deletes made by self are visible.
- */
- public boolean ownDeletesAreVisible(int type) throws ResourceException;
+ /** Indicates whether updates made by others are visible.
+ *
+ * @param type type of the ResultSet i.e. ResultSet.TYPE_XXX
+ * @return true if updates by others are visible for the
+ * ResultSet type; false otherwise
+ * @throws ResourceException Failed to get the information
+ */
+ public
+ boolean othersUpdatesAreVisible(int type) throws ResourceException;
- /**
- * Indicates whether inserts made by self are visible.
- */
- public boolean ownInsertsAreVisible(int type) throws ResourceException;
+ /**
+ * Indicates whether deletes made by others are visible.
+ *
+ * @param type type of the ResultSet i.e. ResultSet.TYPE_XXX
+ * @return true if deletes by others are visible for the
+ * ResultSet type; false otherwise
+ * @throws ResourceException Failed to get the information
+ */
+ public
+ boolean othersDeletesAreVisible(int type) throws ResourceException;
+
+ /**
+ * Indicates whether inserts made by others are visible.
+ *
+ * @param type type of the ResultSet i.e. ResultSet.TYPE_XXX
+ * @return true if inserts by others are visible for the
+ * ResultSet type; false otherwise
+ * @throws ResourceException Failed to get the information
+ */
+ public
+ boolean othersInsertsAreVisible(int type) throws ResourceException;
- /**
- * Indicates whether updates made by self are visible.
- */
- public boolean ownUpdatesAreVisible(int type) throws ResourceException;
- /**
- * Indicates whether or not an resource adapter supports the specified type
- * of ResultSet.
- */
- public boolean supportsResultSetType(int type) throws ResourceException;
+ /* Indicates whether a ResultSet's own updates are visible.
+ *
+ * @param type type of the ResultSet i.e. ResultSet.TYPE_XXX
+ * @return true if updates are visible for the ResultSet
+ * type; false otherwise
+ * @throws ResourceException Failed to get the information
+ **/
+ public
+ boolean ownUpdatesAreVisible(int type) throws ResourceException;
- /**
- * Indicates whether or not a resource adapter supports the concurrency type
- * in combination with the given ResultSet type.
- */
- public boolean supportsResultTypeConcurrency(int type, int concurrency) throws ResourceException;
+ /* Indicates whether a ResultSet's own inserts are visible.
+ *
+ * @param type type of the ResultSet i.e. ResultSet.TYPE_XXX
+ * @return true if inserts are visible for the ResultSet
+ * type; false otherwise
+ * @throws ResourceException Failed to get the information
+ **/
+ public
+ boolean ownInsertsAreVisible(int type) throws ResourceException;
- /**
- * Indicates whether or not a visible row update can be detected.
- */
- public boolean updatesAreDetected(int type) throws ResourceException;
-}
\ No newline at end of file
+ /* Indicates whether a ResultSet's own deletes are visible.
+ *
+ * @param type type of the ResultSet i.e. ResultSet.TYPE_XXX
+ * @return true if inserts are visible for the ResultSet
+ * type; false otherwise
+ * @throws ResourceException Failed to get the information
+ **/
+ public
+ boolean ownDeletesAreVisible(int type) throws ResourceException;
+
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/Streamable.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/Streamable.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/Streamable.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,27 +19,49 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.cci;
+
import java.io.InputStream;
+import java.io.OutputStream;
import java.io.IOException;
-import java.io.OutputStream;
-/**
- * The Streamable interface allows a resource adapter to interact with a Record
- * as a stream of bytes.
- *
- * The Streamable interface is used by a resource adapter.
- */
-public interface Streamable
-{
- /**
- * Read the Streamable from the specified InputStream.
- */
- public void read(InputStream istream) throws IOException;
+/** Streamable interface enables a resource adapter to extract data from
+ * an input Record or set data into an output Record as a stream of
+ * bytes.
+ *
+ * <p>The Streamable interface provides a resource adapter's view
+ * of the data that has been set in a Record instance by a component.
+ *
+ * <p>The Streamable interface is not directly used by a component. It
+ * is used by a resource adapter implementation. A component uses Record
+ * or any derived interfaces to manage records.
+ *
+ * @author Rahul Sharma
+ * @since 0.8
+ * @see javax.resource.cci.Record
+**/
- /**
- * Write the Streamable to the specified OutputStream.
- */
- public void write(OutputStream ostream) throws IOException;
-}
\ No newline at end of file
+public interface Streamable {
+
+ /** Read data from an InputStream and initialize fields of a
+ * Streamable object.
+ *
+ * @param istream InputStream that represents a resource
+ * adapter specific internal representation
+ * of fields of a Streamable object
+ **/
+ public
+ void read(InputStream istream) throws IOException;
+
+
+ /** Write fields of a Streamable object to an OutputStream
+ * @param ostream OutputStream that holds value of a
+ * Streamable object
+ **/
+ public
+ void write(OutputStream ostream) throws IOException;
+
+}
+
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/package.html
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/package.html 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/cci/package.html 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,36 +1,8 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
- <head>
- <!-- $Id$ -->
- <!--
-
- JBoss: The OpenSource J2EE WebOS
-
- Distributable under LGPL license.
- See terms of license at gnu.org.
-
- -->
- </head>
-
- <body bgcolor="white">
- <p>J2EE Connector API - Common Client Interface.
-
- <h2>Package Specification</h2>
- <ul>
- <li><a href="http://java.sun.com/j2ee/1.4/docs/api/index.html">Specified javadocs</a>
- </ul>
-
- <h2>Related Documentation</h2>
- <ul>
- <li><a href="http://java.sun.com/j2ee/connector/download.html">The specification</a>
- </ul>
-
- <h2>Package Status</h2>
- <ul>
- <li><font color="green"><b>STABLE</b></font>
- </ul>
-
- <!-- Put @see and @since tags down here. -->
-
- </body>
+<head>
+</head>
+<body>
+The javax.resource.cci package contains API specification for the Common
+Client Interface (CCI).
+</body>
</html>
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/package.html
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/package.html 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/package.html 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,36 +1,8 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
- <head>
- <!-- $Id$ -->
- <!--
-
- JBoss: The OpenSource J2EE WebOS
-
- Distributable under LGPL license.
- See terms of license at gnu.org.
-
- -->
- </head>
-
- <body bgcolor="white">
- <p>J2EE Connector API.
-
- <h2>Package Specification</h2>
- <ul>
- <li><a href="http://java.sun.com/j2ee/1.4/docs/api/index.html">Specified javadocs</a>
- </ul>
-
- <h2>Related Documentation</h2>
- <ul>
- <li><a href="http://java.sun.com/j2ee/connector/download.html">The specification</a>
- </ul>
-
- <h2>Package Status</h2>
- <ul>
- <li><font color="green"><b>STABLE</b></font>
- </ul>
-
- <!-- Put @see and @since tags down here. -->
-
- </body>
+<head>
+</head>
+<body>
+The javax.resource package is the top-level package for the Java EE
+Connector API specification.
+</body>
</html>
Added: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/Activation.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/Activation.java (rev 0)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/Activation.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -0,0 +1,67 @@
+/*
+* JBoss, Home of Professional Open Source
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
+* by the @authors tag. See the copyright.txt in the distribution for a
+* full listing of individual contributors.
+*
+* This is free software; you can redistribute it and/or modify it
+* under the terms of the GNU Lesser General Public License as
+* published by the Free Software Foundation; either version 2.1 of
+* the License, or (at your option) any later version.
+*
+* This software is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+* Lesser General Public License for more details.
+*
+* You should have received a copy of the GNU Lesser General Public
+* License along with this software; if not, write to the Free
+* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+*/
+
+package javax.resource.spi;
+
+import java.lang.annotation.Target;
+import static java.lang.annotation.ElementType.*;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Documented;
+import static java.lang.annotation.RetentionPolicy.*;
+
+/**
+ * Designates a JavaBean as an <code>ActivationSpec</code>. This annotation may
+ * be placed on a JavaBean. A JavaBean annotated with the Activation annotation
+ * is not required to implement the {@link ActivationSpec ActivationSpec}
+ * interface.
+ *
+ * <p>The ActivationSpec JavaBean contains the configuration information pertaining
+ * to inbound connectivity from an EIS instance. A resource adapter capable of
+ * message delivery to message endpoints must provide an JavaBean class
+ * implementing the {@link ActivationSpec ActivationSpec} interface or annotate
+ * a JavaBean with the <code>Activation</code> annotation for each supported
+ * endpoint message listener type.
+ *
+ * <p>The ActivationSpec JavaBean has a set of configurable properties specific to
+ * the messaging style and the message provider.
+ *
+ * <p>Together with the messageListener annotation element type this annotation
+ * specifies information about a specific message listener type supported by the
+ * messaging resource adapter.
+ *
+ * @since 1.6
+ * @version JSR322-PublicReview
+ */
+
+ at Documented
+ at Retention(RUNTIME)
+ at Target(TYPE)
+public @interface Activation {
+
+ /**
+ * Indicates the message listener type(s) associated with this activation.
+ *
+ * @return The Java types of the Message Listener interface this
+ * activation-spec is associated with.
+ */
+ Class[] messageListeners() default {};
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ActivationSpec.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ActivationSpec.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ActivationSpec.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,20 +19,37 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
/**
- * A marker interface holding the configuration of a message endpoint.
+ * This interface serves as a marker. An instance of an ActivationSpec must be a
+ * JavaBean and must be serializable. This holds the activation configuration
+ * information for a message endpoint.
*
- * An instance must be a javabean and be serializable.
+ * @version 1.0
+ * @author Ram Jeyaraman
*/
-public interface ActivationSpec extends ResourceAdapterAssociation
-{
- /**
- * Optional method that can be used to check configuration by a deployment
- * tool.
+public interface ActivationSpec extends ResourceAdapterAssociation {
+
+ /**
+ * This method may be called by a deployment tool to validate the overall
+ * activation configuration information provided by the endpoint deployer.
+ * This helps to catch activation configuration errors earlier on without
+ * having to wait until endpoint activation time for configuration
+ * validation. The implementation of this self-validation check behavior is
+ * optional.
*
- * @throws InvalidPropertyException for invalid configuration
+ * @throws <code>InvalidPropertyException</code> indicates invalid
+ * configuration property settings.
+ *
+ * @deprecated As of Java EE Connectors 1.6 specification, resource adapter
+ * implementations are recommended to use the annotations or the
+ * XML validation deployment descriptor facilities defined by
+ * the Bean Validation specification to express their validation
+ * requirements of its configuration properties to the
+ * application server.
*/
- void validate() throws InvalidPropertyException;
-}
\ No newline at end of file
+ void validate() throws InvalidPropertyException;
+
+}
Added: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/AdministeredObject.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/AdministeredObject.java (rev 0)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/AdministeredObject.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -0,0 +1,49 @@
+/*
+* JBoss, Home of Professional Open Source
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
+* by the @authors tag. See the copyright.txt in the distribution for a
+* full listing of individual contributors.
+*
+* This is free software; you can redistribute it and/or modify it
+* under the terms of the GNU Lesser General Public License as
+* published by the Free Software Foundation; either version 2.1 of
+* the License, or (at your option) any later version.
+*
+* This software is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+* Lesser General Public License for more details.
+*
+* You should have received a copy of the GNU Lesser General Public
+* License along with this software; if not, write to the Free
+* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+*/
+
+package javax.resource.spi;
+
+import java.lang.annotation.Target;
+import static java.lang.annotation.ElementType.*;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Documented;
+import static java.lang.annotation.RetentionPolicy.*;
+
+/**
+ * Designates a JavaBean as an administered object.Administered objects are
+ * specific to a messaging style or message provider.
+ *
+ * @since 1.6
+ * @version JSR322-PublicReview
+ */
+
+ at Documented
+ at Retention(RUNTIME)
+ at Target(TYPE)
+public @interface AdministeredObject {
+
+ /**
+ * Specifies the Java type of the interface implemented by the administered
+ * object.
+ */
+ Class[] adminObjectInterfaces() default {};
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ApplicationServerInternalException.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ApplicationServerInternalException.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ApplicationServerInternalException.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,64 +19,71 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
-import javax.resource.ResourceException;
-
/**
- * A ApplicationServerInternalException is thrown to indicate error conditions
- * specific to the Applcation server. This could include such errors as
- * configuration related or implementation mechanism related errors.
+ * An <code>ApplicationServerInternalException</code> is thrown
+ * by an application
+ * server to indicate error conditions specific to an application server.
+ * These error conditions can be related to either configuration related
+ * errors or implementation of mechanisms internal to an application server
+ * (example: connection pooling, thread management).
+ *
+ * @version 1.0
+ * @author Rahul Sharma
+ * @author Ram Jeyaraman
*/
-public class ApplicationServerInternalException extends ResourceException
-{
- /**
- * Create an exception.
- */
- public ApplicationServerInternalException()
- {
- super();
- }
-
- /**
- * Create an exception with a reason.
- *
- * @param reason the reason
- */
- public ApplicationServerInternalException(String reason)
- {
- super(reason);
- }
- /**
- * Create an exception with a reason and an errorCode.
- *
- * @param reason the reason
- * @param errorCode the error code
- */
- public ApplicationServerInternalException(String reason, String errorCode)
- {
- super(reason, errorCode);
- }
+public class ApplicationServerInternalException
+ extends javax.resource.ResourceException {
- /**
- * Create an exception with a reason and cause.
- *
- * @param reason the reason
- * @param cause the cause
- */
- public ApplicationServerInternalException(String reason, Throwable cause)
- {
- super(reason, cause);
- }
+ /**
+ * Constructs a new instance with null as its detail message.
+ */
+ public ApplicationServerInternalException() { super(); }
- /**
- * Create an exception with a cause.
- *
- * @param cause the cause
- */
- public ApplicationServerInternalException(Throwable cause)
- {
- super(cause);
- }
-}
\ No newline at end of file
+ /**
+ * Constructs a new instance with the specified detail message.
+ *
+ * @param message the detail message.
+ */
+ public ApplicationServerInternalException(String message) {
+ super(message);
+ }
+
+ /**
+ * Constructs a new throwable with the specified cause.
+ *
+ * @param cause a chained exception of type
+ * <code>Throwable</code>.
+ */
+ public ApplicationServerInternalException(Throwable cause) {
+ super(cause);
+ }
+
+ /**
+ * Constructs a new throwable with the specified detail message and cause.
+ *
+ * @param message the detail message.
+ *
+ * @param cause a chained exception of type
+ * <code>Throwable</code>.
+ */
+ public ApplicationServerInternalException(
+ String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ /**
+ * Constructs a new throwable with the specified detail message and
+ * an error code.
+ *
+ * @param message a description of the exception.
+ * @param errorCode a string specifying the vendor specific error code.
+ */
+ public ApplicationServerInternalException(
+ String message, String errorCode) {
+ super(message, errorCode);
+ }
+}
Added: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/AuthenticationMechanism.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/AuthenticationMechanism.java (rev 0)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/AuthenticationMechanism.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -0,0 +1,101 @@
+/*
+* JBoss, Home of Professional Open Source
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
+* by the @authors tag. See the copyright.txt in the distribution for a
+* full listing of individual contributors.
+*
+* This is free software; you can redistribute it and/or modify it
+* under the terms of the GNU Lesser General Public License as
+* published by the Free Software Foundation; either version 2.1 of
+* the License, or (at your option) any later version.
+*
+* This software is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+* Lesser General Public License for more details.
+*
+* You should have received a copy of the GNU Lesser General Public
+* License along with this software; if not, write to the Free
+* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+*/
+
+package javax.resource.spi;
+
+import java.lang.annotation.Target;
+import static java.lang.annotation.ElementType.*;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Documented;
+import static java.lang.annotation.RetentionPolicy.*;
+
+ at Documented
+ at Retention(RUNTIME)
+ at Target(TYPE)
+
+/**
+ * An annotation used to specify the authentication mechanism
+ * supported by the resource adapter.
+ *
+ * @since 1.6
+ * @version JSR322-PublicReview
+ */
+public @interface AuthenticationMechanism {
+
+ /**
+ * An enumerated type that represents the various interfaces
+ * that a resource adapter may support for the representation
+ * of the credentials.
+ *
+ * @since 1.6
+ * @version JSR322-PublicReview
+ */
+ public enum CredentialInterface {
+ /**
+ * Corresponds to
+ * <code>javax.resource.spi.security.PasswordCredential</code>.
+ * This is the default credential interface
+ */
+ PasswordCredential,
+
+ /**
+ * Corresponds to <code>org.ietf.jgss.GSSCredential</code>
+ */
+ GSSCredential,
+
+ /**
+ * Corresponds to
+ * <code>javax.resource.spi.security.GenericCredential</code>
+ */
+ GenericCredential
+ };
+
+ /**
+ * The authentication-mechanismType specifies an authentication
+ * mechanism supported by the resource adapter. Note that this
+ * support is for the resource adapter and not for the
+ * underlying EIS instance.
+ *
+ */
+ String authMechanism() default "BasicPassword";
+
+ /**
+ * The optional description specifies
+ * any resource adapter specific requirement for the support of
+ * security contract and authentication mechanism.
+ */
+ String description() default "";
+
+ /**
+ * Represents the interface that the resource adapter implementation
+ * supports for the representation of the credentials.
+ *
+ * Note that BasicPassword mechanism type should support the
+ * <code>javax.resource.spi.security.PasswordCredential</code> interface.
+ * The Kerbv5 mechanism type should support the
+ * <code>org.ietf.jgss.GSSCredential</code> interface or the deprecated
+ * <code>javax.resource.spi.security.GenericCredential</code> interface.
+ */
+ CredentialInterface credentialInterface()
+ default CredentialInterface.PasswordCredential;
+}
+
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/BootstrapContext.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/BootstrapContext.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/BootstrapContext.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,39 +19,93 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
import java.util.Timer;
-
import javax.resource.spi.work.WorkManager;
+import javax.resource.spi.work.WorkContext;
+import javax.transaction.TransactionSynchronizationRegistry;
/**
- * Used to pass context to the resource adapter start(BootstrapContext) method.
+ * This provides a mechanism to pass a bootstrap context to a resource adapter
+ * instance when it is bootstrapped. That is, when
+ * (<code>start(BootstrapContext)</code>) method on the
+ * <code>ResourceAdapter</code> class is invoked. The bootstrap
+ * context contains references to useful facilities that could be used by the
+ * resource adapter instance.
+ *
+ * @version JSR322-EarlyDraft
+ * @author Ram Jeyaraman, Sivakumar Thyagarajan
*/
-public interface BootstrapContext
-{
- /**
- * Creates a new Timer that can be used to perform period work.
- *
- * @return the timer instance
- * @throws UnavailableException when not timer is available. It can be
- * retried later.
- */
- Timer createTimer() throws UnavailableException;
+public interface BootstrapContext {
+ /**
+ * Provides a handle to a <code>WorkManager</code> instance. The
+ * <code>WorkManager</code> instance could be used by a resource adapter to
+ * do its work by submitting <code>Work</code> instances for execution.
+ *
+ * @return a <code>WorkManager</code> instance.
+ */
+ WorkManager getWorkManager();
- /**
- * Get the work manager, the resource adapter should use this for all work
- * on new threads.
- *
- * @return the work manager
- */
- WorkManager getWorkManager();
+ /**
+ * Provides a handle to a <code>XATerminator</code> instance. The
+ * <code>XATerminator</code> instance could be used by a resource adapter
+ * to flow-in transaction completion and crash recovery calls from an EIS.
+ *
+ * @return a <code>XATerminator</code> instance.
+ */
+ XATerminator getXATerminator();
- /**
- * Get the XATerminator. The resource adapter should use this to gain access
- * to the transaction and crash recovery.
- *
- * @return the XATerminator
- */
- XATerminator getXATerminator();
-}
\ No newline at end of file
+ /**
+ * Creates a new <code>java.util.Timer</code> instance. The
+ * <code>Timer</code> instance could be used to perform periodic
+ * <code>Work</code> executions or other tasks.
+ *
+ * @throws UnavailableException indicates that a
+ * <code>Timer</code> instance is not available. The
+ * request may be retried later.
+ *
+ * @return a new <code>Timer</code> instance.
+ */
+ Timer createTimer() throws UnavailableException;
+
+ /**
+ * A resource adapter can check an application server’s support
+ * for a particular InflowContext type through this method.
+ * This mechanism enables a resource adapter developer to
+ * dynamically change the InflowContexts submitted with a Work instance
+ * based on the support provided by the application server.
+ *
+ * The application server must employ an exact type equality check (that is
+ * <code>java.lang.Class.equals(java.lang.Class)</code> check) in
+ * this method, to check if it supports the InflowContext type provided
+ * by the resource adapter. This method must be idempotent, that is all
+ * calls to this method by a resource adapter for a particular
+ * <code>InflowContext</code> type must return the same boolean value
+ * throughout the lifecycle of that resource adapter instance.
+ *
+ * @return true if the <code>inflowContextClass</code> is supported
+ * by the application server. false if the <code>inflowContextClass</code>
+ * is unsupported or unknown to the application server.
+ *
+ * @since 1.6
+ */
+
+ boolean isContextSupported(
+ Class<? extends WorkContext> inflowContextClass);
+
+
+ /**
+ * Provides a handle to a <code>TransactionSynchronization</code> instance. The
+ * <code>TransactionSynchronizationRegistry</code> instance could be used by a
+ * resource adapter to register synchronization objects, get transaction state and
+ * status etc. This interface is implemented by the application server by a
+ * stateless service object. The same object can be used by any number of
+ * resource adapter objects with thread safety.
+ *
+ * @return a <code>TransactionSynchronizationRegistry</code> instance.
+ * @since 1.6
+ */
+ TransactionSynchronizationRegistry getTransactionSynchronizationRegistry();
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/CommException.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/CommException.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/CommException.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,59 +19,63 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
-import javax.resource.ResourceException;
-
/**
- * A CommException indicates error conditions related to failed or interrupted
- * communication with an underlying resource. examples include: communication
- * protocol error or connection loss due to server failure.
+ * This indicates errors related to failed or interrupted
+ * communication with an EIS instance. Examples of common error conditions
+ * represented by this exception type are communication protocol error and
+ * invalidated connection due to server failure.
+ *
+ * @version 1.0
+ * @author Rahul Sharma
+ * @author Ram Jeyaraman
*/
-public class CommException extends ResourceException
-{
- /**
- * Create an exception.
- */
- public CommException()
- {
- super();
- }
-
- /**
- * Create an exception with a reason.
- */
- public CommException(String reason)
- {
- super(reason);
- }
+public class CommException extends javax.resource.ResourceException {
- /**
- * Create an exception with a reason and an errorCode.
- */
- public CommException(String reason, String errorCode)
- {
- super(reason, errorCode);
- }
+ /**
+ * Constructs a new instance with null as its detail message.
+ */
+ public CommException() { super(); }
- /**
- * Create an exception with a reason and cause.
- *
- * @param reason the reason
- * @param cause the cause
- */
- public CommException(String reason, Throwable cause)
- {
- super(reason, cause);
- }
+ /**
+ * Constructs a new instance with the specified detail message.
+ *
+ * @param message the detail message.
+ */
+ public CommException(String message) {
+ super(message);
+ }
- /**
- * Create an exception with a cause.
- *
- * @param cause the cause
- */
- public CommException(Throwable cause)
- {
- super(cause);
- }
-}
\ No newline at end of file
+ /**
+ * Constructs a new throwable with the specified cause.
+ *
+ * @param cause a chained exception of type <code>Throwable</code>.
+ */
+ public CommException(Throwable cause) {
+ super(cause);
+ }
+
+ /**
+ * Constructs a new throwable with the specified detail message and cause.
+ *
+ * @param message the detail message.
+ *
+ * @param cause a chained exception of type <code>Throwable</code>.
+ */
+ public CommException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ /**
+ * Constructs a new throwable with the specified detail message and
+ * an error code.
+ *
+ * @param message a description of the exception.
+ * @param errorCode a string specifying the vendor specific error code.
+ */
+ public CommException(String message, String errorCode) {
+ super(message, errorCode);
+ }
+}
Added: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConfigProperty.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConfigProperty.java (rev 0)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConfigProperty.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -0,0 +1,60 @@
+/*
+* JBoss, Home of Professional Open Source
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
+* by the @authors tag. See the copyright.txt in the distribution for a
+* full listing of individual contributors.
+*
+* This is free software; you can redistribute it and/or modify it
+* under the terms of the GNU Lesser General Public License as
+* published by the Free Software Foundation; either version 2.1 of
+* the License, or (at your option) any later version.
+*
+* This software is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+* Lesser General Public License for more details.
+*
+* You should have received a copy of the GNU Lesser General Public
+* License along with this software; if not, write to the Free
+* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+*/
+
+package javax.resource.spi;
+
+import java.lang.annotation.Target;
+import static java.lang.annotation.ElementType.*;
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import static java.lang.annotation.RetentionPolicy.*;
+
+/**
+ * Designates a JavaBean property as a configuration property
+ *
+ * @since 1.6
+ * @version JSR322-PublicReview
+ */
+
+ at Documented
+ at Retention(RUNTIME)
+ at Target( { FIELD, METHOD })
+public @interface ConfigProperty {
+
+ /**
+ * Inferred by the container if unspecified.
+ */
+ Class type() default Object.class;
+
+ String description() default "";
+
+ /**
+ * Inferred by the container for field based annotations if possible
+ */
+ String defaultValue() default "";
+
+ /**
+ * Indicates that the configuration tools must ignore considering this
+ * Property during auto-discovery of Configuration properties.
+ */
+ boolean ignore() default false;
+}
Added: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConnectionDefinition.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConnectionDefinition.java (rev 0)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConnectionDefinition.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -0,0 +1,74 @@
+/*
+* JBoss, Home of Professional Open Source
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
+* by the @authors tag. See the copyright.txt in the distribution for a
+* full listing of individual contributors.
+*
+* This is free software; you can redistribute it and/or modify it
+* under the terms of the GNU Lesser General Public License as
+* published by the Free Software Foundation; either version 2.1 of
+* the License, or (at your option) any later version.
+*
+* This software is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+* Lesser General Public License for more details.
+*
+* You should have received a copy of the GNU Lesser General Public
+* License along with this software; if not, write to the Free
+* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+*/
+
+package javax.resource.spi;
+
+import java.lang.annotation.Target;
+import static java.lang.annotation.ElementType.*;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Documented;
+import static java.lang.annotation.RetentionPolicy.*;
+
+/**
+ * Defines a set of connection interfaces and classes pertaining to a particular
+ * connection type. This annotation can be placed only on a JavaBean that
+ * implements the {@link ManagedConnectionFactory ManagedConnectionFactory}
+ * interface.
+ *
+ * @since 1.6
+ *
+ * @version JSR322-PublicReview
+ */
+
+ at Documented
+ at Retention(RUNTIME)
+ at Target(TYPE)
+public @interface ConnectionDefinition {
+
+ /**
+ * Specifies the ConnectionFactory interface supported by the resource
+ * adapter. Example: javax.resource.cci.ConnectionFactory or
+ * com.wombat.ConnectionFactory
+ */
+ Class connectionFactory();
+
+ /**
+ * Specifies the Class provided by the resource adapter that implements the
+ * resource adapter specific ConnectionFactory interface. Example:
+ * com.wombat.ConnectionFactoryImpl
+ */
+ Class connectionFactoryImpl();
+
+ /**
+ * Specifies the Connection interface supported by the resource adapter.
+ * Example: javax.resource.cci.Connection or com.wombat.Connection
+ */
+ Class connection();
+
+ /**
+ * Specifies the class provided by the resource adapter that implements the
+ * resource adapter specific Connection interface. Example:
+ * com.wombat.ConnectionImpl
+ */
+ Class connectionImpl();
+
+}
\ No newline at end of file
Added: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConnectionDefinitions.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConnectionDefinitions.java (rev 0)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConnectionDefinitions.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -0,0 +1,55 @@
+/*
+* JBoss, Home of Professional Open Source
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
+* by the @authors tag. See the copyright.txt in the distribution for a
+* full listing of individual contributors.
+*
+* This is free software; you can redistribute it and/or modify it
+* under the terms of the GNU Lesser General Public License as
+* published by the Free Software Foundation; either version 2.1 of
+* the License, or (at your option) any later version.
+*
+* This software is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+* Lesser General Public License for more details.
+*
+* You should have received a copy of the GNU Lesser General Public
+* License along with this software; if not, write to the Free
+* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+*/
+
+package javax.resource.spi;
+
+import java.lang.annotation.Target;
+import static java.lang.annotation.ElementType.*;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Documented;
+import static java.lang.annotation.RetentionPolicy.*;
+
+/**
+ * Defines a set of connection definitions that the JavaBean, that has been
+ * annotated with this annotation, is a part of. This annotation can be placed
+ * only on a JavaBean that implements the {@link ManagedConnectionFactory
+ * ManagedConnectionFactory} interface.
+ *
+ * @since 1.6
+ * @version JSR322-PublicReview
+ */
+
+ at Documented
+ at Retention(RUNTIME)
+ at Target(TYPE)
+public @interface ConnectionDefinitions {
+
+ /**
+ * An array of {@link ConnectionDefinition ConnectionDefinition}s associated
+ * with the <code>ManagedConectionFactory</code> JavaBean.
+ *
+ * @return an array of <code>ConnectionDefinition</code>s associated with
+ * the <code>ManagedConnectionFactory</code> instance.
+ */
+ ConnectionDefinition[] value();
+
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConnectionEvent.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConnectionEvent.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConnectionEvent.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,206 +19,146 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
-import java.io.Serializable;
-import java.io.ObjectStreamField;
-import java.io.ObjectInputStream;
-import java.io.IOException;
-import java.io.ObjectOutputStream;
+import javax.resource.ResourceException;
import java.util.EventObject;
-import org.jboss.util.id.SerialVersion;
-
-/**
- * The ConnectionEvent class provides information about the source of a
- * Connection related event. A ConnectionEvent contains:
- * <ul>
+/** The ConnectionEvent class provides information about the source of
+ * a connection related event.A ConnectionEvent instance contains the
+ * following information:
+ * <UL>
+ * <LI>Type of the connection event
+ * <LI>ManagedConnection instance that generated the connection event.
+ * A ManagedConnection instance is returned from the method
+ * ConnectionEvent.getSource.
+ * <LI>Connection handle associated with the ManagedConnection instance;
+ * required for the CONNECTION_CLOSED event and optional for the
+ * other event types.
+ * <LI>Optionally, an exception indicating the connection related error.
+ * Note that exception is used for CONNECTION_ERROR_OCCURRED.
+ * </UL>
*
- * <li>Type of connection event.</li>
- * <li>Managed connection instance that generated the event.</li>
- * <li>Connection handle associated with the managed connection.</li>
- * <li>Optionally an exception indicating an error.</li>
- * </ul>
- * <p>
- * This class is used for the following types of notifications:
- * <ul>
- *
- * <li>Connection closed</li>
- * <li>Local transaction started</li>
- * <li>Local transaction commited</li>
- * <li>Local transaction rolled back</li>
- * <li>Connection error occurred</li>
- * </ul>
- * @version $Revision$
+ * <p>This class defines following types of event notifications:
+ * <UL>
+ * <LI>CONNECTION_CLOSED
+ * <LI>LOCAL_TRANSACTION_STARTED
+ * <LI>LOCAL_TRANSACTION_COMMITTED
+ * <LI>LOCAL_TRANSACTION_ROLLEDBACK
+ * <LI>CONNECTION_ERROR_OCCURRED
+ * </UL>
+ *
+ * @version 0.5
+ * @author Rahul Sharma
+ * @see javax.resource.spi.ConnectionEventListener
*/
-public class ConnectionEvent extends EventObject
-{
- /** @since 4.0.2 */
- static final long serialVersionUID;
- // Constants -----------------------------------------------------
- /**
- * These field names match the j2ee 1.4.1 ri version names
- */
- private static final ObjectStreamField[] serialPersistentFields;
- private static final int ID_IDX = 0;
- private static final int EXCEPTION_IDX = 1;
- private static final int CONN_HANDLE_IDX = 2;
+public class ConnectionEvent extends java.util.EventObject {
- static
- {
- if (SerialVersion.version == SerialVersion.LEGACY)
- {
- serialVersionUID = 2776168349823367611L;
- serialPersistentFields = new ObjectStreamField[] {
- /** @serialField id int */
- new ObjectStreamField("id", int.class),
- /** @serialField e Exception */
- new ObjectStreamField("e", Exception.class),
- /** @serialField connectionHandle Object */
- new ObjectStreamField("connectionHandle", Object.class)
- };
- }
- else
- {
- // j2ee 1.4.1 RI values
- serialVersionUID = 5611772461379563249L;
- serialPersistentFields = new ObjectStreamField[] {
- /** @serialField id int */
- new ObjectStreamField("id", int.class),
- /** @serialField exception Exception */
- new ObjectStreamField("exception", Exception.class),
- /** @serialField connectionHandle Object */
- new ObjectStreamField("connectionHandle", Object.class)
- };
- }
- }
+ /** Event notification that an application component has closed the
+ * connection
+ **/
+ public static final int CONNECTION_CLOSED = 1;
- /**
- * Connection has been closed
- */
- public static final int CONNECTION_CLOSED = 1;
+ /** Event notification that a Resource Manager Local Transaction was
+ * started on the connection
+ **/
+ public static final int LOCAL_TRANSACTION_STARTED = 2;
- /**
- * Local transaction has been started
- */
- public static final int LOCAL_TRANSACTION_STARTED = 2;
+ /** Event notification that a Resource Manager Local Transaction was
+ * committed on the connection
+ **/
+ public static final int LOCAL_TRANSACTION_COMMITTED = 3;
- /**
- * Local transaction has been committed
- */
- public static final int LOCAL_TRANSACTION_COMMITTED = 3;
+ /** Event notification that a Resource Manager Local Transaction was
+ * rolled back on the connection
+ **/
+ public static final int LOCAL_TRANSACTION_ROLLEDBACK = 4;
- /**
- * Local transaction has been rolled back
- */
- public static final int LOCAL_TRANSACTION_ROLLEDBACK = 4;
+ /** Event notification that an error occurred on the connection.
+ * This event indicates that the ManagedConnection instance is
+ * now invalid and unusable.
+ **/
+ public static final int CONNECTION_ERROR_OCCURRED = 5;
- /**
- * Connection error has occurred
- */
- public static final int CONNECTION_ERROR_OCCURRED = 5;
- /** Type of event */
- protected int id;
+ /** Exception associated with the <code>ConnectionEvent</code>
+ * instance.
+ *
+ * @serial
+ **/
+ private Exception exception;
- /** The exception */
- private Exception e = null;
- /** The connectionHandle */
- private Object connectionHandle = null;
+ /** Type of the event
+ **/
+ protected int id;
- /**
- * Create a new ConnectionEvent
- *
- * @param source the source of the event
- * @param eid the event id
- */
- public ConnectionEvent(ManagedConnection source, int eid)
- {
- super(source);
- id = eid;
- }
+ private Object connectionHandle;
+
+ /**
+ * Construct a ConnectionEvent object. Exception defaults to null.
+ *
+ * @param source ManagedConnection that is the
+ * source of the event
+ * @param eid type of the Connection event
+ */
+ public ConnectionEvent(ManagedConnection source, int eid) {
+ super(source);
+ this.id = eid;
+ }
- /**
- * Create a new ConnectionEvent
- *
- * @param source the source of the event
- * @param eid the event id
- * @param exception the exception associated with the event
- */
- public ConnectionEvent(ManagedConnection source, int eid, Exception exception)
- {
- super(source);
- id = eid;
- e = exception;
- }
+ /**
+ * Construct a ConnectionEvent object.
+ *
+ * @param source ManagedConnection that is the
+ * source of the event
+ * @param exception exception about to be thrown to the application
+ * @param eid type of the Connection event
+ */
+ public ConnectionEvent(ManagedConnection source, int eid,
+ Exception exception) {
+ super(source);
+ this.exception = exception;
+ this.id = eid;
+ }
- /**
- * Get the event type
- *
- * @return the event id
- */
- public int getId()
- {
- return id;
- }
+ /**Get the connection handle associated with the Managed
+ * Connection instance. Used for CONNECTION_CLOSED event.
+ *
+ * @return the connection handle. May be null
+ */
+ public Object getConnectionHandle() {
+ return connectionHandle;
+ }
- /**
- * Get the exception
- *
- * @return the exception
- */
- public Exception getException()
- {
- return e;
- }
+ /**
+ * Set the connection handle. Used for CONNECTION_CLOSED event
+ */
+ public void setConnectionHandle(Object connectionHandle) {
+ this.connectionHandle = connectionHandle;
+ }
- /**
- * Set the ConnectionHandle
- *
- * @param connectionHandle the connection handle
- */
- public void setConnectionHandle(Object connectionHandle)
- {
- this.connectionHandle = connectionHandle;
- }
+
+ /**
+ * Get the exception. May be null.
+ *
+ * @return the exception about to be thrown.
+ */
+ public Exception getException() {
+ return exception;
+ }
- /**
- * Get the ConnectionHandle
- *
- * @return the connection handle
- */
- public Object getConnectionHandle()
- {
- return connectionHandle;
- }
+ /**
+ * Get the type of event
+ */
+ public
+ int getId() {
+ return id;
+ }
+}
- // Private -------------------------------------------------------
- private void readObject(ObjectInputStream ois)
- throws ClassNotFoundException, IOException
- {
- ObjectInputStream.GetField fields = ois.readFields();
- String name = serialPersistentFields[ID_IDX].getName();
- this.id = fields.get(name, CONNECTION_ERROR_OCCURRED);
- name = serialPersistentFields[EXCEPTION_IDX].getName();
- this.e = (Exception) fields.get(name, null);
- name = serialPersistentFields[CONN_HANDLE_IDX].getName();
- this.connectionHandle = fields.get(name, null);
- }
- private void writeObject(ObjectOutputStream oos)
- throws IOException
- {
- // Write j2ee 1.4.1 RI field names
- ObjectOutputStream.PutField fields = oos.putFields();
- String name = serialPersistentFields[ID_IDX].getName();
- fields.put(name, id);
- name = serialPersistentFields[EXCEPTION_IDX].getName();
- fields.put(name, e);
- name = serialPersistentFields[CONN_HANDLE_IDX].getName();
- fields.put(name, connectionHandle);
- oos.writeFields();
- }
-}
\ No newline at end of file
+
+
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConnectionEventListener.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConnectionEventListener.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConnectionEventListener.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,51 +19,97 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
import java.util.EventListener;
+import javax.resource.ResourceException;
-/**
- * The ConnectionEventListener interface provides for a callback mechanism to
- * enable objects to listen for events of the ConnectionEvent class.
- *
- * An Application server uses these events to manage its connection pools.
- */
-public interface ConnectionEventListener extends EventListener
-{
+/** The <code>ConnectionEventListener</code> interface provides an event
+ * callback mechanism to enable an application server to receive
+ * notifications from a <code>ManagedConnection</code> instance.
+ *
+ * <p>An application server uses these event notifications to manage
+ * its connection pool, to clean up any invalid or terminated connections
+ * and to manage local transactions.
+ *
+ * <p>An application server implements the
+ * <code>ConnectionEventListener</code> interface. It registers a connection
+ * listener with a <code>ManagedConnection</code> instance by using
+ * <code>ManagedConnection.addConnectionEventListener</code> method.
+ *
+ * @version 0.5
+ * @author Rahul Sharma
+ *
+ * @see javax.resource.spi.ConnectionEvent
+ **/
- /**
- * Notifies the listener that a connection has been closed
- *
- * @param event the closed event
- */
- void connectionClosed(ConnectionEvent event);
+public interface ConnectionEventListener
+ extends java.util.EventListener {
- /**
- * Local transaction has been started
- *
- * @param event the local transaction started event
- */
- void localTransactionStarted(ConnectionEvent event);
+ /** Notifies that an application component has closed the connection.
+ *
+ * <p>A ManagedConnection instance notifies its registered set of
+ * listeners by calling ConnectionEventListener.connectionClosed method
+ * when an application component closes a connection handle. The
+ * application server uses this connection close event to put the
+ * ManagedConnection instance back in to the connection pool.
+ *
+ * @param event event object describing the source of
+ * the event
+ */
+ public
+ void connectionClosed(ConnectionEvent event);
- /**
- * Local transaction has been committed
- *
- * @param event the local transaction committed event
- */
- void localTransactionCommitted(ConnectionEvent event);
+ /** Notifies that a Resource Manager Local Transaction was started on
+ * the ManagedConnection instance.
+ *
+ * @param event event object describing the source of
+ * the event
+ */
+ public
+ void localTransactionStarted(ConnectionEvent event);
- /**
- * Local transaction has been rolled back
- *
- * @param the local transaction rolled back event
- */
- void localTransactionRolledback(ConnectionEvent event);
+ /** Notifies that a Resource Manager Local Transaction was committed
+ * on the ManagedConnection instance.
+ *
+ * @param event event object describing the source of
+ * the event
+ */
+ public
+ void localTransactionCommitted(ConnectionEvent event);
- /**
- * Connection error has occurred
- *
- * @param the connection error event
- */
- void connectionErrorOccurred(ConnectionEvent event);
-}
\ No newline at end of file
+ /** Notifies that a Resource Manager Local Transaction was rolled back
+ * on the ManagedConnection instance.
+ *
+ * @param event event object describing the source of
+ * the event
+ */
+ public
+ void localTransactionRolledback(ConnectionEvent event);
+
+ /** Notifies a connection related error.
+
+ * The ManagedConnection instance calls the method
+ * ConnectionEventListener.connectionErrorOccurred to notify
+ * its registered listeners of the occurrence of a physical
+ * connection-related error. The event notification happens
+ * just before a resource adapter throws an exception to the
+ * application component using the connection handle.
+ *
+ * The connectionErrorOccurred method indicates that the
+ * associated ManagedConnection instance is now invalid and
+ * unusable. The application server handles the connection
+ * error event notification by initiating application
+ * server-specific cleanup (for example, removing ManagedConnection
+ * instance from the connection pool) and then calling
+ * ManagedConnection.destroy method to destroy the physical
+ * connection.
+ *
+ * @param event event object describing the source of
+ * the event
+ */
+ public
+ void connectionErrorOccurred(ConnectionEvent event);
+
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConnectionManager.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConnectionManager.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConnectionManager.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,34 +19,82 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
-import java.io.Serializable;
import javax.resource.ResourceException;
-/**
- * The ConnectionManager interface provides the hook which allows a resource
- * adapter to pass a connection to the Application Server. The Application
- * Server implements this interface in order to control QoS services to the
- * resource adapter for connection pools.
- */
+/** <p>ConnectionManager interface provides a hook for the resource adapter to
+ * pass a connection request to the application server.
+ *
+ * <p>An application server provides implementation of the ConnectionManager
+ * interface. This implementation is not specific to any particular type of
+ * the resource adapter or connection factory interface.
+ *
+ * <p>The ConnectionManager implementation delegates to the application
+ * server to enable latter to provide quality of services (QoS) - security,
+ * connection pool management, transaction management and error
+ * logging/tracing.
+ *
+ * <p>An application server implements these services in a generic manner,
+ * independent of any resource adapter and EIS specific mechanisms. The
+ * connector architecture does not specify how an application server
+ * implements these services; the implementation is specific to an
+ * application server.
+ *
+ * <p>After an application server hooks-in its services, the connection
+ * request gets delegated to a ManagedConnectionFactory instance either
+ * for the creation of a new physical connection or for the matching of
+ * an already existing physical connection.
+ *
+ * <p>An implementation class for ConnectionManager interface is
+ * required to implement the <code>java.io.Serializable</code> interface.
+ *
+ * <p>In the non-managed application scenario, the ConnectionManager
+ * implementation class can be provided either by a resource adapter (as
+ * a default ConnectionManager implementation) or by application
+ * developers. In both cases, QOS can be provided as components by third
+ * party vendors.</p>
+ *
+ * @since 0.6
+ * @author Rahul Sharma
+ * @see javax.resource.spi.ManagedConnectionFactory
+**/
-public interface ConnectionManager extends Serializable
-{
- /**
- * Gets called by the resource adapter's connection factory. The resource adapter
- * uses this method to pass its managed connection factory to the connection manager.
- *
- * @param mcf the managed connection factory
- * @param cxRequestInfo the connection request info
- * @return the connection handle
- * @throws ResourceException for an generic error
- * @throws ApplicationServerInternalException for problems in the application server
- * @throws SecurityException for security problems
- * @throws ResourceAllocationException for problems allocating resources
- * @throws ResourceAdapterInternalException for errors from the resource adapter
- */
- public Object allocateConnection(ManagedConnectionFactory mcf, ConnectionRequestInfo cxRequestInfo)
- throws ResourceException;
-}
\ No newline at end of file
+public interface ConnectionManager
+ extends java.io.Serializable {
+
+ /** <p>The method allocateConnection gets called by the resource adapter's
+ * connection factory instance. This lets connection factory instance
+ * (provided by the resource adapter) pass a connection request to
+ * the ConnectionManager instance.</p>
+ *
+ * <p>The connectionRequestInfo parameter represents information specific
+ * to the resource adapter for handling of the connection request.</p>
+ *
+ * @param mcf
+ * used by application server to delegate
+ * connection matching/creation
+ * @param cxRequestInfo
+ * connection request Information
+ *
+ * @return connection handle with an EIS specific connection interface.
+ *
+ *
+ * @throws ResourceException Generic exception
+ * @throws ApplicationServerInternalException
+ * Application server specific exception
+ * @throws SecurityException Security related error
+ * @throws ResourceAllocationException
+ * Failed to allocate system resources for
+ * connection request
+ * @throws ResourceAdapterInternalException
+ * Resource adapter related error condition
+ **/
+ public
+ Object allocateConnection(ManagedConnectionFactory mcf,
+ ConnectionRequestInfo cxRequestInfo)
+ throws ResourceException;
+
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConnectionRequestInfo.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConnectionRequestInfo.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ConnectionRequestInfo.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,28 +19,51 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
-/**
- * The ConnectionRequestInfo allows a resource adapter to pass its own
- * information along with a request for a connection. In order to make use of
- * this functionality, a resource adapter needs to extend this interface and
- * add it's information.
- */
-public interface ConnectionRequestInfo
-{
- /**
- * Tests object for equality
- *
- * @param other the object to test
- * @return true when equal, false otherwise
- */
- public boolean equals(Object other);
+/** <p>The ConnectionRequestInfo interface enables a resource adapter to
+ * pass its own request specific data structure across the connection
+ * request flow. A resource adapter extends the empty interface to
+ * supports its own data structures for connection request.
+ *
+ * <p>A typical use allows a resource adapter to handle
+ * application component specified per-connection request properties
+ * (example - client ID, language). The application server passes these
+ * properties back across to match/createManagedConnection calls on
+ * the resource adapter. These properties remain opaque to the
+ * application server during the connection request flow.
+ *
+ * <p>Once the ConnectionRequestInfo reaches match/createManagedConnection
+ * methods on the ManagedConnectionFactory instance, resource adapter
+ * uses this additional per-request information to do connection
+ * creation and matching.
+ *
+ * @version 0.8
+ * @author Rahul Sharma
+ * @see javax.resource.spi.ManagedConnectionFactory
+ * @see javax.resource.spi.ManagedConnection
+**/
- /**
- * Generates a hashCode for this object
- *
- * @return the hash code
- */
- public int hashCode();
-}
\ No newline at end of file
+public interface ConnectionRequestInfo {
+
+ /** Checks whether this instance is equal to another. Since
+ * connectionRequestInfo is defined specific to a resource
+ * adapter, the resource adapter is required to implement
+ * this method. The conditions for equality are specific
+ * to the resource adapter.
+ *
+ * @return True if the two instances are equal.
+ **/
+ public
+ boolean equals(Object other);
+
+ /** Returns the hashCode of the ConnectionRequestInfo.
+ *
+ * @return hash code os this instance
+ **/
+ public
+ int hashCode();
+
+
+}
Added: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/Connector.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/Connector.java (rev 0)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/Connector.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -0,0 +1,145 @@
+/*
+* JBoss, Home of Professional Open Source
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
+* by the @authors tag. See the copyright.txt in the distribution for a
+* full listing of individual contributors.
+*
+* This is free software; you can redistribute it and/or modify it
+* under the terms of the GNU Lesser General Public License as
+* published by the Free Software Foundation; either version 2.1 of
+* the License, or (at your option) any later version.
+*
+* This software is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+* Lesser General Public License for more details.
+*
+* You should have received a copy of the GNU Lesser General Public
+* License along with this software; if not, write to the Free
+* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+*/
+
+package javax.resource.spi;
+
+import java.lang.annotation.Target;
+import static java.lang.annotation.ElementType.*;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Documented;
+import static java.lang.annotation.RetentionPolicy.*;
+import javax.resource.spi.work.WorkContext;
+
+/**
+ * The <code>Connector</code> annotation is a component-defining annotation and
+ * it can be used by the resource adapter developer to specify that the JavaBean
+ * is a resource adapter JavaBean. The Connector annotation is applied to the
+ * JavaBean class.
+ *
+ * @since 1.6
+ * @version JSR322-PublicReview
+ */
+
+ at Documented
+ at Retention(RUNTIME)
+ at Target(TYPE)
+public @interface Connector {
+
+ String[] description() default {};
+
+ String[] displayName() default "";
+
+ /**
+ * Specifies the file name for small GIF or JPEG icon images that are
+ * used to represent the resource adapter in a GUI tool.
+ *
+ * Each smallIcon must be associated with a largeIcon element and the
+ * application server must use the ordinal value in their respective
+ * arrays to find the related pairs of icons.
+ */
+ String[] smallIcon() default "";
+
+ /**
+ * Specifies the file name for large GIF or JPEG icon images that are
+ * used to represent the resource adapter in a GUI tool.
+ * Each smallIcon must be associated with a largeIcon element and
+ * the application server must use the ordinal value in their
+ * respective arrays to find the related pairs of icons.
+ */
+ String[] largeIcon() default "";
+
+ /**
+ * Specifies the name of the resource adapter provider vendor.
+ */
+ String vendorName() default "";
+
+ /**
+ * Contains information about the type of EIS. For example, the type of an
+ * EIS can be product name of the EIS independent of any version info.This
+ * helps in identifying EIS instances that can be used with this resource
+ * adapter.
+ */
+ String eisType() default "";
+
+ /**
+ * Specifies the version of the resource adapter implementation.
+ */
+ String version() default "";
+
+ /**
+ * Specifies licensing requirements for the resource adapter module and an
+ * optional description of the licensing terms .
+ */
+ String[] licenseDescription() default "";
+
+ /**
+ * Specifies whether a license is required to deploy and use this resource
+ * adapter
+ */
+ boolean licenseRequired() default false;
+
+ /**
+ * Specifies the version of the Java EE Connector Architecture specification
+ * that is supported by this resource adapter. This information enables
+ * deployer to configure the resource adapter to support deployment and
+ * runtime requirements of the corresponding connector architecture
+ * specification.
+ */
+ String specVersion() default "1.6";
+
+ /**
+ * Specifies the authentication mechanisms supported by the resource
+ * adapter.
+ *
+ * @see AuthenticationMechanism
+ */
+ AuthenticationMechanism[] authMechanisms() default {};
+
+ /**
+ * Specifies whether a license is required to deploy and use this resource
+ * adapter
+ */
+ boolean reauthenticationSupport() default false;
+
+ /**
+ * Specifies the extended security permissions required to be provided for
+ * the operation of the resource adapter module
+ *
+ * @see SecurityPermission
+ */
+ SecurityPermission[] securityPermissions() default {};
+
+ /**
+ * Specifies the level of transaction support provided by the resource
+ * adapter.
+ *
+ * @see TransactionSupport.TransactionSupportLevel
+ */
+ TransactionSupport.TransactionSupportLevel transactionSupport() default TransactionSupport.TransactionSupportLevel.NoTransaction;
+
+ /**
+ * Specifies a list of fully qualified classes that implements the
+ * {@link WorkContext InflowContext} interface that a resource adapter
+ * requires the application server to support.
+ */
+ Class<? extends WorkContext>[] requiredInflowContexts() default {};
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/DissociatableManagedConnection.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/DissociatableManagedConnection.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/DissociatableManagedConnection.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,25 +19,35 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
import javax.resource.ResourceException;
/**
- * A marker interface for connections that support the lazy connection
- * association optimization.
+ * This is a mix-in interface that may be optionally implemented by a
+ * <code>ManagedConnection</code> implementation. An implementation of
+ * this interface must support the lazy connection association optimization.
+ *
+ * @version 1.0
+ * @author Ram Jeyaraman
*/
-public interface DissociatableManagedConnection
-{
- /**
- * Invoked by the application server to dissociate the managed connection
- * from all handles.
- *
- * @throws ResourceException for any error
- * @throws ResourceAdapterInternalException for an internal error in the
- * resource adapter
- * @throws IllegalStateException if the state cannot be cleaned up, e.g. a
- * transaction is in progress
- */
- void dissociateConnections() throws ResourceException;
-}
\ No newline at end of file
+public interface DissociatableManagedConnection {
+
+ /**
+ * This method is called by an application server (that is capable of
+ * lazy connection association optimization) in order to dissociate
+ * a <code>ManagedConnection</code> instance from all of its connection
+ * handles.
+ *
+ * @throws ResourceException generic exception if operation fails.
+ *
+ * @throws ResourceAdapterInternalException
+ * resource adapter internal error condition
+ * @throws IllegalStateException Illegal state for calling connection
+ * cleanup. Example - if a localtransaction is in progress
+ * that doesn't allow connection cleanup.
+ */
+ void dissociateConnections() throws ResourceException;
+}
+
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/EISSystemException.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/EISSystemException.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/EISSystemException.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,59 +19,65 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
-import javax.resource.ResourceException;
-
/**
- * A EISSystemException is used to indicate EIS specific error conditios.
- * Common error conditions are failure of the EIS, communication failure or an
- * EIS specific failure during creation of a new connection.
+ * An <code>EISSystemException</code> is used to indicate any EIS
+ * specific system-level
+ * error conditions. The common error conditions are: failure or inactivity of
+ * an EIS instance, communication failure and EIS specific error in the
+ * creation of a new physical connection.
+ *
+ * @version 1.0
+ * @author Rahul Sharma
+ * @author Ram Jeyaraman
*/
-public class EISSystemException extends ResourceException
-{
- /**
- * Create an exception.
- */
- public EISSystemException()
- {
- super();
- }
- /**
- * Create an exception with a reason.
- */
- public EISSystemException(String reason)
- {
- super(reason);
- }
+public class EISSystemException extends javax.resource.ResourceException {
- /**
- * Create an exception with a reason and an errorCode.
- */
- public EISSystemException(String reason, String errorCode)
- {
- super(reason, errorCode);
- }
+ /**
+ * Constructs a new instance with null as its detail message.
+ */
+ public EISSystemException() { super(); }
- /**
- * Create an exception with a reason and cause.
- *
- * @param reason the reason
- * @param cause the cause
- */
- public EISSystemException(String reason, Throwable cause)
- {
- super(reason, cause);
- }
+ /**
+ * Constructs a new instance with the specified detail message.
+ *
+ * @param message the detail message.
+ */
+ public EISSystemException(String message) {
+ super(message);
+ }
- /**
- * Create an exception with a cause.
- *
- * @param cause the cause
- */
- public EISSystemException(Throwable cause)
- {
- super(cause);
- }
-}
\ No newline at end of file
+ /**
+ * Constructs a new throwable with the specified cause.
+ *
+ * @param cause a chained exception of type <code>Throwable</code>.
+ */
+ public EISSystemException(Throwable cause) {
+ super(cause);
+ }
+
+ /**
+ * Constructs a new throwable with the specified detail message and cause.
+ *
+ * @param message the detail message.
+ *
+ * @param cause a chained exception of type <code>Throwable</code>.
+ */
+ public EISSystemException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ /**
+ * Constructs a new throwable with the specified detail message and
+ * an error code.
+ *
+ * @param message a description of the exception.
+ * @param errorCode a string specifying the vendor specific error code.
+ */
+ public EISSystemException(String message, String errorCode) {
+ super(message, errorCode);
+ }
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/IllegalStateException.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/IllegalStateException.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/IllegalStateException.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,57 +19,64 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
-import javax.resource.ResourceException;
-
/**
- * A IllegalStateException is thrown when a method has been invoked on an
- * object which is in the wrong state to execute the method.
+ * An <code>IllegalStateException</code>
+ * is thrown from a method if the callee (resource
+ * adapter or application server for system contracts) is in an illegal or
+ * inappropriate state for the method invocation.
+ *
+ * @version 1.0
+ * @author Rahul Sharma
+ * @author Ram Jeyaraman
*/
-public class IllegalStateException extends ResourceException
-{
- /**
- * Create an exception.
- */
- public IllegalStateException()
- {
- super();
- }
- /**
- * Create an exception with a reason.
- */
- public IllegalStateException(String reason)
- {
- super(reason);
- }
- /**
- * Create an exception with a reason and an errorCode.
- */
- public IllegalStateException(String reason, String errorCode)
- {
- super(reason, errorCode);
- }
+public class IllegalStateException extends javax.resource.ResourceException {
- /**
- * Create an exception with a reason and cause.
- *
- * @param reason the reason
- * @param cause the cause
- */
- public IllegalStateException(String reason, Throwable cause)
- {
- super(reason, cause);
- }
+ /**
+ * Constructs a new instance with null as its detail message.
+ */
+ public IllegalStateException() { super(); }
- /**
- * Create an exception with a cause.
- *
- * @param cause the cause
- */
- public IllegalStateException(Throwable cause)
- {
- super(cause);
- }
-}
\ No newline at end of file
+ /**
+ * Constructs a new instance with the specified detail message.
+ *
+ * @param message the detail message.
+ */
+ public IllegalStateException(String message) {
+ super(message);
+ }
+
+ /**
+ * Constructs a new throwable with the specified cause.
+ *
+ * @param cause a chained exception of type <code>Throwable</code>.
+ */
+ public IllegalStateException(Throwable cause) {
+ super(cause);
+ }
+
+ /**
+ * Constructs a new throwable with the specified detail message and cause.
+ *
+ * @param message the detail message.
+ *
+ * @param cause a chained exception of type <code>Throwable</code>.
+ */
+ public IllegalStateException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ /**
+ * Constructs a new throwable with the specified detail message and
+ * an error code.
+ *
+ * @param message a description of the exception.
+ * @param errorCode a string specifying the vendor specific error code.
+ */
+ public IllegalStateException(String message, String errorCode) {
+ super(message, errorCode);
+ }
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/InvalidPropertyException.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/InvalidPropertyException.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/InvalidPropertyException.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,99 +19,85 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
import java.beans.PropertyDescriptor;
-import javax.resource.ResourceException;
-
-import org.jboss.util.id.SerialVersion;
-
/**
- * Represents invalid configuration properties
+ * This exception is thrown to indicate invalid configuration
+ * property settings.
+ *
+ * @version 0.2
+ * @author Ram Jeyaraman
*/
-public class InvalidPropertyException extends ResourceException
-{
- /** @since 4.0.2 */
- static final long serialVersionUID;
- static
- {
- if (SerialVersion.version == SerialVersion.LEGACY)
- serialVersionUID = -2395559483586818078L;
- else
- serialVersionUID = -485903720300735741L;
- }
+public class InvalidPropertyException
+ extends javax.resource.ResourceException {
- /** The invalidProperties */
- PropertyDescriptor[] invalidProperties;
-
- /**
- * Create an invalid property exception.
- */
- public InvalidPropertyException()
- {
- super();
- }
+ /*
+ * Holder for invalid properties.
+ */
+ private PropertyDescriptor[] invalidProperties;
- /**
- * Create an invalid property exception with a reason.
- *
- * @param reason the reason
- */
- public InvalidPropertyException(String reason)
- {
- super(reason);
- }
+ /**
+ * Create a InvalidPropertyException.
+ */
+ public InvalidPropertyException() {
+ super();
+ }
- /**
- * Create an invalid property exception with a reason and an errorCode.
- *
- * @param reason the reason
- * @param errorCode the error code
- */
- public InvalidPropertyException(String reason, String errorCode)
- {
- super(reason, errorCode);
- }
+ /**
+ * Create a InvalidPropertyException.
+ *
+ * @param message a description of the exception
+ */
+ public InvalidPropertyException(String message) {
+ super(message);
+ }
- /**
- * Create an invalid property exception with a reason and an error.
- *
- * @param reason the reason
- * @param throwable the error
- */
- public InvalidPropertyException(String reason, Throwable throwable)
- {
- super(reason, throwable);
- }
+ /**
+ * Constructs a new throwable with the specified cause.
+ *
+ * @param cause a chained exception of type <code>Throwable</code>.
+ */
+ public InvalidPropertyException(Throwable cause) {
+ super(cause);
+ }
- /**
- * Create an invalid property exception with an error.
- *
- * @param throwable the error
- */
- public InvalidPropertyException(Throwable throwable)
- {
- super(throwable);
- }
+ /**
+ * Constructs a new throwable with the specified detail message and cause.
+ *
+ * @param message the detail message.
+ *
+ * @param cause a chained exception of type <code>Throwable</code>.
+ */
+ public InvalidPropertyException(String message, Throwable cause) {
+ super(message, cause);
+ }
- /**
- * Get the invalid property descriptors
- *
- * @return an array of invalid property descriptors
- */
- public PropertyDescriptor[] getInvalidPropertyDescriptors()
- {
- return invalidProperties;
- }
+ /**
+ * Constructs a new throwable with the specified detail message and
+ * an error code.
+ *
+ * @param message a description of the exception.
+ * @param errorCode a string specifying the vendor specific error code.
+ */
+ public InvalidPropertyException(String message, String errorCode) {
+ super(message, errorCode);
+ }
- /**
- * Set the invalid property descriptors
- *
- * @param an array of invalid property descriptors
- */
- public void setInvalidPropertyDescriptors(PropertyDescriptor[] invalidProperties)
- {
- this.invalidProperties = invalidProperties;
- }
-}
\ No newline at end of file
+ /**
+ * Set a list of invalid properties.
+ */
+ public void setInvalidPropertyDescriptors(
+ PropertyDescriptor[] invalidProperties) {
+ this.invalidProperties = invalidProperties;
+ }
+
+ /**
+ * Get the list of invalid properties.
+ */
+ public PropertyDescriptor[] getInvalidPropertyDescriptors() {
+ return this.invalidProperties;
+ }
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/LazyAssociatableConnectionManager.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/LazyAssociatableConnectionManager.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/LazyAssociatableConnectionManager.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,27 +19,66 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
import javax.resource.ResourceException;
/**
- * An optioanl mixin interface for connection managers that support the lazy connection
- * association optimization.
+ * This is a mix-in interface that may be optionally implemented by a
+ * <code>ConnectionManager</code> implementation. An implementation of
+ * this interface must support the lazy connection association optimization.
+ *
+ * @version 1.0
+ * @author Ram Jeyaraman
*/
-public interface LazyAssociatableConnectionManager
-{
- /**
- * Invoked by a resource adapter to lazily associate a connection handle with the managed connection
- *
- * @param connection the connection handle
- * @param mcf the managed connection factory
- * @param cxRequestInfo the connection request info
- * @throws ResourceException for an generic error
- * @throws ApplicationServerInternalException for problems in the application server
- * @throws SecurityException for security problems
- * @throws ResourceAllocationException for problems allocating resources
- * @throws ResourceAdapterInternalException for errors from the resource adapter
- */
- void associateConnection(Object connection, ManagedConnectionFactory mcf, ConnectionRequestInfo cxReqInfo) throws ResourceException;
-}
\ No newline at end of file
+public interface LazyAssociatableConnectionManager {
+
+ /**
+ * This method is called by a resource adapter (that is capable of
+ * lazy connection association optimization) in order to lazily associate
+ * a connection object with a <code>ManagedConnection</code> instance.
+ *
+ * @param connection the connection object that is to be associated.
+ *
+ * @param mcf The <code>ManagedConnectionFactory</code> instance that was
+ * originally used to create the connection object.
+ *
+ * @param cxReqInfo connection request information. This information must
+ * be the same as that used to originally create the connection object.
+ *
+ * @throws ResourceException Generic exception.
+ *
+ * @throws ApplicationServerInternalException
+ * Application server specific exception.
+ *
+ * @throws SecurityException Security related error.
+ *
+ * @throws ResourceAllocationException
+ * Failed to allocate system resources for
+ * connection request.
+ * @throws ResourceAdapterInternalException
+ * Resource adapter related error condition.
+ */
+ void associateConnection(Object connection, ManagedConnectionFactory mcf,
+ ConnectionRequestInfo cxReqInfo) throws ResourceException;
+
+ /**
+ * This method is called by the resource adapter (that is capable of
+ * lazy connection association optimization) in order to notify the
+ * application server that a disassociated connection handle is closed.
+ * <p>The application server can then perform any cleanup operations
+ * related to the disassociated connection handle in its connection pool.
+ *
+ * @param connection the disassociated connection object handle that
+ * has been closed
+ *
+ * @param mcf The <code>ManagedConnectionFactory</code> instance that was
+ * originally used to create the connection object.
+ *
+ * @since 1.6
+ */
+ void inactiveConnectionClosed(Object connection,
+ ManagedConnectionFactory mcf);
+}
+
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/LazyEnlistableConnectionManager.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/LazyEnlistableConnectionManager.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/LazyEnlistableConnectionManager.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,24 +19,41 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
import javax.resource.ResourceException;
/**
- * An optioanl mixin interface for connection managers that support the lazy connection
- * enlistment optimization.
+ * This is a mix-in interface that may be optionally implemented by a
+ * <code>ConnectionManager</code> implementation. An implementation of
+ * this interface must support the lazy transaction enlistment optimization.
+ *
+ * @version 1.0
+ * @author Ram Jeyaraman
*/
-public interface LazyEnlistableConnectionManager
-{
- /**
- * Invoked by a resource adapter to lazily enlist a connection handle with the managed connection
- *
- * @param mc the managed connection
- * @throws ResourceException for an generic error
- * @throws ApplicationServerInternalException for problems in the application server
- * @throws ResourceAllocationException for problems allocating resources
- * @throws ResourceAdapterInternalException for errors from the resource adapter
- */
- void lazyEnlist(ManagedConnection mc) throws ResourceException;
-}
\ No newline at end of file
+public interface LazyEnlistableConnectionManager {
+
+ /**
+ * This method is called by a resource adapter (that is capable of
+ * lazy transaction enlistment optimization) in order to lazily enlist
+ * a connection object with a XA transaction.
+ *
+ * @param mc The <code>ManagedConnection</code> instance that needs to be
+ * lazily associated.
+ *
+ * @throws ResourceException Generic exception.
+ *
+ * @throws ApplicationServerInternalException
+ * Application server specific exception.
+ *
+ * @throws ResourceAllocationException
+ * Failed to allocate system resources for
+ * connection request.
+ *
+ * @throws ResourceAdapterInternalException
+ * Resource adapter related error condition.
+ */
+ void lazyEnlist(ManagedConnection mc) throws ResourceException;
+}
+
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/LazyEnlistableManagedConnection.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/LazyEnlistableManagedConnection.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/LazyEnlistableManagedConnection.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,12 +19,17 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
/**
- * A marker interface for connections that support the lazy connection
- * enlistment optimization.
+ * This is a mix-in interface that may be optionally implemented by a
+ * <code>ManagedConnection</code> implementation. An implementation of
+ * this interface must support the lazy transaction enlistment optimization.
+ *
+ * @version 1.0
+ * @author Ram Jeyaraman
*/
-public interface LazyEnlistableManagedConnection
-{
-}
\ No newline at end of file
+public interface LazyEnlistableManagedConnection {
+}
+
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/LocalTransaction.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/LocalTransaction.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/LocalTransaction.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,46 +19,71 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
import javax.resource.ResourceException;
-/**
- * The LocalTransaction interface is for transactions which are managed locally
- * to the underlying resource and don't need an external transaction manager.
+/** LocalTransaction interface provides support for transactions that
+ * are managed internal to an EIS resource manager, and do not require
+ * an external transaction manager.
*
- * If a resource implements the LocalTransaction interface then the Application
- * Server can choose to do local transacton optimization.
- */
-public interface LocalTransaction
-{
- /**
- * Begins a local transaction on the userlying resource.
- *
- * @throws ResourceException for a generic error
- * @throws LocalTransactionException for an error in transaciton management
- * @throws ResourceAdapterInternalException for an internal error in the resource adapter
- * @throws EISSystemException for an EIS specific exception
- */
- public void begin() throws ResourceException;
+ * <p>A resource adapter implements the javax.resource.spi.LocalTransaction
+ * interface to provide support for local transactions that are performed
+ * on the underlying resource manager.
+ *
+ * <p>If a resource adapter supports the LocalTransaction interface, then
+ * the application server can choose to perform local transaction
+ * optimization (uses local transaction instead of a JTA transaction for
+ * a single resource manager case).
+ *
+ * @version 0.5
+ * @author Rahul Sharma
+ * @see javax.resource.spi.ManagedConnection
+ **/
- /**
- * Commits a local transaction on the userlying resource.
- *
- * @throws ResourceException for a generic error
- * @throws LocalTransactionException for an error in transaciton management
- * @throws ResourceAdapterInternalException for an internal error in the resource adapter
- * @throws EISSystemException for an EIS specific exception
- */
- public void commit() throws ResourceException;
- /**
- * Rolls back a local transaction on the userlying resource.
- *
- * @throws ResourceException for a generic error
- * @throws LocalTransactionException for an error in transaciton management
- * @throws ResourceAdapterInternalException for an internal error in the resource adapter
- * @throws EISSystemException for an EIS specific exception
- */
- public void rollback() throws ResourceException;
-}
\ No newline at end of file
+
+public interface LocalTransaction {
+ /** Begin a local transaction
+ *
+ * @throws ResourceException generic exception if operation fails
+ * @throws LocalTransactionException
+ * error condition related
+ * to local transaction management
+ * @throws ResourceAdapterInternalException
+ * error condition internal to resource
+ * adapter
+ * @throws EISSystemException EIS instance specific error condition
+ **/
+ public
+ void begin() throws ResourceException;
+
+ /** Commit a local transaction
+ *
+ * @throws ResourceException generic exception if operation fails
+ * @throws LocalTransactionException
+ * error condition related
+ * to local transaction management
+ * @throws ResourceAdapterInternalException
+ * error condition internal to resource
+ * adapter
+ * @throws EISSystemException EIS instance specific error condition
+ **/
+ public
+ void commit() throws ResourceException;
+
+ /** Rollback a local transaction
+ * @throws ResourceException generic exception if operation fails
+ * @throws LocalTransactionException
+ * error condition related
+ * to local transaction management
+ * @throws ResourceAdapterInternalException
+ * error condition internal to resource
+ * adapter
+ * @throws EISSystemException EIS instance specific error condition
+ **/
+ public
+ void rollback() throws ResourceException;
+
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/LocalTransactionException.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/LocalTransactionException.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/LocalTransactionException.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,61 +19,87 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
-import javax.resource.ResourceException;
-
-/**
- * A LocalTransactionException represents various error conditions related to
- * local transaction management. Common error conditions which are indicated by
- * this exception include failure to commit, attempt to start a transaction
- * while inside a transaction, or any resource adapter transaction related
- * error condition.
+/**
+ * A <code>LocalTransactionException</code> represents various
+ * error conditions related to the local transaction management contract.
+ * The Java Transaction API specification specifies the
+ * <code>javax.transaction.xa.XAException</code> class for exceptions
+ * related to XAResource based transaction management contract.
+ *
+ * <p>The <code>LocalTransactionException</code> is used for the local
+ * transaction management contract to indicate the following common
+ * error conditions:
+ * <UL>
+ * <LI>Invalid transaction context when a transaction operation is executed.
+ * For example, calling <code>commit</code> method on
+ * <code>LocalTransaction</code> object without an active
+ * local transaction is an error condition.
+ * <LI>Transaction is rolled back instead of getting committed during a
+ * <code>commit</code> method call on the <code>LocalTransaction</code>
+ * object.
+ * <LI>An attempt to start a local transaction from the same thread on a
+ * <code>ManagedConnection</code> that is already associated with
+ * an active local transaction.
+ * <LI>Any resource adapter or resource manager specific error conditions
+ * related to local transaction management. Examples are violation of
+ * integrity of resources, deadlock detection, communication failure
+ * during transaction completion, retry required or any internal error
+ * in a resource manager.
+ * </UL>
+ *
+ * @version 1.0
+ * @author Rahul Sharma
+ * @author Ram Jeyaraman
*/
-public class LocalTransactionException extends ResourceException
-{
- /**
- * Create an exception.
- */
- public LocalTransactionException()
- {
- super();
- }
- /**
- * Create an exception with a reason.
- */
- public LocalTransactionException(String reason)
- {
- super(reason);
- }
+public class LocalTransactionException
+ extends javax.resource.ResourceException {
- /**
- * Create an exception with a reason and an errorCode.
- */
- public LocalTransactionException(String reason, String errorCode)
- {
- super(reason, errorCode);
- }
+ /**
+ * Constructs a new instance with null as its detail message.
+ */
+ public LocalTransactionException() { super(); }
- /**
- * Create an exception with a reason and cause.
- *
- * @param reason the reason
- * @param cause the cause
- */
- public LocalTransactionException(String reason, Throwable cause)
- {
- super(reason, cause);
- }
+ /**
+ * Constructs a new instance with the specified detail message.
+ *
+ * @param message the detail message.
+ */
+ public LocalTransactionException(String message) {
+ super(message);
+ }
- /**
- * Create an exception with a cause.
- *
- * @param cause the cause
- */
- public LocalTransactionException(Throwable cause)
- {
- super(cause);
- }
-}
\ No newline at end of file
+ /**
+ * Constructs a new throwable with the specified cause.
+ *
+ * @param cause a chained exception of type <code>Throwable</code>.
+ */
+ public LocalTransactionException(Throwable cause) {
+ super(cause);
+ }
+
+ /**
+ * Constructs a new throwable with the specified detail message and cause.
+ *
+ * @param message the detail message.
+ *
+ * @param cause a chained exception of type <code>Throwable</code>.
+ */
+ public LocalTransactionException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ /**
+ * Constructs a new throwable with the specified detail message and
+ * an error code.
+ *
+ * @param message a description of the exception.
+ * @param errorCode a string specifying the vendor specific error code.
+ */
+ public LocalTransactionException(String message, String errorCode) {
+ super(message, errorCode);
+ }
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ManagedConnection.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ManagedConnection.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ManagedConnection.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,125 +19,258 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
-import java.io.PrintWriter;
-
-import javax.resource.ResourceException;
import javax.security.auth.Subject;
import javax.transaction.xa.XAResource;
+import javax.resource.ResourceException;
-/**
- * A ManagedConnection instance represents a connection to the underlying
- * recource. A ManagedConnection provides access to the two transaction
- * interfaces, XAResource and LocalTransaction. These interfaces are used to
- * manage transactions on the resource.
- */
-public interface ManagedConnection
-{
- /**
- * Creates a new connection handle for the underlying connection.
- *
- * @param subject the subject
- * @param cxRequestInfo the connection request info
- * @throws ResourceException for a generic error
- * @throws ResourceAdapterInternalException for an internal error in the
- * resource adapter
- * @throws SecurityException for a security problem
- * @throws CommException for a communication failure with the EIS
- * @throws EISSystemException for an error from the EIS
- */
- public Object getConnection(Subject subject, ConnectionRequestInfo cxRequestInfo) throws ResourceException;
+/** ManagedConnection instance represents a physical connection
+ * to the underlying EIS.
+ *
+ * <p>A ManagedConnection instance provides access to a pair of
+ * interfaces: <code>javax.transaction.xa.XAResource</code> and
+ * <code>javax.resource.spi.LocalTransaction</code>.
+ *
+ * <p><code> XAResource</code> interface is used by the transaction
+ * manager to associate and dissociate a transaction with the underlying
+ * EIS resource manager instance and to perform two-phase commit
+ * protocol. The ManagedConnection interface is not directly used
+ * by the transaction manager. More details on the XAResource
+ * interface are described in the JTA specification.
+ *
+ * <p>The LocalTransaction interface is used by the application server
+ * to manage local transactions.
+ *
+ * @version 0.5
+ * @author Rahul Sharma
+ * @see javax.resource.spi.ManagedConnectionFactory
+ * @see javax.transaction.xa.XAResource
+ * @see javax.resource.spi.LocalTransaction
+**/
- /**
- * Destroys the connection to the underlying resource.
- *
- * @throws ResourceException for a generic error
- * @throws IllegalStateException if the connection is not a legal state for destruction
- */
- public void destroy() throws ResourceException;
+public interface ManagedConnection {
+
+ /** Creates a new connection handle for the underlying physical connection
+ * represented by the ManagedConnection instance. This connection handle
+ * is used by the application code to refer to the underlying physical
+ * connection. This connection handle is associated with its
+ * ManagedConnection instance in a resource adapter implementation
+ * specific way.</P>
+ *
+ * <P>The ManagedConnection uses the Subject and additional ConnectionRequest
+ * Info (which is specific to resource adapter and opaque to application
+ * server) to set the state of the physical connection.</p>
+ *
+ * @param subject security context as JAAS subject
+ * @param cxRequestInfo ConnectionRequestInfo instance
+ * @return generic Object instance representing the connection
+ * handle. For CCI, the connection handle created by a
+ * ManagedConnection instance is of the type
+ * javax.resource.cci.Connection.
+ *
+ * @throws ResourceException generic exception if operation fails
+ * @throws ResourceAdapterInternalException
+ * resource adapter internal error condition
+ * @throws SecurityException security related error condition
+ * @throws CommException failed communication with EIS instance
+ * @throws EISSystemException internal error condition in EIS instance
+ * - used if EIS instance is involved in
+ * setting state of ManagedConnection
+ *
+ **/
+ public
+ Object getConnection(Subject subject,
+ ConnectionRequestInfo cxRequestInfo)
+ throws ResourceException;
- /**
- * Application server calls this to force cleanup of connection.
- * @throws ResourceException for a generic error
- * @throws ResourceAdapterInternalException for an internal error in the
- * resource adapter
- * @throws IllegalStateException if the connection is not a legal state for cleanup
- */
- public void cleanup() throws ResourceException;
+ /** Destroys the physical connection to the underlying resource manager.
+ *
+ * <p>To manage the size of the connection pool, an application server can
+ * explictly call ManagedConnection.destroy to destroy a
+ * physical connection. A resource adapter should destroy all allocated
+ * system resources for this ManagedConnection instance when the method
+ * destroy is called.
+ *
+ * @throws ResourceException generic exception if operation failed
+ * @throws IllegalStateException illegal state for destroying connection
+ **/
- /**
- * Associates a new application level connection handle with the connection.
- *
- * @param connection the connection
- * @throws ResourceException for a generic error
- * @throws IllegalStateException for an illegal state
- * @throws ResourceAdapterInternalException for an internal error in the
- * resource adapter
- */
- public void associateConnection(Object connection) throws ResourceException;
-
- /**
- * Adds a connection event listener
- *
- * @param listener the listener
- */
- public void addConnectionEventListener(ConnectionEventListener listener);
+ public
+ void destroy() throws ResourceException;
- /**
- * Removes a connection event listener
- *
- * @param listener the listener
- */
- public void removeConnectionEventListener(ConnectionEventListener listener);
+ /** Application server calls this method to force any cleanup on the
+ * ManagedConnection instance.
+ *
+ * <p>The method ManagedConnection.cleanup initiates a cleanup of the
+ * any client-specific state as maintained by a ManagedConnection instance.
+ * The cleanup should invalidate all connection handles that had been
+ * created using this ManagedConnection instance. Any attempt by an application
+ * component to use the connection handle after cleanup of the underlying
+ * ManagedConnection should result in an exception.
+ *
+ * <p>The cleanup of ManagedConnection is always driven by an application
+ * server. An application server should not invoke ManagedConnection.cleanup
+ * when there is an uncompleted transaction (associated with a
+ * ManagedConnection instance) in progress.
- /**
- * Returns an XAResource instance.
- *
- * @return the XAResource
- * @throws ResourceException for a generic error
- * @throws NotSupportedException if not supported
- * @throws ResourceAdapterInternalException for an internal error in the
- * resource adapter
- */
- public XAResource getXAResource() throws ResourceException;
-
- /**
- * Returns a LocalTransaction instance.
- *
- * @return the local transaction
- * @throws ResourceException for a generic error
- * @throws NotSupportedException if not supported
- * @throws ResourceAdapterInternalException for an internal error in the
- * resource adapter
- */
- public LocalTransaction getLocalTransaction() throws ResourceException;
+ * <p>The invocation of ManagedConnection.cleanup method on an already
+ * cleaned-up connection should not throw an exception.
+ *
+ * <p>The cleanup of ManagedConnection instance resets its client specific
+ * state and prepares the connection to be put back in to a connection
+ * pool. The cleanup method should not cause resource adapter to close
+ * the physical pipe and reclaim system resources associated with the
+ * physical connection.
+ *
+ * @throws ResourceException generic exception if operation fails
+ * @throws ResourceAdapterInternalException
+ * resource adapter internal error condition
+ * @throws IllegalStateException Illegal state for calling connection
+ * cleanup. Example - if a localtransaction
+ * is in progress that doesn't allow
+ * connection cleanup
+ *
+ **/
+ public
+ void cleanup() throws ResourceException;
- /**
- * Gets metadata inormation for this instances underlying resource manager
- * instance.
- *
- * @return the managed connection meta data
- * @throws ResourceException for a generic error
- * @throws NotSupportedException if not supported
- */
- public ManagedConnectionMetaData getMetaData() throws ResourceException;
-
- /**
- * Gets the logwriter for this instance.
- *
- * @return the log writer
- * @throws ResourceException for a generic error
- */
- public PrintWriter getLogWriter() throws ResourceException;
+ /** Used by the container to change the association of an
+ * application-level connection handle with a ManagedConneciton
+ * instance. The container should find the right ManagedConnection
+ * instance and call the associateConnection method.
+ *
+ * <p>The resource adapter is required to implement the associateConnection
+ * method. The method implementation for a ManagedConnection should
+ * dissociate the connection handle (passed as a parameter) from its
+ * currently associated ManagedConnection and associate the new
+ * connection handle with itself.
+ *
+ * @param connection Application-level connection handle
+ *
+ * @throws ResourceException Failed to associate the connection
+ * handle with this ManagedConnection
+ * instance
+ * @throws IllegalStateException Illegal state for invoking this
+ * method
+ * @throws ResourceAdapterInternalException
+ * Resource adapter internal error
+ * condition
+ *
+ **/
+ public
+ void associateConnection(Object connection)
+ throws ResourceException;
- /**
- * Sets the logwriter for this instance.
- *
- * @param out the writer
- * @throws ResourceException for a generic error
- * @throws ResourceAdapterInternalException for an internal error in the
- * resource adapter
- */
- public void setLogWriter(PrintWriter out) throws ResourceException;
-}
\ No newline at end of file
+
+
+ /** Adds a connection event listener to the ManagedConnection
+ * instance.
+ *
+ * <p>The registered ConnectionEventListener instances are notified of
+ * connection close and error events, also of local transaction related
+ * events on the Managed Connection.
+ *
+ * @param listener a new ConnectionEventListener to be registered
+ **/
+ public
+ void addConnectionEventListener(ConnectionEventListener listener);
+
+ /** Removes an already registered connection event listener from the
+ * ManagedConnection instance.
+ *
+ * @param listener already registered connection event listener to be
+ * removed
+ **/
+ public
+ void removeConnectionEventListener(
+ ConnectionEventListener listener);
+
+ /** Returns an <code>javax.transaction.xa.XAresource</code> instance.
+ * An application server enlists this XAResource instance with the
+ * Transaction Manager if the ManagedConnection instance is being used
+ * in a JTA transaction that is being coordinated by the Transaction
+ * Manager.
+ *
+ * @return XAResource instance
+ *
+ * @throws ResourceException generic exception if operation fails
+ * @throws NotSupportedException if the operation is not supported
+ * @throws ResourceAdapterInternalException
+ * resource adapter internal error condition
+ **/
+ public
+ XAResource getXAResource() throws ResourceException;
+
+ /** Returns an <code>javax.resource.spi.LocalTransaction</code> instance.
+ * The LocalTransaction interface is used by the container to manage
+ * local transactions for a RM instance.
+ *
+ * @return LocalTransaction instance
+ *
+ * @throws ResourceException generic exception if operation fails
+ * @throws NotSupportedException if the operation is not supported
+ * @throws ResourceAdapterInternalException
+ * resource adapter internal error condition
+ **/
+ public
+ LocalTransaction getLocalTransaction() throws ResourceException;
+
+ /** <p>Gets the metadata information for this connection's underlying
+ * EIS resource manager instance. The ManagedConnectionMetaData
+ * interface provides information about the underlying EIS instance
+ * associated with the ManagedConenction instance.
+ *
+ * @return ManagedConnectionMetaData instance
+ *
+ * @throws ResourceException generic exception if operation fails
+ * @throws NotSupportedException if the operation is not supported
+ **/
+ public
+ ManagedConnectionMetaData getMetaData() throws ResourceException;
+
+ /** Sets the log writer for this ManagedConnection instance.
+ *
+ * <p>The log writer is a character output stream to which all logging and
+ * tracing messages for this ManagedConnection instance will be printed.
+ * Application Server manages the association of output stream with the
+ * ManagedConnection instance based on the connection pooling
+ * requirements.</p>
+ *
+ * <p>When a ManagedConnection object is initially created, the default
+ * log writer associated with this instance is obtained from the
+ * ManagedConnectionFactory. An application server can set a log writer
+ * specific to this ManagedConnection to log/trace this instance using
+ * setLogWriter method.</p>
+ *
+ * @param out Character Output stream to be associated
+ *
+ * @throws ResourceException generic exception if operation fails
+ * @throws ResourceAdapterInternalException
+ * resource adapter related error condition
+ **/
+ public
+ void setLogWriter(java.io.PrintWriter out) throws ResourceException;
+
+ /** Gets the log writer for this ManagedConnection instance.
+ *
+ * <p>The log writer is a character output stream to which all logging and
+ * tracing messages for this ManagedConnection instance will be printed.
+ * ConnectionManager manages the association of output stream with the
+ * ManagedConnection instance based on the connection pooling
+ * requirements.</p>
+ *
+ * <p>The Log writer associated with a ManagedConnection instance can be
+ * one set as default from the ManagedConnectionFactory (that created
+ * this connection) or one set specifically for this instance by the
+ * application server.</p>
+ *
+ * @return Character ourput stream associated with this Managed-
+ * Connection instance
+ *
+ * @throws ResourceException generic exception if operation fails
+ **/
+ public
+ java.io.PrintWriter getLogWriter() throws ResourceException;
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ManagedConnectionFactory.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ManagedConnectionFactory.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ManagedConnectionFactory.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,107 +19,180 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
-import java.io.PrintWriter;
-import java.io.Serializable;
+import javax.security.auth.Subject;
import java.util.Set;
-
import javax.resource.ResourceException;
-import javax.security.auth.Subject;
+import javax.resource.NotSupportedException;
-/**
- * A ManagedConnectionFactory is a factory for the creation of
- * ManagedConnection objects and ConnectionFactory objects. It provides methods
- * which can be used to match ManagedConnetions.
+/**
+ * ManagedConnectionFactory instance is a factory of both ManagedConnection
+ * and EIS-specific connection factory instances. This interface supports
+ * connection pooling by providing methods for matching and creation of
+ * ManagedConnection instance. A ManagedConnectionFactory
+ * instance is required to be a JavaBean.
+ *
+ * @version 0.6
+ * @author Rahul Sharma
+ *
+ * @see javax.resource.spi.ManagedConnection
*/
-public interface ManagedConnectionFactory extends Serializable
-{
- /**
- * Creates a connection factory instance. The connection manager is provided
- * by the resource adapter.
- *
- * @return the connection factory
- * @throws ResourceException for a generic error
- * @throws ResourceAdapterInternalException for an internal error in the
- * resource adapter
- */
- public Object createConnectionFactory() throws ResourceException;
- /**
- * Creates a connection factory instance. the connection manager is provided
- * by the application server
- *
- * @param cxManager the connection manager
- * @return the connection factory
- * @throws ResourceException for a generic error
- * @throws ResourceAdapterInternalException for an internal error in the
- * resource adapter
- */
- public Object createConnectionFactory(ConnectionManager cxManager) throws ResourceException;
+public interface ManagedConnectionFactory extends java.io.Serializable {
- /**
- * Creates a new ManagedConnection
- *
- * @param subject the subject
- * @param cxRequestInfo the connection request info
- * @return the managed connection
- * @throws ResourceException for a generic error
- * @throws ResourceAllocationException for an error allocting resources
- * @throws ResourceAdapterInternalException for an internal error in the
- * resource adapter
- * @throws SecurityException for a security problem
- * @throws EISSystemException for an error from the EIS
- */
- public ManagedConnection createManagedConnection(Subject subject, ConnectionRequestInfo cxRequestInfo)
- throws ResourceException;
+ /**
+ * Creates a Connection Factory instance. The Connection Factory
+ * instance gets initialized with the passed ConnectionManager. In
+ * the managed scenario, ConnectionManager is provided by the
+ * application server.
+ *
+ * @param cxManager ConnectionManager to be associated with
+ * created EIS connection factory instance
+ * @return EIS-specific Connection Factory instance or
+ * javax.resource.cci.ConnectionFactory instance
+ *
+ * @throws ResourceException Generic exception
+ * @throws ResourceAdapterInternalException
+ * Resource adapter related error condition
+ */
+ public Object createConnectionFactory(ConnectionManager cxManager)
+ throws ResourceException;
- /**
- * Returns a matching connection from the set.
- *
- * @param connectionSet the connection set
- * @param subject the subject
- * @param cxRequestInfo the connection request info
- * @return the managed connection
- * @throws ResourceException for a generic error
- * @throws ResourceAdapterInternalException for an internal error in the
- * resource adapter
- * @throws SecurityException for a security problem
- * @throws NotSupportedException if not supported
- */
- public ManagedConnection matchManagedConnections(Set connectionSet, Subject subject,
- ConnectionRequestInfo cxRequestInfo) throws ResourceException;
+ /**
+ * Creates a Connection Factory instance. The Connection Factory
+ * instance gets initialized with a default ConnectionManager provided
+ * by the resource adapter.
+ *
+ * @return EIS-specific Connection Factory instance or
+ * javax.resource.cci.ConnectionFactory instance
+ *
+ * @throws ResourceException Generic exception
+ * @throws ResourceAdapterInternalException
+ * Resource adapter related error condition
+ */
+ public Object createConnectionFactory() throws ResourceException;
- /**
- * Gets the logwriter for this instance.
- *
- * @return the log writer
- * @throws ResourceException for a generic error
- */
- public PrintWriter getLogWriter() throws ResourceException;
-
- /**
- * Sets the logwriter for this instance.
- *
- * @param out the log writer
- * @throws ResourceException for a generic error
- * @throws ResourceAdapterInternalException for an internal error in the
- * resource adapter
- */
- public void setLogWriter(PrintWriter out) throws ResourceException;
-
- /**
- * Tests object for equality
- *
- * @param other the other object
- * @return true when equals, false otherwise
- */
- public boolean equals(Object other);
+
+ /**
+ * Creates a new physical connection to the underlying EIS
+ * resource manager.
+ *
+ * <p>ManagedConnectionFactory uses the security information (passed as
+ * Subject) and additional ConnectionRequestInfo (which is specific to
+ * ResourceAdapter and opaque to application server) to create this new
+ * connection.
+ *
+ * @param subject Caller's security information
+ * @param cxRequestInfo Additional resource adapter specific connection
+ * request information
+ *
+ * @throws ResourceException generic exception
+ * @throws SecurityException security related error
+ * @throws ResourceAllocationException
+ * failed to allocate system resources for
+ * connection request
+ * @throws ResourceAdapterInternalException
+ * resource adapter related error condition
+ * @throws EISSystemException internal error condition in EIS instance
+ *
+ * @return ManagedConnection instance
+ */
+ public ManagedConnection createManagedConnection(
+ Subject subject,
+ ConnectionRequestInfo cxRequestInfo)
+ throws ResourceException;
- /**
- * Generates a hashCode for this object
- *
- * @return the hash code
- */
- public int hashCode();
-}
\ No newline at end of file
+ /**
+ * Returns a matched connection from the candidate set of connections.
+ *
+ *
+ * <p>ManagedConnectionFactory uses the security info (as in Subject)
+ * and information provided through ConnectionRequestInfo and additional
+ * Resource Adapter specific criteria to do matching. Note that criteria
+ * used for matching is specific to a resource adapter and is not
+ * prescribed by the Connector specification.</p>
+ *
+ * <p>This method returns a ManagedConnection instance that is the best
+ * match for handling the connection allocation request.</p>
+ *
+ * @param connectionSet candidate connection set
+ * @param subject caller's security information
+ * @param cxRequestInfo additional resource adapter specific
+ * connection request information
+ *
+ * @throws ResourceException generic exception
+ * @throws SecurityException security related error
+ * @throws ResourceAdapterInternalException
+ * resource adapter related error condition
+ * @throws NotSupportedException if operation is not supported
+ *
+ * @return ManagedConnection if resource adapter finds an
+ * acceptable match otherwise null
+ **/
+ public ManagedConnection matchManagedConnections(
+ Set connectionSet,
+ Subject subject,
+ ConnectionRequestInfo cxRequestInfo)
+ throws ResourceException;
+
+ /**
+ * Set the log writer for this ManagedConnectionFactory instance.</p>
+ *
+ * <p>The log writer is a character output stream to which all logging and
+ * tracing messages for this ManagedConnectionfactory instance will be
+ * printed.</p>
+ *
+ * <p>ApplicationServer manages the association of output stream with the
+ * ManagedConnectionFactory. When a ManagedConnectionFactory object is
+ * created the log writer is initially null, in other words, logging is
+ * disabled. Once a log writer is associated with a
+ * ManagedConnectionFactory, logging and tracing for
+ * ManagedConnectionFactory instance is enabled.
+ *
+ * <p>The ManagedConnection instances created by ManagedConnectionFactory
+ * "inherits" the log writer, which can be overridden by ApplicationServer
+ * using ManagedConnection.setLogWriter to set ManagedConnection specific
+ * logging and tracing.
+ *
+ * @param out PrintWriter - an out stream for
+ * error logging and tracing
+ * @throws ResourceException generic exception
+ * @throws ResourceAdapterInternalException
+ * resource adapter related error condition
+ */
+ public void setLogWriter(java.io.PrintWriter out) throws ResourceException;
+
+ /**
+ * Get the log writer for this ManagedConnectionFactory instance.
+ *
+ * <p>The log writer is a character output stream to which all logging and
+ * tracing messages for this ManagedConnectionFactory instance will be
+ * printed
+ *
+ * <p>ApplicationServer manages the association of output stream with the
+ * ManagedConnectionFactory. When a ManagedConnectionFactory object is
+ * created the log writer is initially null, in other words, logging is
+ * disabled.
+ *
+ * @return PrintWriter
+ * @throws ResourceException generic exception
+ */
+ public java.io.PrintWriter getLogWriter() throws ResourceException;
+
+ /**
+ * Returns the hash code for the ManagedConnectionFactory
+ *
+ * @return hash code for the ManagedConnectionFactory
+ */
+ public int hashCode();
+
+ /**
+ * Check if this ManagedConnectionFactory is equal to another
+ * ManagedConnectionFactory.
+ *
+ * @return true if two instances are equal
+ */
+ public boolean equals(Object other);
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ManagedConnectionMetaData.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ManagedConnectionMetaData.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ManagedConnectionMetaData.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,48 +19,59 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
import javax.resource.ResourceException;
-/**
- * The ManagedConnectionMetaData interface provides information about the
- * underlying resource associated with a ManagedConnetion. The Application
- * Server can use this information to get information at runtime from the
- * underlying resource.
- */
-public interface ManagedConnectionMetaData
-{
- /**
- * Returns product name of the underlying resource.
- *
- * @return the product name
- * @throws ResourceException for a generic error
- */
- public String getEISProductName() throws ResourceException;
+/** The ManagedConnectionMetaData interface provides information about the
+ * underlying EIS instance associated with a ManagedConnection instance.
+ * An application server uses this information to get runtime information
+ * about a connected EIS instance.
+ *
+ * <p>The method ManagedConnection.getMetaData returns a
+ * ManagedConnectionMetaData instance.
+ *
+ * @version 0.8
+ * @author Rahul Sharma
+ * @see javax.resource.spi.ManagedConnection
+**/
- /**
- * Returns product version of the underlying resource.
- *
- * @return the product version
- * @throws ResourceException for a generic error
- */
- public String getEISProductVersion() throws ResourceException;
+public interface ManagedConnectionMetaData {
- /**
- * Returns the maximum supported number of connections allowed to the
- * underlying resource.
- *
- * @return the maximum number of connections
- * @throws ResourceException for a generic error
- */
- public int getMaxConnections() throws ResourceException;
+ /** Returns Product name of the underlying EIS instance connected
+ * through the ManagedConnection.
+ *
+ * @return Product name of the EIS instance.
+ **/
+ public
+ String getEISProductName() throws ResourceException;
- /**
- * Returns user name associated with the underlying connection.
- *
- * @return the user name
- * @throws ResourceException for a generic error
- */
- public String getUserName() throws ResourceException;
-}
\ No newline at end of file
+ /** Returns product version of the underlying EIS instance connected
+ * through the ManagedConnection.
+ *
+ * @return Product version of the EIS instance
+ **/
+ public
+ String getEISProductVersion() throws ResourceException;
+
+ /** Returns maximum limit on number of active concurrent connections
+ * that an EIS instance can support across client processes. If an EIS
+ * instance does not know about (or does not have) any such limit, it
+ * returns a 0.
+ *
+ * @return Maximum limit for number of active concurrent connections
+ **/
+ public
+ int getMaxConnections() throws ResourceException;
+
+ /** Returns name of the user associated with the ManagedConnection
+ * instance. The name corresponds to the resource principal under whose
+ * whose security context, a connection to the EIS instance has been
+ * established.
+ *
+ * @return name of the user
+ **/
+ public
+ String getUserName() throws ResourceException;
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ResourceAdapter.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ResourceAdapter.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ResourceAdapter.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,55 +19,132 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
import javax.resource.ResourceException;
+import javax.resource.NotSupportedException;
+import javax.resource.spi.ActivationSpec;
import javax.resource.spi.endpoint.MessageEndpointFactory;
+
import javax.transaction.xa.XAResource;
/**
- * Operations for lifecycle management and message endpoint configuration.
- * Implementations of this interface must be javabeans
+ * This represents a resource adapter instance and contains operations for
+ * lifecycle management and message endpoint setup. A concrete implementation
+ * of this interface is required to be a JavaBean.
+ *
+ * @version 1.0
+ * @author Ram Jeyaraman
*/
-public interface ResourceAdapter
-{
- /**
- * Used to bootstrap the resource adapter
- *
- * @param ctx the bootstrap context
- * @throws ResourceAdapterInternalException for a bootstrap failure
- */
- void start(BootstrapContext ctx) throws ResourceAdapterInternalException;
+public interface ResourceAdapter {
- /**
- * Used to stop the resource adapter
- */
- void stop();
-
- /**
- * Activates the endpoint factory
- *
- * @param endpointFactory the endpoint factory
- * @param spec the activation spec
- * @throws ResourceException for a generic error
- * @throws NotSupportedException for incorrect activation
- */
- void endpointActivation(MessageEndpointFactory endpointFactory, ActivationSpec spec) throws ResourceException;
-
- /**
- * Deactivates the endpoint
- *
- * @param endpointFactory the endpoint factory
- * @param spec the activation spec
- */
- void endpointDeactivation(MessageEndpointFactory endpointFactory, ActivationSpec spec);
-
- /**
- * Called by the application server during recovery
- *
- * @param specs the activation specs
- * @return the XAResources used to perform the recovery
- * @throws ResourceException for a generic error
- */
- XAResource[] getXAResources(ActivationSpec[] specs) throws ResourceException;
-}
\ No newline at end of file
+ // lifecycle operations
+
+ /**
+ * This is called when a resource adapter instance is bootstrapped. This
+ * may be during resource adapter deployment or application server startup.
+ * This is a startup notification from the application server, and this
+ * method is called by an application server thread. The application server
+ * thread executes in an unspecified context.
+ *
+ * <p>During this method call a ResourceAdapter JavaBean is
+ * responsible for initializing the resource adapter
+ * instance. Any exception thrown during this method
+ * call causes the application server to abort the bootstrap procedure
+ * for this specific resource adapter instance.
+ *
+ * @param ctx a bootstrap context containing references to
+ * useful facilities that could be used by a resource adapter instance.
+ *
+ * @throws ResourceAdapterInternalException indicates bootstrap failure.
+ * The resource adapter instance is unusable and must be discarded.
+ */
+ void start(BootstrapContext ctx) throws ResourceAdapterInternalException;
+
+ /**
+ * This is called when a resource adapter instance is undeployed or
+ * during application server shutdown. This is a shutdown notification
+ * from the application server, and this method is called by an
+ * application server thread. The application server
+ * thread executes in an unspecified context.
+ *
+ * <p>During this method call, a ResourceAdapter
+ * JavaBean is responsible for performing an orderly shutdown of the
+ * resource adapter instance. Any exception thrown by this
+ * method call does not alter the
+ * processing of the application server shutdown or resource
+ * adapter undeployment that caused this method call. The application
+ * server may log the exception information for error reporting purposes.
+ */
+ void stop();
+
+ // message endpoint setup operations
+
+ /**
+ * This is called during the activation of a message endpoint. This causes
+ * the resource adapter instance to do the necessary setup (ie., setup
+ * message delivery for the message endpoint with a message provider).
+ * Note that message delivery to the message endpoint might start even
+ * before this method returns.
+ *
+ * <p>Endpoint activation is deemed successful only when this method
+ * completes successfully without throwing any exceptions.
+ *
+ * @param endpointFactory a message endpoint factory instance.
+ *
+ * @param spec an activation spec JavaBean instance.
+ *
+ * @throws NotSupportedException indicates message endpoint
+ * activation rejection due to incorrect activation
+ * setup information.
+ */
+ void endpointActivation(MessageEndpointFactory endpointFactory,
+ ActivationSpec spec) throws ResourceException;
+
+ /**
+ * This is called when a message endpoint is deactivated. The instances
+ * passed as arguments to this method call should be identical to those
+ * passed in for the corresponding </code>endpointActivation</code> call.
+ * This causes the resource adapter to stop delivering messages to the
+ * message endpoint.
+ *
+ * <p>Any exception thrown by this method is ignored. After
+ * this method call, the endpoint is deemed inactive.
+ *
+ * @param endpointFactory a message endpoint factory instance.
+ *
+ * @param spec an activation spec JavaBean instance.
+ */
+ void endpointDeactivation(MessageEndpointFactory endpointFactory,
+ ActivationSpec spec);
+
+ /**
+ * This method is called by the application server during crash recovery.
+ * This method takes in an array of <code>ActivationSpec</code> JavaBeans
+ * and returns an array of <code>XAResource</code> objects each of which
+ * represents a unique resource manager.
+ *
+ * The resource adapter may return null if it does not implement the
+ * <code>XAResource</code> interface. Otherwise, it must return an array
+ * of <code>XAResource</code> objects, each of which represents a unique
+ * resource manager that was used by the endpoint applications.
+ *
+ * The application server uses the <code>XAResource</code> objects to
+ * query each resource manager for a list of in-doubt transactions.
+ * It then completes each pending transaction by sending the commit
+ * decision to the participating resource managers.
+ *
+ * @param specs an array of <code>ActivationSpec</code> JavaBeans each of
+ * which corresponds to an deployed endpoint application that was
+ * active prior to the system crash.
+ *
+ * @throws ResourceException generic exception if operation fails due to an
+ * error condition.
+ *
+ * @return an array of <code>XAResource</code> objects each of which
+ * represents a unique resource manager.
+ */
+ XAResource[] getXAResources(ActivationSpec[] specs)
+ throws ResourceException;
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ResourceAdapterAssociation.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ResourceAdapterAssociation.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ResourceAdapterAssociation.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,30 +19,45 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
import javax.resource.ResourceException;
/**
- * Interface used to associate the resource adapter with objects that implement
- * this interface.
+ * This interface specifies the methods to associate a
+ * <code>ResourceAdapter</code> object with other objects that
+ * implement this interface like
+ * <code>ManagedConnectionFactory</code> and <code>ActivationSpec</code>.
+ *
+ * @version 1.0
+ * @author Ram Jeyaraman
*/
-public interface ResourceAdapterAssociation
-{
- /**
- * Retrieve the resource adapter
- *
- * @return the resource adapter
- */
- ResourceAdapter getResourceAdapter();
+public interface ResourceAdapterAssociation {
- /**
- * Set the resource adapter
- *
- * @param the resource adapter
- * @throws ResourceException for any error
- * @throws ResourceAdapterInternalException for an error in the resource adapter
- * @throws IllegalStateException if invoked more than once
- */
- void setResourceAdapter(ResourceAdapter ra) throws ResourceException;
-}
\ No newline at end of file
+ /**
+ * Get the associated <code>ResourceAdapter</code> object.
+ *
+ * @return the associated <code>ResourceAdapter</code> object.
+ */
+ ResourceAdapter getResourceAdapter();
+
+ /**
+ * Associate this object with a <code>ResourceAdapter</code> object.
+ * Note, this method must be called exactly once. That is, the
+ * association must not change during the lifetime of this object.
+ *
+ * @param ra <code>ResourceAdapter</code> object to be associated with.
+ *
+ * @throws ResourceException generic exception.
+ *
+ * @throws ResourceAdapterInternalException
+ * resource adapter related error condition.
+ *
+ * @throws IllegalStateException indicates that this object is in an
+ * illegal state for the method invocation. For example, this occurs when
+ * this method is called more than once on the same object.
+ */
+ void setResourceAdapter(ResourceAdapter ra) throws ResourceException;
+}
+
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ResourceAdapterInternalException.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ResourceAdapterInternalException.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ResourceAdapterInternalException.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,60 +19,72 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
-import javax.resource.ResourceException;
-
-/**
- * A ResourceAdapterInternalException indicates any system level error
- * conditions related to a resource adapter. Examples are invalid
- * configuration, failure to create a connection to an underlying resource,
- * other error condition internal to the resource adapter.
+/**
+ * A <code>ResourceAdapterInternalException</code> indicates any
+ * system-level error conditions related to a resource adapter.
+ * The common conditions indicated by this exception type are:
+ * <UL>
+ * <LI>Invalid configuration for creation of a new physical connection. An
+ example is invalid server name for a target EIS instance.
+ * <LI>Failure to create a physical connection to a EIS instance due to
+ * communication protocol error or any resource adapter implementation
+ * specific error.
+ * <LI>Error conditions internal to resource adapter implementation.
+ * </UL>
+ *
+ * @version 1.0
+ * @author Rahul Sharma
+ * @author Ram Jeyaraman
*/
-public class ResourceAdapterInternalException extends ResourceException
-{
- /**
- * Create an exception.
- */
- public ResourceAdapterInternalException()
- {
- super();
- }
-
- /**
- * Create an exception with a reason.
- */
- public ResourceAdapterInternalException(String reason)
- {
- super(reason);
- }
- /**
- * Create an exception with a reason and an errorCode.
- */
- public ResourceAdapterInternalException(String reason, String errorCode)
- {
- super(reason, errorCode);
- }
+public class ResourceAdapterInternalException
+ extends javax.resource.ResourceException {
- /**
- * Create an exception with a reason and cause.
- *
- * @param reason the reason
- * @param cause the cause
- */
- public ResourceAdapterInternalException(String reason, Throwable cause)
- {
- super(reason, cause);
- }
+ /**
+ * Constructs a new instance with null as its detail message.
+ */
+ public ResourceAdapterInternalException() { super(); }
- /**
- * Create an exception with a cause.
- *
- * @param cause the cause
- */
- public ResourceAdapterInternalException(Throwable cause)
- {
- super(cause);
- }
-}
\ No newline at end of file
+ /**
+ * Constructs a new instance with the specified detail message.
+ *
+ * @param message the detail message.
+ */
+ public ResourceAdapterInternalException(String message) {
+ super(message);
+ }
+
+ /**
+ * Constructs a new throwable with the specified cause.
+ *
+ * @param cause a chained exception of type <code>Throwable</code>.
+ */
+ public ResourceAdapterInternalException(Throwable cause) {
+ super(cause);
+ }
+
+ /**
+ * Constructs a new throwable with the specified detail message and cause.
+ *
+ * @param message the detail message.
+ *
+ * @param cause a chained exception of type <code>Throwable</code>.
+ */
+ public ResourceAdapterInternalException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ /**
+ * Constructs a new throwable with the specified detail message and
+ * an error code.
+ *
+ * @param message a description of the exception.
+ * @param errorCode a string specifying the vendor specific error code.
+ */
+ public ResourceAdapterInternalException(String message, String errorCode) {
+ super(message, errorCode);
+ }
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ResourceAllocationException.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ResourceAllocationException.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ResourceAllocationException.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,57 +19,68 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
-import javax.resource.ResourceException;
-
/**
- * A ResourceAllocationException can be thrown to indicate a failure to
- * allocate system resources such as threads or physical connections.
+ * A <code>ResourceAllocationException</code> can be thrown by an
+ * application server or
+ * resource adapter to indicate any failure to allocate system resources
+ * (example: threads, physical connections). An example is error condition
+ * when an upper bound is reached on the maximum number of physical
+ * connections that can be managed by an application server specific
+ * connection pool.
+ *
+ * @version 1.0
+ * @author Rahul Sharma
+ * @author Ram Jeyaraman
*/
-public class ResourceAllocationException extends ResourceException
-{
- /**
- * Create an exception.
- */
- public ResourceAllocationException()
- {
- super();
- }
- /**
- * Create an exception with a reason.
- */
- public ResourceAllocationException(String reason)
- {
- super(reason);
- }
- /**
- * Create an exception with a reason and an errorCode.
- */
- public ResourceAllocationException(String reason, String errorCode)
- {
- super(reason, errorCode);
- }
+public class ResourceAllocationException
+ extends javax.resource.ResourceException {
- /**
- * Create an exception with a reason and cause.
- *
- * @param reason the reason
- * @param cause the cause
- */
- public ResourceAllocationException(String reason, Throwable cause)
- {
- super(reason, cause);
- }
+ /**
+ * Constructs a new instance with null as its detail message.
+ */
+ public ResourceAllocationException() { super(); }
- /**
- * Create an exception with a cause.
- *
- * @param cause the cause
- */
- public ResourceAllocationException(Throwable cause)
- {
- super(cause);
- }
-}
\ No newline at end of file
+ /**
+ * Constructs a new instance with the specified detail message.
+ *
+ * @param message the detail message.
+ */
+ public ResourceAllocationException(String message) {
+ super(message);
+ }
+
+ /**
+ * Constructs a new throwable with the specified cause.
+ *
+ * @param cause a chained exception of type <code>Throwable</code>.
+ */
+ public ResourceAllocationException(Throwable cause) {
+ super(cause);
+ }
+
+ /**
+ * Constructs a new throwable with the specified detail message and cause.
+ *
+ * @param message the detail message.
+ *
+ * @param cause a chained exception of type <code>Throwable</code>.
+ */
+ public ResourceAllocationException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ /**
+ * Constructs a new throwable with the specified detail message and
+ * an error code.
+ *
+ * @param message a description of the exception.
+ * @param errorCode a string specifying the vendor specific error code.
+ */
+ public ResourceAllocationException(String message, String errorCode) {
+ super(message, errorCode);
+ }
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/SecurityException.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/SecurityException.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/SecurityException.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,60 +19,78 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
-import javax.resource.ResourceException;
-
-/**
- * A SecurityException indicates error conditions related to the security
- * contract between an application server and a resource adapter. Common types
- * of conditions represented by this exception include: invalid security
- * information - subject, failure to connect, failure to authenticate, access
- * control exception.
+/**
+ * A <code>SecurityException</code> indicates error conditions
+ * related to the security
+ * contract between an application server and resource adapter. The common
+ * error conditions represented by this exception are:
+ * <UL>
+ * <LI>Invalid security information (represented as a Subject instance) passed
+ * across the security contract - for example, credentials have expired or
+ * have invalid format.
+ * <LI>Lack of support for a specific security mechanism in an EIS or resource
+ * adapter.
+ * <LI>Failure to create a connection to an EIS because of failed
+ * authentication or authorization.
+ * <LI>Failure to authenticate a resource principal to an EIS instance
+ * or failure
+ * to establish a secure association with an underlying EIS instance.
+ * <LI>Access control exception to indicate that a requested access to an EIS
+ * resource or a request to create a new connection is denied.
+ * </UL>
+ *
+ * @version 1.0
+ * @author Rahul Sharma
+ * @author Ram Jeyaraman
*/
-public class SecurityException extends ResourceException
-{
- /**
- * Create an exception.
- */
- public SecurityException()
- {
- super();
- }
- /**
- * Create an exception with a reason.
- */
- public SecurityException(String reason)
- {
- super(reason);
- }
- /**
- * Create an exception with a reason and an errorCode.
- */
- public SecurityException(String reason, String errorCode)
- {
- super(reason, errorCode);
- }
+public class SecurityException extends javax.resource.ResourceException {
- /**
- * Create an exception with a reason and cause.
- *
- * @param reason the reason
- * @param cause the cause
- */
- public SecurityException(String reason, Throwable cause)
- {
- super(reason, cause);
- }
+ /**
+ * Constructs a new instance with null as its detail message.
+ */
+ public SecurityException() { super(); }
- /**
- * Create an exception with a cause.
- *
- * @param cause the cause
- */
- public SecurityException(Throwable cause)
- {
- super(cause);
- }
-}
\ No newline at end of file
+ /**
+ * Constructs a new instance with the specified detail message.
+ *
+ * @param message the detail message.
+ */
+ public SecurityException(String message) {
+ super(message);
+ }
+
+ /**
+ * Constructs a new throwable with the specified cause.
+ *
+ * @param cause a chained exception of type <code>Throwable</code>.
+ */
+ public SecurityException(Throwable cause) {
+ super(cause);
+ }
+
+ /**
+ * Constructs a new throwable with the specified detail message and cause.
+ *
+ * @param message the detail message.
+ *
+ * @param cause a chained exception of type <code>Throwable</code>.
+ */
+ public SecurityException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ /**
+ * Constructs a new throwable with the specified detail message and
+ * an error code.
+ *
+ * @param message a description of the exception.
+ * @param errorCode a string specifying the vendor specific error code.
+ */
+ public SecurityException(String message, String errorCode) {
+ super(message, errorCode);
+ }
+}
Added: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/SecurityPermission.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/SecurityPermission.java (rev 0)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/SecurityPermission.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -0,0 +1,56 @@
+/*
+* JBoss, Home of Professional Open Source
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
+* by the @authors tag. See the copyright.txt in the distribution for a
+* full listing of individual contributors.
+*
+* This is free software; you can redistribute it and/or modify it
+* under the terms of the GNU Lesser General Public License as
+* published by the Free Software Foundation; either version 2.1 of
+* the License, or (at your option) any later version.
+*
+* This software is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+* Lesser General Public License for more details.
+*
+* You should have received a copy of the GNU Lesser General Public
+* License along with this software; if not, write to the Free
+* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+*/
+
+package javax.resource.spi;
+
+import java.lang.annotation.Target;
+import static java.lang.annotation.ElementType.*;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Documented;
+import static java.lang.annotation.RetentionPolicy.*;
+
+/**
+ * The SecurityPermission annotation can be used by the developer, as part of
+ * the Connector annotation, to specify the extended security permissions
+ * required by the resource adapter
+ *
+ * @since 1.6
+ * @version JSR322-PublicReview
+ */
+
+ at Documented
+ at Retention(RUNTIME)
+ at Target(TYPE)
+public @interface SecurityPermission {
+ /**
+ * Specifies an optional description to mention any specific reason that a
+ * resource requires a given security permission.
+ */
+ String description() default "";
+
+ /**
+ * Specifies a security permission based on the Security policy file syntax.
+ * These security permissions are different from those required by the
+ * default permission set as specified in the connector specification.
+ */
+ String permissionSpec() default "";
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/SharingViolationException.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/SharingViolationException.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/SharingViolationException.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,62 +19,65 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
-import javax.resource.ResourceException;
-
/**
- * Thrown when a shared connection is used in an unshareable manner.
+ * This is thrown to indicate a connection sharing violation.
+ *
+ * <p>This may be thrown by a resource adapter when an application
+ * uses a shareable connection in an unshareable manner.
+ *
+ * @version 1.0
+ * @author Ram Jeyaraman
*/
-public class SharingViolationException extends ResourceException
-{
- /**
- * Create an exception.
- */
- public SharingViolationException()
- {
- super();
- }
+public class SharingViolationException
+ extends javax.resource.ResourceException {
- /**
- * Create an exception with a reason.
- *
- * @param reason the reason
- */
- public SharingViolationException(String reason)
- {
- super(reason);
- }
+ /**
+ * Constructs a new instance with null as its detail message.
+ */
+ public SharingViolationException() { super(); }
- /**
- * Create an exception with a reason and an errorCode.
- *
- * @param reason the reason
- * @param errorCode the error code
- */
- public SharingViolationException(String reason, String errorCode)
- {
- super(reason, errorCode);
- }
+ /**
+ * Constructs a new instance with the specified detail message.
+ *
+ * @param message the detail message.
+ */
+ public SharingViolationException(String message) {
+ super(message);
+ }
- /**
- * Create an exception with a reason and an error.
- *
- * @param reason the reason
- * @param throwable the error
- */
- public SharingViolationException(String reason, Throwable throwable)
- {
- super(reason, throwable);
- }
+ /**
+ * Constructs a new throwable with the specified cause.
+ *
+ * @param cause a chained exception of type
+ * <code>Throwable</code>.
+ */
+ public SharingViolationException(Throwable cause) {
+ super(cause);
+ }
- /**
- * Create an exception with an error.
- *
- * @param throwable the error
- */
- public SharingViolationException(Throwable throwable)
- {
- super(throwable);
- }
-}
\ No newline at end of file
+ /**
+ * Constructs a new throwable with the specified detail message and cause.
+ *
+ * @param message the detail message.
+ *
+ * @param cause a chained exception of type
+ * <code>Throwable</code>.
+ */
+ public SharingViolationException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ /**
+ * Constructs a new throwable with the specified detail message and
+ * error code.
+ *
+ * @param message a description of the exception.
+ * @param errorCode a string specifying the vendor specific error code.
+ */
+ public SharingViolationException(String message, String errorCode) {
+ super(message, errorCode);
+ }
+}
Added: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/TransactionSupport.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/TransactionSupport.java (rev 0)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/TransactionSupport.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -0,0 +1,79 @@
+/*
+* JBoss, Home of Professional Open Source
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
+* by the @authors tag. See the copyright.txt in the distribution for a
+* full listing of individual contributors.
+*
+* This is free software; you can redistribute it and/or modify it
+* under the terms of the GNU Lesser General Public License as
+* published by the Free Software Foundation; either version 2.1 of
+* the License, or (at your option) any later version.
+*
+* This software is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+* Lesser General Public License for more details.
+*
+* You should have received a copy of the GNU Lesser General Public
+* License along with this software; if not, write to the Free
+* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+*/
+
+package javax.resource.spi;
+
+/**
+ * This interface may be optionally implemented by a
+ * <code>ManagedConnectionFactory</code> to provide its level of transaction
+ * support at runtime.
+ *
+ * <p>When a <code>ManagedConnectionFactory</code> implements this interface,
+ * the application server uses the <code>TransactionSupportLevel</code> returned
+ * by getTransactionSupport() method and not the value specified in the
+ * resource adapter deployment descriptor or deployer configuration
+ *
+ * @since 1.6
+ * @version JSR322-EarlyDraft
+ */
+public interface TransactionSupport extends java.io.Serializable {
+
+ /**
+ * An enumerated type that represents the levels of transaction support
+ * a resource adapter may support.
+ *
+ * @since 1.6
+ * @version JSR322-EarlyDraft
+ */
+ public enum TransactionSupportLevel {
+ /**
+ * The resource adapter supports neither resource manager nor JTA
+ * transactions.
+ * @since 1.6
+ */
+ NoTransaction,
+ /**
+ * The resource adapter supports resource manager local transactions
+ * by implementing the <code>LocalTransaction</code> interface.
+ * @since 1.6
+ */
+ LocalTansaction,
+ /**
+ * The resource adapter supports both resource manager local
+ * and JTA transactions by implementing the <code>LocalTransaction</code>
+ * and <code>XAResource</code> interfaces.
+ * @since 1.6
+ */
+ XATransaction
+ };
+
+ /**
+ * Get the level of transaction support, supported by the
+ * <code>ManagedConnectionFactory</code>. A resource adapter must always
+ * return a level of transaction support whose ordinal value in
+ * <code>TransactionSupportLevel</code> enum is equal to or lesser than
+ * the resource adapter's transaction support classification.
+ *
+ * @since 1.6
+ */
+ public TransactionSupportLevel getTransactionSupport();
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/UnavailableException.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/UnavailableException.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/UnavailableException.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,62 +19,61 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
-import javax.resource.ResourceException;
-
/**
- * Thrown when a service is unavailable
+ * This is thrown to indicate that a service is unavailable.
+ *
+ * @version 1.0
+ * @author Ram Jeyaraman
*/
-public class UnavailableException extends ResourceException
-{
- /**
- * Create an unavailable exception.
- */
- public UnavailableException()
- {
- super();
- }
+public class UnavailableException extends javax.resource.ResourceException {
- /**
- * Create an unavailable exception with a reason.
- *
- * @param reason the reason
- */
- public UnavailableException(String reason)
- {
- super(reason);
- }
+ /**
+ * Constructs a new instance with null as its detail message.
+ */
+ public UnavailableException() { super(); }
- /**
- * Create an unavailable exception with a reason and an errorCode.
- *
- * @param reason the reason
- * @param errorCode the error code
- */
- public UnavailableException(String reason, String errorCode)
- {
- super(reason, errorCode);
- }
+ /**
+ * Constructs a new instance with the specified detail message.
+ *
+ * @param message the detail message.
+ */
+ public UnavailableException(String message) {
+ super(message);
+ }
- /**
- * Create an unavailable exception with a reason and an error.
- *
- * @param reason the reason
- * @param throwable the error
- */
- public UnavailableException(String reason, Throwable throwable)
- {
- super(reason, throwable);
- }
+ /**
+ * Constructs a new throwable with the specified cause.
+ *
+ * @param cause a chained exception of type
+ * <code>Throwable</code>.
+ */
+ public UnavailableException(Throwable cause) {
+ super(cause);
+ }
- /**
- * Create an unavailable exception with an error.
- *
- * @param throwable the error
- */
- public UnavailableException(Throwable throwable)
- {
- super(throwable);
- }
-}
\ No newline at end of file
+ /**
+ * Constructs a new throwable with the specified detail message and cause.
+ *
+ * @param message the detail message.
+ *
+ * @param cause a chained exception of type
+ * <code>Throwable</code>.
+ */
+ public UnavailableException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ /**
+ * Constructs a new throwable with the specified detail message and
+ * an error code.
+ *
+ * @param message a description of the exception.
+ * @param errorCode a string specifying the vendor specific error code.
+ */
+ public UnavailableException(String message, String errorCode) {
+ super(message, errorCode);
+ }
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ValidatingManagedConnectionFactory.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ValidatingManagedConnectionFactory.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/ValidatingManagedConnectionFactory.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,23 +19,43 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
import java.util.Set;
-
import javax.resource.ResourceException;
-/**
- * A mixin interface for connection factories that can validate their managed connections
- */
-public interface ValidatingManagedConnectionFactory
-{
- /**
- * Returns the invalid connections in a set
- *
- * @param connectionSet the set of connections to validate
- * @return the set of invalid connections
- * @throws ResourceException for a generic error
- */
- Set getInvalidConnections(Set connectionSet) throws ResourceException;
-}
\ No newline at end of file
+/**
+ * This interface is implemented by a <code>ManagedConnectionFactory</code>
+ * instance that supports the ability to validate
+ * <code>ManagedConnection</code> objects.
+ *
+ * <p>This may be used by the application server to prune invalid
+ * <code>ManagedConnection</code> objects from its connection pool.
+ *
+ * <p>The application server may use this functionality to test the
+ * validity of a <code>ManagedConnection</code> by passing in a
+ * <code>Set</code> of size one( with the <code>ManagedConnection</code>
+ * that has to be tested for validity as the only member of the
+ * <code>Set</code>.
+ *
+ *
+ * @author Ram Jeyaraman
+ * @version 1.0
+ */
+public interface ValidatingManagedConnectionFactory {
+
+ /**
+ * This method returns a set of invalid <code>ManagedConnection</code>
+ * objects chosen from a specified set of <code>ManagedConnection</code>
+ * objects.
+ *
+ * @param connectionSet a set of <code>ManagedConnection</code> objects
+ * that need to be validated.
+ *
+ * @return a set of invalid <code>ManagedConnection</code> objects.
+ *
+ * @throws ResourceException generic exception.
+ */
+ Set getInvalidConnections(Set connectionSet) throws ResourceException;
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/XATerminator.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/XATerminator.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/XATerminator.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,55 +19,111 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi;
+import javax.transaction.xa.Xid;
import javax.transaction.xa.XAException;
-import javax.transaction.xa.Xid;
-/**
- * Transaction completion and crash recovery
+/**
+ * <p>The XATerminator interface is used for transaction completion and
+ * crash recovery flows.
+ *
+ * @version 1.0
+ * @author Ram Jeyaraman
+ *
*/
-public interface XATerminator
-{
- /**
- * Commit the transaction
- *
- * @param xid the xid
- * @param onePhase true for one phase commit, false for two phase
- * @throws XAException for an error
- */
- void commit(Xid xid, boolean onePhase) throws XAException;
+public interface XATerminator {
- /**
- * Forget the transaction
- *
- * @param xid the xid
- * @throws XAException for an error
- */
- void forget(Xid xid) throws XAException;
+ /**
+ * Commits the global transaction specified by xid.
+ *
+ * @param xid A global transaction identifier
+ *
+ * @param onePhase If true, the resource manager should use a one-phase
+ * commit protocol to commit the work done on behalf of xid.
+ *
+ * @exception XAException An error has occurred. Possible XAExceptions
+ * are XA_HEURHAZ, XA_HEURCOM, XA_HEURRB, XA_HEURMIX, XAER_RMERR,
+ * XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.
+ *
+ * <P>If the resource manager did not commit the transaction and the
+ * parameter onePhase is set to true, the resource manager may throw
+ * one of the XA_RB* exceptions. Upon return, the resource manager has
+ * rolled back the branch's work and has released all held resources.
+ */
+ void commit(Xid xid, boolean onePhase) throws XAException;
- /**
- * Prepare the transaction
- *
- * @param xid the xid
- * @return Either XA_RDONLY or XA_OK
- * @throws XAException for an error
- */
- int prepare(Xid xid) throws XAException;
+ /**
+ * Tells the resource manager to forget about a heuristically
+ * completed transaction branch.
+ *
+ * @param xid A global transaction identifier.
+ *
+ * @exception XAException An error has occurred. Possible exception
+ * values are XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or
+ * XAER_PROTO.
+ */
+ void forget(Xid xid) throws XAException;
- /**
- * Rollback the transaction
- *
- * @param xid the xid
- * @throws XAException for an error
- */
- void rollback(Xid xid) throws XAException;
-
- /**
- * Retrieve xids that are recoverable
- *
- * @param flag the recovery option
- * @throws XAException for an error
- */
- Xid[] recover(int flag) throws XAException;
-}
\ No newline at end of file
+ /**
+ * Ask the resource manager to prepare for a transaction commit
+ * of the transaction specified in xid.
+ *
+ * @param xid A global transaction identifier.
+ *
+ * @exception XAException An error has occurred. Possible exception
+ * values are: XA_RB*, XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL,
+ * or XAER_PROTO.
+ *
+ * @return A value indicating the resource manager's vote on the
+ * outcome of the transaction. The possible values are: XA_RDONLY
+ * or XA_OK. These constants are defined in
+ * <code> javax.transaction.xa.XAResource</code> interface.
+ * If the resource manager wants to roll back the
+ * transaction, it should do so by raising an appropriate XAException
+ * in the prepare method.
+ */
+ int prepare(Xid xid) throws XAException;
+
+ /**
+ * Obtains a list of prepared transaction branches from a resource
+ * manager. The transaction manager calls this method during recovery
+ * to obtain the list of transaction branches that are currently in
+ * prepared or heuristically completed states.
+ *
+ * @param flag One of TMSTARTRSCAN, TMENDRSCAN, TMNOFLAGS. TMNOFLAGS
+ * must be used when no other flags are set in the parameter. These
+ * constants are defined in <code>javax.transaction.xa.XAResource</code>
+ * interface.
+ *
+ * @exception XAException An error has occurred. Possible values are
+ * XAER_RMERR, XAER_RMFAIL, XAER_INVAL, and XAER_PROTO.
+ *
+ * @return The resource manager returns zero or more XIDs of the
+ * transaction branches that are currently in a prepared or
+ * heuristically completed state. If an error occurs during the
+ * operation, the resource manager should throw the appropriate
+ * XAException.
+ */
+ Xid[] recover(int flag) throws XAException;
+
+ /**
+ * Informs the resource manager to roll back work done on behalf
+ * of a transaction branch.
+ *
+ * @param xid A global transaction identifier.
+ *
+ * @exception XAException An error has occurred. Possible XAExceptions are
+ * XA_HEURHAZ, XA_HEURCOM, XA_HEURRB, XA_HEURMIX, XAER_RMERR, XAER_RMFAIL,
+ * XAER_NOTA, XAER_INVAL, or XAER_PROTO.
+ *
+ * <p>If the transaction branch is already marked rollback-only the
+ * resource manager may throw one of the XA_RB* exceptions. Upon return,
+ * the resource manager has rolled back the branch's work and has released
+ * all held resources.
+ */
+ void rollback(Xid xid) throws XAException;
+}
+
+
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/endpoint/MessageEndpoint.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/endpoint/MessageEndpoint.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/endpoint/MessageEndpoint.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,45 +19,76 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi.endpoint;
-import java.lang.reflect.Method;
-
+import java.lang.NoSuchMethodException;
import javax.resource.ResourceException;
+import javax.resource.spi.ResourceAdapterInternalException;
+import javax.resource.spi.ApplicationServerInternalException;
+import javax.resource.spi.IllegalStateException;
+import javax.resource.spi.UnavailableException;
/**
- * A factory for message end points
+ * This defines a contract for a message endpoint. This is implemented by an
+ * application server.
+ *
+ * @version 1.0
+ * @author Ram Jeyaraman
*/
-public interface MessageEndpoint
-{
- /**
- * Invoked before delivery
- *
- * @param method the method on the endpoint
- * @throws NoSuchMethodException when there is no such method
- * @throws ResourceException for a generic error
- * @throws ApplicationServerInternalException for an error in the
- * application server
- * @throws IllegalStateException when not in the correct state, eg. before
- * and after delivery are not paired
- * @throws UnavailableException when the endpoint is unavailable
- */
- void beforeDelivery(Method method) throws NoSuchMethodException, ResourceException;
+public interface MessageEndpoint {
- /**
- * Invoked after delivery
- *
- * @throws ResourceException for a generic error
- * @throws ApplicationServerInternalException for an error in the
- * application server
- * @throws IllegalStateException when not in the correct state, eg. before
- * and after delivery are not paired
- * @throws UnavailableException when the endpoint is unavailable
- */
- void afterDelivery() throws ResourceException;
+ /**
+ * This is called by a resource adapter before a message is delivered.
+ *
+ * @param method description of a target method. This information about
+ * the intended target method allows an application server to decide
+ * whether to start a transaction during this method call, depending
+ * on the transaction preferences of the target method.
+ * The processing (by the application server) of the actual message
+ * delivery method call on the endpoint must be independent of the
+ * class loader associated with this descriptive method object.
+ *
+ * @throws NoSuchMethodException indicates that the specified method
+ * does not exist on the target endpoint.
+ *
+ * @throws ResourceException generic exception.
+ *
+ * @throws ApplicationServerInternalException indicates an error
+ * condition in the application server.
+ *
+ * @throws IllegalStateException indicates that the endpoint is in an
+ * illegal state for the method invocation. For example, this occurs when
+ * <code>beforeDelivery</code> and <code>afterDelivery</code>
+ * method calls are not paired.
+ *
+ * @throws UnavailableException indicates that the endpoint is not
+ * available.
+ */
+ void beforeDelivery(java.lang.reflect.Method method)
+ throws NoSuchMethodException, ResourceException;
- /**
- * Release the endpoint
- */
- void release();
-}
\ No newline at end of file
+ /**
+ * This is called by a resource adapter after a message is delivered.
+ *
+ * @throws ResourceException generic exception.
+ *
+ * @throws ApplicationServerInternalException indicates an error
+ * condition in the application server.
+ *
+ * @throws IllegalStateException indicates that the endpoint is in an
+ * illegal state for the method invocation. For example, this occurs when
+ * beforeDelivery and afterDelivery method calls are not paired.
+ *
+ * @throws UnavailableException indicates that the endpoint is not
+ * available.
+ */
+ void afterDelivery() throws ResourceException;
+
+ /**
+ * This method may be called by the resource adapter to indicate that it
+ * no longer needs a proxy endpoint instance. This hint may be used by
+ * the application server for endpoint pooling decisions.
+ */
+ void release();
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/endpoint/MessageEndpointFactory.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/endpoint/MessageEndpointFactory.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/endpoint/MessageEndpointFactory.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,33 +19,60 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi.endpoint;
-import java.lang.reflect.Method;
-
+import java.lang.NoSuchMethodException;
+import javax.transaction.xa.XAResource;
import javax.resource.spi.UnavailableException;
-import javax.transaction.xa.XAResource;
/**
- * A factory for message end points
+ * This serves as a factory for creating message endpoints.
+ *
+ * @version 1.0
+ * @author Ram Jeyaraman
*/
-public interface MessageEndpointFactory
-{
- /**
- * Creates a message endpoint
- *
- * @param resource the xa resource
- * @return the message endpoint
- * @throws UnavailableException a transient failure in the endpoint
- */
- MessageEndpoint createEndpoint(XAResource resource) throws UnavailableException;
+public interface MessageEndpointFactory {
- /**
- * Tests whether the delivery is transactional for the given method
- *
- * @param method the method to test
- * @return true for transacted delivery, false otherwise
- * @throws NoSuchMethodException if there is no such method for the endpoint
- */
- boolean isDeliveryTransacted(Method method) throws NoSuchMethodException;
-}
\ No newline at end of file
+ /**
+ * This is used to create a message endpoint. The message endpoint is
+ * expected to implement the correct message listener type.
+ *
+ * @param xaResource an optional <code>XAResource</code>
+ * instance used to get transaction notifications when the message delivery
+ * is transacted.
+ *
+ * @return a message endpoint instance.
+ *
+ * @throws UnavailableException indicates a transient failure
+ * in creating a message endpoint. Subsequent attempts to create a message
+ * endpoint might succeed.
+ */
+ MessageEndpoint createEndpoint(XAResource xaResource)
+ throws UnavailableException;
+
+ /**
+ * This is used to find out whether message deliveries to a target method
+ * on a message listener interface that is implemented by a message
+ * endpoint will be transacted or not.
+ *
+ * The message endpoint may indicate its transacted delivery preferences
+ * (at a per method level) through its deployment descriptor. The message
+ * delivery preferences must not change during the lifetime of a
+ * message endpoint.
+ *
+ * @param method description of a target method. This information about
+ * the intended target method allows an application server to find out
+ * whether the target method call will be transacted or not.
+ *
+ * @throws NoSuchMethodException indicates that the specified method
+ * does not exist on the target endpoint.
+ *
+ * @return true, if message endpoint requires transacted message delivery.
+ */
+ boolean isDeliveryTransacted(java.lang.reflect.Method method)
+ throws NoSuchMethodException;
+}
+
+
+
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/endpoint/package.html
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/endpoint/package.html 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/endpoint/package.html 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,36 +1,7 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
- <head>
- <!-- $Id$ -->
- <!--
-
- JBoss: The OpenSource J2EE WebOS
-
- Distributable under LGPL license.
- See terms of license at gnu.org.
-
- -->
- </head>
-
- <body bgcolor="white">
- <p>J2EE Connector API - Message Endpoint.
-
- <h2>Package Specification</h2>
- <ul>
- <li><a href="http://java.sun.com/j2ee/1.4/docs/api/index.html">Specified javadocs</a>
- </ul>
-
- <h2>Related Documentation</h2>
- <ul>
- <li><a href="http://java.sun.com/j2ee/connector/download.html">The specification</a>
- </ul>
-
- <h2>Package Status</h2>
- <ul>
- <li><font color="green"><b>STABLE</b></font>
- </ul>
-
- <!-- Put @see and @since tags down here. -->
-
- </body>
+<head>
+</head>
+<body>
+This package contains system contracts for service endpoint interactions.
+</body>
</html>
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/package.html
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/package.html 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/package.html 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,36 +1,8 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
- <head>
- <!-- $Id$ -->
- <!--
-
- JBoss: The OpenSource J2EE WebOS
-
- Distributable under LGPL license.
- See terms of license at gnu.org.
-
- -->
- </head>
-
- <body bgcolor="white">
- <p>J2EE Connector API - System Programmer Interface.
-
- <h2>Package Specification</h2>
- <ul>
- <li><a href="http://java.sun.com/j2ee/1.4/docs/api/index.html">Specified javadocs</a>
- </ul>
-
- <h2>Related Documentation</h2>
- <ul>
- <li><a href="http://java.sun.com/j2ee/connector/download.html">The specification</a>
- </ul>
-
- <h2>Package Status</h2>
- <ul>
- <li><font color="green"><b>STABLE</b></font>
- </ul>
-
- <!-- Put @see and @since tags down here. -->
-
- </body>
+<head>
+</head>
+<body>
+The javax.resource.spi package contains APIs for the system
+contracts defined in the Java EE Connector Architecture specification.
+</body>
</html>
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/security/GenericCredential.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/security/GenericCredential.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/security/GenericCredential.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,56 +19,103 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi.security;
+import java.security.Principal; // to fix javadoc warning
import javax.resource.spi.SecurityException;
-/**
- * The interface GenericCredential defines a method of representing a security
- * credential for a resource which is independent of the security mechanism. It
- * can be used to wrap any type of underlying credentials, for example it could
- * be used to wrap Kerberos credentials. This allows the resource adapter to
- * utilize the credentials for sign-on to the EIS.
- *
- * @deprecated Use org.ietf.jgss.GSSCredential
+/** The interface <code>javax.resource.spi.security.GenericCredential</code>
+ * defines a security mechanism independent interface for accessing
+ * security credential of a resource principal.
+ *
+ * <p>The <code>GenericCredential</code> interface provides a Java
+ * wrapper over an underlying mechanism specific representation of
+ * a security credential. For example, the <code>GenericCredential</code>
+ * interface can be used to wrap Kerberos credentials.
+ *
+ * <p>The connector architecture does not define any standard format
+ * and requirements for security mechanism specific credentials. For
+ * example, a security credential wrapped by a GenericCredential
+ * interface can have a native representation specific to an operating
+ * system.
+ *
+ * <p>The GenericCredential interface enables a resource adapter to
+ * extract information about a security credential. The resource adapter
+ * can then manage EIS sign-on for a resource principal by either:
+ * <UL>
+ * <LI>using the credentials in an EIS specific manner if the underlying
+ * EIS supports the security mechanism type represented by the
+ * GenericCredential instance, or,
+ * <LI>using GSS-API if the resource adapter and underlying EIS
+ * instance support GSS-API.
+ * </UL>
+ *
+ * @author Rahul Sharma
+ * @version 0.7
+ * @since 0.7
+ * @see javax.security.auth.Subject
+ * @see java.security.Principal
+ * @deprecated The preferred way to represent generic credential information
+ * is via the <code>org.ietf.jgss.GSSCredential</code> interface in
+ * J2SE Version 1.4, which provides similar functionality.
*/
-public interface GenericCredential
-{
- /**
- * Gets security data from the credential.
- *
- * @deprecated Use org.ietf.jgss.GSSCredential
- * @return Credential data
- */
- public byte[] getCredentialData() throws SecurityException;
- /**
- * Returns the mechanism type for the credential
- *
- * @deprecated Use org.ietf.jgss.GSSCredential
- * @return Mechanism Type
- */
- public String getMechType();
+public interface GenericCredential {
- /**
- * Returns the name of the principal associated with the credential
- *
- * @deprecated Use org.ietf.jgss.GSSCredential
- * @return Principal name
- */
- public String getName();
+ /** Returns the name of the resource principal associated
+ * with a GenericCredential instance.
+ *
+ * @return Name of the principal
+ **/
+ public
+ String getName();
- /**
- * Tests object for equality
- *
- * @deprecated Use org.ietf.jgss.GSSCredential
- */
- public boolean equals(Object other);
+ /** Returns the mechanism type for the GenericCredential instance.
+ * The mechanism type definition for GenericCredential should be
+ * consistent with the Object Identifier (OID) based representation
+ * specified in the GSS specification. In the GenericCredential
+ * interface, the mechanism type is returned as a stringified
+ * representation of the OID specification.
+ *
+ * @return mechanism type
+ **/
+ public
+ String getMechType();
- /**
- * Generates a hashCode for this object
- *
- * @deprecated Use org.ietf.jgss.GSSCredential
- */
- public int hashCode();
-}
\ No newline at end of file
+ /** Gets security data for a specific security mechanism represented
+ * by the GenericCredential. An example is authentication data required
+ * for establishing a secure association with an EIS instance on
+ * behalf of the associated resource principal.
+ *
+ * <p>The getCredentialData method returns the credential
+ * representation as an array of bytes. Note that the connector
+ * architecture does not define any standard format for the returned
+ * credential data.
+ *
+ * @return credential representation as an array of bytes.
+ * @throws SecurityException
+ * Failed operation due to security related
+ * error condition
+ **/
+ public
+ byte[] getCredentialData() throws SecurityException;
+
+ /** Tests if this GenericCredential instance refers to the same entity
+ * as the supplied object. The two credentials must be acquired over
+ * the same mechanisms and must refer to the same principal.
+ *
+ * Returns true if the two GenericCredentials refer to the same entity;
+ * false otherwise.
+ **/
+ public
+ boolean equals(Object another);
+
+ /** Returns the hash code for this GenericCredential
+ *
+ * @return hash code for this GenericCredential
+ **/
+ public
+ int hashCode();
+
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/security/PasswordCredential.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/security/PasswordCredential.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/security/PasswordCredential.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,97 +19,132 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi.security;
-import java.io.Serializable;
-import java.util.Arrays;
-
import javax.resource.spi.ManagedConnectionFactory;
/**
- * The class PasswordCredential is a placeholder for username and password.
- * @version $Revision$
+ * The class PasswordCredential acts as a holder for username and
+ * password.
+ *
+ * @see javax.resource.spi.ManagedConnectionFactory
+ *
+ * @author Rahul Sharma
+ * @version 0.6
+ * @since 0.6
*/
-public final class PasswordCredential implements Serializable
-{
- static final long serialVersionUID = -1770833344350711674L;
- /** The userName */
- private String userName;
- /** The password */
- private char[] password;
+public final class PasswordCredential implements java.io.Serializable {
- /** The managed connection factory */
- private ManagedConnectionFactory mcf = null;
+ private String userName;
+ private char[] password;
+ private ManagedConnectionFactory mcf;
- /**
- * Constructor, creates a new password credential
- *
- * @param userName the user name
- * @param password the password
- */
- public PasswordCredential(String userName, char[] password)
- {
- this.userName = userName;
- this.password = password;
- }
+ /**
+ * Creates a new <code>PasswordCredential</code> object from the given
+ * user name and password.
+ *
+ * <p> Note that the given user password is cloned before it is stored in
+ * the new <code>PasswordCredential</code> object.
+ *
+ * @param userName the user name
+ * @param password the user's password
+ **/
+ public
+ PasswordCredential(String userName, char[] password) {
+ this.userName = userName;
+ this.password = (char[])password.clone();
+ }
- /**
- * Returns the username
- *
- * @return Username
- */
- public String getUserName()
- {
- return userName;
- }
+ /**
+ * Returns the user name.
+ *
+ * @return the user name
+ **/
+ public
+ String getUserName() {
+ return userName;
+ }
- /**
- * Returns the password
- *
- * @return password
- */
- public char[] getPassword()
- {
- return password;
- }
+ /**
+ * Returns the user password.
+ *
+ * <p> Note that this method returns a reference to the password. It is
+ * the caller's responsibility to zero out the password information after
+ * it is no longer needed.
+ *
+ * @return the password
+ **/
+ public
+ char[] getPassword() {
+ return password;
+ }
- /**
- * Get the managed connection factory associated with this username password
- * pair.
- *
- * @return the managed connection factory
- */
- public ManagedConnectionFactory getManagedConnectionFactory()
- {
- return mcf;
- }
+ /** Gets the target ManagedConnectionFactory for which the user name and
+ * password has been set by the application server. A ManagedConnection-
+ * Factory uses this field to find out whether PasswordCredential should
+ * be used by it for sign-on to the target EIS instance.
+ *
+ * @return ManagedConnectionFactory instance for which user name and
+ * password have been specified
+ **/
+ public
+ ManagedConnectionFactory getManagedConnectionFactory() {
+ return mcf;
+ }
- /**
- * Set the managed connection factory associated with this username password
- * pair.
- *
- * @param mcf the managed connection factory
- */
- public void setManagedConnectionFactory(ManagedConnectionFactory mcf)
- {
- this.mcf = mcf;
- }
+ /** Sets the target ManagedConenctionFactory instance for which the user
+ * name and password has been set by the application server.
+ *
+ * @param mcf ManagedConnectionFactory instance for which user name
+ * and password have been specified
+ **/
+ public
+ void setManagedConnectionFactory(ManagedConnectionFactory mcf) {
+ this.mcf = mcf;
+ }
- public boolean equals(Object other)
- {
- if (this == other)
- return true;
- if (other == null || getClass() != other.getClass())
- return false;
- final PasswordCredential otherCredential = (PasswordCredential) other;
- if( userName == null && userName != otherCredential.userName )
- return false;
- return userName.equals(otherCredential.userName) && Arrays.equals(password, otherCredential.password);
- }
+ /** Compares this PasswordCredential with the specified object for
+ * equality. The two PasswordCredential instances are the same if
+ * they are equal in username and password.
+ *
+ * @param other Object to which PasswordCredential is to be compared
+ * @return <tt>true</tt> if and if the specified object is a
+ * PasswordCredential whose username and password are
+ * equal to this instance.
+ **/
+ public
+ boolean equals(Object other) {
+ if (!(other instanceof PasswordCredential))
+ return false;
- public int hashCode()
- {
- return userName.hashCode();
- }
-}
\ No newline at end of file
+ PasswordCredential pc = (PasswordCredential)other;
+
+ if (!(userName.equals(pc.userName)))
+ return false;
+
+ if (password.length != pc.password.length)
+ return false;
+
+ for (int i = 0; i < password.length;i++) {
+ if (password[i] != pc.password[i])
+ return false;
+ }
+
+ return true;
+ }
+
+ /** Returns the hash code for this PasswordCredential
+ *
+ * @return hash code for this PasswordCredential
+ **/
+ public
+ int hashCode() {
+ String s = userName;
+ s += new String(password);
+ return s.hashCode();
+ }
+
+}
+
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/security/package.html
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/security/package.html 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/security/package.html 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,36 +1,8 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
- <head>
- <!-- $Id$ -->
- <!--
-
- JBoss: The OpenSource J2EE WebOS
-
- Distributable under LGPL license.
- See terms of license at gnu.org.
-
- -->
- </head>
-
- <body bgcolor="white">
- <p>J2EE Connector API - Security.
-
- <h2>Package Specification</h2>
- <ul>
- <li><a href="http://java.sun.com/j2ee/1.4/docs/api/index.html">Specified javadocs</a>
- </ul>
-
- <h2>Related Documentation</h2>
- <ul>
- <li><a href="http://java.sun.com/j2ee/connector/download.html">The specification</a>
- </ul>
-
- <h2>Package Status</h2>
- <ul>
- <li><font color="green"><b>STABLE</b></font>
- </ul>
-
- <!-- Put @see and @since tags down here. -->
-
- </body>
+<head>
+</head>
+<body>
+The javax.resource.spi.security package contains APIs for the security
+management contract.
+</body>
</html>
Added: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/DistributableWork.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/DistributableWork.java (rev 0)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/DistributableWork.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -0,0 +1,40 @@
+/*
+* JBoss, Home of Professional Open Source
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
+* by the @authors tag. See the copyright.txt in the distribution for a
+* full listing of individual contributors.
+*
+* This is free software; you can redistribute it and/or modify it
+* under the terms of the GNU Lesser General Public License as
+* published by the Free Software Foundation; either version 2.1 of
+* the License, or (at your option) any later version.
+*
+* This software is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+* Lesser General Public License for more details.
+*
+* You should have received a copy of the GNU Lesser General Public
+* License along with this software; if not, write to the Free
+* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+*/
+
+package javax.resource.spi.work;
+
+import java.lang.Object;
+import java.lang.Runnable;
+import java.lang.Exception;
+import java.lang.Throwable;
+import java.io.Serializable;
+
+/**
+ * This models a <code>Work</code> instance that would be distributed by a
+ * <code>DistributableWorkManager</code> for execution in a remote
+ * <code>DistributableWorkManager</code>
+ *
+ * @since 1.6
+ * @version JSR322-PublicReview
+ */
+public interface DistributableWork extends Work, Serializable {
+}
Added: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/DistributableWorkManager.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/DistributableWorkManager.java (rev 0)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/DistributableWorkManager.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -0,0 +1,45 @@
+/*
+* JBoss, Home of Professional Open Source
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
+* by the @authors tag. See the copyright.txt in the distribution for a
+* full listing of individual contributors.
+*
+* This is free software; you can redistribute it and/or modify it
+* under the terms of the GNU Lesser General Public License as
+* published by the Free Software Foundation; either version 2.1 of
+* the License, or (at your option) any later version.
+*
+* This software is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+* Lesser General Public License for more details.
+*
+* You should have received a copy of the GNU Lesser General Public
+* License along with this software; if not, write to the Free
+* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+*/
+
+package javax.resource.spi.work;
+
+/**
+ * This interface models a <code>WorkManager</code> that supports distributed
+ * execution of Work instances.
+ *
+ * <p> A <code>DistributableWorkManager</code> may choose to distribute a
+ * <code>Work</code> instance submitted by a resource adapter to another
+ * <code>WorkManager</code> instance running in a different Java virtual
+ * machine (that is running in the same host or different hosts) for
+ * achieving optimal resource utilization or for providing better
+ * response times.
+ *
+ * <p> A <code>WorkManager</code> implementation that supports the submission
+ * of <code>DistributableWork</code> instances must implement the
+ * <code>DistributableWorkManager</code> marker interface.
+ *
+ * @since 1.6
+ * @version JSR322-PublicDraft
+ * @author Sivakumar Thyagarajan
+ */
+public interface DistributableWorkManager extends WorkManager {
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/ExecutionContext.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/ExecutionContext.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/ExecutionContext.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,63 +19,100 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi.work;
+import java.lang.Object;
+import java.lang.Runnable;
+import java.lang.Exception;
+import java.lang.Throwable;
+
+import javax.transaction.xa.Xid;
import javax.resource.NotSupportedException;
-import javax.transaction.xa.Xid;
+//import javax.resource.spi.security.SecurityContext;
/**
- * An execution context provides context information for work, e.g.
- * transaction, security, etc.
+ * This class models an execution context (transaction, security, etc)
+ * with which the <code>Work</code> instance must be executed.
+ * This class is provided as a convenience for easily creating
+ * <code>ExecutionContext</code> instances by extending this class
+ * and overriding only those methods of interest.
+ *
+ * <p>Some reasons why it is better for <code>ExecutionContext</code>
+ * to be a class rather than an interface:
+ * <ul><li>There is no need for a resource adapter to implement this class.
+ * It only needs to implement the context information like
+ * transaction, etc.
+ * <li>The resource adapter code does not have to change when the
+ * <code>ExecutionContext</code> class evolves. For example, more context
+ * types could be added to the <code>ExecutionContext</code> class
+ * (in the future) without forcing resource adapter implementations
+ * to change.</ul>
+ *
+ * Note: Resource adapters that are developed for Connectors 1.6 specification
+ * compliant application servers and above, are recommended to use
+ * the <code>TransactionInflowContext</code> interface instead of this
+ * class. See Chapter.11 Generic Inflow Context in the Connectors 1.6
+ * specification for more details.
+ *
+ * @version 1.0
+ * @author Ram Jeyaraman
*/
-public class ExecutionContext
-{
- /** The xid */
- private Xid xid;
- /** The timeout */
- private long timeout = WorkManager.UNKNOWN;
+public class ExecutionContext {
- /**
- * Get the xid
- *
- * @return the xid
- */
- public Xid getXid()
- {
- return xid;
- }
+ /**
+ * transaction context.
+ */
+ private Xid xid;
- /**
- * Set the xid
- *
- * @param xid the xid
- */
- public void setXid(Xid xid)
- {
- this.xid = xid;
- }
+ /**
+ * transaction timeout value.
+ */
+ private long transactionTimeout = WorkManager.UNKNOWN;
- /**
- * Get the transaction timeout
- *
- * @return the transaction timeout or WorkManager.UNKNOWN for an invalid or
- * unspecified value
- */
- public long getTransactionTimeout()
- {
- return timeout;
- }
- /**
- * Set the transaction timeout
- *
- * @param timeout the timeout
- * @throws NotSupportedException for an invalid timeout
- */
- public void setTransactionTimeout(long timeout) throws NotSupportedException
- {
- if (timeout < 0)
- throw new NotSupportedException("Illegal timeout " + timeout);
- this.timeout = timeout;
- }
-}
\ No newline at end of file
+ /**
+ * set a transaction context.
+ *
+ * @param xid transaction context.
+ */
+ public void setXid(Xid xid) { this.xid = xid; }
+
+ /**
+ * @return an Xid object carrying a transaction context,
+ * if any.
+ */
+ public Xid getXid() { return this.xid; }
+
+ /**
+ * Set the transaction timeout value for a imported transaction.
+ *
+ * @param timeout transaction timeout value in seconds. Only positive
+ * non-zero values are accepted. Other values are illegal and are
+ * rejected with a <code>NotSupportedException</code>.
+ *
+ * @throws NotSupportedException thrown to indicate an illegal timeout
+ * value.
+ */
+ public void setTransactionTimeout(long timeout)
+ throws NotSupportedException {
+ if (timeout > 0) {
+ this.transactionTimeout = timeout;
+ } else {
+ throw new NotSupportedException("Illegal timeout value");
+ }
+ }
+
+ /**
+ * Get the transaction timeout value for a imported transaction.
+ *
+ * @return the specified transaction timeout value in seconds. When no
+ * timeout value or an illegal timeout value had been specified, a value of
+ * -1 (<code>WorkManager.UNKNOWN</code>) is returned; the timeout
+ * processing of such a transaction depends on the application server
+ * implementation.
+ */
+ public long getTransactionTimeout() {
+ return this.transactionTimeout;
+ }
+}
Added: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/HintsWorkContext.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/HintsWorkContext.java (rev 0)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/HintsWorkContext.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -0,0 +1,94 @@
+/*
+* JBoss, Home of Professional Open Source
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
+* by the @authors tag. See the copyright.txt in the distribution for a
+* full listing of individual contributors.
+*
+* This is free software; you can redistribute it and/or modify it
+* under the terms of the GNU Lesser General Public License as
+* published by the Free Software Foundation; either version 2.1 of
+* the License, or (at your option) any later version.
+*
+* This software is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+* Lesser General Public License for more details.
+*
+* You should have received a copy of the GNU Lesser General Public
+* License along with this software; if not, write to the Free
+* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+*/
+
+package javax.resource.spi.work;
+
+import java.io.Serializable;
+import java.util.Map;
+import java.util.HashMap;
+
+/**
+ * A standard {@link WorkContext WorkContext} that allows a {@link Work
+ * Work} instance to propagate quality-of-service (QoS) hints about the
+ * {@link Work Work} to the <code>WorkManager</code>.
+ *
+ * @since 1.6
+ * @see javax.resource.spi.work.WorkContextProvider
+ * @version JSR322-PublicReview
+ */
+
+public class HintsWorkContext implements WorkContext {
+ String description = "Hints Inflow Context";
+ String name = "HintsWorkContext";
+
+ /**
+ * {@inheritDoc}
+ */
+ public String getDescription() {
+ return description;
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public String getName() {
+ return name;
+ }
+
+ /**
+ * Set a brief description of the role played by the instance of
+ * HintsWorkContext and any other related debugging information.
+ *
+ * This could be used by the resource adapter and the WorkManager
+ * for logging and debugging purposes.
+ */
+ public void setDescription(String description){
+ this.description = description;
+ }
+
+ /**
+ * Set the associated name of the HintsWorkContext. This
+ * could be used by the resource adapter and the WorkManager
+ * for logging and debugging purposes.
+ */
+ public void setName(String name){
+ this.name = name;
+ }
+
+ Map<String, Serializable> hints = new HashMap<String, Serializable>();
+
+ /**
+ * Set a Hint and a related value. The hintName must be non-Null.
+ * Standard HintNames are defined in the Connector specification. Use of
+ * "javax.resource." prefixed hintNames are reserved for use by the
+ * Connector specification.
+ *
+ */
+ public void setHint(String hintName, Serializable value) {
+ hints.put(hintName, value);
+ }
+
+ public Map<String, Serializable> getHints() {
+ return hints;
+ }
+
+}
Added: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/SecurityWorkContext.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/SecurityWorkContext.java (rev 0)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/SecurityWorkContext.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -0,0 +1,205 @@
+/*
+* JBoss, Home of Professional Open Source
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
+* by the @authors tag. See the copyright.txt in the distribution for a
+* full listing of individual contributors.
+*
+* This is free software; you can redistribute it and/or modify it
+* under the terms of the GNU Lesser General Public License as
+* published by the Free Software Foundation; either version 2.1 of
+* the License, or (at your option) any later version.
+*
+* This software is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+* Lesser General Public License for more details.
+*
+* You should have received a copy of the GNU Lesser General Public
+* License along with this software; if not, write to the Free
+* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+*/
+
+package javax.resource.spi.work;
+
+import javax.security.auth.Subject;
+import javax.security.auth.callback.CallbackHandler;
+
+/**
+ * A standard {@link WorkContext WorkContext} that allows a {@link Work
+ * Work} instance to propagate security related context information from an EIS
+ * to an application server.
+ * <p>
+ *
+ *
+ * This allows an EIS/resource adapter to flow-in security context information
+ * and execute a Work instance, and call methods on a MessageEndpoint interface,
+ * to effect message inflow, within that Work instance, in the context of an
+ * established identity.
+ * <p>
+ *
+ *
+ * A resource adapter indicates to the WorkManager, that a Work instance needs
+ * to be run in a specified security execution context by submitting a Work
+ * instance that implements WorkContextProvider interface and ensuring that
+ * the List of WorkContexts for that Work instance contains an instance of its
+ * subclass of SecurityWorkContext.
+ * <p>
+ *
+ *
+ * It should be noted however that when a resource adapter flows-in an identity
+ * to be used by the application server, the propagated identity may or may not
+ * belong to the application server's security domain.
+ * <p>
+ *
+ *
+ * There are therefore, two scenarios while a resource adapter propagates a
+ * security identity from an EIS to the application server:
+ * <p>
+ *
+ * <ul>
+ * <li>Case 1: Resource adapter flows-in an identity in the application server's
+ * security domain: In this case, the application server could just set the
+ * initiating principal, flown-in from the resource adapter, as the security
+ * context the Work instance executes as.</li>
+ * <li>Case 2: Resource adapter flows-in an identity belonging to the EIS'
+ * security domain: The resource adapter establishes a connection to the EIS and
+ * needs to perform a Work in the context of an EIS identity. In this case, the
+ * initiating or caller principal does not exist in the application server's
+ * security domain and a translation from one domain to the other needs to be
+ * performed.</li>
+ * </ul>
+ * <p>
+ *
+ * @since 1.6
+ * @see javax.resource.spi.work.WorkContextProvider
+ * @version JSR322-EarlyDraft
+ */
+
+public abstract class SecurityWorkContext implements WorkContext {
+
+ /**
+ * {@inheritDoc}
+ */
+ public String getDescription() {
+ return "Security Inflow Context";
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public String getName() {
+ return "SecurityWorkContext";
+ }
+
+ /**
+ * The container calls this method to set up the security Context for the
+ * <code>Work</code> instance.
+ * <p>
+ *
+ * The handler argument must not be null, and the argument handler and the
+ * <code>CallbackHandler</code> passed to this method must support the
+ * following <code>Callback</code>s defined in JSR 196: Java Authentication
+ * SPI for Containers specification:
+ * <p>
+ * <ul>
+ * <li>CallerPrincipalCallback</li>
+ * <li>GroupPrincipalCallback</li>
+ * <li>PasswordValidationCallback</li>
+ * </ul>
+ * The following <code>Callback</code>s may be supported by the container.
+ * <ul>
+ * <li>CertStoreCallback
+ * <li>
+ * <li>PrivateKeyCallback
+ * <li>
+ * <li>SecretKeyCallback
+ * <li>
+ * <li>TrustStoreCallback
+ * <li>
+ * </ul>
+ * <p>
+ *
+ * A resource adapter might use the <code>CallerPrincipalCallback</code> “to
+ * set the container's representation of the caller principal. The
+ * CallbackHandler must establish the argument Principal as the caller
+ * principal associated with the invocation being processed by the
+ * container. When the argument Principal is null, the handler will
+ * establish the container's representation of the unauthenticated caller
+ * principal.”
+ * <p>
+ *
+ * A resource adapter might use the <code>GroupPrincipalCallback</code> “to
+ * establish the container's representation of the corresponding group
+ * principals within the Subject. When a null value is passed to the groups
+ * argument, the handler will establish the container's representation of no
+ * group principals within the Subject. Otherwise, the handler's processing
+ * of this callback is additive, yielding the union (without duplicates) of
+ * the principals existing within the Subject, and those created with the
+ * names occuring within the argument array. The CallbackHandler will define
+ * the type of the created principals.”
+ * <p>
+ *
+ * A resource adapter might use the <code>PasswordValidationCallback</code>
+ * “to employ the password validation facilities of its containing runtime.”
+ * <p>
+ *
+ * The executionSubject argument must be non-null and it must not be
+ * read-only. It is expected that this method will populate this
+ * executionSubject with principals and credentials that would be flown into
+ * the application server.
+ * <p>
+ *
+ * The serviceSubject argument must be non-null and it must not be
+ * read-only. It represents the application server and it may be used by the
+ * Work implementation to retrieve Principals and credentials necessary to
+ * establish a connection to the EIS (in the cause of mutual-auth like
+ * scenarios). If the Subject is not null, the Work implementation may
+ * collect the server credentials, as necessary, by using the callback
+ * handler passed to them .
+ * <p>
+ *
+ *
+ * When this method is called, the method implementation
+ * <ul>
+ * <li>identifies the security context that needs to be flown-in to the
+ * application server to serve as the execution context of the Work
+ * instance.</li>
+ * <li>populates the executionSubject with the EIS Principals and
+ * Credentials that it wants to serve as the security context for the Work
+ * instance to be executed in.</li>
+ * <li>adds instances of the necessary Callbacks , usually a subset of the
+ * ones listed above, to an array and invokes the handle() method in the
+ * container's CallbackHandler implementation passing in the array of
+ * Callback instances.</li>
+ * <li>on sucessful return from the CallbackHandler.handle() method the
+ * setSecurityContext returns after ensuring that the executionSubject is
+ * populated with the valid Principals and Credentials that represent the
+ * execution context of the Work instance</li>
+ * </ul>
+ * <p>
+ *
+ * @see JSR 196: Java Authentication SPI for Containers specification and
+ * related JavaDoc
+ *
+ * @param handler
+ * A <code>CallbackHandler</code> provided by the
+ * <code>WorkManager</code> that supports the
+ * <code>Callback</code>s described above
+ * @param executionSubject
+ * A Subject that represents the security identity that needs to
+ * be established as the context for the <code>Work</code>
+ * instance. It is used by the method implementation to store
+ * Principals and credentials that needs to be used as the
+ * security context of the <code>Work</code> instance.
+ * @param serviceSubject
+ * A Subject that represents the application server It may be
+ * used by the method implementation as the source of Principals
+ * or credentials to be used to validate a connection to the EIS.
+ * If the Subject is not null, the method implementation may add
+ * additional Principals or credentials (pertaining to the
+ * recipient of the service request) to the Subject. *
+ */
+ public abstract void setupSecurityContext(CallbackHandler handler,
+ Subject executionSubject, Subject serviceSubject);
+}
Added: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/TransactionWorkContext.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/TransactionWorkContext.java (rev 0)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/TransactionWorkContext.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -0,0 +1,56 @@
+/*
+* JBoss, Home of Professional Open Source
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
+* by the @authors tag. See the copyright.txt in the distribution for a
+* full listing of individual contributors.
+*
+* This is free software; you can redistribute it and/or modify it
+* under the terms of the GNU Lesser General Public License as
+* published by the Free Software Foundation; either version 2.1 of
+* the License, or (at your option) any later version.
+*
+* This software is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+* Lesser General Public License for more details.
+*
+* You should have received a copy of the GNU Lesser General Public
+* License along with this software; if not, write to the Free
+* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+*/
+
+package javax.resource.spi.work;
+
+/**
+ * A standard <code>WorkContext</code> that allows a <code>Work</code>
+ * instance to propagate transaction related context information from an EIS to
+ * an application server.<p>
+ *
+ * This class extends <code>ExecutionContext</code> so that a resource adapter
+ * developer could migrate their existing code from
+ * <code>ExecutionContext</code> to <code>TransactionWorkContext</code>
+ * easily.<p>
+ *
+ * @since 1.6
+ * @see javax.resource.spi.work.WorkContext
+ * @see javax.resource.spi.work.ExecutionContext
+ * @version JSR322-EarlyDraft
+ */
+
+public class TransactionWorkContext extends ExecutionContext implements
+ WorkContext {
+ /**
+ * {@inheritDoc}
+ */
+ public String getDescription() {
+ return "Transaction Inflow Context";
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public String getName() {
+ return "TransactionWorkContext";
+ }
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/Work.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/Work.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/Work.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,15 +19,28 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi.work;
+import java.lang.Object;
+import java.lang.Runnable;
+import java.lang.Exception;
+import java.lang.Throwable;
+
/**
- * Work submitted to a work manager
+ * This models a <code>Work</code> instance that would be executed by a
+ * <code>WorkManager</code> upon submission.
+ *
+ * @version 1.0
+ * @author Ram Jeyaraman
*/
-public interface Work extends Runnable
-{
- /**
- * Invoked by the work manager as a hint to stop processing
- */
- void release();
-}
\ No newline at end of file
+public interface Work extends Runnable {
+
+ /**
+ * The <code>WorkManager</code> might call this method to hint the
+ * active <code>Work</code> instance to complete execution as soon as
+ * possible. This would be called on a seperate thread other than the
+ * one currently executing the <code>Work</code> instance.
+ */
+ void release();
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkAdapter.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkAdapter.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkAdapter.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,26 +19,42 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi.work;
+import java.lang.Object;
+import java.lang.Runnable;
+import java.lang.Exception;
+import java.lang.Throwable;
+
/**
- * A helper for work listener implementations
+ * This class is provided as a convenience for easily creating
+ * <code>WorkListener</code> instances by extending this class
+ * and overriding only those methods of interest.
+ *
+ * @version 1.0
+ * @author Ram Jeyaraman
*/
-public class WorkAdapter implements WorkListener
-{
- public void workAccepted(WorkEvent e)
- {
- }
+public class WorkAdapter implements WorkListener {
- public void workCompleted(WorkEvent e)
- {
- }
+ /**
+ * Invoked when a <code>Work</code> instance has been accepted.
+ */
+ public void workAccepted(WorkEvent e) {}
- public void workRejected(WorkEvent e)
- {
- }
+ /**
+ * Invoked when a <code>Work</code> instance has been rejected.
+ */
+ public void workRejected(WorkEvent e) {}
- public void workStarted(WorkEvent e)
- {
- }
-}
\ No newline at end of file
+ /**
+ * Invoked when a <code>Work</code> instance has started execution.
+ * This only means that a thread has been allocated.
+ */
+ public void workStarted(WorkEvent e) {}
+
+ /**
+ * Invoked when a <code>Work</code> instance has completed execution.
+ */
+ public void workCompleted(WorkEvent e) {}
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkCompletedException.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkCompletedException.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkCompletedException.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,62 +19,77 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi.work;
-import javax.resource.ResourceException;
-
/**
- * An error thrown when work is completed.
+ * This exception is thrown by a <code>WorkManager</code> to indicate that
+ * a submitted <code>Work</code> instance has completed with an exception.
+ *
+ * <p>This could be thrown only after the execution of a
+ * <code>Work</code> instance has started (that is, after a thread has
+ * been allocated for <code>Work</code> execution). The allocated thread sets
+ * up an execution context (if it has been specified), and then calls
+ * <code>Work.run()</code>.
+ *
+ * <p>Any exception thrown during execution context setup or during
+ * <code>Work</code> execution (that is, during <code>Work.run()</code>) is
+ * chained within this exception.
+ *
+ * <p>An associated error code indicates the nature of the error condition.
+ * Possible error codes are <code>WorkException.TX_RECREATE_FAILED</code>,
+ * <code>WorkException.TX_CONCURRENT_WORK_DISALLOWED</code> or
+ * <code>WorkException.UNDEFINED</code>.
+ *
+ * @version 1.0
+ * @author Ram Jeyaraman
*/
-public class WorkCompletedException extends WorkException
-{
- /**
- * Create an exception.
- */
- public WorkCompletedException()
- {
- super();
- }
+public class WorkCompletedException extends WorkException {
- /**
- * Create an exception with a reason.
- *
- * @param reason the reason
- */
- public WorkCompletedException(String reason)
- {
- super(reason);
- }
+ /**
+ * Constructs a new instance with null as its detail message.
+ */
+ public WorkCompletedException() { super(); }
- /**
- * Create an exception with a reason and an errorCode.
- *
- * @param reason the reason
- * @param errorCode the error code
- */
- public WorkCompletedException(String reason, String errorCode)
- {
- super(reason, errorCode);
- }
+ /**
+ * Constructs a new instance with the specified detail message.
+ *
+ * @param message the detail message.
+ */
+ public WorkCompletedException(String message) {
+ super(message);
+ }
- /**
- * Create an exception with a reason and an error.
- *
- * @param reason the reason
- * @param throwable the error
- */
- public WorkCompletedException(String reason, Throwable throwable)
- {
- super(reason, throwable);
- }
+ /**
+ * Constructs a new throwable with the specified cause.
+ *
+ * @param cause a chained exception of type
+ * <code>Throwable</code>.
+ */
+ public WorkCompletedException(Throwable cause) {
+ super(cause);
+ }
- /**
- * Create an exception with an error.
- *
- * @param throwable the error
- */
- public WorkCompletedException(Throwable throwable)
- {
- super(throwable);
- }
+ /**
+ * Constructs a new throwable with the specified detail message and cause.
+ *
+ * @param message the detail message.
+ *
+ * @param cause a chained exception of type
+ * <code>Throwable</code>.
+ */
+ public WorkCompletedException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ /**
+ * Constructs a new throwable with the specified detail message and
+ * an error code.
+ *
+ * @param message a description of the exception.
+ * @param errorCode a string specifying the vendor specific error code.
+ */
+ public WorkCompletedException(String message, String errorCode) {
+ super(message, errorCode);
+ }
}
Added: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkContext.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkContext.java (rev 0)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkContext.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -0,0 +1,66 @@
+/*
+* JBoss, Home of Professional Open Source
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
+* by the @authors tag. See the copyright.txt in the distribution for a
+* full listing of individual contributors.
+*
+* This is free software; you can redistribute it and/or modify it
+* under the terms of the GNU Lesser General Public License as
+* published by the Free Software Foundation; either version 2.1 of
+* the License, or (at your option) any later version.
+*
+* This software is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+* Lesser General Public License for more details.
+*
+* You should have received a copy of the GNU Lesser General Public
+* License along with this software; if not, write to the Free
+* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+*/
+
+package javax.resource.spi.work;
+
+import java.io.Serializable;
+
+/**
+ * This class serves as a standard mechanism for a resource adapter to propagate
+ * an imported context from an enterprise information system to an application
+ * server.
+ *
+ * <p> A <code>Work</code> instance, that implements the
+ * <code>WorkContextProvider</code>, could provide a
+ * <code>List</code> of these <code>WorkContext</code> instances
+ * (through the getWorkContexts() method), and have them setup as the
+ * execution context by the <code>WorkManager</code> when the
+ * <code>Work</code> instance gets executed.
+ *
+ * @since 1.6
+ * @version JSR322-EarlyDraft
+ */
+
+// @OpenQ : getName/getDescription useful for debugging purposes?
+public interface WorkContext extends Serializable{
+ /**
+ * Get the associated name of the <code>WorkContext</code>. This could
+ * be used by the WorkManager and the resource adapter for debugging
+ * purposes.
+ * <p>
+ *
+ * @return the associated name of the <code>WorkContext</code>
+ */
+ String getName();
+
+ /**
+ * Get the brief description of the role played by the
+ * <code>WorkContext</code> and any other related debugging information.
+ * This could be used by the WorkManager and the resource adapter for
+ * debugging purposes.
+ * <p>
+ *
+ * @return the associated description of the <code>WorkContext</code>
+ */
+ String getDescription();
+
+}
Added: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkContextErrorCodes.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkContextErrorCodes.java (rev 0)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkContextErrorCodes.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -0,0 +1,81 @@
+/*
+* JBoss, Home of Professional Open Source
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
+* by the @authors tag. See the copyright.txt in the distribution for a
+* full listing of individual contributors.
+*
+* This is free software; you can redistribute it and/or modify it
+* under the terms of the GNU Lesser General Public License as
+* published by the Free Software Foundation; either version 2.1 of
+* the License, or (at your option) any later version.
+*
+* This software is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+* Lesser General Public License for more details.
+*
+* You should have received a copy of the GNU Lesser General Public
+* License along with this software; if not, write to the Free
+* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+*/
+
+package javax.resource.spi.work;
+
+/**
+ * This class models the possible error conditions that might occur during
+ * associating an <code>WorkContext</code> with a <code>Work</code>
+ * instance.
+ *
+ * <p> This class is not designed as an Enumerated type (Enum), as the error codes
+ * listed below could be expanded to accommodate custom error conditions for
+ * custom <code>WorkContext</code> types.
+ *
+ * @since 1.6
+ * @version JSR322-EarlyDraft
+ */
+public class WorkContextErrorCodes {
+ private WorkContextErrorCodes(){}
+
+ /**
+ * Indicates that a <code>WorkContext</code> type, that was not
+ * specified as optional, passed in by the <code>Work</code> instance is
+ * not supported by the container.
+ *
+ * @since 1.6
+ */
+ public static final String UNSUPPORTED_CONTEXT_TYPE = "1";
+
+ /**
+ * Indicates that there are more than instance of a
+ * <code>WorkContext</code> type passed in by the <code>Work</code>
+ * instance.
+ * <p>
+ *
+ * @since 1.6
+ */
+ public static final String DUPLICATE_CONTEXTS = "2";
+
+ /**
+ * Indicates a failure in recreating the <code>WorkContext</code>
+ * instance. For <code>TransactionWorkContext</code> instances, the
+ * <code>WorkManager</code> must use this failure code when it should have
+ * used {@link WorkException#TX_RECREATE_FAILED} as the error code.
+ *
+ * @since 1.6
+ */
+ public static final String CONTEXT_SETUP_FAILED = "3";
+
+ /**
+ * Indicates that the container cannot support recreating the
+ * <code>WorkContext</code> instance. For
+ * <code>TransactionWorkContext</code> instances, the
+ * <code>WorkManager</code> must use this failure code when it should have
+ * used {@link WorkException#TX_CONCURRENT_WORK_DISALLOWED} as the error
+ * code.
+ *
+ * @since 1.6
+ */
+ public static final String CONTEXT_SETUP_UNSUPPORTED = "4";
+
+}
Added: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkContextLifecycleListener.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkContextLifecycleListener.java (rev 0)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkContextLifecycleListener.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -0,0 +1,80 @@
+/*
+* JBoss, Home of Professional Open Source
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
+* by the @authors tag. See the copyright.txt in the distribution for a
+* full listing of individual contributors.
+*
+* This is free software; you can redistribute it and/or modify it
+* under the terms of the GNU Lesser General Public License as
+* published by the Free Software Foundation; either version 2.1 of
+* the License, or (at your option) any later version.
+*
+* This software is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+* Lesser General Public License for more details.
+*
+* You should have received a copy of the GNU Lesser General Public
+* License along with this software; if not, write to the Free
+* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+*/
+
+package javax.resource.spi.work;
+
+/**
+ * This class models the various events that occur during the processing of the
+ * <code>WorkContext</code>s associated with a <code>Work</code>
+ * instance. This interface may be implemented by a <code>WorkContext</code>
+ * instance to receive notifications from the <code>WorkManager</code> when
+ * the <code>WorkContext</code> is set as the execution context of the
+ * <code>Work</code> instance it is associated with.
+ * <p>
+ *
+ * When a <code>WorkManager</code> sets up the execution context of a
+ * <code>Work</code> instance that implements
+ * <code>WorkContextProvider</code>, the <code>WorkManager</code> must
+ * make the relevant lifecycle notifications if an <code>WorkContext</code>
+ * instance implements this interface.
+ * <p>
+ *
+ * When a <code>Work</code> instance is submitted to the Connector
+ * <code>WorkManager</code> using one of the methods that passes in a
+ * <code>WorkListener</code> as a parameter, the <code>WorkManager</code>
+ * must send <code>Work</code> related notifications to the
+ * <code>WorkListener</code> and <code>WorkContext</code> setup related
+ * notifications to this interface.
+ * <p>
+ *
+ * The possible error conditions that might occur during associating an
+ * <code>WorkContext</code> with a <code>Work</code> instance is captured
+ * in {@link WorkContextErrorCodes}.
+ * <p>
+ *
+ * @since 1.6
+ * @version JSR322-EarlyDraft
+ */
+
+public interface WorkContextLifecycleListener {
+
+ /**
+ * Invoked when the <code>WorkContext</code> instance was successfully
+ * set as the execution context for the <code>Work</code> instance.
+ *
+ * @since 1.6
+ */
+ void contextSetupComplete();
+
+ /**
+ * Invoked when the <code>WorkContext</code> instance was set as the
+ * execution context for the <code>Work</code> instance it was associated
+ * with.
+ *
+ * @param errorCode
+ * One of the error-codes defined in or subclasses of
+ * {@link WorkContextErrorCodes WorkContextErrorCodes}
+ * @since 1.6
+ * @see WorkContextErrorCodes
+ */
+ void contextSetupFailed(String errorCode);
+}
Added: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkContextProvider.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkContextProvider.java (rev 0)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkContextProvider.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -0,0 +1,53 @@
+/*
+* JBoss, Home of Professional Open Source
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
+* by the @authors tag. See the copyright.txt in the distribution for a
+* full listing of individual contributors.
+*
+* This is free software; you can redistribute it and/or modify it
+* under the terms of the GNU Lesser General Public License as
+* published by the Free Software Foundation; either version 2.1 of
+* the License, or (at your option) any later version.
+*
+* This software is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+* Lesser General Public License for more details.
+*
+* You should have received a copy of the GNU Lesser General Public
+* License along with this software; if not, write to the Free
+* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+*/
+
+package javax.resource.spi.work;
+
+import java.util.List;
+import java.io.Serializable;
+
+/**
+ * This interface specifies the methods a {@link Work Work} instance uses to
+ * associate a <code>List</code> of {@link WorkContext WorkContext}
+ * instances to be set when the <code>Work</code> instance gets executed by a
+ * {@link WorkManager WorkManager}.
+ *
+ * <p> A <code>Work</code> instance could optionally implement this interface to
+ * indicate to the <code>WorkManager</code>, that the
+ * <code>WorkContext</code>s provided by this <code>Work</code> instance
+ * through the {@link #getWorkContexts() getWorkContexts} method must be
+ * used while setting the execution context of the <code>Work</code> instance.<p>
+ *
+ * @since 1.6
+ * @version JSR322-EarlyDraft
+ */
+public interface WorkContextProvider extends Serializable{
+
+ /**
+ * Gets an instance of <code>WorkContexts</code> that needs to be used
+ * by the <code>WorkManager</code> to set up the execution context while
+ * executing a <code>Work</code> instance.
+ *
+ * @return an <code>List</code> of <code>WorkContext</code> instances.
+ */
+ List<WorkContext> getWorkContexts();
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkEvent.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkEvent.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkEvent.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,185 +19,140 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi.work;
+import java.lang.Object;
+import java.lang.Runnable;
+import java.lang.Exception;
+import java.lang.Throwable;
import java.util.EventObject;
-import java.io.ObjectStreamField;
-import java.io.ObjectInputStream;
-import java.io.IOException;
-import java.io.ObjectOutputStream;
-import org.jboss.util.id.SerialVersion;
-
/**
- * Events that occur on work
- * @version $Revision$
+ * This class models the various events that occur during the processing of
+ * a <code>Work</code> instance.
+ *
+ * @version 1.0
+ * @author Ram Jeyaraman
*/
-public class WorkEvent extends EventObject
-{
- /** @since 4.0.2 */
- static final long serialVersionUID;
+public class WorkEvent extends EventObject {
- // Constants -----------------------------------------------------
- /**
- * These field names match the j2ee 1.4.1 ri version names
- */
- private static final ObjectStreamField[] serialPersistentFields;
- private static final int TYPE_IDX = 0;
- private static final int WORK_IDX = 1;
- private static final int EXCPEPTION_IDX = 2;
- private static final int DURATION_IDX = 2;
+ /**
+ * Indicates <code>Work</code> instance has been accepted.
+ */
+ public static final int WORK_ACCEPTED = 1;
- /** The WORK_ACCEPTED value */
- public static final int WORK_ACCEPTED = 1;
- /** The WORK_REJECTED value */
- public static final int WORK_REJECTED = 2;
- /** The WORK_STARTED value */
- public static final int WORK_STARTED = 3;
- /** The WORK_COMPLETED value */
- public static final int WORK_COMPLETED = 4;
-
- static
- {
- if (SerialVersion.version == SerialVersion.LEGACY)
- {
- serialVersionUID = 6971276136970053051L;
- serialPersistentFields = new ObjectStreamField[] {
- /** @serialField type int */
- new ObjectStreamField("type", int.class),
- /** @serialField work Work */
- new ObjectStreamField("work", Work.class),
- /** @serialField exception WorkException */
- new ObjectStreamField("e", WorkException.class),
- /** @serialField startDuration long */
- new ObjectStreamField("startDuration", long.class)
- };
- }
- else
- {
- // j2ee 1.4.1 RI values
- serialVersionUID = -3063612635015047218L;
- serialPersistentFields = new ObjectStreamField[] {
- /** @serialField type int */
- new ObjectStreamField("type", int.class),
- /** @serialField work Work */
- new ObjectStreamField("work", Work.class),
- /** @serialField exception WorkException */
- new ObjectStreamField("exception", WorkException.class),
- /** @serialField startDuration long */
- new ObjectStreamField("startDuration", long.class)
- };
- }
- }
+ /**
+ * Indicates <code>Work</code> instance has been rejected.
+ */
+ public static final int WORK_REJECTED = 2;
- /** The event type */
- private int type;
- /** The work */
- private Work work;
- /** The exception */
- private WorkException e;
- /** The start delay in millis */
- private long startDuration;
-
- /**
- * Create a new WorkEvent
- *
- * @param source the source of the event
- * @param type the type
- * @param work the work
- * @param e the exception
+ /**
+ * Indicates <code>Work</code> instance has started execution.
+ */
+ public static final int WORK_STARTED = 3;
+
+ /**
+ * Indicates <code>Work</code> instance has completed execution.
+ */
+ public static final int WORK_COMPLETED = 4;
+
+ /**
+ * The event type.
+ */
+ private int type;
+
+ /**
+ * The <code>Work</code> object on which the event occured.
+ */
+ private Work work;
+
+ /**
+ * The exception that occured during <code>Work</code> processing.
+ */
+ private WorkException exc;
+
+ /**
+ * The start delay duration (in milliseconds).
+ */
+ private long startDuration = WorkManager.UNKNOWN;
+
+ /**
+ * Constructor.
+ *
+ * @param source The object on which the event initially
+ * occurred.
+ *
+ * @param type The event type.
+ *
+ * @param work The <code>Work</code> object on which
+ * the event occured.
+ *
+ * @param exc The exception that occured during
+ * <code>Work</code> processing.
+
*/
- public WorkEvent(Object source, int type, Work work, WorkException e)
- {
- this(source, type, work, e, 0l);
- }
-
- /**
- * Create a new WorkEvent
- *
- * @param source the source of the event
- * @param type the type
- * @param work the work
- * @param e the exception
- * @param startDuration the delay in the start in milliseconds
- */
- public WorkEvent(Object source, int type, Work work, WorkException e, long startDuration)
- {
- super(source);
- this.type = type;
- this.work = work;
- this.e = e;
- this.startDuration = startDuration;
- }
-
- /**
- * Get the type
- *
- * @return the type
- */
- public int getType()
- {
- return type;
- }
-
- /**
- * Get the work
- *
- * @return the work
- */
- public Work getWork()
- {
- return work;
- }
-
- /**
- * Get the exception
- *
- * @return the work exception
- */
- public WorkException getException()
- {
- return e;
- }
-
- /**
- * Get the start duration
- *
- * @return the start duration
- */
- public long getStartDuration()
- {
- return startDuration;
- }
+ public WorkEvent(Object source, int type, Work work, WorkException exc) {
+ super(source);
+ this.type = type;
+ this.work = work;
+ this.exc = exc;
+ }
- // Private -------------------------------------------------------
- private void readObject(ObjectInputStream ois)
- throws ClassNotFoundException, IOException
- {
- ObjectInputStream.GetField fields = ois.readFields();
- String name = serialPersistentFields[TYPE_IDX].getName();
- this.type = fields.get(name, 0);
- name = serialPersistentFields[WORK_IDX].getName();
- this.work = (Work) fields.get(name, null);
- name = serialPersistentFields[EXCPEPTION_IDX].getName();
- this.e = (WorkException) fields.get(name, null);
- name = serialPersistentFields[DURATION_IDX].getName();
- this.startDuration = fields.get(name, 0L);
- }
+ /**
+ * Constructor.
+ *
+ * @param source The object on which the event initially
+ * occurred.
+ *
+ * @param type The event type.
+ *
+ * @param work The <code>Work</code> object on which
+ * the event occured.
+ *
+ * @param exc The exception that occured during
+ * <code>Work</code> processing.
+ *
+ * @param startDuration The start delay duration
+ * (in milliseconds).
+ */
+ public WorkEvent(Object source, int type, Work work, WorkException exc,
+ long startDuration) {
+ this(source, type, work, exc);
+ this.startDuration = startDuration;
+ }
- private void writeObject(ObjectOutputStream oos)
- throws IOException
- {
- // Write j2ee 1.4.1 RI field names
- ObjectOutputStream.PutField fields = oos.putFields();
- String name = serialPersistentFields[TYPE_IDX].getName();
- fields.put(name, type);
- name = serialPersistentFields[WORK_IDX].getName();
- fields.put(name, work);
- name = serialPersistentFields[EXCPEPTION_IDX].getName();
- fields.put(name, e);
- name = serialPersistentFields[DURATION_IDX].getName();
- fields.put(name, startDuration);
- oos.writeFields();
- }
+ /**
+ * Return the type of this event.
+ *
+ * @return the event type.
+ */
+ public int getType() { return this.type; }
+
+ /**
+ * Return the <code>Work</code> instance which is the cause of the event.
+ *
+ * @return the <code>Work</code> instance.
+ */
+ public Work getWork() { return this.work; }
+
+ /**
+ * Return the start interval duration.
+ *
+ * @return the time elapsed (in milliseconds) since the <code>Work</code>
+ * was accepted, until the <code>Work</code> execution started. Note,
+ * this does not offer real-time guarantees. It is valid to return -1, if
+ * the actual start interval duration is unknown.
+ */
+ public long getStartDuration() { return this.startDuration; }
+
+ /**
+ * Return the <code>WorkException</code>. The actual
+ * <code>WorkException</code> subtype returned depends on the type of the
+ * event.
+ *
+ * @return a <code>WorkRejectedException</code> or a
+ * <code>WorkCompletedException</code>, if any.
+ */
+ public WorkException getException() { return this.exc; }
}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkException.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkException.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkException.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,73 +19,89 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi.work;
-import javax.resource.ResourceException;
-
/**
- * Thrown when there is an error handling work.
+ * A common base class for all <code>Work</code> processing related exceptions.
+ *
+ * @version 1.0
+ * @author Ram Jeyaraman
*/
-public class WorkException extends ResourceException
-{
- /** An internal error */
- public static final String INTERNAL = "-1";
- /** An undefined error */
- public static final String UNDEFINED = "0";
- /** Expiration before work was started */
- public static final String START_TIMED_OUT = "1";
- /** Not allowed to do concurrent work on a transaction */
- public static final String TX_CONCURRENT_WORK_DISALLOWED = "2";
- /** Could not recreate the transaction context */
- public static final String TX_RECREATE_FAILED = "3";
+public class WorkException extends javax.resource.ResourceException {
- /**
- * Create an exception.
- */
- public WorkException()
- {
- super();
- }
- /**
- * Create an exception with a reason.
- *
- * @param reason the reason
- */
- public WorkException(String reason)
- {
- super(reason);
- }
+ /**
+ * Indicates an internal error condition.
+ */
+ public static final String INTERNAL = "-1";
- /**
- * Create an exception with a reason and an errorCode.
- *
- * @param reason the reason
- * @param errorCode the error code
- */
- public WorkException(String reason, String errorCode)
- {
- super(reason, errorCode);
- }
+ /**
+ * Undefined error code.
+ */
+ public static final String UNDEFINED = "0";
- /**
- * Create an exception with a reason and an error.
- *
- * @param reason the reason
- * @param throwable the error
- */
- public WorkException(String reason, Throwable throwable)
- {
- super(reason, throwable);
- }
+ /**
+ * Indicates start timeout expiration.
+ */
+ public static final String START_TIMED_OUT = "1";
- /**
- * Create an exception with an error.
- *
- * @param throwable the error
- */
- public WorkException(Throwable throwable)
- {
- super(throwable);
- }
+ /**
+ * Indicates that concurrent work within a transaction is
+ * disallowed. That is, there is already another <code>Work</code>
+ * instance associated with the specified transaction context.
+ */
+ public static final String TX_CONCURRENT_WORK_DISALLOWED = "2";
+
+ /**
+ * Indicates a failure in recreating the specified transaction context.
+ */
+ public static final String TX_RECREATE_FAILED = "3";
+
+ /**
+ * Constructs a new instance with null as its detail message.
+ */
+ public WorkException() { super(); }
+
+ /**
+ * Constructs a new instance with the specified detail message.
+ *
+ * @param message the detail message.
+ */
+ public WorkException(String message) {
+ super(message);
+ }
+
+ /**
+ * Constructs a new throwable with the specified cause.
+ *
+ * @param cause a chained exception of type
+ * <code>Throwable</code>.
+ */
+ public WorkException(Throwable cause) {
+ super(cause);
+ }
+
+ /**
+ * Constructs a new throwable with the specified detail message and cause.
+ *
+ * @param message the detail message.
+ *
+ * @param cause a chained exception of type
+ * <code>Throwable</code>.
+ */
+ public WorkException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ /**
+ * Constructs a new throwable with the specified detail message and
+ * an error code.
+ *
+ * @param message a description of the exception.
+ * @param errorCode a string specifying the vendor specific error code.
+ */
+ public WorkException(String message, String errorCode) {
+ super(message, errorCode);
+ }
}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkListener.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkListener.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkListener.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,41 +19,49 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi.work;
+import java.lang.Object;
+import java.lang.Runnable;
+import java.lang.Exception;
+import java.lang.Throwable;
import java.util.EventListener;
/**
- * Listens to events on work
- * @version $Revision$
+ * This models a <code>WorkListener</code> instance which would be notified
+ * by the <code>WorkManager</code> when the various <code>Work</code>
+ * processing events (work accepted, work rejected, work started,
+ * work completed) occur.
+ *
+ * The <code>WorkListener</code> instance must not make any thread
+ * assumptions and must be thread-safe ie., a notification could
+ * occur from any arbitrary thread. Further, it must not make any
+ * assumptions on the ordering of notifications.
+ *
+ * @version 1.0
+ * @author Ram Jeyaraman
*/
-public interface WorkListener extends EventListener
-{
- /**
- * Invoked when work is accepted
- *
- * @param e the event
- */
- void workAccepted(WorkEvent e);
+public interface WorkListener extends EventListener {
- /**
- * Invoked when work is rejected
- *
- * @param e the event
- */
- void workRejected(WorkEvent e);
+ /**
+ * Invoked when a <code>Work</code> instance has been accepted.
+ */
+ void workAccepted(WorkEvent e);
- /**
- * Invoked when work is started
- *
- * @param e the event
- */
- void workStarted(WorkEvent e);
+ /**
+ * Invoked when a <code>Work</code> instance has been rejected.
+ */
+ void workRejected(WorkEvent e);
- /**
- * Invoked when work is completed
- *
- * @param e the event
- */
- void workCompleted(WorkEvent e);
-}
\ No newline at end of file
+ /**
+ * Invoked when a <code>Work</code> instance has started execution.
+ * This only means that a thread has been allocated.
+ */
+ void workStarted(WorkEvent e);
+
+ /**
+ * Invoked when a <code>Work</code> instance has completed execution.
+ */
+ void workCompleted(WorkEvent e);
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkManager.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkManager.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkManager.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,87 +19,245 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi.work;
+import java.lang.Object;
+import java.lang.Runnable;
+import java.lang.Exception;
+import java.lang.Throwable;
/**
- * Interface used to associate the resource adapter with objects that implement
- * this interface.
+ * This interface models a <code>WorkManager</code> which provides a facility
+ * to submit <code>Work</code> instances for execution. This frees the user
+ * from having to create Java threads directly to do work. Further, this
+ * allows efficient pooling of thread resources and more control over thread
+ * usage.
+ *
+ * The various stages in <code>Work</code> processing are:
+ * <ul>
+ * <li> work submit: A <code>Work</code> instance is being submitted for
+ * execution. The <code>Work</code> instance could either be accepted or
+ * rejected with a <code>WorkRejectedException</code> set to an appropriate
+ * error code. </li>
+ *
+ * <li> work accepted: The submitted <code>Work</code> instance has been
+ * accepted. The accepted <code>Work</code> instance could either start
+ * execution or could be rejected again with a
+ * <code>WorkRejectedException</code> set to an appropriate error code.
+ * There is no guarantee on when the execution would start unless a start
+ * timeout duration is specified. When a start timeout is specified, the
+ * <code>Work</code> execution must be started within the specified
+ * duration (not a real-time guarantee), failing which a
+ * <code>WorkRejectedException</code> set to an error code
+ * (<code>WorkRejected.TIMED_OUT</code>) is thrown. </li>
+ *
+ * <li> work rejected: The <code>Work</code> instance has been rejected.
+ * The <code>Work</code> instance could be rejected during <code>Work</code>
+ * submittal or after the <code>Work</code> instance has been accepted
+ * (but before Work instance starts execution). The rejection could be due
+ * to internal factors or start timeout expiration. A
+ * <code>WorkRejectedException</code> with an appropriate error code
+ * (indicates the reason) is thrown in both cases. </li>
+ *
+ * <li> work started: The execution of the <code>Work</code>
+ * instance has started. This means that a thread
+ * has been allocated for its execution. But this
+ * does not guarantee that the allocated thread has been scheduled to run
+ * on a CPU resource. Once execution is started, the allocated thread
+ * sets up an appropriate execution context (transaction , security, etc)
+ * and calls Work.run(). Note, any exception thrown during execution context
+ * setup or Work.run() leads to completion of processing. </li>
+ *
+ * <li> work completed: The execution of the <code>Work</code> has been
+ * completed. The execution could complete with or without an exception.
+ * The <code>WorkManager</code> catches any exception thrown during
+ * <code>Work</code> processing (which includes execution context setup),
+ * and wraps it with a <code>WorkCompletedException</code>. </li>
+ * </ul>
+ *
+ * @version 1.0
+ * @author Ram Jeyaraman
*/
-public interface WorkManager
-{
- /** Unknown/unspecified start delay */
- static final long UNKNOWN = -1l;
- /** No start delay */
- static final long IMMEDIATE = 0l;
- /** Indefinite start delay */
- static final long INDEFINITE = Long.MAX_VALUE;
-
- /**
- * Executes the work, the call blocks until the work completes
- *
- * @param work the work
- * @throws WorkException a generic error
- * @throws WorkRejectedException if the work is rejected
- * @throws WorkCompletedException if the work completes with an exception
- */
- void doWork(Work work) throws WorkException;
-
- /**
- * Executes the work, the call blocks until the work completes
- *
- * @param work the work
- * @param startTimeout the wait before execution
- * @param ctx the execution context
- * @param listener the work listener
- * @throws WorkException a generic error
- * @throws WorkRejectedException if the work is rejected
- * @throws WorkCompletedException if the work completes with an exception
- */
- void doWork(Work work, long startTimeout, ExecutionContext ctx, WorkListener listener) throws WorkException;
-
- /**
- * Executes the work, the call blocks until the work starts
- *
- * @param work the work
- * @return the time elapsed until the work starts
- * @throws WorkException a generic error
- * @throws WorkRejectedException if the work is rejected
- */
- long startWork(Work work) throws WorkException;
-
-
- /**
- * Executes the work, the call blocks until the work starts
- *
- * @param work the work
- * @param startTimeout the wait before execution
- * @param ctx the execution context
- * @param listener the work listener
- * @return the time elapsed until the work starts
- * @throws WorkException a generic error
- * @throws WorkRejectedException if the work is rejected
- */
- long startWork(Work work, long startTimeout, ExecutionContext ctx, WorkListener listener) throws WorkException;
-
- /**
- * Executes the work, the call returns immediatley
- *
- * @param work the work
- * @throws WorkException a generic error
- * @throws WorkRejectedException if the work is rejected
- */
- void scheduleWork(Work work) throws WorkException;
-
- /**
- * Executes the work, the call returns immediately
- *
- * @param work the work
- * @param startTimeout the wait before execution
- * @param ctx the execution context
- * @param listener the work listener
- * @throws WorkException a generic error
- * @throws WorkRejectedException if the work is rejected
- */
- void scheduleWork(Work work, long startTimeout, ExecutionContext ctx, WorkListener listener) throws WorkException;
-}
\ No newline at end of file
+public interface WorkManager {
+
+ /**
+ * A constant to indicate timeout duration. A zero timeout value indicates
+ * an action be performed immediately.
+ */
+ long IMMEDIATE = 0L;
+
+ /**
+ * A constant to indicate timeout duration. A maximum timeout value
+ * indicates that an action be performed arbitrarily without any time
+ * constraint.
+ */
+ long INDEFINITE = Long.MAX_VALUE;
+
+ /**
+ * A constant to indicate an unknown start delay duration or other unknown
+ * values.
+ */
+ long UNKNOWN = -1;
+
+ /**
+ * Accepts a <code>Work</code> instance for processing. This call
+ * blocks until the <code>Work</code> instance completes execution.
+ * There is no guarantee on when the accepted <code>Work</code>
+ * instance would start execution ie., there is no time constraint
+ * to start execution.
+ *
+ * @param work The unit of work to be done.
+ * Could be long or short-lived.
+ *
+ * @throws WorkRejectedException indicates that a
+ * <code>Work</code> instance has been rejected from further processing.
+ * This can occur due to internal factors.
+ *
+ * @throws WorkCompletedException indicates that a
+ * <code>Work</code> instance has completed execution with an exception.
+ */
+ void doWork(Work work) // startTimeout = INDEFINITE
+ throws WorkException;
+
+ /**
+ * Accepts a <code>Work</code> instance for processing. This call
+ * blocks until the <code>Work</code> instance completes execution.
+ *
+ * @param work The unit of work to be done.
+ * Could be long or short-lived.
+ *
+ * @param startTimeout a time duration (in milliseconds)
+ * within which the execution of the <code>Work</code> instance must
+ * start. Otherwise, the <code>Work</code> instance is rejected with a
+ * <code>WorkRejectedException</code> set to an appropriate error code
+ * (<code>WorkRejectedException.TIMED_OUT</code>). Note, this
+ * does not offer real-time guarantees.
+ *
+ * @param execContext an object containing the execution
+ * context with which the submitted <code>Work</code> instance must
+ * be executed.
+ *
+ * @param workListener an object which would be notified
+ * when the various <code>Work</code> processing events (work accepted,
+ * work rejected, work started, work completed) occur.
+ *
+ * @throws WorkRejectedException indicates that a
+ * <code>Work</code> instance has been rejected from further processing.
+ * This can occur due to internal factors or start timeout expiration.
+ *
+ * @throws WorkCompletedException indicates that a
+ * <code>Work</code> instance has completed execution with an exception.
+ */
+ void doWork(Work work, long startTimeout,
+ ExecutionContext execContext, WorkListener workListener)
+ throws WorkException;
+
+ /**
+ * Accepts a <code>Work</code> instance for processing. This call
+ * blocks until the <code>Work</code> instance starts execution
+ * but not until its completion. There is no guarantee on when
+ * the accepted <code>Work</code> instance would start
+ * execution ie., there is no time constraint to start execution.
+ *
+ * @param work The unit of work to be done.
+ * Could be long or short-lived.
+ *
+ * @return the time elapsed (in milliseconds) from <code>Work</code>
+ * acceptance until start of execution. Note, this does not offer
+ * real-time guarantees. It is valid to return -1, if the actual start
+ * delay duration is unknown.
+ *
+ * @throws WorkRejectedException indicates that a
+ * <code>Work</code> instance has been rejected from further processing.
+ * This can occur due to internal factors.
+ */
+ long startWork(Work work) // startTimeout = INDEFINITE
+ throws WorkException;
+
+ /**
+ * Accepts a <code>Work</code> instance for processing. This call
+ * blocks until the <code>Work</code> instance starts execution
+ * but not until its completion. There is no guarantee on when
+ * the accepted <code>Work</code> instance would start
+ * execution ie., there is no time constraint to start execution.
+ *
+ * @param work The unit of work to be done.
+ * Could be long or short-lived.
+ *
+ * @param startTimeout a time duration (in milliseconds)
+ * within which the execution of the <code>Work</code> instance must
+ * start. Otherwise, the <code>Work</code> instance is rejected with a
+ * <code>WorkRejectedException</code> set to an appropriate error code
+ * (<code>WorkRejectedException.TIMED_OUT</code>). Note, this
+ * does not offer real-time guarantees.
+ *
+ * @param execContext an object containing the execution
+ * context with which the submitted <code>Work</code> instance must
+ * be executed.
+ *
+ * @param workListener an object which would be notified
+ * when the various <code>Work</code> processing events (work accepted,
+ * work rejected, work started, work completed) occur.
+ *
+ * @return the time elapsed (in milliseconds) from <code>Work</code>
+ * acceptance until start of execution. Note, this does not offer
+ * real-time guarantees. It is valid to return -1, if the actual start
+ * delay duration is unknown.
+ *
+ * @throws WorkRejectedException indicates that a
+ * <code>Work</code> instance has been rejected from further processing.
+ * This can occur due to internal factors or start timeout expiration.
+ */
+ long startWork(Work work, long startTimeout,
+ ExecutionContext execContext, WorkListener workListener)
+ throws WorkException;
+
+ /**
+ * Accepts a <code>Work</code> instance for processing. This call
+ * does not block and returns immediately once a <code>Work</code>
+ * instance has been accepted for processing. There is no guarantee
+ * on when the submitted <code>Work</code> instance would start
+ * execution ie., there is no time constraint to start execution.
+ *
+ * @param work The unit of work to be done.
+ * Could be long or short-lived.
+ *
+ * @throws WorkRejectedException indicates that a
+ * <code>Work</code> instance has been rejected from further processing.
+ * This can occur due to internal factors.
+ */
+ void scheduleWork(Work work) // startTimeout = INDEFINITE
+ throws WorkException;
+
+ /**
+ * Accepts a <code>Work</code> instance for processing. This call
+ * does not block and returns immediately once a <code>Work</code>
+ * instance has been accepted for processing.
+ *
+ * @param work The unit of work to be done.
+ * Could be long or short-lived.
+ *
+ * @param startTimeout a time duration (in milliseconds)
+ * within which the execution of the <code>Work</code> instance must
+ * start. Otherwise, the <code>Work</code> instance is rejected with a
+ * <code>WorkRejectedException</code> set to an appropriate error code
+ * (<code>WorkRejectedException.TIMED_OUT</code>). Note, this
+ * does not offer real-time guarantees.
+ *
+ * @param execContext an object containing the execution
+ * context with which the submitted <code>Work</code> instance must
+ * be executed.
+ *
+ * @param workListener an object which would be notified
+ * when the various <code>Work</code> processing events (work accepted,
+ * work rejected, work started, work completed) occur.
+ *
+ * @throws WorkRejectedException indicates that a
+ * <code>Work</code> instance has been rejected from further processing.
+ * This can occur due to internal factors.
+ */
+ void scheduleWork(Work work, long startTimeout,
+ ExecutionContext execContext, WorkListener workListener)
+ throws WorkException;
+}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkRejectedException.java
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkRejectedException.java 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/WorkRejectedException.java 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,6 +1,6 @@
/*
* JBoss, Home of Professional Open Source
-* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* Copyright 2008, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
@@ -19,62 +19,69 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
+
package javax.resource.spi.work;
-import javax.resource.ResourceException;
+/**
+ * This exception is thrown by a <code>WorkManager</code> to indicate
+ * that a submitted <code>Work</code> instance has been rejected. The
+ * rejection could be due to internal factors or start timeout expiration.
+ *
+ * <p>This could be thrown only before the execution of a
+ * <code>Work</code> instance starts (that is, before a
+ * thread has been allocated for <code>Work</code> execution).
-/**
- * Thrown when a work is rejected.
+ * <p>An associated error code indicates the nature of the error condition.
+ * Possible error codes are <code>WorkException.START_TIMED_OUT</code>,
+ * <code>WorkException.INTERNAL</code> or <code>WorkException.UNDEFINED</code>.
+ *
+ * @version 1.0
+ * @author Ram Jeyaraman
*/
-public class WorkRejectedException extends WorkException
-{
- /**
- * Create an exception.
- */
- public WorkRejectedException()
- {
- super();
- }
+public class WorkRejectedException extends WorkException {
- /**
- * Create an exception with a reason.
- *
- * @param reason the reason
- */
- public WorkRejectedException(String reason)
- {
- super(reason);
- }
+ /**
+ * Constructs a new instance with null as its detail message.
+ */
+ public WorkRejectedException() { super(); }
- /**
- * Create an exception with a reason and an errorCode.
- *
- * @param reason the reason
- * @param errorCode the error code
- */
- public WorkRejectedException(String reason, String errorCode)
- {
- super(reason, errorCode);
- }
+ /**
+ * Constructs a new instance with the specified detail message.
+ *
+ * @param message the detail message.
+ */
+ public WorkRejectedException(String message) {
+ super(message);
+ }
- /**
- * Create an exception with a reason and an error.
- *
- * @param reason the reason
- * @param throwable the error
- */
- public WorkRejectedException(String reason, Throwable throwable)
- {
- super(reason, throwable);
- }
+ /**
+ * Constructs a new throwable with the specified cause.
+ *
+ * @param cause a chained exception of type <code>Throwable</code>.
+ */
+ public WorkRejectedException(Throwable cause) {
+ super(cause);
+ }
- /**
- * Create an exception with an error.
- *
- * @param throwable the error
- */
- public WorkRejectedException(Throwable throwable)
- {
- super(throwable);
- }
+ /**
+ * Constructs a new throwable with the specified detail message and cause.
+ *
+ * @param message the detail message.
+ *
+ * @param cause a chained exception of type <code>Throwable</code>.
+ */
+ public WorkRejectedException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ /**
+ * Constructs a new throwable with the specified detail message and
+ * an error code.
+ *
+ * @param message a description of the exception.
+ * @param errorCode a string specifying the vendor specific error code.
+ */
+ public WorkRejectedException(String message, String errorCode) {
+ super(message, errorCode);
+ }
}
Modified: projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/package.html
===================================================================
--- projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/package.html 2008-12-10 15:50:12 UTC (rev 82193)
+++ projects/javaee/trunk/jboss-jca-api/src/main/javax/resource/spi/work/package.html 2008-12-10 16:19:26 UTC (rev 82194)
@@ -1,36 +1,7 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
- <head>
- <!-- $Id$ -->
- <!--
-
- JBoss: The OpenSource J2EE WebOS
-
- Distributable under LGPL license.
- See terms of license at gnu.org.
-
- -->
- </head>
-
- <body bgcolor="white">
- <p>J2EE Connector API - Work Management.
-
- <h2>Package Specification</h2>
- <ul>
- <li><a href="http://java.sun.com/j2ee/1.4/docs/api/index.html">Specified javadocs</a>
- </ul>
-
- <h2>Related Documentation</h2>
- <ul>
- <li><a href="http://java.sun.com/j2ee/connector/download.html">The specification</a>
- </ul>
-
- <h2>Package Status</h2>
- <ul>
- <li><font color="green"><b>STABLE</b></font>
- </ul>
-
- <!-- Put @see and @since tags down here. -->
-
- </body>
+<head>
+</head>
+<body>
+This package contains APIs for the Work Management, Generic Inflow and Security Inflow contracts.
+</body>
</html>
More information about the jboss-cvs-commits
mailing list