Project Open ESB Starter Kit – Troubleshooting Guide

Project Open ESB Starter Kit, available from Java Platform, Enterprise Edition 5 (Java EE 5) SDK Update 1, provides a JBI runtime with Business Process Execution Language (BPEL) support. For additional information on Open ESB Starter Kit, including links to documentation and download bundles, refer to Open ESB Starter Kit At A Glance.

This Troubleshooting Guide is based on the Sun Java System Application Server Platform Edition 9 Troubleshooting Guide, but contains information specific to Open ESB Starter Kit. When troubleshooting Open ESB Starter Kit, you might want to first refer to the Application Server Troubleshooting Guide to see if that manual provides a solution to your problem.

The following documentation would also be helpful in troubleshooting Open ESB Starter Kit:

Plan Ahead

Backup and Restore Instructions

As you experiment with Open ESB Starter Kit and the JBI runtime, there might be times when you need to revert the Application Server to a previously saved working configuration. Use the backup-domain option to the asadmin command to take “snapshots” of your server configuration.

The Application Server Administration Guide provides complete documentation on the backup-domain and restore-domain options to the asadmin command. Here is a summary of this procedure:

To backup and restore a server configuration:

Start the application server

<appserver-install-root>/bin/asadmin start-domain <domain-name>
Stop the domain

<appserver-install-root>/bin/asadmin stop-domain <domain-name>
Back up the domain

<appserver-install-root>/bin/asadmin backup-domain <domain-name>

Backed up directories are stored by default in the <appserver-install-root>/backups directory.
Make changes to the Application Server configuration and/or domain(s), as desired.
If necessary, restore the server and/or domain configuration to the state saved in Step 3, above.

<appserver-install-root>/bin/asadmin restore-domain --filename <backup_file> <domain-name>

Verify Configuration Information

What version of Application Server are you using?

Open ESB Starter Kit has been verified for use with:
- Sun Java Systems Application Server 9.0 Update 1
- GlassFish Application Server, Version 1
What version of Open ESB Starter Kit are you using?

Make sure you are using Open ESB Starter Kit available from any of the following Java EE 5 SDK distributions (or installable jar) listed on the Java EE 5 SDK Downloads page.
What version of the Java 2 Platform, Standard Edition (J2SE) are you using?

Open ESB Starter Kit is verified for J2SE 5 Update 6.
If you are using the tools available with the NetBeans^TM IDE, which version are you using?

Open ESB Starter Kit tools are available with the NetBeans IDE 5.5 Enterprise Pack. You can download the NetBeans IDE 5.5 Enterprise Pack from the NetBeans Products page. If you are downloading the Java EE 5 SDK from the Java EE 5 SDK Downloads page, use the Tools option. The tools option includes the NetBeans 5.5 IDE plus the Enterprise Pack.

Installation Information

Make sure you have downloaded and installed the Open ESB Starter Kit as directed. Refer to Open ESB Starter Kit Download Page and the Open ESB Starter Kit Installation page for the various ways you can download and install Open ESB Starter Kit.

JBI Installation Image

After installing Open ESB Starter Kit, verify the installation image. The following tree shows the key Open ESB directories in the Application Server addons directory:

<AppServerRoot>
       |
       +--addons
           |
           +--jbi
	       |
	       +--appserver
	       |    |
	       |    +--ant
	       +--bin
	       |
	       |
	       +--components
	       |      |
	       |      +--bindings
	       |      |
	       |      |--engines
	       |      |--sharedlibraries
	       |
	       +--config
	       |
	       +--doc
	       |   |
	       |   +--antdoc
	       |   |
	       |   +--javadoc
	       |
	       +--lib
	       |
	       +--jbi-addon-kit (if installed)

The following tree shows the JBI installation image within an Application Server domain:

<AppServerRoot>
       |
       +--domains
             |
             domain-name
                      |
                      + jbi
                         |
                         +--bin
                         |
                         +--bindings
                         |
                         +--config
                         |
                         +--engines
                         |
                         +--sharedlibraries
                         |
                         +--system

Identify the Problem

Log Files

The JBI runtime, service engines, and binding components write information to Application Server log files that you can use to troubleshoot problems with Open ESB Starter Kit. Check the log files available at the following location:

<appserver-install-root>/domains/<domain-name>/logs/server.log

