Configure EJB bindings in SCA OASIS applications

We can configure EJB service and reference bindings for use in SCA OASIS applications.

(dist)(zos)

New feature:

The SCA stateless session bean binding is a protocol binding that we can use to integrate SCA with EJB-based services. The product provides OASIS support for both EJB 3.x and 2.x bindings for services and references.newfeat

• Configure an EJB service binding to expose an SCA service as a stateless session bean for consumption by Java EE applications.

• Configure an EJB reference binding to enable SCA components to invoke stateless session beans.

• Configure EJB service bindings and invoke them in caller applications.

  Steps follow for configuring EJB 3.x and 2.x bindings:

  EJB 3.x binding

  1. Configure an EJB 3.x binding in a composite definition.

     The following example shows an OASIS composite definition that has a service exposed over an EJB 3.x binding:

     <composite xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200912"
                targetNamespace="http://www.ibm.com/samples/sca/ejb/jobbank"
                name="JobBank">
        <component name="CompanyComponent">
           <implementation.java class="com.app.jobbank.CompanyImpl"/>
           <!-- Expose service over the EJB 3.x binding -->
              <service name="Company">
                 <interface.java interface="com.app.jobbank.Company"/>
                 <binding.ejb/>
              </service>
        </component>
     </composite>

     The default ejb-version is EJB3 in an SCA OASIS implementation. You do not need to specify ejb-version. However, we can explicitly define ejb-version; for example:

     <binding.ejb ejb-version="EJB3"/>

     Do not specify the uniform resource identifier (URI) for the EJB service binding in the composite definition. The run time will generate a unique URI, which is used as the JNDI name for the session bean endpoint that is generated for the SCA service, and ignore any URI for the EJB service binding in the composite definition.

  2. Package the SCA composite with the service interface and implementation in a JAR and deploy the JAR in a business-level application.

     During SCA service startup, the run time generates a stateless session bean endpoint in memory that a Java EE client can invoke using the Java EE client programming model.

     The JNDI name for a generated session bean has the following format:

     ejb/sca/ejbbinding/component_name/service_name#package.qualified.sca.interface

     The JNDI name for the generated session bean for the jobbank composite service in step 1 is:

     ejb/sca/ejbbinding/CompanyComponent/Company#com.app.jobbank.Company

  3. Invoke the SCA service from a Java EE client application.

     The following code shows how to lookup and invoke an SCA service exposed as an EJB 3.x binding from a Java EE caller application:

     // Look up EJB for the SCA service Object remoteObj =
        initialContext.lookup("ejb/sca/ejbbinding/CompanyComponent/Company#com.app.jobbank.Company");
     Company company = (Company) PortableRemoteObject.narrow(remoteObj, Company.class); 
     // Invoke component service by invoking EJB method String result = company.getCompanyInfo("ACME");

     The Java EE caller application should use an SCA service interface as an EJB remote interface for the lookup and invocation. In the sample code, Company is an SCA service or business interface that is declared under the <interface.java> element. Thus, the only class required by the Java EE caller application is an SCA service or business interface.

     The SCA service can be looked up based on the WebSphere topology like a typical EJB; for example:

     "cell/nodes/node/servers/server_name/ejb/sca/ejbbinding/CompanyComponent/Company#com.app.jobbank.Company"
     
     "cell/clusters/cluster_name/ejb/sca/ejbbinding/CompanyComponent/Company#com.app.jobbank.Company"
     
     "corbaname:iiop:host:port/NameServiceServerRoot#ejb/sca/ejbbinding/CompanyComponent/Company#com.app.jobbank.Company"

  EJB 2.x binding

  1. Configure an EJB 2.x binding in a composite definition.

     The following example shows an OASIS composite definition that has a service exposed over an EJB 2.x binding:

     <composite xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200912"
                targetNamespace="http://www.ibm.com/samples/sca/ejb/jobbank"
                name="JobBank">
        <component name="CompanyComponent">
           <implementation.java class="com.app.jobbank.CompanyImpl"/>
           <!-- Expose service over the EJB 3.x binding -->
           <service name="Company">
              <interface.java interface="com.app.jobbank.Company"/>
              <binding.ejb ejb-version="EJB2"/>
           </service>
        </component>
     </composite>

     We must explicitly define ejb-version as EJB2.

     Do not specify the URI for the EJB service binding in the composite definition. The run time will generate a unique URI, which is used as the JNDI name for the session bean endpoint that is generated for the SCA service, and ignore any URI for the EJB service binding in the composite definition.

  2. Package the SCA composite with the stateless session bean service binding in a JAR and deploy the JAR in a business-level application.

     During deployment, the SCA run time generates a 2.x stateless session bean. The JNDI name pattern for a generated session bean is:

     ejb/sca/ejbbinding/component_name/service_name

     The JNDI name for the generated session bean for the jobbank composite service in step 1 is:

     ejb/sca/ejbbinding/CompanyComponent/Company

     The generated session bean for the composite service is under the directory, profile_root/installedApps/cell_name/sca.composite.nameApp.ear; for example: profile_root/installedApps/cell_name/JobBankApp.ear.

  3. Invoke the SCA service from a Java EE client application.

     The Java EE caller application invoking this SCA service should do either of the following:

     • Bundle generated classes from the directory in step 2 with the client application.

     • Add the generated EJB module JAR file from the directory in step 2 to the client class path.

       If the caller application is running on a non-WebSphere application server, a "Bare" Java Standard Edition (SE), or a version of WAS previous to version 7.0 without the Feature Pack for EJB 3.0, then you must run the createEJBStubs command for the generated EJB module to generate client-side stubs and include the generated subs at the client application. The createEJBStubs command is under the profile_root/installedApps/cell_name/sca.composite.nameApp.ear/ directory. See the topic on the create stubs command.

       If the caller of the SCA service is another SCA reference with an EJB binding, the caller SCA composite does not need to include the generated home, remote interface because the SCA reference binding implementation can invoke the SCA service binding implementation using only the SCA interface.

