34 Using Service Data Objects and Enterprise JavaBeans

This chapter describes how Enterprise JavaBeans and SOA composite applications interact by passing service data object (SDO) parameters.

This chapter includes the following sections:

Section 34.1, "Introduction to SDO and Enterprise JavaBeans Binding"
Section 34.2, "Designing an Enterprise JavaBeans Application"
Section 34.3, "Creating an Enterprise JavaBeans Adapter Service in Oracle JDeveloper"
Section 34.4, "Designing an Enterprise JavaBeans Client to Invoke Oracle SOA Suite"
Section 34.5, "Specifying Enterprise JavaBeans Roles"
Section 34.6, "Configuring JNDI Access"

34.1 Introduction to SDO and Enterprise JavaBeans Binding

SDOs enable you to modify business data regardless of how it is physically accessed. Knowledge is not required about how to access a particular back-end data source to use SDO in a SOA composite application. Consequently, you can use static or dynamic programming styles and obtain connected and disconnected access.

Enterprise JavaBeans are server-side domain objects that fit into a standard component-based architecture for building enterprise applications with Java. These objects become distributed, transactional, and secure components.

Oracle SOA Suite interfaces are described by the Web Services Description Language (WSDL) file. Enterprise JavaBeans interfaces are described by Java interfaces. Invocations between the two are made possible in Oracle SOA Suite by an Enterprise JavaBeans Java interface that corresponds to an Oracle SOA Suite WSDL interface.

Through this interface, Oracle SOA Suite provides support for the following:

Invoking Enterprise JavaBeans with SDO parameters through an Enterprise JavaBeans adapter reference. In this scenario, a SOA composite application passes SDO parameters to an external Enterprise JavaBeans application.
Invoking an Enterprise JavaBeans adapter service through Enterprise JavaBeans with SDO parameters. In this scenario, an Enterprise JavaBeans application passes SDO parameters into a SOA composite application.

Figure 34-1 provides an overview.

Figure 34-1 SDO and Enterprise JavaBeans Binding Integration

Description of "Figure 34-1 SDO and Enterprise JavaBeans Binding Integration"

34.2 Designing an Enterprise JavaBeans Application

This section provides a high-level overview of the steps for designing an Enterprise JavaBeans application. For more information, see the following documentation:

Oracle Fusion Middleware Programming Enterprise JavaBeans, Version 3.0 for Oracle WebLogic Server
Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework
Oracle JDeveloper online help table of contents for the following topics:
- Enterprise JavaBeans
- SDO for Enterprise JavaBeans/JPA
Access the help by selecting Help > Table of Contents in Oracle JDeveloper.

34.2.1 How to Create SDO Objects Using the SDO Compiler

Select one of the following options for creating SDO objects:

EclipseLink is an open source, object-relational mapping package for Java developers. EclipseLink provides a framework for storing Java objects in a relational database or converting Java objects to XML documents.

Use EclipseLink to create SDO objects. For instructions on installing, configuring, and using EclipseLink to create SDO objects, visit the following URL:
```
http://wiki.eclipse.org/EclipseLink/Installing_and_Configuring_EclipseLink
```
Oracle JDeveloper enables you to create an SDO service interface for JPA entities. While this feature is more tailored for use with the Oracle Application Development Framework (ADF) service binding in a SOA composite application, you can also use this feature with the Enterprise JavaBeans service binding in SOA composite applications. The SDO service interface feature generates the necessary WSDL and XSD files. If you use this feature, you must perform the following tasks to work with the Enterprise JavaBeans service binding:
- Browse for and select this WSDL file in the SOA Resource Browser dialog, which is accessible from the WSDL URL field of the Create EJB Service dialog (described in Section 34.3, "Creating an Enterprise JavaBeans Adapter Service in Oracle JDeveloper").
- Add the BC4J Service Runtime library to the SOA project. To add this library, double-click the project and select Libraries and Classpath to add the library in the Project Properties dialog. You are now ready to design the logic.
For more information, see the SDO for Enterprise JavaBeans/JPA topic in the Oracle JDeveloper online help (this includes instructions on how create to an SDO service interface).

