29 JEJB Transport

This chapter provides an overview of the JEJB transport and describes how to use and configure it in your services.

This chapter includes the following sections:

Section 29.1, "About the JEJB Transport"
Section 29.2, "Creating and Configuring JEJB Services"
Section 29.3, "Use Cases"
Section 29.4, "Transport Configuration Reference"
Section 29.5, "Testing JEJB Services"
Section 29.6, "UDDI Integration"

29.1 About the JEJB Transport

The JEJB transport lets you pass Plain Old Java Objects (POJOs) through Oracle 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 Section 29.3, "Use Cases."

To a J2EE client, a JEJB proxy service pipeline 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. This XML fragment 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 detailed information on POJOs in message flows, see "Java Content in the body Variable" and "Extensibility Using Java Callouts and POJOs" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

The JEJB transport is always synchronous, so the pattern is always request-response.

For deployment, Oracle Service Bus automatically packages JEJB proxy services as enterprise archives (EARs).

29.1.1 Difference 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 Oracle Service Bus to the target EJB methods using an RMI serialization/deserialization cycle.

The EJB transport provides a "Support Transaction" flag, but all Oracle Service Bus proxy services provide transactional support, making the transaction option unnecessary for JEJB business services.

29.1.2 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)

29.1.3 WSDL Generation

For proxy and business services, the JEJB transport generates a Document-style WSDL with Literal encoding that is used solely for describing the message passed to the pipeline. The WSDL format lets you leverage Oracle Service Bus WSDL features such as per-operation monitoring.

The message structure defined in the WSDL 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 29-1.

Following is the behavior of the pipeline message format for XMLBeans type of parameters:

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.

29.1.4 Error Handling

This section describes how the JEJB transport handles errors.

29.1.4.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. $fault 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 would expect the response in one of these formats:

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

Format, where jcid is a reference to the error in the object repository:

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

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

Format, where jcid is a reference to the error in the object repository:

<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

Format, where jcid is a reference to the error in the object repository:

<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>

To raise your own exceptions to return to the caller, raise them in a Java Callout in the proxy service pipeline.

29.1.4.1.1 Java Callout and Service Callout Exceptions

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

29.1.4.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 on a service.

29.1.4.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.

29.1.4.2.2 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.

29.2 Creating and Configuring JEJB Services

This section provides instructions for creating and configuring JEJB proxy and business services.

29.2.1 Creating and Packaging Your Client EJB JAR

This section provides guidelines on creating and packaging POJOs to represent EJB invocations and operations for JEJB proxy and business services.

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 Section 29.4.1, "JEJB Endpoint URI," or is valid for JMS messages if you are using JMS to invoke EJBs.
Note:

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.
Avoid unnecessary serialization/deserialization cycles by not duplicating the JARs uploaded as Archive Resources to support Java Callouts. Package all archive resource classes in a single archive JAR so that multiple Java Callouts do not serialize/deserialize the objects.
Package your interface and dependent classes in a single "client" JAR and import it into Oracle Service Bus. While this is the client JAR you will select when configuring a service, it is not technically a fully expanded EJB client JAR, because it contains no stubs. The actual bean (hence Oracle WebLogic Server stub generation) does not exist until a JEJB proxy service is created and activated.

29.2.2 Register a JNDI Provider Resource (Business Services)

A JNDI Provider resource lets you specify the communication protocols and security credentials used to retrieve EJB stubs bound in the JNDI tree of remote Oracle WebLogic Server domains. (For more information on how to set up a JNDI tree, see Oracle Fusion Middleware Programming JNDI for Oracle WebLogic Server.)

Typically, the target EJB is not located in the same domain as Oracle 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 Oracle 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 an Oracle WebLogic Server Foreign JNDI Provider, Oracle recommends that you do not.

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

29.2.2.1 Adding a JNDI Provider

For information about registering and configuring a JNDI provider resource in Oracle Service Bus, see Section 4.8, "JNDI Providers.".

29.2.3 Configuring a JEJB Proxy or Business Service

This section describes the high-level steps for configuring a JEJB proxy or business service. The scenarios described in Section 29.3, "Use Cases" illustrate when you need to create JEJB proxy and business services. Each use case provides general implementation guidelines.

On the General page of the service, select the Transport Typed option.
On the Transport page:
1. Select the jejb protocol.
2. Enter the Endpoint URI information as described in Section 29.4.1, "JEJB Endpoint URI."
3. Set other global transport options as described in Section 4.3.6, "Proxy Service Transport Configuration Page" and Section 4.2.4, "Business Service Transport Configuration Page."
On the JEJB Transport page, configure the transport options for the service, described in Section 29.4.2, "JEJB Transport Configuration for Proxy Services" and Section 29.4.3, "JEJB Transport Configuration for Business Services."
Set the remaining service options as described in Section 4.3, "Proxy Service Configuration" and Section 4.2, "Business Service Configuration."
See your particular use case in Section 29.3, "Use Cases" for implementation guidelines.

29.3 Use Cases

Following 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 Section 29.2.3, "Configuring a JEJB Proxy or Business Service."

29.3.1 EJB Invokes an External Service

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

Figure 29-1 An EJB Invokes an External Service

Description of "Figure 29-1 An EJB Invokes an External Service"

In Figure 29-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.

Caution:

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 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 gets passed to the calling EJB method. View the proxy service's generated WSDL to see the expected message format. For information on viewing the generated WSDL, see "Viewing Resource Details" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

Note:

In the proxy service pipeline, you can pass POJO arguments to Java Callouts, to another proxy service using, for example, a Service Callout or a Publish action, or to a business service.

