Chapter 23. Troubleshooting

23.1. Troubleshooting Your JBoss Enterprise SOA Platform Installation

Here are the solutions to some of the problems users most commonly encounter.
JBOSS_HOME set incorrectly
If the optional environmental variable, JBOSS_HOME, is set then it must point to the correct directory. If you have multiple installations, check that it is pointing to the one that you are trying to run.

Warning

Do not set this variable unless you have a specific need to do so.
Java installed incorrectly
If the Java environment has been installed or configured incorrectly, then the JBoss Enterprise SOA Platform will not function.
VM Cannot Allocate Sufficient Memory
This error occurs when there is not enough free memory available to the system to satisfy the JBoss Enterprise SOA Platform';s requirements. You can increase the amount available in one of three ways: by exiting applications, allocating more virtual memory, or physically increasing the amount of RAM installed on the system.

23.2. Troubleshooting the Boot Process

Errors in the server.log are indicated by the keyword "ERROR". If you see an error in the log, look through this list to find the cause:
  1. "Address already in use" - There is already a server running on port 8080.
  2. "Java not found" - The Java JRE may not be installed, or if it is, your PATH environment variable is not set to locate the java runtime.
  3. "Class not found" - The CLASSPATH environment variable is not set properly. You really don't need to set this variable as the server startup script sets it for you.
  4. If you see any of these errors, examine the server.log messages that come before and after the error message for additional information regarding the root cause of the error.

23.3. End-Point Reference

An end-point reference (EPR) contains the address information and technical specifications for a service. Indeed, all ESB-aware services are identified using end-point references. It is through these references that services are contacted. The are stored in the registry. Services add their end-point references to the registry when they are launched and should automatically remove them when they terminate. A service may have multiple end-point references. End-point references are also known as binding templates.
End-point references can contain links to the tModels designating the interface specifications for a particular service.

23.4. Troubleshooting Registry Services

Although the Registry lists services, it cannot determine their statuses. In other words, there can be no guarantee that an end-point reference listed in the Registry is valid (it may, for instance, be malformed or it may be representing a service that is no longer active.) This is because the JBoss Enterprise SOA Platform does not currently possess life-cycle monitoring functionality. Hence, the administrator must manually update or remove invalid end-point references.

Important

ESB services create their own end-point references automatically. These end-points are internal implementations, so you should never modify them. If you do, Red Hat will not support you.

23.5. Remove an End-Point Reference from the Registry

Prerequisites

  • Ensure the system is in an inactive state

Procedure 23.1. Task

  1. Open the end-point reference file in your text editor.
  2. Set the end-point reference's remove-old-service tag value to true: 
    <jms-listener name="JMS-ESBListener"  busidref="quickstartEsbChannel">
        <property name="remove-old-service" value="true"/>
</jms-listener>

    Warning

    Always use this option with caution, because the entire service, including every one of its end-point references, will be removed.
  3. Save the file and exit.

23.6. Apache Scout

Apache Scout is an open source implementation of JAXR, created by the Apache Project.
There are currently four implementations of the org.jboss.soa.esb.scout.proxy.transportClass class, one each for SOAP, SAAJ, RMI and Embedded Java (Local).

23.7. Service Registry and Apache Scout Troubleshooting Checklist

  • If you decide to use remote method invocation, be sure to obtain the juddi-client.jar file, (SOA_ROOT/jboss-as./server/PROFILE/deployers/esb.deployer/lib/juddi-client-VERSION.jar)
  • Ensure that the jbossesb-properties.xml file is on the class-path and that it is being read correctly. If not, the Registry try to use "null" as the name with which to instantiate classes.
  • Make sure that META-INF/esb.juddi.client.xml file specifies a valid transport.
  • Make sure that the persistence.xml file's settings are valid and that the Hibernate dialect you have chosen matches that used by the database.
  • Ensure that the esb.juddi.xml file is on the class-path. This contains some of the Registry's configuration settings.
  • Sometimes, if a service fails or does not shut down cleanly, old entries may linger on in the Registry. Remove these manually.

23.8. Further Service Registry Troubleshooting Resources

To learn more about troubleshooting the Registry, visit these locations:

23.9. Java Message Service

A Java Message Service (JMS) is a Java API for sending messages between two clients. It allows the different components of a distributed application to communicate with each other and thereby allows them to be loosely coupled and asynchronous. There are many different Java Message Service providers available. Red Hat recommends using HornetQ.

23.10. IBM Websphere MQ Java Message Service Provider Diagnostic Tracing Functionality

The IBM WebSphere MQ Java Message Service component has a message tracing capability. This can be useful when you are trying to diagnose problems.

23.11. Diagnostic Trace

A diagnostic trace is a method of troubleshooting where you can trace files and settings to see if there has been an error in the production process.

23.12. Enable Diagnostic Tracing for the IBM Websphere MQ JCA Adapter

You can set the diagnostic trace as a property on the resource adapter, or in the Java Virtual Machine's system properties. With the JBoss ESB/Application, Red Hat recommends you use the JVM system properties approach.
However, on systems that are started via use of the ./run.sh shell script, you should use the following approach:

Procedure 23.2. Task

  1. Open the run.conf File

    Open the file in a text editor: vi SOA_ROOT/jboss-as/bin/run.conf.

  2. Edit the run.conf File

    Appending the following lines onto the end of the file: 
    # Settings to enable WebSphere MQ resource adapter trace
JAVA_OPTS="$JAVA_OPTS -DtraceEnabled=true -DtraceDestination=wmq_jca.trc
-DtraceLevel=10 -DlogWriterEnabled=false"

  3. Enable Client Logging

    Still in the text editor, set the MQJMS_TRACE_LEVEL property: 
    # Settings to enable WebSphere MQ resource adapter and client trace
JAVA_OPTS="$JAVA_OPTS -DtraceEnabled=true -DtraceDestination=wmq_jca.trc
-DtraceLevel=10 -DlogWriterEnabled=false -DMQJMS_TRACE_LEVEL=base"

  4. Save

    Save the file and exit.

23.13. Enable Diagnostic Tracing for the IBM Websphere MQ Java Client

Procedure 23.3. Task

  • Call the enableTrace Static Method

    Call the com.ibm.mq.MQEnvironment's enableTrace static method.