Using the JEJB Transport

30.1 Introduction to the JEJB Transport

The JEJB transport lets you pass Plain Old Java Objects (POJOs) through Service Bus.

For example, you can use an EJB to invoke a remote EJB operation or a non-EJB service, or you can invoke an EJB operation with a non-EJB request. Use case details are described in Use Cases.

To a J2EE client, a JEJB proxy service looks like a stateless session bean. A JEJB proxy service, on receiving the method arguments, passes their XML representation in the pipeline $body variable. POJO arguments are represented as the XML fragment, which contains the location of the actual POJO stored in the object repository within the pipeline. XML arguments can either be passed by value or by reference (referencing the actual object stored in the object repository). Primitive types are always passed by value.

For more information on POJOs in pipelines, see Java Content in the Body Variable and Using Java Callouts and POJOs..

The JEJB transport is always synchronous, so the messaging pattern is always request-response. For deployment, Service Bus automatically packages JEJB proxy services as enterprise archives (EARs).

30.1.1 Differences Between the JEJB Transport and the EJB Transport

The EJB transport, available only for business services, invokes remote EJBs through the Java Web Services (JWS) framework. The JEJB transport, which lets you invoke remote EJBs and external services with POJOs, passes POJOs directly through Service Bus to the target EJB methods using an RMI serialization/deserialization cycle. The EJB transport provides a "Support Transaction" flag, but all proxy services provide transactional support, making the transaction option unnecessary for JEJB business services.

30.1.2 JEJB Transport WSDL Generation

For proxy and business services, the JEJB transport generates a Document-style WSDL file with Literal encoding that is used solely for describing the message passed to the pipeline. The WSDL format lets you leverage Service Bus WSDL features such as per-operation monitoring. The message structure defined in the WSDL file may differ from the actual pipeline message at runtime if you inline your POJO arguments in the message using the Pass XMLBeans by value option, described in Table 30-1.

Following is the behavior of the pipeline message format for XMLBeans parameter types:

Proxy Services

Request Parameters: Request parameters in the pipeline message refer to an inline XML object if Pass XMLBeans by value is true; otherwise the reference is to java-content ref.
Response Parameter: The response may refer to an inline XML object or the java-content ref, as the response may come in either form from the business service.

Business Services

Response Parameter: Return parameters in the pipeline message refer to an inline XML object if Pass XMLBeans by value is true; otherwise the reference is to java-content ref.
Request Parameters: Request method parameters in the pipeline message may refer to an inline XML object or the java-content ref, as the request may come in either form from the proxy service.

30.1.3 JEJB Transport Error Handling

This section describes how the JEJB transport handles errors.

30.1.3.1 Exception Propagation in the Response

The JEJB transport stores request exceptions in the object repository and propagates them to the JEJB proxy service through the $fault variable. The $fault variable would contain the location of the exception instance within the <java-exception> <java-content ref="jcid"/> </java-exception> element, where jcid is the reference to the exception instance stored in the object repository.

To propagate the user exception to the client, the JEJB proxy service expects the response in one of the following formats. In all cases, jcid is a reference to the error in the object repository.

env:Envelope/env:Fault/detail/mc:java-exception

<detail>
    <mc:java-exception>
        <mc:java-content ref="jcid"/>
    </mc:java-exception>
    ...
</detail>

env:Envelope/env:Fault/detail/mc:fault/mc:java-exception

<detail>
    <mc:fault xmlns:mc="http://www.bea.com/wli/sb/context">
        <mc:java-exception>
            <mc:java-content ref="jcid"/>
        </mc:java-exception>
        ...
    </mc:fault>
</detail>

env:Envelope/ env:Fault/detail/mc:fault/mc:details/con1:ReceivedFaultDetail/con1:detail/mc:java-exception

<con:details>
    <con1:ReceivedFaultDetail   
          xmlns:con1="http://www.bea.com/wli/sb/stages/transform/config">
        <con1:faultcode>soapenv:Server</con1:faultcode>
        <con1:faultstring>checkExceptionConversion</con1:faultstring>
        <con1:detail>
            <mc:java-exception>
                <mc:java-content ref="jcid"/>
            </mc:java-exception>
        </con1:detail>
    </con1:ReceivedFaultDetail>