29.3.2 Non-EJB Client Invokes an EJB

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

Figure 29-2 A Non-EJB Client Invokes an EJB

Description of "Figure 29-2 A Non-EJB Client Invokes an EJB"

In Figure 29-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 to see the expected message format. For information on viewing the generated WSDL, see "Viewing Resource Details" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

The JEJB business service uses its generated WSDL to map the incoming message to the EJB remote interface and invoke the remote EJB method directly.

29.3.3 EJB Invokes EJB

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

Figure 29-3 An EJB Invokes an EJB

Description of "Figure 29-3 An EJB Invokes an EJB"

In Figure 29-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 Oracle Service Bus, this architecture lets you leverage Oracle 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 and the pipeline, and then deploys it as an EAR 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. The proxy service passes the message to the business service, and the business service uses its generated WSDL to map the message to the remote interface and invoke the remote method directly.

To keep your pipeline logic independent of the JEJB transport, you can route messages from the JEJB proxy service to a local proxy service. The local proxy service can then perform the pipeline logic before forwarding the messages to the JEJB business service. If you use this pattern, make sure the local proxy is of type WSDL (with support for the business service operations) so that it has access to the Java objects.

29.4 Transport Configuration Reference

This section provides details on constructing endpoint URIs and configuring the JEJB transport in proxy and business services.

29.4.1 JEJB Endpoint URI

Following are the endpoint URI formats for JEJB proxy and business services.

Note:

JEJB services do not support co-located calls.

29.4.1.1 Proxy Service JEJB Endpoint URI

The URL format is ejb_jndi_name. 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.

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

29.4.1.2 Business Service JEJB Endpoint URI

Following is the endpoint URI format for a JEJB business service:

jejb:jndi_provider_name:ejb_jndi_name

The jndi_provider_name is the remote JNDI context.

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.

Note:

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

cell/nodes/node_name/servers/server_name/ejb_jndi_name

cell/clusters/cluster_name/ejb_jndi_name

as described in the IBM WebSphere documentation at http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.nd.iseries.doc/info/iseriesnd/ae/rnam_example_prop3.html

29.4.2 JEJB Transport Configuration for Proxy Services

Use this page to configure transport settings for proxy services using the JEJB transport protocol.

Table 29-1 describes the transport-specific configuration options for business services that use the JEJB transport.

Table 29-1 JEJB Transport Configuration for Proxy Services

Option	Description
Dispatch Policy	Select the instance of Oracle 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 to Optimize Scheduled Work" in Oracle Fusion Middleware Configuring Server Environments for Oracle WebLogic Server "Using Work Managers with Oracle Service Bus" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus
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 Section 29.1.3, "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.
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	EJB 2.1 only – Select the required EJBHome interface from the options populated by the client JAR.
Remote Interface	EJB 2.1 only – This field is automatically populated based on the configuration of the Home Interface.
Business Interface	EJB 3.0 only – Select the business interface from the client JAR that you want to invoke.
Target Namespace	This field is populated by information picked up from the JAR.
Methods	Select the required methods. Click + to expand the method, which lets you 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. WSDLs require unique operation names.

29.4.3 JEJB Transport Configuration for Business Services

Use this page to configure transport settings for business services using the JEJB transport protocol.

Table 29-2 describes the transport-specific configuration options for business services that use the JEJB transport.

Table 29-2 JEJB Transport Configuration for Business Services

Option	Description
Dispatch Policy	Select the instance of Oracle 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 to Optimize Scheduled Work" in Oracle Fusion Middleware Configuring Server Environments for Oracle WebLogic Server "Using Work Managers with Oracle Service Bus" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus
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 Section 29.1.3, "WSDL Generation."
Pass Caller's Subject	As an alternative to selecting a Service Account, select this option to have Oracle Service Bus pass the authenticated subject from the proxy service when invoking the EJB.
Service Account	Click Browse and select a JNDI service account from the list displayed. If no service account is specified, an anonymous subject is used.For more information, see Section 4.19, "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 service. The Client JAR is registered as a generic Archive Resource.
Home Interface	EJB 2.1 only – Select the required EJBHome interface from the options populated by the JAR.
Remote Interface	EJB 2.1 only – This field is automatically populated based on the configuration of the Home Interface.
Business Interface	EJB 3.0 only – Select the business interface from the client JAR that you want to invoke.
Target Namespace	This field is populated by information picked up from the JAR.
Methods	Select the required methods. Click + to expand the method, which lets you 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. WSDLs require unique operation names.

29.5 Testing JEJB Services

In the Oracle Service Bus Test Console you can test JEJB services that pass POJOs by value ("Pass XMLBeans by value" option), but not by reference. The Test Console supports only primitive, String, and XML arguments. The transport passes supported POJO arguments and their values as XML specifying the invocation point (the EJB method).

29.6 UDDI Integration

This section describes the UDDI publish and import details for JEJB proxy services:

29.6.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 (Not included are operation aliases, parameters, or return details. Method names are passed in one property with all the method signatures appended. Method signatures are separated by the # character.

29.6.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: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 the no JNDI provider is found, but the host:port matches the localhost IP and listen port, the resulting business service will be local (no JNDI provider).
Client JAR – The transport provider downloads the client JARs and, if the manifest classpath exists in the JARs, creates the corresponding JAR resources in the matching directory structure. The first URI in the list is the root client JAR. If no manifest classpath exists in the JARs, you must manually add the resource JARs as dependencies to the root JAR. If a resource in the imported client JAR has the same name as another resource in the domain, the imported resource overwrites the existing resource.

Make sure that the client JAR 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 (that is, they are not selected).