1 Introduction

This document specifies the means by which SCA composites and components, as defined in the SCA Assembly Specification [SCA-Assembly], connect to and access services provided by Enterprise Information Systems (EIS). The connectivity is based on the Java EE Connector Architecture (JCA) specification version 1.5 [JCA15], and is provided via a binding.jca element which applies to the references and services of an SCA composite or SCA component.

The connection to exchange data with the EIS is characterized by two sets of configuration parameters, the connection and interaction parameters. The former set determines the location of the target system the latter determines characteristics that need to be specified to invoke one specific service available at the endpoint. JCA Binding model captures these parameters as separate sets to allow their reuse and reconfiguration.

This binding places no requirement on SCA runtimes to support bidirectional interfaces as defined by the SCA Assembly Specification [SCA-Assembly], SCA runtimes can implement support for bidirectional interfaces using extensions to the binding element.

1.1 Terminology

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC Keywords [RFC2119].

This specification uses predefined namespace prefixes throughout; they are given in the following list. Note that the choice of any namespace prefix is arbitrary and not semantically significant.

*Prefix*	*Namespace*	*Notes*
xs	"http://www.w3.org/2001/XMLSchema"	Defined by XML Schema 1.0 specification
sca	"http://docs.oasis-open.org/ns/opencsa/sca/200912"	Defined by the SCA specifications

Table 1‑1: Prefixes and Namespaces used in this specification

1.2 Normative References

[RFC2119] S. Bradner, Key words for use in RFCs to Indicate Requirement Levels, http://www.ietf.org/rfc/rfc2119.txt, IETF RFC 2119, March 1997.

[JCA15] J2EE Connector Architecture Specification Version 1.5
http://java.sun.com/j2ee/connector/

[WSDL] E. Christensen et al, Web Service Description Language (WSDL) 1.1, http://www.w3.org/TR/2001/NOTE-wsdl-20010315, W3C Note, March 15 2001.

R. Chinnici et al, Web Service Description Language (WSDL) Version 2.0 Part 1: Core Language, http://www.w3.org/TR/2007/REC-wsdl20-20070626/, W3C Recommendation, June 26 2007.

[SCA-Assembly] OASIS Committee Draft 05, “Service Component Architecture Assembly Model Specification Version 1.1”, January 2010
http://docs.oasis-open.org/opencsa/sca-assembly/sca-assembly-1.1-spec-cd05.pdf

[SCA-Policy] OASIS Committee Draft 02, “SCA Policy Framework Specification Version 1.1”, February 2009
http://docs.oasis-open.org/opencsa/sca-policy/sca-policy-1.1-spec-cd02.pdf

1.3 Non-Normative References

N/A

1.4 Naming Conventions

The naming conventions used by artefacts defined in this specification are:

· The naming conventions defined by section 1.3 of the SCA Assembly Specification [SCA-Assembly].

· Where the names of elements and attributes consist partially or wholly of acronyms, the letters of the acronyms use the same case. When the acronym appears at the start of the name of an element or an attribute, or after a period, it is in lower case. If it appears elsewhere in the name of an element or an attribute, it is in upper case. For example, an attribute might be named "uri" or "jndiURL".

· Where the names of types consist partially or wholly of acronyms, the letters of the acronyms are in all upper case. For example, an XML Schema type might be named "JCABinding" or "MessageID".

· Values, including local parts of QName values, follow the rules for names of elements and attributes as stated above, with the exception that the letters of acronyms are in all upper case. For example, a value might be "JMSDefault" or "namespaceURI".

2 JCA Binding

The JCA binding element is defined by the pseudo-schema in Snippet 2‑1.

<binding.jca initialContextFactory=”xs:anyURI”?

jndiURL=”xs:anyURI”?

name=”NCName”?

requires=”list of xs:QName”?

policySets=”list of xs:QName”?

uri=”xsd:anyURI”?>

<property name=“NMTOKEN” type=“NMTOKEN”>*

</resourceAdapter>?

<connection jndiName=”xs:anyURI”? type="NMTOKEN”

create=”always or never or ifNotExist”?>

<property name=“NMTOKEN” type=“NMTOKEN”>*

</connection>

<resAuth>container|application</resAuth>?

</outboundConnection>?

<property name=“NMTOKEN” type=“NMTOKEN”>*

</resourceAdapter>

<activationSpec jndiName=”xs:anyURI”? type="NMTOKEN”

create=”always or never or ifNotExist”?>

<property name=“NMTOKEN” type=“NMTOKEN”>*

</activationSpec>

</inboundConnection>?

<property name=“NMTOKEN” type=“NMTOKEN”>*

</connectionSpec>?

<property name=“NMTOKEN” type=“NMTOKEN”>*

</interactionSpec>?

<property name=”NMTOKEN” type=”NMTOKEN”>*

</interactionSpec>?

</operation>*

</outboundInteraction>?

<listener type=”NMTOKEN”>?

<inboundOperation name="NMTOKEN" selectedOperation="NMTOKEN">*

</inboundInteraction>?

<wireFormat ... />?

<operationSelector ... />?

</binding.jca>