34.2.2 How to Create a Session Bean and Import the SDO Objects

To create a session bean and import the SDO objects:

Create a simple session bean with the Create Session Bean wizard. For details on using this wizard, see the Creating a Session Bean topic in the Oracle JDeveloper online help.
Import the SDO objects into your project through the Project Properties dialog.
Add logic and necessary import and library files. In particular, you must import the Commonj.sdo.jar file. JAR files can be added in the Libraries and Classpath dialog. This dialog is accessible by double-clicking the project and selecting Libraries and Classpath in the Project Properties dialog. You are now ready to design the logic.
Expose the method to the remote interface.

34.2.3 How to Create a Profile and an EAR File

To create a profile and an EAR file:

Create an Enterprise JavaBeans JAR profile in the Project Properties dialog.
Create an application level EAR file in the Application Properties dialog.

34.2.4 How to Define the SDO Types with an Enterprise JavaBeans Bean

An Enterprise JavaBeans bean must define the SDO types. Example 34-1 provides details.

Caution:

Where to call define can be nontrivial. You must force the types to be defined before remote method invocation (RMI) marshalling must occur and in the right helper context. The EclipseLink SDO implementation indexes the helper instance with the application name or class loader.When you invoke the Enterprise JavaBeans method, an application name is available to the EclipseLink SDO runtime. The EclipseLink SDO looks up the context using the application name as the key. Ensure that the types are defined when the application name is visible. When an Enterprise JavaBeans static block is initialized, the application name is not created. Therefore, putting the define in the static block does not work if you are using the default application name-based context. One way to get the application name initialized is to allocate more than two instance beans using the weblogic-ejb-jar.xml file.

Example 34-1 Definition of SDO Types

InputStreamReader reader = new InputStreamReader(url.openStream());
StreamSource source = new StreamSource(reader);
List<SDOType> list = ((SDOXSDHelper) XSDHelper.INSTANCE).define(source, null);

The weblogic-ejb-jar.xml file is the descriptor file that must be added in the deployment jar. The weblogic-ejb-jar.xml file is automatically created when you create a session bean. This file must be modified by adding the following entries.

Example 34-2 weblogic-ejb-jar.xml File

<?xml version = '1.0' encoding = 'windows-1252'?>
<weblogic-ejb-jar xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xsi:schemaLocation="http://www.bea.com/ns/weblogic/weblogic-ejb-jar
 http://www.bea.com/ns/weblogic/weblogic-ejb-jar/1.0/weblogic-ejb-jar.xsd"
                  xmlns="http://www.bea.com/ns/weblogic/weblogic-ejb-jar">

    <weblogic-enterprise-bean>
    <ejb-name>HelloEJB</ejb-name>
    <stateless-session-descriptor>
      <pool>
        <initial-beans-in-free-pool>2</initial-beans-in-free-pool>
      </pool>
    </stateless-session-descriptor>
  </weblogic-enterprise-bean>

    </weblogic-ejb-jar>

Figure 34-2 provides a code example of a session bean with SDO logic defined:

Figure 34-2 Session Bean with Defined SDO Logic

Description of "Figure 34-2 Session Bean with Defined SDO Logic"

34.2.5 How to Use Web Service Annotations

In order to generate the WSDL file, the Enterprise JavaBeans interface must use the following web service annotations. Use of these annotations is described in JSR 224: Java API for XML-Based Web Services (JAX-WS) 2.0. Visit the following URL for details:

http://www.jcp.org/en/jsr/detail?id=224

In addition, only a document/literal WSDL is currently supported by the Enterprise JavaBeans binding layer.

Table 34-1 describes the annotations to use.

Table 34-1 Annotations