</con:details>

If you want to raise your own exceptions to return to the caller, raise them in a Java Callout in the pipeline.

If you configure a Java Callout or Service Callout in an error handler for "Reply with Failure," format the $body so that it conforms to one of the previously described fault structures.

30.1.3.2 Application and Connection Errors

This section describes the conditions under which the JEJB transport throws application and communication errors, which are subject to the retry configuration of a service.

30.1.3.2.1 Connection Errors

The JEJB transport throws connection errors in the following situations:

NamingExceptions looking up the EJBs raised during the remote call.
A runtime or remote exception is thrown, but the ongoing transaction has not been set as rollback-only, signifying that the error occurred before the invocation of the EJB container.

30.1.3.2.1.1 Application Errors

The JEJB transport throws application errors in the following situations:

A runtime or remote exception is thrown and the ongoing transaction has been set as rollback-only (likely by the EJB container), signifying the EJB container has been reached and a fatal error either occurred within the container or within the EJB itself.
Business exceptions defined in the EJB business interface.
An exception caused by a faulty encoding of the parameters in XML.

30.2 Prerequisites for Creating JEJB Services

This section provides information you need to know before you create JEJB proxy and business services.

30.2.1 Creating and Packaging Your Client EJB JAR File

When you use JEJB services, you need to create and package POJOs to represent EJB invocations and operations for the JEJB proxy and business services. Use the following guidelines.

Define an interface of type java.io.Serializable and include any necessary helper classes, such as business exceptions. The interface does not need to extend any class as long as the interface is valid for one of the RMI protocols described in JEJB Transport Endpoint URI, or is valid for JMS messages if you are using JMS to invoke EJBs.

Though not required, you can make the interface a remote interface as defined by the EJB 2.1 specification or annotate methods with the javax.ejb.Remote annotation to designate it as an EJB 3.0 business interface. For a simple POJO interface (no EJB remote interface) or an interface annotated with javax.ejb.Remote, the JEJB transport provider generates the 3.0 EJB interface out of the JEJB proxy service. For a remote interface, the JEJB transport provider generates the 2.1 EJB interface out of the JEJB proxy service.
The objects received as arguments must be passable to any required classes in a Java Callout archive resource.
An array of any type is considered a POJO.
To avoid unnecessary serialization/deserialization cycles, do not duplicate the JAR files uploaded as Service Bus archive resources to support Java callouts. Package all archive resource classes in a single JAR file so multiple Java callouts do not serialize/deserialize the objects.
Package your interface and dependent classes in a single client JAR file and import it into Service Bus. While this is the client JAR file you will select when configuring a service, it is not technically a fully expanded EJB client JAR file because it contains no stubs. The actual bean (hence WebLogic Server stub generation) does not exist until a JEJB proxy service is created and activated.

30.2.2 Registering a JNDI Provider Resource (Business Services)

A JNDI provider resource allows you to specify the communication protocols and security credentials used to retrieve EJB stubs bound in the JNDI tree of remote Oracle WebLogic Server domains. Typically, the target EJB is not located in the same domain as Service Bus. In this case, you must register a JNDI provider resource. When the EJB is located in the same domain, you can define a provider to specify credentials and take advantage of stubs caching, though doing so is optional.

The JNDI provider has a high performance caching mechanism for remote connections and EJB stubs. The preferred communication protocol from Service Bus to an Oracle WebLogic Server domain is t3 or t3s. If messages need to go through a firewall, you can use HTTP tunneling.

Note:

Although it is possible to use a WebLogic Server Foreign JNDI provider, Oracle recommends that you do not.

The transport does not support two-way SSL or client certificate to look-up the JNDI tree or access a method on an EJB.

For information about registering and configuring a JNDI provider resource in Service Bus, see Working with JNDI Provider Resources.

30.3 Use Cases

These are the supported use cases for using the JEJB transport in proxy and business services.

Each use case provides implementation guidelines for you to use in conjunction with the general service configuration, as described in JEJB Transport Configuration Reference.

30.3.1 EJB Invoking an External Service