Snippet 2‑1: binding.jca Pseudo-Schema

The binding.jca element has the attributes:

· /binding.jca/@uri – the binding’s @uri attribute specifies the connection to the EIS. For a reference, it defines the endpoint allowing connecting to the target EIS by providing the JNDI name under which a ConnectionFactory is located. For a service, the @uri defines the endpoint to allow the EIS system to connect to the SCA system by defining the JNDI lookup name of an ActivationSpec, for example @uri=”java:comp/env/eis/TRAN_EIS”.

The @uri attribute, the inboundConnection and the outboundConnection element are mutually exclusive and the SCA runtime MUST raise an error if more than one is present [BJC20001].

For an SCA service with a binding.jca element with the @uri attribute value specified, if the JNDI location identified by the @uri attribute does not locate an Activation Spec the SCA runtime MUST raise an error [BJC20021].

For an SCA reference with a binding.jca element with the @uri attribute value specified, if the JNDI location identified by the @uri attribute does not locate a Connection Factory the SCA runtime MUST raise an error [BJC20022].

· /binding.jca/@initialContextFactory – the name of the JNDI initial context factory.

The @initialContextFactory attribute MUST NOT be specified if the @uri attribute is not present [BJC20002].

· /binding.jca/@jndiURL – the URL for the JNDI provider.

The @jndiURL attribute MUST NOT be specified if the @uri attribute is not present [BJC20003].

· /binding.jca/@name - as defined in the SCA Assembly Specification [SCA-Assembly].

· /binding.jca/@requires - as defined in the SCA Assembly Specification [SCA-Assembly].

· /binding.jca/@policySets - as defined in the SCA Assembly Specification [SCA-Assembly].

· /binding.jca/outboundConnection – defines the outbound connection characteristics.

The outboundConnection element MUST NOT be specified for services [BJC20004].

· /binding.jca/outboundConnection/@managed – determines whether the interaction with the EIS system is to be performed in the managed or non-managed mode. If the value is true (default), the JNDI name is used to obtain connection to the EIS and use adapter in the managed mode. If the value is false, the connection information is used to invoke adapter in the non-managed mode i.e. by creating instance of the ManagedConnectionFactory and using it to create Connection. For the full description of the managed and non-managed mode refer to section 6.9 of the JCA 1.5 specification [JCA15].

· /binding.jca/outboundConnection/resourceAdapter – specifies the name, type and properties of the Resource Adapter Java bean.

The SCA runtime MAY restrict valid properties of the outbound connection’s Resource Adapter Java bean depending on the deployment platform [BJC20005].

The outboundConnection/resourceAdapter element MUST NOT be specified when the @managed attribute value is “false” [BJC20006].

· /binding.jca/outboundConnection/resourceAdapter/@type – the fully qualified name of the class implementing the JCA ResourceAdapter interface.

If the outboundConnection/resourceAdapter/@type attribute is specified and the named Java class cannot be located or does not implement the javax.resource.spi.ResourceAdapter interface the SCA runtime MUST raise an error [BJC20028].

· /binding.jca/outboundConnection/resourceAdapter/@name – the optional name that uniquely identifies the existing instance of the resource adapter.

· /binding.jca/outboundConnection/resourceAdapter/property – contains the subset of the properties of the Resource Adapter Java Bean that need to be set in order to access specified EIS service. The full list of Resource Adapter properties can be obtained by introspecting the Java Bean.

· /binding.jca/outboundConnection/connection – specifies the properties of the connection factory used to create connections to the service endpoint.

· /binding.jca/outboundConnection/connection/@type – the fully qualified name of the class implementing the JCA ManagedConnectionFactory interface.

If the outboundConnection/connection/@type attribute is specified and the named Java class cannot be located or does not implement the javax.resource.cci.ConnectionFactory interface the SCA runtime MUST raise an error [BJC20027].

· /binding.jca/outboundConnection/connection/@jndiName – the JNDI name of the connection factory that the binding uses to connection to the EIS. The behavior of this attribute is determined by the value of the @create attribute:

– If the @create attribute value for an outboundConnection/connection or inboundConnection/activationSpec element is "always" and the @jndiName attribute is present and the resource cannot be created at the location specified by the @jndiName attribute, then the SCA runtime MUST raise an error [BJC20007].

If the @create attribute value for an outboundConnection/connection or inboundConnection/activationSpec element is "always" and the @jndiName attribute is not present and the resource cannot be created, then the SCA runtime MUST raise an error [BJC20008].

If the @jndiName attribute is omitted this specification places no restriction on the JNDI location of the created resource.

– If the @create attribute value for an outboundConnection/connection or inboundConnection/activationSpec element is "ifNotExist" then the @jndiName attribute MUST specify the location of the possibly existing resource [BJC20013].

If the @create attribute value for an outboundConnection/connection or inboundConnection/activationSpec element is “ifNotExist” and the resource does not exist at the location identified by the @jndiName attribute, but cannot be created there then the SCA runtime MUST raise an error [BJC20014].