For more information on using Application Server logging to troubleshoot problems, refer to the “Overview” chapter of the Application Server Troubleshooting Guide and the “Configuring Logging” chapter of the Application Server Administration Guide. These chapters provide information on setting log levels to get more detailed log messages and how to specify logger names for various modules.

Note: All JBI runtime loggers have logger names that begin with the name “com.sun.jbi.” JBI logger modules do not appear in the Application Server Admin Console. Instead, you have to search the server.log file to view JBI logging messages.

Modifying Log Levels for the JBIFramework

To modify the log levels for the JBIFramework module in the Application Server Admin Console:

In the Admin Console, select Applications | Lifecycle Modules | JBIFramework.
In the Additional Properties panel, select the toggle for com.sun.jbi.defaultLogLevel.
In the Value field, type in the log level you want for the JBI Framework module.
Select Save to save your log level changes.

Modifying Log Levels Using JConsole

To modify log levels for JBI service engines and binding components installed in your JBI environment:

Start the JConsole for your J2SE environment by executing the jconsole command in your J2SE bin directory.
In the JConsole window, click the MBeans tab.
In the MBeans tab, to the following locations for the service engine or binding component MBeans installed in your JBI environment:

com.sun.jbi/<domain-name>/componentname/Logger/Installed/Binding/
com.sun.jbi/<domain-name>/componentname/Logger/Installed/Engine/
Click a binding component or service engine MBean to view the Display Name, Logger Name, and to set the DisplayLevel.

Thread Dumps

The Application Server provides instructions to obtain thread dumps. For information on how to get a thread dump, refer to the “Overview” chapter of the Application Server Troubleshooting Guide.

Online Forums

The following online forums are available for discussion of Open ESB Starter Kit and JBI issues. You can monitor or participate in these forums to help resolve any issues that might arise in your implementation.

This section provides solutions to some common problems that might occur with Open ESB Starter Kit, including the JBI runtime, JBI service engines, and JBI binding components.

JBI Runtime – Troubleshooting JBI Ant Commands

JBI Ant References

Open ESB Starter Kit provides the following JBI Ant references:

JBI Ant Targets Reference
implementation to Ant commands that allow you to invoke JBI Ant administration targets without having to write your own Ant XML scripts.
JBI Ant Tasks Reference
Reference to JBI Ant tasks that perform installation, deployment, life cycle and query functions.

The JBI Ant Task Reference and JBI Ant Target Reference can be found in your Open ESB Starter Kit installation at the following location:

<appserver-install-root>/addons/jbi/doc/antdoc/

You can also find them online at the following location:

Absolute Paths When Installing a JBI Component of Deploying a Service Assembly

Absolute paths are required when invoking the tasks that install or uninstall a JBI component or tasks that deploy or undeploy a service assembly. In these cases, you specify the absolute path to the archive file (.jar or .zip file) for the component or service assembly. If you specify a relative path, the command will fail. For example, to install the following component:

Here is an example error message that is reported if the path is specified incorrectly:

Install component failed. [
  ERROR:(UIANT2002)Component archive file not found (comp_installer.zip).
]

JBI Ant Administration Build File

All JBI Ant administration commands must specify the location of the build file with the -f option. The JBI Ant build file can be found at the following location:

<appserver-install-root>/addons/jbi/bin/jbi_admin.xml

For example:

asant -f <appserver-install-root>/addons/jbi/bin/jbi_admin.xml [options] [target]

If the path is specified incorrectly or is missing, the asant utility displays the following message:

Buildfile: jbi_admin.xml does not exist!
Build failed

Name/Value Pairs for Ant Targets

When invoking Ant targets, make sure you are passing the correct arguments using the -D option.

Each -D option specifies a name/value pair that represents a property name and value that you want to pass to the ant script.

After specifying the option, make sure you then specify the Ant target. A common mistake is to forget to include this target.

If you still get errors, double-check that the options are correctly specified.

Here is an example of an error message that is reported if arguments are specified incorrectly or the Ant target is missing:

BUILD FAILED
...<AppServer>\jbi\bin\jbi_admin.xml:119: Install component failed.
[ERROR:(UIANT2002)Component archive file not found (${jbi.install.file}).]

Deploying Service Assemblies to Components

One of the most frequent JBI administration tasks is deploying a service assembly to a component. Here is the typical order of events for this scenario:

Install a JBI component.
This is typically a one-time task.
Start the component.
Installing a component does not automatically start the component. You must explicitly start the component after it is installed.

