Using the EJB Transport, AquaLogic Service Bus supports native RMI invocation of Stateless Session Beans deployed on WebLogic Server 8.1, 9.0, 9.1 or 9.2. It allows transactional and secure communications. The EJB transport can also be leveraged to expose an EJB as a Web service through AquaLogic Service Bus.
This section includes the following topics:
You can design business services in AquaLogic Service Bus to use the EJB transport. The EJB transport is fully integrated into the AquaLogic Service Bus configuration, management, monitoring, and test consoles. Business services built with the EJB transport can be used for Publish, Service Callout, and service invocations. You cannot create proxy services that use the EJB transport.
An EJB can be exposed as a Web service, without the need for tools or the modification of the legacy code on the application server that hosts the EJB.
The EJB transport provides the following capabilities:
Before you can configure a business service in AquaLogic Service Bus, you must register a JNDI provider resource and a client JAR resource. This section describes how to design and configure an EJB transport business service in AquaLogic Service Bus. It includes the following topics:
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 WebLogic 8.1 or 9.x domains. (For more information how to setup a JNDI tree, see Programming WebLogic JNDI in the BEA WebLogic Server documentation.)
Typically, the target EJB is not located in the same domain as AquaLogic 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, although it is optional in this case.
The JNDI provider has a high performance caching mechanism for remote connections and EJB stubs. The preferred communication protocol from AquaLogic Service Bus to a WebLogic Server domain is t3
or t3s
. If messages need to go through a fire wall, you can use HTTP tunneling. For more information about HTTP tunneling, see HTTP Tunneling and Encrypted Communication.
Notes: |
For information about registering and configuring a JNDI provider resource in AquaLogic Service Bus, see "Adding a JNDI Provider" in System Administration in Using the AquaLogic Service Bus Console.
A client JAR must be registered as a resource in AquaLogic Service Bus. It is therefore part of the AquaLogic Service Bus configuration and can be exported from and imported into a project.
An EJB client JAR file must contain the interfaces and classes needed by AquaLogic Service Bus to access an EJB. This includes the remote and home interfaces and any dependent types to which the client is exposed, such as method parameter types or application exceptions. If your business service requires converter classes, they also need to be included in the JAR file. For information about converter classes, see Converter Classes.
Consider the following guidelines when using EJB client JARs:
For information about registering and configuring a JAR resource in AquaLogic Service Bus, see "Adding a JAR" in JARs in Using the AquaLogic Service Bus Console.
If the EJB methods are protected, you can specify the credentials you want to use for the invocations. Those credentials are often different than the credentials used by the JNDI provider. For information about adding and using service accounts, see Service Accounts in Using the AquaLogic Service Bus Console.
If you do not know the JNDI name for an EJB, you can browse the EJB Server JNDI tree. For information about browsing the JNDI tree using the WebLogic Server Administration Console, see:
This section provides information about creating a business service that uses the EJB transport. It includes the following topics:
An EJB business service is a Transport Typed Service, meaning that the type of the transport is determined by the configuration of the service. The EJB transport is currently the only such transport type. You can add other transports by using the AquaLogic Service Bus Transport SDK.
An entry in the Description field is optional.
ejb:
provider
:
jndi_name
If the EJB is deployed locally, you need not provide a JNDI provider name. In this case, the URI format is:
ejb::
jndi_name
After completing the general configuration of the business service you specify EJB transport-specific information such as the Home and Remote interfaces. The EJB Transport Configuration page in the AquaLogic Service Bus Console is shown in the following figure.
To Configure the EJB Transport
If the EJB methods are protected and you defined a service account as described in Create a Service Account (Optional), click Browse to locate the appropriate Service Account.
For information about transaction processing with the EJB Transport, see Transaction Processing, Retries, and Errors Handling.
When you select a Client JAR, a list of its Home Interface is displayed on this page.
Notice that the Remote Interface is automatically deduced from the Home Interface and the configuration page is refreshed. The Remote Interface field is populated and other options are provided that allow you to control the interface of the service and the WSDL generated when you finish configuration of this business service.
An EJB business service is a Transport Typed Service, which means the type of the transport is determined by the configuration of the service.
The type of an EJB business service is equivalent to a SOAP XML service—in other words, you can use an EJB business service like any other SOAP XML business service. A WSDL is generated when you save the EJB Transport Configuration.
The WSDL is generated based on the interface of the EJB. The EJB transport configuration page provides configuration options for you to control the interface of the service and the WSDL that is generated. To do so, complete the configuration on the EJB Transport Configuration page as shown in the preceding figure:
sayHello
and sort
.The following figure shows an example of a custom methods configurations.
Note: | If the credentials or transaction settings are different between the methods for a given EJB, you can leverage the ability to customize the methods for a given business service, and create a business service per method. This gives you fine-grained control over transactions and credentials. |
An EJB business service can be used as a SOAP XML business service. You can publish to, route to, or callout to an EJB business service. If you need transaction support, set the QoS to Exactly-Once. See Transaction Processing, Retries, and Errors Handling.
You can also use the test console to validate your configuration and to help you to determine the shape of the XML request.
You can leverage the EJB transport to easily expose EJBs as Web Services.
Note: You cannot create a proxy service from an existing EJB business service—you must first get the WSDL generated from the EJB business service, and then create the proxy service based on that WSDL. To do so, complete the following steps:
The WSDL is contained in a JAR file. You can obtain the WSDL only if there is no pending session.
If the configuration of the business service changes, a new WSDL is generated. If that happens, you must get the new WSDL and re-register it as a WSDL resource.
You can now invoke the EJB as a Web Service with no need for purchasing an expensive Web Service toolkit or carrying out intrusive actions on the EJB server.
This section includes information about EJB transport that will help you understand how EJB business services behave at run time depending on how they are configured at design time. It includes the following topics:
The EJB transport can create, suspend, and propagate transactions. The transaction between AquaLogic Service Bus and the EJB server are XA transactions. If you use transactions with HTTP tunneling or have a dedicated communication channel and the EJBs are deployed on 8.1 servers, you must set the security interoperability mode for the transaction manager to performance
. For information about setting the security interoperability mode and other transaction configurations, see
Configuring Transactions in Programming WebLogic JTA.
To determine the behavior of the EJB business service, considerations include whether the proxy service pipeline has a transactional context, and what qualities of service (QoS) settings are specified in the pipeline when invoking the service:
For more information about QoS in AquaLogic Service Bus services, see Quality of Service.
Assuming that the EJB business service is configured for retries or failovers, the EJB transport distinguishes the following types of exceptions:
Retries and failover are based on the type of errors and also in the QoS:
See Transactions for other repercussions of QoS specifications for an EJB business service.
When throwing a checked exception, according to the EJB specifications, the ongoing transaction can be specified as rollback only.
If the ongoing transaction is set as rollback only by the EJB developer, the transaction is eventually rolled back by its creator (most likely the proxy service).
If the ongoing transaction is not set to rollback only, and a checked exception is raised, it is important to catch EJB checked exceptions in the pipeline with an error handler. If those exceptions are not caught, the pipeline errors are propagated back to the proxy service. The proxy service, in turn, is likely to rollback the ongoing transaction (depending of the transport implementation)—this may not be the intended result.
For example, assume you have an EJB with the following method:
public void withdrawFunds(float amount) throws RemoteException, InsufficientFundsException {...}
Also assume that when an InsufficientFundsException
exception is thrown, the EJB does not set the current transaction as rollback only. In most scenarios, it is wrong to allow the proxy service to roll back the transaction—you may need to configure an error handler in the pipeline to catch the error and avoid this scenario.
The EJB transport is responsible for the XMLJava conversion. The conversion is performed by the WebLogic Server JAX-RPC engine.
The EJB transport natively supports the following types:
For the full list of natively supported types, see Data Types and Data Binding in Programming Web Services for WebLogic Server.
An EJB method can use parameters/return types that are either not supported by the JAX-RPC engine (an error is reported at design time), or that do not map directly to XML (errors occur at run time). The most commonly used unsupported types are:
You can write a custom converter class than converts those types into types more suitable for XMLJava conversions. The EJB transport supports custom converter classes.
A Converter class is a Java class that implements and conforms to the contract defined by the com.bea.wli.sb.transports.ejb.ITypeConverter
Java interface of the AquaLogic Service Bus public API. For information about the ITypeConverter
Java interface and other AquaLogic Service Bus APIs, see the
AquaLogic Service Bus Javadoc.
To use a converter class for an EJB business service, you must:
The information in this section is provided to help you troubleshoot problems when designing or running an EJB business service.
The EJB transport uses the same logger as other AquaLogic Service Bus transports. To enable the debug mode, before starting the server, edit the wlidebug.xml
file in the domain directory and set the category wli-sb-transports-debug to true
. For more information about the wlidebug.xml
file and the debug flags, see Debugging AquaLogic Service Bus.
During design time, the EJB transport generates files in the subfolder alsbejbtransport and subfolders prefixed with appcgen_ in the temp
directory. It is safe to delete those folders and files, and sometimes may be useful to check them to determine what went wrong during activation.
When an EJB business service is created an application is deployed on the AquaLogic Server. You can use the WebLogic Server Administration Console to monitor and tune this application. The name of EJB business service applications is prepended with ALSB EJB
, which is followed by the WSDL type and an auto generated suffix.
The following items may help in the event that you need to troubleshoot a problem with an EJB business service:
The system cannot find the path specified):Probably the string length of the path of the file being extracted was too long
You can try to reduce the path length by creating a shorter path to the AquaLogic Service Bus domain, or you can use the following option to override the WebLogic Server temp
directory when starting the server:
-Dweblogic.j2ee.application.tmpDir=$desired_short_dir
t3-server-abbrev-table-size
element to 255
in the config.xml
file in the AquaLogic Service Bus domain, as shown in the following code snippet: <server>
<name>AdminServer</name>
<ssl>
<name>AdminServer</name>
<enabled>true</enabled>
</ssl>
<t3-server-abbrev-table-size>255</t3-server-abbrev-table-size>
<listen-address></listen-address>
</server>