If the @create attribute value for an outboundConnection/connection or inboundConnection/activationSpec element is “ifNotExist” and the @jndiName attribute refers to an existing resource that is not a connection factory of the appropriate type or an activation spec of the appropriate type respectively then the SCA runtime MUST raise an error [BJC20018].

– If the @create attribute value for an outboundConnection/connection or inboundConnection/activationSpec element is "never" then the @jndiName attribute MUST specify the location of the existing resource [BJC20019].

If the @create attribute value for an outboundConnection/connection or inboundConnection/activationSpec element is "never" and the resource is not present at the location identified by the @jndiName attribute, or the location refers to a resource of an incorrect type then the SCA runtime MUST raise an error [BJC20020].

· /binding.jca/outboundConnection/connection/property – contains the subset of the properties of the Managed Connection Factory Java Bean that need to be set in order to access specified EIS service. The full list of Managed Connection Factory properties can be obtained by introspecting the Java Bean.

· /binding.jca/outboundConnection/connection/@create – indicates whether the element containing the attribute should be created when the containing composite is deployed. Valid values are “always”, “never” and “ifNotExist”. "always" indicates that new resources are created for use by this binding; "never" indicates that existing resources are used and none created; "ifNotExist" indicates that if the resources already exist those are used, otherwise new ones are created. Refer to the outboundConnection/connection/@jndiName attribute for a detailed definition of each case. The default value is “ifNotExist”.

· /binding.jca/outboundConnection/connection/resAuth – specifies the authentication mechanism used by the resource adapter in the managed environment. Valid values are "container" and "application". "container" indicates that the SCA runtime takes the responsibility for configuring and managing the EIS sign-on; "application" indicates that the security details specified via the outboundConnection/connectionSpec element are used instead. If this element is omitted then no authentication is required by this binding definition.

· /binding.jca/outboundInteraction – defines characteristics of the outbound interaction.

The outboundInteraction element MUST NOT be specified for services [BJC20009].

· /binding.jca/outboundInteraction/connectionSpec – specifies client-level connection properties to be used when creating a connection. The ConnectionSpec object is used in several patterns that justify its definition in the interaction binding.

· /binding.jca/outboundInteraction/connectionSpec/@type – the fully qualified name of the class implementing javax.resource.cci.ConnectionSpec interface to be used when creating a connection.

If the outboundInteraction/connectionSpec/@type attribute is specified and the named Java class cannot be located or does not implement the javax.resource.cci.ConnectionSpec interface the SCA runtime MUST raise an error [BJC20030].

· /binding.jca/outboundInteraction/connectionSpec/property – specifies the set of client-level connection properties to be used when creating a connection, e.g. user name or password.

· /binding.jca/outboundInteraction/interactionSpec – specifies the interaction properties that apply to all operations that do not have one defined via an operation element.

When an operation is invoked via a reference with a binding.jca element, if there is an ouboundInteraction/operation element whose @name attribute matches the name of the operation being invoked, the SCA runtime MUST use the values supplied by the interactionSpec child of the operation element instead of the interactionSpec child of the binding.jca element, if any [BJC20025].

· /binding.jca/outboundInteraction/interactionSpec/@type – the fully qualified name of the class implementing the javax.resource.cci.InteractionSpec interface.

If the outboundInteraction/interactionSpec/@type attribute is specified and the named Java class cannot be located or does not implement the javax.resource.cci.InteractionSpec interface the SCA runtime MUST raise an error [BJC20032].

· /binding.jca/outboundInteraction/interactionSpec/property – specifies the set of interaction properties.

· /binding.jca/outboundInteraction/operation – specifies interactionSpec properties for individual operations in the interface associated with the binding.

· /binding.jca/outboundInteraction/operation/@name – the name of the operation in the interface for which the interactionSpec properties apply.

The value of the outboundInteraction/operation/@name attribute MUST be unique within the ouboundInteraction element and MUST match the name of one of the operations in the containing service’s or reference’s interface [BJC20026].

· /binding.jca/outboundInteraction/operation/interactionSpec – specifies the interaction properties for the named operation.

· /binding.jca/outboundInteraction/operation/interactionSpec/@type – the fully qualified name of the class implementing the javax.resource.cci.InteractionSpec interface.

If the outboundInteraction/operation/interactionSpec/@type attribute is specified and the named Java class cannot be located or does not implement the javax.resource.cci.InteractionSpec interface the SCA runtime MUST raise an error [BJC20033].

· /binding.jca/inboundConnection – defines the inbound connection characteristics.

The inboundConnection element MUST NOT be specified for references [BJC20010].

· /binding.jca/inboundConnection/resourceAdapter – specifies the name, type and properties of the Resource Adapter Java bean.

The SCA runtime MAY restrict valid properties of the inbound connection’s Resource Adapter Java bean depending on the deployment platform [BJC20011].

The inboundConnection/resourceAdapter element MUST NOT be specified when the @managed attribute is “false” [BJC20012].

· /binding.jca/inboundConnection/resourceAdapter/@type – the fully qualified name of the class implementing the ResourceAdapter interface.

If the inboundConnection/resourceAdapter/@type attribute is specified and the named Java class cannot be located or does not implement the javax.resource.spi.ResourceAdapter interface the SCA runtime MUST raise an error [BJC20029].