Name	Description
`@javax.jws.WebResult;` `@javax.jws.WebParam;`	Customize the mapping of an individual parameter to a web service message part and XML element. Both annotations are used to map SDO parameters to the correct XML element from the normalized message payload.
`@javax.jws.Oneway;`	Denote a method as a web service one-way operation that has only an input message and no output message. The Enterprise JavaBeans binding component does not expect any reply in this case.
`@javax.xml.ws.RequestWrapper;` `@javax.xml.ws.ResponseWrapper;`	Tell the Enterprise JavaBeans binding components whether the deserialized object must be unwrapped or whether a wrapper must be created before serialization. An Enterprise JavaBeans interface can be generated from an existing WSDL or obtained by some other means. If the WSDL does not exist, it can be generated.
`@javax.xml.ws.WebFault;`	Map WSDL faults to Java exceptions. This annotation captures the fault element name used when marshalling the JAXB type generated from the global element referenced by the WSDL fault message.
`@oracle.webservices.PortableWebService`	Specify the `targetNamespace` and `serviceName` used for the WSDL. For example: @PortableWebService( targetNamespace = "http://hello.demo.oracle/", serviceName = "HelloService") The `serviceName` is used as the WSDL file name. If it is not specified in the annotations, the SEI class name is used instead.
Add appropriate method parameter annotations	Add to control how message elements and types are mapped to the WSDL. For example, if your interface is in `doc/lit/bare` style, add the following annotations to the methods. @WebMethod @SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
`@SDODatabinding`	Add to the interface class to use the existing schema instead of a generated one. For example: @SDODatabinding(schemaLocation = "etc/HelloService.xsd")

Example 34-3 provides an example of an Enterprise JavaBeans interface with annotations.

Example 34-3 Enterprise JavaBeans Interface with Annotations

@Remote
@PortableWebService(targetNamespace = "http://www.example.org/customer-example",
 serviceName = "CustomerSessionEJBService")
@SDODatabinding(schemaLocation = "customer.xsd")
public interface CustomerSessionEJB {
     @WebMethod(operationName="createCustomer")
   @SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
   @WebResult(targetNamespace = "http://www.example.org/customer-example",
 partName = "parameters", name = "customer")
   CustomerType createCustomer();
     @WebMethod(operationName="addPhoneNumber")
   @SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
   @WebResult(targetNamespace = "http://www.example.org/customer-example",
 partName = "parameters", name = "customer")
   CustomerType addPhoneNumber(@WebParam(targetNamespace =
 "http://www.example.org/customer-example", partName = "parameters", name =
 "phone-number")PhoneNumber phNumber);
}

34.2.6 How to Deploy the Enterprise JavaBeans EAR File

To deploy the EAR file from Oracle JDeveloper:

Select the Application context menu to the right of the application name.
Select Deploy and deploy the EAR file to a previously created application server connection.

34.3 Creating an Enterprise JavaBeans Adapter Service in Oracle JDeveloper

This section describes how to create an Enterprise JavaBeans adapter reference or Enterprise JavaBeans adapter service in Oracle JDeveloper. This adapter service enables the Enterprise JavaBeans application to communicate with Oracle SOA Suite and Oracle SOA Suite to communicate with remote Enterprise JavaBeans.

34.3.1 Invoking SDO-based Enterprise JavaBeans from SOA Composite Applications

You can invoke Enterprise JavaBeans with SDO parameters from the Enterprise JavaBeans adapter reference in SOA composite applications.

34.3.1.1 How to Invoke SDO-based Enterprise JavaBeans from SOA Composite Applications

To invoke SDO-based Enterprise JavaBeans from SOA composite applications:

Drag an EJB Adapter Service icon into the External References swimlane.

The Create EJB Service dialog appears, as shown in Figure 34-3.

Figure 34-3 Create EJB Service in External References Swimlane

Description of "Figure 34-3 Create EJB Service in External References Swimlane"

Enter the details shown in Table 34-2:

Table 34-2 Create EJB Service Dialog