Note that when you shutdown the Application Server, the state of the component is preserved. When you restart the Application Server, the component will be in the state at the time the Application Server shut down.
Deploy a service assembly to a component.
This task is performed multiple times, once for each service assembly you deploy to the component.

Make sure the component is in the started state before the service assembly is deployed to it. Otherwise the deployment will fail with “component not started“ message.
Start the service assembly.
Once a service assembly is deployed, it must be explicitly started. You cannot exchange messages or invoke services within that service assembly unless the service assembly is in the started state.

In some cases, your deployment might be partially successful. This can occur when a service assembly is deployed to multiple components for the following reasons:
- One or more of the components are not available (the target is missing)
- The components are in a state where they cannot accept the deployments
- There might be a deployment failure on a particular component
Partial success deployments generate messages that have a WARNING message followed by zero or more messages ( ERROR, WARNING or INFO) from each component involved in the deployment. These messages indicate problems with the deployment that are not considered critical to report as a failure of the deployment.

Here is an example:
Service assembly deployment succeeded. [ WARNING:(JBIMA1004)The Service Assembly ant_test_assembly_unit_1 was deployed successfully. Component: ant_test_engine1 ERROR:(JBIMA0474)Cannot change state of service unit ant_test_engine_1_asa1. Component ant_test_engine1 is in an incorrect state. Component: ant_test_binding1 INFO:(JBIMAXXX) Component specific message which is not a error. ] Service assembly deployment succeeded. [ WARNING:(JBIMA1422)Service assembly ant_test_assembly_unit_1 was deployed succ essfully, however some service units from the service assembly could not be depl oyed since their target components are not installed on the specified instance l ist or are missing in the system. These service unit : components are : { ant_te st_binding_1_asa1 : ant_test_binding1,} ]

Uninstalling JBI Components

When uninstalling a JBI component, first make sure all service assemblies are stopped, shut down, and undeployed. This is to avoid other services attempting to access services that will no longer be available because of the uninstallation. Otherwise the uninstall will fail.

After all service assemblies are undeployed, then you can stop, shut down, and uninstall the JBI component.

Shared Libraries

If a JBI component is dependent on a shared library, then you must first install the shared library before you install the component. Before uninstalling a shared library, make sure you first uninstall any component dependent on the shared library.

The following documentation on shared components includes documentation of dependencies on shared libraries: JBI Component Documentation

You can also discover shared library dependencies by searching a component's jbi.xml descriptor file for the "shared-library" element. You can find the jbi.xml descriptor file in the archive (.jar or .zip file) for the component. The META-INF directory contains the jbi.xml file.

Classpath Exceptions

Classpath exceptions can occur during installation/uninstallation of a component or during runtime for the component.

If you encounter class not found exceptions for a JBI component, examine either the bootstrap-class-path or the component-class-path elements, which are defined in the jbi.xml descriptor file for the component.

For errors during installation/uninstallation, verify that the bootstrap-class-path element contains all the classes required by the component.

For errors during runtime, verify that the component-class-path element contains all the classes required by the component.

JBI Component Documentation

Documentation on JBI components available for Open ESB Starter Kit is available here: JBI Component Documentation

This documentation provides the following information:

Configuration information
Component capabilities
Component limitations
Versions of the underlying protocols that are supported
Typical use cases

JBI Component Installation

Open ESB Starter Kit comes with the following JBI components installed by default:

BPEL Service Engine
HTTP SOAP Binding Component
Java EE Service Engine

The following additional JBI components are available for download and installation:

XSLT Service Engine
JMS Binding Component
File Binding Component

Refer to the Open ESB Starter Kit Download page for information on downloading and installing these components.

Troubleshooting JBI Components

Accessing Web Services Through HTTP

Make sure your web services are accessible through HTTP. If a web service is not accessible through HTTP, the HTTP client in Netbeans is unable to create a connection, generating an exception similar to the following:

com.sun.xml.messaging.saaj.SOAPExceptionImpl: java.security.PrivilegedActionExc
eption: com.sun.xml.messaging.saaj.SOAPExceptionImpl: Message send failed
        at com.sun.xml.messaging.saaj.client.p2p.HttpSOAPConnection.call(HttpSO
APConnection.java:127)
        at org.netbeans.modules.compapp.catd.ConfiguredTest.sendMessage(Configu
redTest.java:1445)
        at org.netbeans.modules.compapp.catd.ConfiguredTest$ConcurrentTestSendO