· /binding.jca/inboundConnection/resourceAdapter/@name – the optional name that uniquely identifies the existing instance of the resource adapter.

· /binding.jca/inboundConnection/activationSpec – identifies the activation spec that the binding uses to connect to an EIS. The attributes of this element follow the rules defined for the outboundConnection/connection element.

· /binding.jca/inboundConnection/activationSpec/@type – the fully qualified name of the class implementing the ActivationSpec interface.

If the inboundConnection/activationSpec/@type attribute is specified and the named Java class cannot be located or does not implement the javax.resource.spi.ActivationSpec interface the SCA runtime MUST raise an error [BJC20031].

· /binding.jca/inboundConnection/activationSpec/@jndiName – the JNDI name of the activation. The behaviour of this attribute is determined by the value of the @create attribute as defined for the outboundConnection/connection/@jndiName attribute.

· /binding.jca/inboundConnection/activationSpec/@create – indicates whether the element containing the attribute should be created when the containing composite is deployed. Valid values are “always”, “never” and “ifNotExist”. "always" indicates that new resources are created for use by this binding; "never" indicates that existing resources are used and none created; "ifNotExist" indicates that if the resources already exist those are used, otherwise new ones are created. Refer to the outboundConnection/connection/@jndiName attribute for a detailed definition of each case. The default value is “ifNotExist”.

· /binding.jca/inboundInteraction – defines characteristics of the inbound interaction.

The inboundInteraction element MUST NOT be specified for references [BJC20015].

· /binding.jca/inboundInteraction/listener/@type – the fully qualified name of the listener interface supported by this group of interactions.

If the inboundInteraction/listener element is not specified, the SCA runtime MUST use the default javax.resource.cci.MessageListener interface from the JCA specification [BJC20016].

If the inboundInteraction/listener/@type attribute is specified and the named Java class cannot be located or does not implement the javax.resource.cci.MessageListener interface the SCA runtime MUST raise an error [BJC20034].

· /binding.jca/inboundInteraction/inboundOperation – maps the name of the EIS event received by ResourceAdapter to the name of the operation in the interface.

· /binding.jca/inboundInteraction/inboundOperation/@name – the name of the operation in the interface.

The value of the inboundInteraction/inboundOperation/@name attribute MUST match the name of one of the operations in the containing service's or reference's interface [BJC20023].

· /binding.jca/inboundInteraction/inboundOperation/@selectedOperation – the value generated by the operationSelector that corresponds to the operation in the service or reference interface identified by the operationProperties/@name attribute.

The value of the inboundInteraction/inboundOperation/@selectedOperation attribute MUST be unique across the inboundInteraction element [BJC20024].

· /binding.jca/wireFormat – identifies the wire format used by requests and responses sent or received by this binding as defined in the SCA Assembly Specification [SCA-Assembly].

· /binding.jca/operationSelector – identifies the operation selector used when receiving requests for a service as defined in the SCA Assembly Specification [SCA-Assembly].

The binding.jca element MUST conform to the XML schema defined in sca-binding-jca-1.1.xsd [BJC20017].

2.1 Extensibility

The JCA Binding allows further customization of the binding element and its subelements with vendor specific attributes or elements. This is done by providing extension points in the schema; refer to Appendix A, “JCA XML Binding Schema: sca-binding-jca-1.1.xsd” for the locations of these extension points.

3 Policy

The JCA Specification [JCA15]does not define generic Resource Adapter characteristics that could be set using standard policy intents as defined in the SCA Policy Specification [SCA-Policy]. This specification places no requirements on the intents that are listed as either @alwaysProvides or @mayProvides in the bindingType for binding.jca.

4 Operation Selectors and Wire Formats

In general JCA resource adapters deal with records. There is not usually a built-in concept of “operation” that corresponds to that defined in a WSDL [WSDL] portType. Records have a format which corresponds in some way to the schema of an input or output message of an operation in the interface of a service or reference, however additional Resource Adapter-specific information is required in order for an SCA runtime to know how to identify the operation and understand the format of records.

The process of identifying the operation to be invoked is operation selection; the information that describes the contents of messages is a wire format. The binding element as described in the SCA Assembly Specification [SCA-Assembly] provides the means to identify specific operation selection via the operationSelector element and the format of messages received and to be sent using the wireFormat element.

When a service with a JCA binding receives a message, the SCA runtime resolves the name of the operation in the service's interface that is to be invoked by using the operationSelector and inboundInteraction elements defined for the binding. The resolved operation name is defined as follows:

· If the selected operation name generated by the operationSelector matches the value of an inboundInteraction/inboundOperation/@selectedOperation attribute then the resolved operation name is the value of the inboundInteraction/inboundOperation/@name attribute.

· Otherwise the resolved operation name is the selected operation name generated by the operationSelector.

When a message is received at an SCA service with JCA binding and the resolved operation name is in the target component’s interface, the SCA runtime MUST invoke the target component using the resolved operation name [BJC40001].

When a message is received at an SCA service with JCA binding and the resolved operation name is not in the target component's interface the SCA runtime MUST raise an error [BJC40002].