You can invoke an external service with an EJB through Service Bus, as illustrated by Figure 30-1.

Figure 30-1 An EJB Invoking an External Service

Description of "Figure 30-1 An EJB Invoking an External Service"

In Figure 30-1, the JEJB proxy service serves as a stateless session bean to the EJB client interface. The JEJB transport provider for the proxy service generates a stateless session EJB from the remote/business interface in the client JAR and the pipeline, then deploys it as an EAR at the JNDI address specified in the endpoint URI.

Note:

Be sure to install policies that protect the JNDI entries from being modified.

The EJB makes a call to a remote interface provided by the proxy service EJB client JAR, passing transaction and security details to the proxy service as well.

The EJB client interface is a POJO with method arguments that the JEJB transport provider represents as a WSDL file and passes into the proxy service $body variable as XML. You can introspect the $body content to transform the message into the required format to pass to the business service and invoke the external service. The actual POJO is stored in the object repository, and the XML in the $body references it with a <java-content ref=""> element.

In the response, provide a Java callout that converts the response to an EJB return format that is passed to the calling EJB method. View the proxy service's generated WSDL file to see the expected message format.

Note:

In the proxy service pipeline, you can pass POJO arguments to Java callouts to a business service or to another proxy service using, for example, a service callout or a publish action.

30.3.2 Non-EJB Client Invoking an EJB

You can invoke an EJB with a non-EJB client through Service Bus, as illustrated in Figure 30-2.

Figure 30-2 A Non-EJB Client Invoking an EJB

Description of "Figure 30-2 A Non-EJB Client Invoking an EJB"

In Figure 30-2, a non-EJB client makes a call to a proxy service configured with a transport that matches the request; for example, a JMS proxy service making an invocation with a JMS topic or queue.

You configure a Java callout in the request, which converts the request into an XML representation of an EJB call in the $body variable. Put operations in the $operation variable. View the business service's generated WSDL file to see the expected message format. The JEJB business service uses its generated WSDL file to map the incoming message to the EJB remote interface and invoke the remote EJB method directly.

30.3.3 EJB Invoking EJB

You can invoke an EJB with an EJB through Service Bus, as illustrated in Figure 30-3.

Figure 30-3 An EJB Invoking an EJB

Description of "Figure 30-3 An EJB Invoking an EJB"

In Figure 30-3, the EJB call is passed through the proxy and business services to invoke another EJB method. Rather than making a direct RMI call outside of Service Bus, this architecture lets you leverage Service Bus features such as message routing, UDDI integration, alerts, monitoring, reporting, and result caching.

The JEJB transport provider for the proxy service generates a stateless session EJB from the remote/business interface in the client JAR file and the pipeline, and then deploys it as an EAR file at the JNDI address specified in the endpoint URI.

At runtime the JEJB proxy service receives a POJO as method argument, stores it in the object repository, and generates an XML representation of the POJO in the proxy service $body variable according to the generated proxy service WSDL file. The proxy service passes the message to the business service, and the business service uses its generated WSDL file to map the message to the remote interface and invoke the remote method directly.

30.4 UDDI Integration

You can publish and import JEJB proxy service properties to and from UDDI registries.

30.4.1 UDDI Publish

JEJB proxy services publish the following properties to a UDDI registry:

