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:
- "Address already in use" - There is already a server running on port 8080.
- "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.
- "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.
- 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
- Open the end-point reference file in your text editor.
- 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. - 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.jarfile, (SOA_ROOT/jboss-as./server/PROFILE/deployers/esb.deployer/lib/juddi-client-VERSION.jar) - Ensure that the
jbossesb-properties.xmlfile 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.xmlfile specifies a valid transport. - Make sure that the
persistence.xmlfile's settings are valid and that the Hibernate dialect you have chosen matches that used by the database. - Ensure that the
esb.juddi.xmlfile 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:
- The JBoss jUDDI Wiki: http://www.jboss.org/community/docs/DOC-11217
- The JBoss ESB User Forum: http://community.jboss.org/en/jbossesb?view=discussions.
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
Open the run.conf File
Open the file in a text editor:vi SOA_ROOT/jboss-as/bin/run.conf.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"
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"
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 thecom.ibm.mq.MQEnvironment's enableTrace static method.