nlyRunnable.run(ConfiguredTest.java:1301)
        at java.lang.Thread.run(Thread.java:595)
Caused by: java.security.PrivilegedActionException: com.sun.xml.messaging.saaj.
OAPExceptionImpl: Message send failed
        at java.security.AccessController.doPrivileged(Native Method)
        at com.sun.xml.messaging.saaj.client.p2p.HttpSOAPConnection.call(HttpSO
APConnection.java:121)
        ... 3 more
Caused by: com.sun.xml.messaging.saaj.SOAPExceptionImpl: Message send failed
        at com.sun.xml.messaging.saaj.client.p2p.HttpSOAPConnection.post(HttpSO
APConnection.java:305)
        at com.sun.xml.messaging.saaj.client.p2p.HttpSOAPConnection$Priviledged
Post.run(HttpSOAPConnection.java:150)
        ... 5 more
Caused by: java.net.ConnectException: Connection refused: connect
        at java.net.PlainSocketImpl.socketConnect(Native Method)
        at java.net.PlainSocketImpl.doConnect(PlainSocketImpl.java:333)
        at java.net.PlainSocketImpl.connectToAddress(PlainSocketImpl.java:195)
        at java.net.PlainSocketImpl.connect(PlainSocketImpl.java:182)
        at java.net.Socket.connect(Socket.java:516)
        at java.net.Socket.connect(Socket.java:466)
        at sun.net.NetworkClient.doConnect(NetworkClient.java:157)
        at sun.net.www.http.HttpClient.openServer(HttpClient.java:365)
        at sun.net.www.http.HttpClient.openServer(HttpClient.java:477)
        at sun.net.www.http.HttpClient.<init>(HttpClient.java:214)
        at sun.net.www.http.HttpClient.New(HttpClient.java:287)
        at sun.net.www.http.HttpClient.New(HttpClient.java:299)
        at sun.net.www.protocol.http.HttpURLConnection.getNewHttpClient(HttpURL
Connection.java:796)
        at sun.net.www.protocol.http.HttpURLConnection.plainConnect(HttpURLConn
ection.java:748)
        at sun.net.www.protocol.http.HttpURLConnection.connect(HttpURLConnectio
n.java:673)
        at sun.net.www.protocol.http.HttpURLConnection.getOutputStream(HttpURLC
onnection.java:840)
        at com.sun.xml.messaging.saaj.client.p2p.HttpSOAPConnection.post(HttpSO
APConnection.java:262)
        ... 6 more

Possible Solutions:

If the web service is provisioned by a Composite Application Project, check to make sure your web service is deployed and running. One way of doing this is using your browser to get the WSDL for your endpoint.

For example, if your endpoint is http://localhost:12000/echoService, you can use the ?WSDL syntax to see if your endpoint is present. For this endpoint, you should be able to type http://localhost:12000/echoService?WSDL in a browser to get the WSDL for the endpoint. If you are able to get the WSDL, that means the service is up.
If the web service is provisioned by another web service provider, make sure that the endpoint is accessible as described by the documentation for that third party web service provider.

Unprovisioned PortTypes in WSDL

When building a Composite Application project in NetBeans, you might get an error that looks like the following in the Output window of Netbeans:

***Warning: PORT w/o address: {yahoonews}YahooNewsPt

This error message indicates that you have a WSDL in your project with a particular PortType that is not being provisioned and/or it's not being called. Basically it indicates an unused WSDL. This may or may not be good depending on whether you expect the WSDL to be used as part of your composite application.

Possible Solutions:

If your WSDL is not being used in your project, remove it. It only takes up space and the various components have to parse it only to realize that it was not part of the application.
If your Composite Application is using this WSDL (either provisioning it or calling it), make sure that your Services (BPEL, XSLT, and others) are set up properly. Pay attention to partner links and roles to make sure everything is correct.

SOAP Faults Without Detailed Messages

A project can build and deploys properly, but running a test case can generate a SOAP Fault that has no detail. This SOAP fault can look something like this:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
     xmlns:xsd="http://www.w3.org/2001/XMLSchema"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:schemaLocation="http://schemas.xmlsoap.org/soap/envelope/ 
http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header/>
  <SOAP-ENV:Body>
     <SOAP-ENV:Fault>
        <faultcode>SOAP-ENV:Server</faultcode>
        <faultstring></faultstring>
     </SOAP-ENV:Fault>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Solution:

The SOAP 1.1 Specification defines 4 distinct fault codes that can occur (see http://www.w3.org/TR/2000/NOTE-SOAP-20000508/#_Toc478383510). The Server code indicates that some type of error occurred that could not be attributed to the message itself. Usually, when this type of error occurs, a flaw occurred in the processing of the message.

An error without a definitive faultstring usually implies something simply failed in the processing of the message. The failure was so catastrophic that no message could be generated to properly explain the issue. The best approach in this case is to examine the log files to determine the best course of action.

SOAP Faults: Resolving One or More Operations

After creating a WSDL, provisioning it using the HTTP BC and the BPEL Service Engine, and deploying it, a generated test case (created using the test case generator in the Composite Application project) results in an error similar to this:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
     xmlns:xsd="http://www.w3.org/2001/XMLSchema"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:schemaLocation="http://schemas.xmlsoap.org/soap/envelope/
http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <SOAP-ENV:Fault>
         <faultcode>SOAP-ENV:Server</faultcode>
         <faultstring>More than one operation defined. Unable to resolve 
operation: ...</faultstring>
      </SOAP-ENV:Fault>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Solution:

With web services, multiple operations can map to a single endpoint. For example, you may have one endpoint defined at http://localhost:12000/echoService, you might have several operations available at that endpoint. You must be able to uniquely define each operation; the uniqueness depends on how the operation is bound to the concrete binding. For HTTP BC, the operation is determined based on several factors:

If the encoding is rpc-style, the name of the operation is part of the SOAP message. This allows us to properly determine the correct operation.
If the encoding is document-style, the name of the operation is not part of the SOAP message. HTTP BC compares the message structure of the operation. Presumably, one operation will have different inputs than another operation.
If the user uses the SOAPAction URI, that will also uniquely identify an operation to route a message to.

If HTTP BC cannot determine how to route the message it receives at a particular endpoint to the correct operation, you will receive the Fault message shown above.

Make each operation in your PortType unique. By unique, it must be distinguishable based on the SOAP message on the wire. This may mean using different messages for each operation if using document style. If that is not possible, it may involve defining unique SOAP Action URI attributes for each operation.

Java^TM Platform, Enterprise Edition (Java EE) 5 Technologies

Project Open ESB Starter Kit
Troubleshooting Guide

Contents

Troubleshooting Overview

Plan Ahead

Backup and Restore Instructions

To backup and restore a server configuration:

Verify Configuration Information

Installation Information

JBI Installation Image

Identify the Problem

Log Files

Modifying Log Levels for the JBIFramework

Modifying Log Levels Using JConsole

Thread Dumps

Online Forums

Solutions to Some Common Problems

JBI Runtime – Troubleshooting JBI Ant Commands

JBI Ant References

Absolute Paths When Installing a JBI Component of Deploying a Service Assembly

JBI Ant Administration Build File

Name/Value Pairs for Ant Targets

Deploying Service Assemblies to Components

Uninstalling JBI Components

Shared Libraries

Classpath Exceptions

JBI Component Documentation

JBI Component Installation

Troubleshooting JBI Components

Accessing Web Services Through HTTP

Unprovisioned PortTypes in WSDL

SOAP Faults Without Detailed Messages

SOAP Faults: Resolving One or More Operations

JavaTM Platform, Enterprise Edition (Java EE) 5 Technologies

Project Open ESB Starter KitTroubleshooting Guide

Contents

Troubleshooting Overview

Plan Ahead

Backup and Restore Instructions

To backup and restore a server configuration:

Verify Configuration Information

Installation Information

JBI Installation Image

Identify the Problem

Log Files

Modifying Log Levels for the JBIFramework

Modifying Log Levels Using JConsole

Thread Dumps

Online Forums

Solutions to Some Common Problems

JBI Runtime – Troubleshooting JBI Ant Commands

JBI Ant References

Absolute Paths When Installing a JBI Component of Deploying a Service Assembly

JBI Ant Administration Build File

Name/Value Pairs for Ant Targets

Deploying Service Assemblies to Components

Uninstalling JBI Components

Shared Libraries

Classpath Exceptions

JBI Component Documentation

JBI Component Installation

Troubleshooting JBI Components

Accessing Web Services Through HTTP

Unprovisioned PortTypes in WSDL

SOAP Faults Without Detailed Messages

SOAP Faults: Resolving One or More Operations

Java^TM Platform, Enterprise Edition (Java EE) 5 Technologies

Project Open ESB Starter Kit
Troubleshooting Guide