Field	Value
Name	Accept the default value or enter a different name.
Type	Displays Reference if you dragged this icon into the External References swimlane.
JNDI Name	Enter the JNDI name of your Enterprise JavaBeans.
Java Interface	Click the Browse icon to invoke the Class Browser dialog for selecting the fully qualified Java class name of the previously created Enterprise JavaBeans interface. This class must exist in the selected JAR file. If a JAR file is not specified, it is assumed that the class is in the /SCA-INF/classes subdirectory of the current project directory. If you have a new JAR file, you must add it to the project by selecting Project Properties > Libraries and Classpath > Add JAR/Directory from the Application main menu. This action enables the JAR file to display in the Class Browser.
WSDL URL	Note: Ensure that you have created the annotations for the Enterprise JavaBeans interface before generating the WSDL file, as described in Section 34.2.5, "How to Use Web Service Annotations." Click the second icon to the right to generate a WSDL file that represents the Enterprise JavaBeans interface. If you created SDO objects through Oracle JDeveloper, as described in Section 34.2.1, "How to Create SDO Objects Using the SDO Compiler," ensure that you select the WSDL file that was automatically generated with this option.
Port Type	Select the port type.
Callback Port Type	Select the callback port type (for asynchronous services).

Click OK.

34.3.2 Invoking SOA Composite Applications from Enterprise JavaBeans Using SDO Parameters

You can invoke an Enterprise JavaBeans adapter service in SOA composite applications from Enterprise JavaBeans using SDO parameters.

34.3.2.1 How to Invoke SOA Composite Applications from Enterprise JavaBeans using SDO Parameters

To invoke SOA composite applications from Enterprise JavaBeans using SDO parameters:

Drag an EJB Adapter Service icon into the Exposed Services swimlane.

The Create EJB Service dialog appears, as shown in Figure 34-4.

Figure 34-4 Create EJB Service in Exposed Services Swimlane

Description of "Figure 34-4 Create EJB Service in Exposed Services Swimlane"

Enter the details shown in Table 34-3:

Table 34-3 Create EJB Service in Exposed Services Swimlane

Field	Value
Name	Accept the default value or enter a different name.
Type	Displays Service if you dragged this icon into the Exposed Services swimlane.
Service ID	Accept the default value or enter a different name. The service ID is used as a token to uniquely identify the composite service entry from the Enterprise JavaBeans application. If multiple versions of the same composite are deployed, only the default version is used when the invocation arrives. Different composites trying to use the same service ID receive an error during deployment.
Java Interface	Click the Browse icon to invoke the Class Browser dialog for selecting the fully qualified Java class name of the previously created Enterprise JavaBeans interface. This class must exist in the selected JAR file. If a JAR file is not specified, it is assumed that the class is in the /SCA-INF/classes subdirectory of the current project directory. If you have a new JAR file, you must add it to the project by selecting Project Properties > Libraries and Classpath > Add JAR/Directory from the Application main menu. This action enables the JAR file to display in the Class Browser.
WSDL URL	Note: Ensure that you have created the annotations for the Enterprise JavaBeans interface before generating the WSDL file, as described in Section 34.2.5, "How to Use Web Service Annotations." Click the second icon to the right to generate a WSDL file that represents the Enterprise JavaBeans interface. If you created SDO objects through Oracle JDeveloper, as described in Section 34.2.1, "How to Create SDO Objects Using the SDO Compiler," ensure that you select the WSDL file that was automatically generated with this option.
Port Type	Select the port type.
Callback Port Type	Select the callback port type (for asynchronous services).

Click OK.

34.4 Designing an Enterprise JavaBeans Client to Invoke Oracle SOA Suite

To invoke an SDO - Enterprise JavaBeans service from Enterprise JavaBeans, you must use the client library. Follow these guidelines to design an Enterprise JavaBeans client.

Look up the SOAServiceInvokerBean from the JNDI tree.
Get an instance of SOAServiceFactory and ask the factory to return a proxy for the Enterprise JavaBeans service interface.
You can include a client side Enterprise JavaBeans invocation library (fabric-ejbClient.jar or the fabric-runtime.jar file located in the Oracle JDeveloper home directory or Oracle WebLogic Server) in the Enterprise JavaBeans client application. For example, the fabric-runtime.jar file can be located in the JDev_Home\jdeveloper\soa\modules\oracle.soa.fabric_11.1.1 directory.

If the Enterprise JavaBeans application is running in a different JVM than Oracle SOA Suite, the Enterprise JavaBeans application must reference the ejbClient library.

Example 34-4 provides an example.