This specification does not define default behavior for the operation selection or wire format of a JCA binding. This choice had been made because the implementations of generic Record interfaces that define the data exchanged between JCA adapter and its client are specific to a particular adapter and, unlike JMS, cannot be used in a generic manner.

No standard means is provided for linking the wireFormat or operationSelector elements with the runtime components that implement their behavior.

5 Examples

5.1 Minimal JCA Binding

The minimal JCA Binding in Snippet 5‑1 only contains the binding’s @uri attribute with the JNDI name of the connection factory, which allows the binding runtime to obtain a Connection to execute requests against the EIS. Since no interaction properties are specified, it is assumed that Resource Adapter accepts null values for the invocation methods.

<binding.jca uri="java:comp/env/eis/EISMCF"/>

</reference>

Snippet 5‑1: Example Minimal Binding

5.2 Existing resources

In the example reference with JCA Binding in Snippet 5‑2 the binding’s @uri attribute specifies the existing resource - the JNDI name under which the connection factory object is located. The interaction properties are specified explicitly in the inlined outboundInteraction element.

<binding.jca uri="java:comp/env/eis/EISMCF">

<property name="userid">SYSAD</property>

</connectionSpec>

</interactionSpec>

</operation>

</outboundInteraction>

</binding.jca>

</reference>

Snippet 5‑2: Example Binding Using Existing Resources

5.3 Resource Creation

Snippet 5‑3 presents a reference with a JCA binding where the connection resources do not exist and need to be created.

<binding.jca>

<resourceAdapter

name="connector.file.FAResourceAdapter">

</resourceAdapter>

<connection jndiName="FAManagedConnectionFactory"

create="always">

<property name="host">localhost</property>

</connection>

</outboundConnection>

</binding.jca>

</reference>

Snippet 5‑3: Example Binding that Creates a Resource

6 Conformance

The XML schema pointed to by the RDDL document at the namespace URI, defined by this specification, are considered to be authoritative and take precedence over the XML schema defined in the appendix of this document. There are two categories of artifacts for which this specification defines conformance:

a) SCA JCA Binding XML Document

b) SCA Runtime

6.1 SCA JCA Binding XML Document

An SCA JCA Binding XML document is an SCA Composite Document or an SCA ComponentType Document, as defined by the SCA Assembly specification Section 13.1 [SCA-Assembly], that uses the binding.jcaelement.

An SCA JCA Binding XML document MUST be a conformant SCA Composite Document or an SCA ComponentType Document, as defined by the SCA Assembly Specification [SCA-Assembly], and MUST comply with all statements in Appendix B: “Conformance Items” related to elements and attributes in an SCA JCA Binding XML document, notably all "MUST" statements have to be implemented.

6.2 SCA Runtime

An implementation that claims to conform to the requirements of an SCA Runtime defined in this specification has to meet the following conditions:

The implementation MUST comply with all statements in Appendix B: “Conformance Items” related to an SCA Runtime, notably all "MUST" statements have to be implemented
The implementation MUST conform to the SCA Assembly Model Specification Version 1.1 [SCA-Assembly], and to the SCA Policy Framework Version 1.1 [SCA-Policy]
The implementation MUST reject an SCA JCA Binding XML Document that is not conformant per Section 6.1

A. JCA XML Binding Schema: sca-binding-jca-1.1.xsd

<?xml version="1.0" encoding="UTF-8"?>

OASIS trademark, IPR and other policies apply. -->

<schema xmlns="http://www.w3.org/2001/XMLSchema"

targetNamespace=" http://docs.oasis-open.org/ns/opencsa/sca/200912"

xmlns:sca=" http://docs.oasis-open.org/ns/opencsa/sca/200912" elementFormDefault="qualified">

<element name="outboundConnection"

type="sca:JCAOutboundConnection" minOccurs="0" />

<element name="inboundConnection"

type="sca:JCAInboundConnection" minOccurs="0" />

<element name="outboundInteraction"

type="sca:JCAOutboundInteraction" minOccurs="0" />

<element name="inboundInteraction"

type="sca:JCAInboundInteraction" minOccurs="0" />

<element name="property" type="sca:Property" minOccurs="0"

maxOccurs="unbounded"/>

</sequence>

<attribute name="initialContextFactory" type="anyURI"

use="optional"/>

</extension>

</complexContent>

</complexType>

</restriction>

</simpleType>

</restriction>

</simpleType>

<element name="resourceAdapter" type="sca:ResourceAdapter"

minOccurs="0" />

<any namespace="##other" processContents="lax" minOccurs="0"

maxOccurs="unbounded" />

</sequence>

<attribute name="managed" type="boolean" use="optional"

default="true" />

</complexType>

<any namespace="##other" processContents="lax" minOccurs="0"

maxOccurs="unbounded" />

</sequence>

</complexType>

<element name="connectionSpec" type="sca:ConnectionSpec"

minOccurs="0" />

<element name="interactionSpec" type="sca:InteractionSpec"

minOccurs="0" />

<any namespace="##other" processContents="lax" minOccurs="0"

maxOccurs="unbounded" />

