This chapter includes the following sections:
In Service Bus, you can use business services configured with the EJB transport for publish, service callout, and service invocations. You cannot create proxy services that use the EJB transport.
The EJB transport provides the following capabilities:
Transactional Integrity: EJB business services can be called in the context of a global transaction. The EJB transport can also suspend or start a global transaction before invoking an EJB.
Security Propagation: The security context established from a Service Bus client is propagated to the other external system. For example, an incoming SOAP over HTTP request to Service Bus that requires authentication is authenticated by Service Bus and the authenticated subject can then be propagated to the EJB server. For more information on security propagation, see Important Information Regarding Cross-Domain Security Support in Administering Security for Oracle WebLogic Server.
HTTP Tunneling and Encrypted Communication: You can access EJBs that are behind a firewall with HTTP tunneling. For additional security, use SSL to encrypt all of the communications with the EJB Server.
JNDI Provider: EJB transport leverages the JNDI provider (a Service Bus resource). The JNDI provider defines communication protocols and security credentials for accessing remote servers. A JNDI provider can be reused by multiple EJB business services. This provides a centralized way for administrators to manage remote EJB server configurations.
For information about JNDI provider resources, see Working with JNDI Provider Resources.
High Performance Caching: The EJB transport is built on high performance cache. This allows the reuse of established connections and minimizes EJB stubs lookups.
Failover and Load Balancing: The EJB transport can take advantage of scenarios in which the same EJB is deployed in multiple domains or on a cluster for load balancing or failover or both.
Advanced XML to Java Binding Capabilities: The EJB transport leverages the Oracle WebLogic Server JAX-WS stack to perform Java to XML bindings. The JAX-WS stack is a high performance engine that supports advanced Java objects such as XML Beans. If the Java type is not recognized by the stack, an extension mechanism is provided to facilitate support of these Java types. For information about this extension mechanism (using the converter classes), see Supported Types and Converter Classes.
Intelligent Retries: The EJB transport makes retry decisions based on the nature of the failure that can occur during the invocation of an EJB.
Before you can configure a business service to use the EJB transport, you must create a JNDI provider resource and a client JAR resource. This section outlines the steps required to design and configure an EJB transport business service in Service Bus.
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, 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 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 certificate to look-up 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.
In order to be used by Service Bus services, a client JAR file must be registered as a resource in Service Bus. It becomes a part of the 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 Service Bus to access an EJB. This includes the remote and home interfaces (EJB 2.1) or business interfaces (EJB 3.0) and any dependent types to which the client is exposed, such as method parameter types or application exceptions.
Beginning in Service Bus 12.2.1, the EJB transport uses the JAX-WS stack. The JAX-WS stack supports mapping Java classes to XML and back for most Java types. The converter classes may not be required for most cases. The converter classes supported in this release are mostly to ensure backward compatibility with business services created for previous versions of Service Bus.
If your business service requires converter classes, you can register a JAR file containing the converter classes as a Service Bus resource and subsequently use these classes to help map parameter and return value types to Java classes that can be mapped to XML. Alternatively, you can package these converter classes in the EJB client JAR. For information about converter classes, see Custom Converter Classes.
Consider the following guidelines when using EJB client JARs:
Adding home and remote interfaces in the system classpath is bad practice and is not supported by Service Bus.
Oracle recommends that you keep the client JAR file size small, include a single home interface per JAR file, and not register the entire ejb-jar file.
Service Bus supports client-jar files compiled with JDK 1.4 or later.
In order to use complex type inheritance by extension in your Service Bus EJB implementation, you need to create and use converter classes, as described in Supported Types and Converter Classes. For information about registering and configuring a client or converter JAR resource in Service Bus, see Working with JAR Files.
If the EJB methods are protected, you can specify the credentials you want to use for the invocations using a service account. Those credentials are often different than the credentials used by the JNDI provider. For information about adding and using service accounts, see Working with Service Accounts.
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 Oracle WebLogic Server Administration Console, see View objects in the JNDI tree in the Oracle WebLogic Server Administration Console Online Help.
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 quality of service to Exactly-Once. For more information, see Advanced EJB Transport Topics.
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.
You cannot create a proxy service from an existing EJB business service. You must first get the WSDL file generated from the EJB business service, and then create the proxy service based on that WSDL file. To do so, complete the following steps.
This section includes information about the EJB transport that will help you understand how EJB business services behave at runtime depending on the design time configuration.
The EJB transport can create, suspend, and propagate transactions. The transactions between Service Bus and the EJB server are XA transactions. If you use transactions with HTTP tunneling or have a dedicated communication channel, 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 Developing JTA Applications for Oracle WebLogic Server.
For the deployment descriptors to be set appropriately for XA-capable resources, you must set the XA attribute on the referenced connection factory before creating a proxy service.
To determine the behavior of the EJB business service, considerations include whether the pipeline has a transactional context, and what quality of service (QoS) settings are specified in the pipeline when invoking the service:
QoS Best-Effort: If Best-Effort QoS is specified in the pipeline, no transaction is propagated to the EJB, and any ongoing transaction is suspended before invocation and resumed after invocation.
QoS Exactly-Once: If Exactly-Once QoS is specified in the pipeline and the EJB does not support transactions (that is, the Supports Transaction option on the EJB transport configuration page is not checked), no transaction is propagated to the EJB. As in the case of Best-Effort, any ongoing transaction is suspended before invocation and resumed afterwards.
If the EJB supports transactions (that is, the Supports Transaction option on the EJB transport configuration page is checked), the EJB is invoked in the context of a transaction, and any ongoing transaction is propagated to the EJB. If no transaction is present, a transaction is created before invocation and committed afterwards.
For more information about QoS in Service Bus services, see Quality of Service.
Assuming that an EJB business service is configured for retries or failovers, the EJB transport distinguishes the following types of exceptions:
Runtime exceptions or remote exceptions: These are typically unexpected fatal errors or communication exceptions.
Exception raised by the JAX-WS engine: These are exceptions that occur during the XML to Java conversion.
EJB checked exceptions: These are exceptions declared in the EJB method signature specific to the EJB implementation. They are also called business exceptions.
Retries and failover are based on the type of errors and also in the QoS, as described below.
QoS Best-Effort
If a runtime or remote exception is thrown, the EJB transport attempts retries or failovers.
If an exception occurs in the JAX-WS engine, an error is raised to the pipeline and no retries or failover attempts are made.
If an EJB checked exception is thrown, an error is raised to the pipeline and no retries or failover attempts are made.
QoS Exactly-Once
If a runtime or remote exception is thrown and the ongoing transaction has been set as rollback only (likely by the EJB container), the EJB container has been reached and a fatal error occurred either within the EJB container or the EJB. In this case, no retries or failover attempts are made and an error is raised to the pipeline.
If a runtime or remote exception is thrown but the ongoing transaction has not been set as rollback only, an error occurred before the invocation of the EJB container and the EJB transport will attempt retries or failovers. Note that in this case, the EJB transport still respects the exactly-once semantic.
If an exception occurs in the JAX-WS engine, the EJB transport sets the ongoing transaction to rollback only and an error is raised to the pipeline; no retries or failover attempts are made.
If an EJB Checked Exception is thrown, an error is raised to the pipeline and no retries or failover attempts are made.
See EJB Transport 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 conversion between XML and Java. The conversion is performed by the Oracle WebLogic Server JAX-WS engine. The EJB transport natively supports the following types:
Primitive types
XmlObject (Apache version only)
Schema generated XMLBeans (Apache version only, XMLBeans extending from org.apache.xmlbeans.XmlObject)
JavaBean classes
For the full list of natively supported types, see "Using JAXB Data Binding" in Developing JAX-WS Web Services for Oracle WebLogic Server.
An EJB method can use parameters and return types that are either not supported by the JAX-WS engine (an error is reported at design time) or that do not map directly to XML (errors occur at runtime). The most commonly used unsupported types include the following:
"Object", "Object[]"
Java Collections, as they are not strongly typed (for example, List or Set)
Java classes that do not follow the JavaBean pattern (for example, Map)
You can write a custom converter class that converts those types into types more suitable for conversion between XML and Java.
The EJB transport supports session beans with input argument or return type of XMLBean type (org.apache.xmlbeans.*).
Beginning 12.2.1, the EJB transport uses the JAX-WS stack, which uses JAXB as the default binding mechanism. JAXB does not understand XMLBean types. The EJB transport relies on a plugin module in order to support XMLBean types.
The following are limitations of the XMLBean plugin:
XMLBeans extending from org.apache.xmlbeans.XmlObject are supported using the plugin module.
XMLBean objects extending from com.bea.xml.* are not supported.
Using XMLBeans along with user-defined Java objects is not supported. If an EJB contains both Java objects and Xmlbeans as inputs arguments or return types, the EJB transport returns a runtime error.
JAX-WS mandates that user defined java objects used as input argument or method return type in EJB methods should have default constructor, which is a constructor that takes no parameters.
This means the user-defined Java types that worked in previous versions of Service Bus (even if they did not have the default constructor) need to be modified to include the default constructor. See Programming the User-Defined Java Data Type for more information.
Service Bus generates an intermediate web service that precisely matches the EJB structure. Since not all EJBs and their data types can be mapped to web service data types, you can create a converter class to change the shape of the intermediate web service and enable the internal transformation of the SOAP data types into the required EJB types on the Service Bus side. 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 Service Bus public API.
The JAX-WS specification requires certain criteria of EJB parameters and return types for wrapping them into a web service layer, with specific requirements for data types. For more information, see "Programming the JWS File" in Developing JAX-WS Web Services for Oracle WebLogic Server. Converter classes let you customize the Service Bus EJB wrapper in a way that exposes data types over the web service layer, which can then be turned into the data types required by the EJB. The wrapper implementation is based on the provided EJB client classes, must match the EJB interface precisely, and is accessible through a web service layer (created using WebLogic Servers's JWS toolset).
Business exception classes thrown by an EJB method must comply with JAX-WS 2.2 Specification Section 3.7 to ensure proper mapping of the exception class details into the WSDL type definition for the fault element. All private, non-transient fields with corresponding getter methods in the exception class get mapped to the exception type definition in the WSDL file.
See Creating and Using a Custom Exception in Developing JAX-WS Web Services for Oracle WebLogic Server for additional information.
The information in this section is provided to help you troubleshoot problems when designing or running an EJB business service.
In addition, you can enable debugging, as described in Debugging Oracle Service Bus Applications .
In previous versions of Service Bus, the EJB transport used JAX-RPC as the underlying stack. As this version uses JAX-WS, you may encounter compatibility issues with WSDLs; JAX-RPC and JAX-WS are two different implementations and are not cross-compatible.
The WSDLs generated by JAX-RPC and JAX-WS differ while using arrays as method input/return type. JAX-RPC uses a wrapper to represent the array values, but JAX-WS does not.
The WSDLs generated by JAX-RPC and JAX-WS are as follows:
JAX-WS Generated WSDL
<xs:complexType name="ArrayOfJavaLangstring_literal">
<xs:sequence>
<xs:element maxOccurs="unbounded" minOccurs="0" name="JavaLangstring" nillable="true" type="xs:string"/>
</xs:sequence>
</xs:complexType>
<xs:element name="ArrayOfJavaLangstring_literal" type="open:ArrayOfJavaLangstring_literal" xmlns:open="http://www.openuri.org/"/>
<xs:element name="returnNames">
<xs:complexType>
<xs:sequence>
<xs:element name="arg0" type="open:ArrayOfJavaLangstring_literal" xmlns:open="http://www.openuri.org/"/>
</xs:sequence>
</xs:complexType>
</xs:element>JAX-WS Generated WSDL
<xsd:complexType name="returnNames">
<xsd:sequence>
<xsd:element form="qualified" maxOccurs="unbounded" name="arg0" nillable="true" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>The WebLogic Server implementation of JAX-RPC wraps the repeated element in a wrapper:
<foo>
<param1>
<JavaLangstring>arrayItemOfp1</JavaLangstring>
<JavaLangstring>arrayItemOfp1</JavaLangstring>
<JavaLangstring>arrayItemOfp1</JavaLangstring>
</param1>
</foo>
JAX-WS uses inline repeated elements for arrays:
<foo> <param1>arrayItemOfp1</param1> <param1>arrayItemOfp1</param1> <param1>arrayItemOfp1</param1> </foo>
A stateless session bean which has the business method String[] returnNames(String[] names) would expect the following request and response payloads with JAX-RPC (previous versions of Service Bus) and JAX-WS (Service Bus 12.2.1) generated WSDLs:
JAX-RPC Request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
</soap:Header>
<soapenv:Body>
<open:returnNames xmlns:open="http://www.openuri.org/">
<open:arg0>
<open:JavaLangstring>John</open:JavaLangstring>
<open:JavaLangstring>Eric</open:JavaLangstring>
<open:JavaLangstring>Mark</open:JavaLangstring>
</open:arg0>
</open:returnNames>
</soapenv:Body>
</soapenv:Envelope>JAX-RPC Response
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header/>
<env:Body>
<m:returnNamesResponse xmlns:m="http://www.openuri.org/">
<m:return>
<m:JavaLangstring>John</m:JavaLangstring>
<m:JavaLangstring>Eric</m:JavaLangstring>
<m:JavaLangstring>Mark</m:JavaLangstring>
</m:return>
</m:returnNamesResponse>
</env:Body>
</env:Envelope>JAX-WS Request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
</soap:Header>
<soapenv:Body>
<open:returnNames xmlns:open="http://www.openuri.org/">
<open:arg0>John</open:arg0>
<open:arg0>Eric</open:arg0>
<open:arg0>Mark</open:arg0>
</open:returnNames>
</soapenv:Body>
</soapenv:Envelope>JAX-WS Response
<S:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Header/>
<S:Body>
<ns0:returnNamesResponse xmlns:ns0="http://www.openuri.org/">
<ns0:return>John</ns0:return>
<ns0:return>Eric</ns0:return>
<ns0:return>Mark</ns0:return>
</ns0:returnNamesResponse>
</S:Body>
</S:Envelope>Due to the difference in generated WSDLs, any XPath functions applied on the request payload may result in different behavior. Modify your XPath functions to account for this difference.
During design time, the EJB transport generates files in a subfolder 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 and activated, an application is deployed on the Service Bus server. You can use the Oracle WebLogic Server Administration Console and Fusion Middleware Control to monitor and tune this application.
The following information may help in the event that you need to troubleshoot a problem with an EJB business service:
The following error when creating a business service is due to a Windows operating system limitation. Paths containing more than 255 characters are not supported.
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 Service Bus domain, or you can use the following option to override the Oracle WebLogic Server temp directory when starting the server:
-Dweblogic.j2ee.application.tmpDir=$desired_short_dir
If you get an XML marshalling error when invoking an EJB business service and you believe the request to be valid against the service WSDL document, you probably need to write a converter class. For information, see Custom Converter Classes.
If the EJB interfaces and stubs are changed on the remote server, the first time you try to invoke the new EJB, an error is thrown. Those changes on the remote server are not visible to Service Bus, so it tries to invoke the cached EJB stubs, which are no longer valid. However, when the invocation error occurs, the transport assumes that those stubs are now invalid, and removes them from the cache. In this way, the error is prevented on subsequent attempts to invoke the EJB. To avoid this first-time error, you can reset the JNDI provider in the Oracle Service Bus Console.
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. Service Bus generates a WSDL file when you save the EJB transport configuration. The generated WSDL file is 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 file that is generated.
Use the following URI pattern for the EJB transport endpoint URIs in business services:
ejb:jndi_provider_name:ejb_jndi_name
where jndi_provider_name is the name of the Service Bus JNDI provider resource.
If the EJB is deployed locally, the JNDI provider name is not required. In this case, use the following URI format:
ejb::ejb_jndi_name
For EJB 3.0 business services on Oracle WebLogic Server, ejb_jndi_name takes the form of mappedName#BusinessInterface.
If your EJBs are running on IBM WebSphere, ejb_jndi_name must be in one of the 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.
The following table describes the properties you use to configure an EJB transport for a business service. For more information, see Creating and Configuring Business Services.
Table 28-1 EJB Transport Properties for Business Services
| Properties | Description |
|---|---|
|
Pass Caller's Subject |
Select this check box to have Service Bus pass the authenticated subject from the proxy service when invoking the EJB and no service accounts are configured. This is an alternative to using a service account, and the Service Account field is disabled when this option is selected. |
|
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 option is not available if you select the Pass Caller's Subject option. For more information, see Working with Service Accounts. |
|
Supports Transaction |
Select this check box to specify that the EJB supports transactions. |
|
EJB 3.0 |
Select this check box if the interface uses EJB version 3.0. |
|
Client Jar |
Click Browse to select an EJB client JAR resource from the list of available resources. |
|
Converter Jar |
Click Browse to select an EJB converter class JAR resource from the list of available options. This field appears after you select the client JAR file above. For more information, see Adding a Client or Converter JAR File and Custom Converter Classes. |
|
Home Interface |
Select the required EJBHome interface from the options populated by the JAR file. This field is available for EJB 2.1 only. The JNDI name in this URI sample must be associated with the EJBHome interface you select here. If the EJB is not of the required type or an EJBHome interface is not specified in the client JAR file, Service Bus displays a warning. |
|
Remote Interface |
Displays the remote interface, and is automatically populated depending on the configuration of the Home Interface. This for EJB 2.1 only. |
|
Business Interface |
Select the business interface in the client JAR that you want to invoke. This field is available for EJB 3.0 only. |
|
Target Namespace |
Displays the namespace determined from information picked up from the JAR file. This field only appears when you select EJB 3.0 and specify a client JAR file. |
|
Style |
Select Document Wrapped or RPC according to your requirements. If two or more methods of your stateless session EJB have the same number and data type of parameters, and you want the operations to be document-oriented, specify that they be document-wrapped. The style is important because when routing or publishing to the EJB, Even though the RPC style is supported with JAX-WS, Document Wrapped is recommended for new EJB endpoints. Existing EJB business services can still use the RPC style. |
|
Encoding |
Specify the encoding of the SOAP message, either Encoded or Literal. |
|
Methods |
Configure the methods of the EJB remote or business interface you selected. Select the required methods (you can select multiple methods). Expand the method to configure, and then edit the default parameter values and select a converter if provided (or required). You can change the default operation name for each method. By default, the operation name is the method name. If an EJB contains methods with same name, you must change the operation names so they are unique; WSDL files require unique operation names. You can select methods to include or exclude. You must exclude the methods with parameters or return types that are not supported by the JAX-WS stack or you must associate such arguments with converter classes. Note: If the credentials or transaction settings are different between the methods for an EJB, you can customize the methods for a specific business service, and create a business service per method. This gives you fine-grained control over transactions and credentials. |
|
Exceptions |
Displays any business exceptions thrown by a method. If an EJB method throws an exception that has data types not supported by Java Web Services (JWS), such as an ArrayList, use the Exceptions field to select a converter class that converts the exception to a type supported by JWS. Your converter class must implement |