• Configure EJB reference bindings.

  An EJB reference binding enables SCA components to invoke stateless session beans.

  The following example shows an SCA composite definition containing an SCA reference with an EJB binding:

  <composite xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200912"
             targetNamespace="http://www.ibm.com/samples/sca/ejb/jobbank"
             name="JobBank">
  
    <component name="CompanyComponent">
  
       <reference name="extEJBService">
          <interface.java interface="com.app.resumebank.ResumeBank"/>
          <binding.ejb uri="ejb/com/app/resumebank/ResumeBankHome"/>
       </reference>
  
    </component> 
  </composite> 

  An EJB reference binding supports invocation of both local and remote stateless session beans.

  The binding URI should be the JNDI name of the stateless session bean which the SCA reference is trying to invoke. The JNDI name of the session bean can be in the EJB 2.x or EJB 3.x format based on whether the target EJB version is 2.x or 3.x. The JNDI name can be local if the target is a local session bean or remote if the target is remote.

  You do not need to specify an ejb-version attribute under the <binding.ejb> element for an EJB reference binding.

  Also, we do not need to package the target session bean home interface or client stubs with an SCA component with an EJB reference binding. The EJB session bean binding implementation can dynamically look up, create, and invoke the bean without the usual EJB client classes.

  For the SCA reference interface, use either the target EJB interface or its compatible interface. Interface compatibility rules are defined under Section 3.1, Compatibility of Interfaces used for SCA Services & References with EJB Session Bean Interfaces, of the EJB Session Bean Binding Specification 1.1.

  Some of the supported binding uri formats are in the following list. For binding uri, follow EJB 2.x or EJB 3.x JNDI lookup name formats based on the target EJB type.

  Corba url format

  <binding.ejb uri="corbaname:iiop:host:port/NameServiceServerRoot#jndi_name"/>

  Local session bean

  <binding.ejb uri="ejblocal:jndi_name"/>

  uri based on the topology

  Cluster

  <binding.ejb uri="cell/clusters/cluster_name/jndi_name" />

  Server

  <binding.ejb uri="cell/nodes/node/servers/server_name/jndi_name" />

  Persistent namespace

  <binding.ejb uri="cell/persistent/name_in_persistent_namespace_binding"/>

  If the SCA EJB reference binding is referencing another SCA service with an EJB binding in the same product cell, we can use the reference target=componentName/serviceName instead of the reference binding URI. For example:

  <reference name="anotherSCAEJBBindingService" target="SCAEJBServiceComponent/EJBService"/>

  If only one service exists for the service component, we can specify only the component name for the target and use the reference target=componentName instead of the reference binding URI. For example:

  <reference name="anotherSCAEJBBindingService" target="SCAEJBServiceComponent"/>

Results

You have configured an EJB service or reference binding for an SCA OASIS application.

Use of the bindings has the following limitations:

• A local EJB invocation from a Java EE application to an SCA service with an EJB 2.x or EJB 3.x binding is not supported.

• A Java EE application running on a non-WebSphere application server, on "bare" Java Standard Edition (SE), or on a WebSphere application server previous to Version 7.0 without the Feature Pack for EJB 3.0 cannot invoke the SCA EJB 3.x service binding.

• The product does not support an SCA composite that has both EJB 2.x and EJB 3.x services in different components but implements the same interface.

What to do next

Ensure that the components do not use an SCA OASIS implementation that the product does not support.

product does not support these sections of the SCA EJB Session Bean

Section

Not supported in SCA OASIS implementation

2 Session Bean Binding Schema

binding.ejb/@uri for SCA service binding The SCA stateless EJB implementation automatically generates a unique URI based on the component name, service name, and service interface. The URI is used as the EJB service endpoint. See step 1 in the "Configure EJB service bindings and invoke them in caller applications" procedure. corbaname:rir:#ejb/MyHome The product supports the cobra url format: corbaname:iiop:host:port/NameServiceServerRoot#jndi_name ejb-link-name The product does not support ejb-link-name in the SCA OASIS implementation.

Related concepts

Unsupported SCA specification sections

Related tasks

Specify bindings in an SCA environment

Configure EJB bindings in SCA applications

Create SCA business-level applications

Create stubs command