</sequence>

</complexType>

<element name="inboundOperation" type="sca:InboundOperation"

minOccurs="0" maxOccurs="unbounded" />

<any namespace="##other" processContents="lax" minOccurs="0"

maxOccurs="unbounded" />

</sequence>

</complexType>

<element name="property" type="sca:Property" minOccurs="0"

maxOccurs="unbounded" />

<any namespace="##other" processContents="lax" minOccurs="0"

maxOccurs="unbounded" />

</sequence>

</complexType>

<element name="property" type="sca:Property" minOccurs="0"

maxOccurs="unbounded" />

<any namespace="##other" processContents="lax" minOccurs="0"

maxOccurs="unbounded" />

</sequence>

<attribute name="create" type="sca:JCACreateResource" use="optional"

default="ifNotExist" />

</complexType>

<element name="property" type="sca:Property" minOccurs="0"

maxOccurs="unbounded" />

<any namespace="##other" processContents="lax" minOccurs="0"

maxOccurs="unbounded" />

</sequence>

<attribute name="create" type="sca:JCACreateResource" use="optional"

default="ifNotExist"/>

</complexType>

<element name="interactionSpec" type="sca:InteractionSpec"

minOccurs="0" />

<any namespace="##other" processContents="lax" minOccurs="0"

maxOccurs="unbounded" />

</sequence>

</complexType>

<any namespace="##other" processContents="lax" minOccurs="0"

maxOccurs="unbounded" />

</sequence>

</complexType>

<element name="property" type="sca:Property" minOccurs="0"

maxOccurs="unbounded" />

<any namespace="##other" processContents="lax" minOccurs="0"

maxOccurs="unbounded" />

</sequence>

</complexType>

<element name="property" type="sca:Property" minOccurs="0"

maxOccurs="unbounded" />

<any namespace="##other" processContents="lax" minOccurs="0"

maxOccurs="unbounded" />

</sequence>

</complexType>

<element name="binding.jca" type="sca:JCABinding"

substitutionGroup="sca:binding" />

</schema>

B. Conformance Items

This section contains a list of conformance items for the SCA JCA Binding specification.