URI
EJB Spec Version
Client JAR
Home Interface (for EJB 2.1 only)
Remote Interface (the Business Interface for EJB 3.0)
Method names. The following are not included: operation aliases, parameters, and return details. Method names are passed in one property with all the method signatures appended. Method signatures are separated by the pound (#) character.

30.4.2 UDDI Import

This section describes how the JEJB transport handles service import from a UDDI registry.

URI: The JEJB transport provider attempts to match the host and port information from the URI property in the UDDI registry with a JNDI provider resource registered on the server.

If the transport provider cannot find a JNDI provider, the import fails. However, if no JNDI provider is found but the host and port match the localhost IP and listen port, the resulting business service will be local (no JNDI provider).
Client JAR: The transport provider downloads the client JAR files and, if the manifest classpath exists in the JAR files, creates the corresponding JAR resources in the matching directory structure. The first URI in the list is the root client JAR file. If no manifest classpath exists in the JAR files, you must manually add the resource JAR files as dependencies to the root JAR file. If a resource in the imported client JAR file has the same name as another resource in the domain, the imported resource overwrites the existing resource.

Make sure that the client JAR file you are importing does not already exist in your domain.
Method Names: Methods included in the corresponding property are automatically selected in the endpoint configuration. All the other methods are marked as excluded.

30.5 JEJB Transport Configuration Reference

This section provides information about endpoint URI formats, environment values, and configuring the JEJB transport in proxy and business services.

30.5.1 JEJB Transport Endpoint URI

The format for the endpoint URIs depend on whether you are configuring a proxy service or a business service.

Note:

JEJB services do not support co-located calls.

30.5.1.1 Proxy Service JEJB Endpoint URI

The URI configured for a JEJB proxy service becomes the global JNDI name for locating the stateless session bean generated by the JEJB transport from the remote/business interface in the client JAR. The URL format is ejb_jndi_name.

Note:

For EJB 3.0, ejb_jndi_name is the mappedName attribute of the @javax.ejb.Stateless annotation in the generated bean. The lookup JNDI name for the generated EJB service is suffixed with #interface_class, which is the fully qualified name of the business interface.

You can access the JEJB proxy service as:

EJB 2.1: protocol://host:port/ejb_jndi_name
EJB 3.0: protocol://host:port/ejb_jndi_name#interface_class

The protocol can be one of the following RMI protocols:

iiop/iiops: For generic, server-agnostic use.
t3/t3s: For use with Oracle WebLogic Server.
http/https: For tunneling and use with Oracle WebLogic Server.

For example:

EJB 2.1: t3://localhost:7001/osb.jejb.myJejbProxy
EJB 3.0: t3://localhost:7001/osb.jejb.myJejbProxy#com.example.MyEjb3

30.5.1.2 Business Service JEJB Endpoint URI

Use the following endpoint URI format for a JEJB business service:

jejb:jndi_provider_name:ejb_jndi_name

The jndi_provider_name is the remote JNDI context, and the ejb_jndi_name is the remote EJB's JNDI name.

For example:

EJB 2.1: jejb:myProvider:osb.jejb.myJejbBiz21
EJB 3.0: jejb:myProvider:myBiz31#osb.jejb.myJejbBiz

where #osb.jejb.myJejbBiz is the fully qualified business interface.

If your EJBs are running on IBM WebSphere, ejb_jndi_name must be in the on of following formats:

cell/nodes/node_name/servers/server_name/ejb_jndi_name

or
cell/clusters/cluster_name/ejb_jndi_name

For more information, refer to the IBM WebSphere documentation.

30.5.2 Configuring Proxy Services to Use the JEJB Transport

The following table describes the properties you use to configure a JEJB transport for a proxy service. For instructions on creating a proxy service, see Creating and Configuring Proxy Services.

Table 30-1 JEJB Transport Properties for Proxy Services

Property	Description
Dispatch Policy	Select the instance of WebLogic Server Work Manager that you want to use for the dispatch policy for this endpoint. The default Work Manager is used if no other Work Manager exists. For information about Work Managers, see: Using Work Managers with Service Bus "Using Work Managers to Optimize Scheduled Work" in Administering Server Environments for Oracle WebLogic Server
EJB Spec Version	Select the EJB version of the remote EJB interface.
Pass XMLBeans by value	Select this option if you want the transport to generate an "inlined" XML representation of POJO arguments (an XMLObject) whose parameters you can access and manipulate with XQuery expressions. Note: Type information is not available inline for XMLObjects passed by value. If you use this option, you cannot pass the typed XMLObject as the argument in a Java Callout in a proxy service pipeline. Do not select this option if you want to pass the POJO by reference, which also results in better performance. For more information, see JEJB Transport WSDL Generation.
Transaction Attribute	Select one of the following options for handling transactions: Supports: The transport accepts an incoming transaction. Quality of service is exactly-once if the operation is invoked in a transaction and best-effort if the operation is invoked outside of a transaction. Required: The transport accepts an incoming transaction. If no ongoing transaction exists, the transport starts one. Quality of service is exactly-once. RequiresNew: The transport always starts a new transaction, suspending an ongoing transaction. Quality of service is exactly-once. Mandatory: The transport invokes the method in the existing transaction. Quality of service is exactly-once. NotSupported: The transport suspends an existing transaction and resumes it on invocation. Quality of service is best-effort. Never: The transport does not invoke the method in a transaction. Quality of service is best-effort.
Remote Client Timeout	Specify the length of time in seconds that a remote RMI client will wait before timing out.
Client JAR	Click Browse and select an EJB client JAR resource from the list displayed. The client JAR contains the remote or business interface for the remote EJB. The client JAR is registered as a generic archive resource.
Home Interface	For EJB 2.1 only, select the required EJBHome interface from the options populated by the client JAR.
Remote Interface	For EJB 2.1 only, this field is automatically populated based on the configuration of the home interface.
Business Interface	For EJB 3.0 only, select the business interface from the client JAR file that you want to invoke.
Target Namespace	The target namespace of the generated WSDL file. This field is automatically populated by information picked up from the JAR.
Methods	Select the required methods from the list of available methods. The available methods depend on the JAR file being used. By default, all methods are selected. Expand a method to edit the default parameter values. You can change the default operation name for a given method. By default, the operation name is the method name. If an EJB contains methods with same name (overloaded), you must change the operation names so that they are unique. WSDL files require unique operation names.

30.5.3 Configuring Business Services

The following table describes the properties you use to configure a JEJB transport for a business service. For more information, see Creating and Configuring Business Services.

Table 30-2 JEJB Transport Configuration for Business Services

Option	Description
Dispatch Policy	Select the instance of WebLogic Server Work Manager that you want to use for the dispatch policy for this endpoint. The default Work Manager is used if no other Work Manager exists. For information about Work Managers, see: Using Work Managers with Service Bus "Using Work Managers to Optimize Scheduled Work" in Administering Server Environments for Oracle WebLogic Server
EJB Spec Version	Select the EJB version of the remote EJB interface.
Pass XMLBeans by value	Select this option if you want the transport to generate an "inlined" XML representation of POJO arguments (an XMLObject) whose parameters you can access and manipulate with XQuery expressions. Note: Type information is not available inline for XMLObjects passed by value. If you use this option, you cannot pass the typed XMLObject as the argument in a Java Callout in a proxy service pipeline. Do not select this option if you want to pass the POJO by reference, which also results in better performance. Do not select this option if you want to pass the POJO by reference, which also results in better performance. For more information, see JEJB Transport WSDL Generation.
Pass Caller's Subject	Select this option as an alternative to selecting a service account. When you select this option, Service Bus passes the authenticated subject from the proxy service when invoking the EJB.
Service Account	Enter a service account that will be used for authentication to access the service. If no service account is specified, an anonymous subject is used. This field is required if you selected Basic authentication. For more information, see Working with Service Accounts.
Client JAR	Click Browse and select an EJB client JAR resource from the list displayed. The client JAR contains the remote or business interface for the remote EJB. The Client JAR is registered as a generic Archive Resource.
Home Interface	For EJB 2.1 only, select the required EJBHome interface from the options populated by the client JAR.
Remote Interface	For EJB 2.1 only, this field is automatically populated based on the configuration of the home interface.
Business Interface	For EJB 3.0 only, select the business interface from the client JAR file that you want to invoke.
Target Namespace	The target namespace of the generated WSDL file. This field is automatically populated by information picked up from the JAR.
Methods	Select the required methods from the list of available methods. The available methods depend on the JAR file being used. By default, all methods are selected. Expand a method to edit the default parameter values. You can change the default operation name for a given method. By default, the operation name is the method name. If an EJB contains methods with same name (overloaded), you must change the operation names so that they are unique. WSDL files require unique operation names.

30.5.4 JEJB Transport Environment Values

The JEJB transport stores the following environment values for JEJB services:

Service URI
Work Manager
UDDI Auto Publish (Proxy Services)
Service Account (Business Services)

These values correspond to transport properties in business and proxy services. For more information, see JEJB Transport Configuration Reference.