Example 34-4 Enterprise JavaBeans Client Code

Properties props = new Properties();
        props.put(Context.INITIAL_CONTEXT_FACTORY,
 "weblogic.jndi.WLInitialContextFactory");
        props.put(Context.PROVIDER_URL, "t3://" + HOSTNAME + ":" + PORT);
        InitialContext ctx = new InitialContext(props);
        SOAServiceInvokerBean invoker =
                (SOAServiceInvokerBean)
 ctx.lookup("SOAServiceInvokerBean#oracle.integration.platform.blocks.sdox.ejb.api.
SOAServiceInvokerBean");

        //--  Create a SOAServiceFactory instance
        SOAServiceFactory serviceFactory = SOAServiceFactory.newInstance(invoker);

        //--  Get a dynamice proxy that is essentially a remote reference
        HelloInterface ejbRemote =
 serviceFactory.createService("MyTestEJBService", HelloInterface.class);

        //--  Invoke methods
        Item item = (Item) DataFactory.INSTANCE.create(Item.class);
        item.setNumber(new BigInteger("32"));
        SayHello sayHello = (SayHello)
 DataFactory.INSTANCE.create(SayHello.class);
        sayHello.setItem(item);

        SayHelloResponse response = ejbRemote.sayHello(sayHello);
        Item reply = response.getResult();

34.5 Specifying Enterprise JavaBeans Roles

To specify role names required to invoke SOA composite applications from any Java EE application, you add the roles names in the Enterprise JavaBeans adapter service configuration. The Enterprise JavaBeans adapter service checks to see if the caller principal has the security role.

<service name="EJBService" ui:wsdlLocation="BPELEJBProcess.wsdl">
    <interface.wsdl
interface="http://xmlns.oracle.com/EJBApplication/EJBProject/BPELEJBProcess#wsdl.int
erface(BPELProcess1)"callbackInterface="http://xmlns.oracle.com/EJBApplication/
EJBProject/BPELEJBProcess#
wsdl.interface(BPELEJBProcessCallback)"/>
<property name="rolesAllowed">Superuser, Admin</property>
    <binding.ejb javaInterface="java.class.ejb.com" serviceId="EJBService"
                 jarLocation="soaejb.jar"/>
</service>

34.6 Configuring JNDI Access

This section describes two methods for configuring JNDI access.

34.6.1 How to Create a Foreign JNDI

Follow these guidelines to configure JNDI access.

You can configure a foreign JNDI provider to link a foreign JNDI tree to your local server instance and access the object as if it is local. See Oracle Fusion Middleware Programming JNDI for Oracle WebLogic Server.
You can also provide JNDI environment variables as the properties for the Enterprise JavaBeans adapter reference, as shown in Example 34-5. An Enterprise JavaBeans binding component enables you to create your own map or use the default EJBBC binding component map. Note that the map property is optional if you use EJBBC. For security reasons, the JNDI security credentials must be stored in a CSF store and be referenced as shown in Example 34-5.
Example 34-5 Environment Variables for Enterprise JavaBeans Adapter Reference
```
<property name=
"java.naming.factory.initial">weblogic.jndi.WLInitialContextFactory</property>
<property name="java.naming.provider.url">t3://host:7001</property>
<property name="oracle.jps.credstore.map">default</property>
<property name="oracle.jps.credstore.key">weblogic</property>
```

The security credential can also be stored in the credential store framework. For more information, see Oracle Fusion Middleware Security Guide.

34.6.2 How to Create a Custom CSF Map for JNDI Lookup

If you create your own credential store framework (CSF) map instead of using the default Enterprise JavaBeans BC CSF map, you must modify the Domain_Home/config/fmwconfig/system-jazn.data.xml file and add the following permission to the entry for the fabric-runtime.jar permission grant.

<class>oracle.security.jps.service.credstore.CredentialAccessPermission</class>
   <name>>context=SYSTEM,mapName=*,keyName=*</name> 
   <actions>*</actions> 
</permission>

You must then restart Oracle WebLogic Server.

For more information on CSF, see Oracle Fusion Middleware Security Guide.