Conformance ID	Description
[BJC20001]	The *@uri* attribute, the *inboundConnection* and the *outboundConnection* element are mutually exclusive and the SCA runtime MUST raise an error if more than one is present
[BJC20002]	The *@initialContextFactory* attribute MUST NOT be specified if the *@uri* attribute is not present
[BJC20003]	The *@jndiURL* attribute MUST NOT be specified if the *@uri* attribute is not present
[BJC20004]	The *outboundConnection* element MUST NOT be specified for services
[BJC20005]	The SCA runtime MAY restrict valid properties of the outbound connection’s Resource Adapter Java bean depending on the deployment platform
[BJC20006]	The *outboundConnection/resourceAdapter* element MUST NOT be specified when the *@managed* attribute value is *“false”*
[BJC20007]	If the @create attribute value for an outboundConnection/connection or inboundConnection/activationSpec element is "always" and the @jndiName attribute is present and the resource cannot be created at the location specified by the @jndiName attribute, then the SCA runtime MUST raise an error
[BJC20008]	If the @create attribute value for an outboundConnection/connection or inboundConnection/activationSpec element is "always" and the @jndiName attribute is not present and the resource cannot be created, then the SCA runtime MUST raise an error
[BJC20009]	The *outboundInteraction* element MUST NOT be specified for services
[BJC20010]	The *inboundConnection* element MUST NOT be specified for references
[BJC20011]	The SCA runtime MAY restrict valid properties of the inbound connection’s Resource Adapter Java bean depending on the deployment platform
[BJC20012]	The *inboundConnection/resourceAdapter* element MUST NOT be specified when the *@managed* attribute is *“false”*
[BJC20013]	If the @create attribute value for an outboundConnection/connection or inboundConnection/activationSpec element is "ifNotExist" then the @jndiName attribute MUST specify the location of the possibly existing resource
[BJC20014]	If the @create attribute value for an outboundConnection/connection or inboundConnection/activationSpec element is “ifNotExist” and the resource does not exist at the location identified by the @jndiName attribute, but cannot be created there then the SCA runtime MUST raise an error
[BJC20015]	The *inboundInteraction* element MUST NOT be specified for references
[BJC20016]	If the *inboundInteraction/listener* element is not specified, the SCA runtime MUST use the default javax.resource.cci.MessageListener interface from the JCA specification
[BJC20017]	The binding.jca element MUST conform to the XML schema defined in sca-binding-jca-1.1.xsd
[BJC20018]	If the @create attribute value for an outboundConnection/connection or inboundConnection/activationSpec element is “ifNotExist” and the @jndiName attribute refers to an existing resource that is not a connection factory of the appropriate type or an activation spec of the appropriate type respectively then the SCA runtime MUST raise an error
[BJC20019]	If the @create attribute value for an outboundConnection/connection or inboundConnection/activationSpec element is "never" then the @jndiName attribute MUST specify the location of the existing resource
[BJC20020]	If the @create attribute value for an outboundConnection/connection or inboundConnection/activationSpec element is "never" and the resource is not present at the location identified by the @jndiName attribute, or the location refers to a resource of an incorrect type then the SCA runtime MUST raise an error
[BJC20021]	For an SCA service with a binding.jca element with the @uri attribute value specified, if the JNDI location identified by the @uri attribute does not locate an Activation Spec the SCA runtime MUST raise an error
[BJC20022]	For an SCA reference with a binding.jca element with the @uri attribute value specified, if the JNDI location identified by the @uri attribute does not locate a Connection Factory the SCA runtime MUST raise an error
[BJC20023]	The value of the inboundInteraction/inboundOperation/@name attribute MUST match the name of one of the operations in the containing service's or reference's interface
[BJC20024]	The value of the inboundInteraction/inboundOperation/@selectedOperation attribute MUST be unique across the inboundInteraction element
[BJC20025]	When an operation is invoked via a reference with a binding.jca element, if there is an ouboundInteraction/operation element whose @name attribute matches the name of the operation being invoked, the SCA runtime MUST use the values supplied by the interactionSpec child of the operation element instead of the interactionSpec child of the binding.jca element, if any
[BJC20026]	The value of the outboundInteraction/operation/@name attribute MUST be unique within the ouboundInteraction element and MUST match the name of one of the operations in the containing service’s or reference’s interface
[BJC20027]	If the outboundConnection/connection/@type attribute is specified and the named Java class cannot be located or does not implement the javax.resource.cci.ConnectionFactory interface the SCA runtime MUST raise an error
[BJC20028]	If the outboundConnection/resourceAdapter/@type attribute is specified and the named Java class cannot be located or does not implement the javax.resource.spi.ResourceAdapter interface the SCA runtime MUST raise an error
[BJC20029]	If the inboundConnection/resourceAdapter/@type attribute is specified and the named Java class cannot be located or does not implement the javax.resource.spi.ResourceAdapter interface the SCA runtime MUST raise an error
[BJC20030]	If the outboundInteraction/connectionSpec/@type attribute is specified and the named Java class cannot be located or does not implement the javax.resource.cci.ConnectionSpec interface the SCA runtime MUST raise an error
[BJC20031]	If the inboundConnection/activationSpec/@type attribute is specified and the named Java class cannot be located or does not implement the javax.resource.spi.ActivationSpec interface the SCA runtime MUST raise an error
[BJC20032]	If the outboundInteraction/interactionSpec/@type attribute is specified and the named Java class cannot be located or does not implement the javax.resource.cci.InteractionSpec interface the SCA runtime MUST raise an error
[BJC20033]	If the outboundInteraction/operation/interactionSpec/@type attribute is specified and the named Java class cannot be located or does not implement the javax.resource.cci.InteractionSpec interface the SCA runtime MUST raise an error
[BJC20034]	If the inboundInteraction/listener/@type attribute is specified and the named Java class cannot be located or does not implement the javax.resource.cci.MessageListener interface the SCA runtime MUST raise an error
[BJC40001]	When a message is received at an SCA service with JCA binding and the resolved operation name is in the target component’s interface, the SCA runtime MUST invoke the target component using the resolved operation name
[BJC40002]	When a message is received at an SCA service with JCA binding and the resolved operation name is not in the target component's interface the SCA runtime MUST raise an error

C. Java EE Connector Architecture

C.1 Introduction

The connector architecture specification defines set of contracts that allow interoperability of the resource adapters and application server environments. The specification also defines set of client interfaces that can be optionally supported by the adapter and allow the use of adapter functionality by the application clients. The following figure illustrates the relationships of these interfaces.

The SPI defines the following management contracts that give adapter consistent view of the infrastructure provided by the server and give sever consistent view of all the adapters thus helping with integration of adapters and servers.

Lifecycle management allows application server to control the startup of the adapter and notification to allow it to shutdown in an orderly fashion

Work management allows the adapter to use the server resources such as threads in an efficient way and allows server to manage system resources appropriately.
Connection management lets the server control the pooling, reusing and caching of the physical connections to the EIS system thus allowing for better scalability.
Transactions allow the server to control EIS resource managers and provide application clients with the transactional access to external resources.
Security contract allow for secure access to the EIS systems with security information configured and provided by the application server
Message inflow contract allows Resource Adapter to deliver events initiated by the EIS system to the application component executing on the application server.
Transaction inflow contract allow the application server to participate and execute in the context of the transaction initiated by the EIS system.

The CCI defines set of interfaces to access EIS functionality, through the resource adapter, from the application client. The CCI also provides access to some of the SPIs for transactions and security management to allow for executions of clients running in the non-managed mode, without the presence of the Application Server.

C.2 Selected JCA CCI Interfaces

Record

public interface javax.resource.cci.Record

extends java.lang.Cloneable, java.io.Serializable {

public String getRecordName();
public void setRecordName(String name);

public void setRecordShortDescription(String description);

public String getRecordShortDescription();

public boolean equals(Object other);

public int hashCode();

public Object clone() throws CloneNotSupportedException;

}

Interaction

public interface javax.resource.cci.Interaction {

public Connection getConnection();

public void close() throws ResourceException;

public boolean execute(InteractionSpec ispec,

Record input, Record output) throws ResourceException;

public Record execute(InteractionSpec ispec,

Record input) throws ResourceException;

}

MessageListener

interface javax.resource.cci.MessageListener {

Record onMessage(Record inputData) throws ResourceException;

}

D. Acknowledgements

The following individuals have participated in the creation of this specification and are gratefully acknowledged:

Participants:

Participant Name	Affiliation
Bryan Aupperle	IBM
Ron Barack	SAP AG
Michael Beisiegel	IBM
Henning Blohm	SAP AG
David Booz	IBM
Martin Chapman	Oracle Corporation
Jean-Sebastien Delfino	IBM
Laurent Domenech	TIBCO Software Inc.
Jacques Durand	Fujitsu Limited
Mike Edwards	IBM
Billy Feng	Primeton Technologies, Inc.
Nimish Hathalia	TIBCO Software Inc.
Simon Holdsworth	IBM
Eric Johnson	TIBCO Software Inc.
Uday Joshi	Oracle Corporation
Khanderao Kand	Oracle Corporation
Anish Karmarkar	Oracle Corporation
Nickolaos Kavantzas	Oracle Corporation
Mark Little	Red Hat
Ashok Malhotra	Oracle Corporation
Jim Marino	Individual
Jeff Mischkinsky	Oracle Corporation
Dale Moberg	Axway Software
Simon Nash	Individual
Sanjay Patil	SAP AG
Plamen Pavlov	SAP AG
Peter Peshev	SAP AG
Piotr Przybylski	IBM
Luciano Resende	IBM
Tom Rutt	Fujitsu Limited
Vladimir Savchenko	SAP AG
Scott Vorthmann	TIBCO Software Inc.
Tim Watson	Oracle Corporation
Owen Williams	Avaya, Inc.

E. Revision History

Revision	Date	Editor	Changes Made
1	2008-01-16	Anish Karmarkar	Applied the OASIS template + related changes to the Submission
2	2008-08-06	Piotr Przybylski	Updates for consistency with JMS Binding and to resolve the following: BINDINGS-13 BINDINGS-14 BINDINGS-28 BINDINGS-30 BINDINGS-32 BINDINGS-38
cd01-rev1	2008-10-16	Simon Holdsworth	Updates to resolve following issues: BINDINGS-41
cd01-rev2	2008-10-20	Piotr Przybylski	Update for RFC2119 conformance Updated to resolve following issues: BINDINGS-53
cd02	2009-02-16	Simon Holdsworth	Renamed and applied editorial issues
cd02-rev1	2009-05-22	Simon Holdsworth	Updates to resolve issue BINDINGS-63 (conformance statement numbering) Updated assembly namespace to 200903
cd02-rev2	2009-05-22	Simon Holdsworth	Updates to resolve following issues: BINDINGS-22 BINDINGS-45 BINDINGS-58 BINDINGS-69 Fixed errors in schema
cd02-rev3	2009-06-19	Simon Holdsworth	Updates to resolve following issues: BINDINGS-75 Added acknowledgements
cd02-rev4	2009-06-24	Simon Holdsworth	Updates to resolve following issues BINDINGS-78 Renamed document to old form Editorial fixes around external references; changed all links to hyperlinks
cd02-rev5	2009-06-24	Simon Holdsworth	Fixed broken cross-reference
cd03	2009-06-29	Simon Holdsworth	Update name to cd03
cd03-rev1	2010-01-24	Simon Holdsworth	Editorial fix to schema name Updates to resolve issues: BINDINGS-88 BINDINGS-89 BINDINGS-107
cd03-rev2	2010-02-17	Bryan Aupperle	Added captions for figures
cd03-rev3	2010-02-22	Simon Holdsworth	Updated for resolutions to issues: BINDINGS-101 BINDINGS-102 Updated assembly namespace Updates for editorial action items: 20091015-3: no change to copyright (currently consistent with all other SCA specs) 20091015-4: clarified the text describing the JCA binding 20091015-5: removed “further specification” text 20091015-7: duplication in abstract and introduction: no changes made 20091015-8: removed non-normative references section 20091015-9: cleaned up naming conventions section 20091015-10: cleaned up some phrases that used “allows” 20091015-11: clarified uses of the @uri attribute 20091015-12: no changes made (currently consistent with all other SCA specs) Fixed documentation of connectionSpec, interactionSpec and inboundOperation elements to include explicit bullets for the elements’ children
cd03-rev4	2010-03-15	Simon Holdsworth	Updated to resolve issues: BINDINGS-120 BINDINGS-121 BINDINGS-122 BINDINGS-123
cd03-rev5	2010-03-18	Simon Holdsworth	Updated to resolve issues: BINDINGS-125 Editorial cleanup Updated Assembly references to CD05 Fixed SCA namespace definition to 200912
cd03-rev6	2010-04-16	Simon Holdsworth	Updated to resolve issue BINDINGS-129
cd04	2010-04-30	Simon Holdsworth	Rename and fix acknowledgements, fix Assembly link to cd05, fixup for publication