5.0.2 Release Notes

JBoss Enterprise SOA Platform 5

Changes in the 5.0.2 Release


These Release Notes contain important information regarding changes in the 5.0.2 release of the JBoss Enterprise SOA Platform.
The JBoss Enterprise SOA Platform is a certified, tested, and supported environment for developing Enterprise Application Integration and SOA solutions.
For the latest version of these release notes please refer to the online documentation available at http://www.redhat.com/docs/en-US/JBoss_SOA_Platform/.

1. Components of the 5.0.2 Release

The JBoss Enterprise SOA Platform includes the following components.

Table 1. Included Components

Component Version
JBoss EAP 5.0.1
JBoss ESB 4.7 CP02
JBoss Rules 5.0.1
JBoss jBPM 3.2.9
Apache jUDDI 3.0.1
PicketLink 1.0


The JBoss Enterprise SOA Platform includes the Hypersonic database (HQSQL) for testing and demonstration purposes. Hypersonic is not suitable for use in a production environment and it is not supported in that capacity. Instructions on how to change the database provider are in the Post-Installation Configuration section of the JBoss Enterprise SOA Platform Getting Started Guide.
The following features are included as Technology Previews only:
  • Support for SAML Tokens
  • JBoss Rules Fusion
    The JBoss Rules Fusion is an API for Event Drive Architecture (EDA) and is provided as a Technology Preview. It is accessible from the JBoss Rules API but the JBoss ESB does not currently provide any support for it. You will need to create your own custom actions to interact with Fusion functions from the ESB.


Technology Preview features are not fully supported and may not be functionally complete. They are not intended for production use. These features are included to provide customers with early access to upcoming product innovations, enabling them to test functionality and provide feedback during the development process.
Red Hat JBoss support will provide commercially-reasonable efforts to resolve any reported issues that customers experience when using these features.

2. Requirements and Installation

The JBoss Enterprise SOA Platform Getting Started Guide contains details of software and hardware requirements as well as detailed installation instructions.
The JBoss Enterprise SOA Platform Getting Started Guide can be found online at http://www.redhat.com/docs/en-US/JBoss_SOA_Platform/.

3. Documentation

The documentation for the JBoss Enterprise SOA Platform is available online at http://www.redhat.com/docs/en-US/JBoss_SOA_Platform.


Read the Getting Started Guide first as it contains instructions for installing and configuring the platform.
The documentation consists of the following books:
  • Getting Started Guide
  • ESB Administration Guide
  • JBoss Rules Reference Guide
  • jBPM Reference Guide
  • ESB Programmer's Guide
  • ESB Services Guide
  • Smooks Users' Guide


Documentation for the JBoss Enterprise Application Platform (EAP) is available online at http://www.redhat.com/docs/en-US/JBoss_Enterprise_Application_Platform/.

4. Resolved Issues

Each release of the JBoss Enterprise SOA Platform contains all the fixes from the previous releases. Refer to the Release Notes for each release for details.
The following issues have been resolved for the 5.0.2 release of the JBoss Enterprise SOA Platform:
An Invalid End-Point Address error would occur if the user tried to access http://localhost:8080/jbossws/services whilst a WAR file was embedded in a JAR archive. This occurred because the web service inside the ESB archive was deployed in such a way that the WAR did not contain the WEB-INF/jboss-web.xml file, meaning that the web service's WSDL would be inaccessible.
This was a backwards-compatibility issue. It has been fixed by adding jboss-web.xml and specifying a context root. As a result, the error no longer occurs.
The jUDDI v3 database was created through the use of Hibernate. This was in contrast to the other ESB components, which used SQL scripts. The Schema tool has now been revised to support the creation of the jUDDI database.
A null pointer exception would occur when the user deployed a JAX-WS end-point with types in the target name-space that ended with #. To fix this problem, the software has been changed so that it now detects the presence of the # character and converts it to _ in the schema name-space. It does so at the point in time at which the temporary filename to which the schema is written is generated. (This filename is based on the schema's name-space.) As a result, the exception no longer occurs.
Previously, the Schema tool would only support a limited number of databases. It has now been enhanced and, as a result, supports these second-tier databases:
  • MySQL 5.0
  • PostgreSQL 8.2.4
  • Microsoft SQL Server 2008
  • Oracle 11g
Three quick-starts have been removed. These are xsd_validation , webservice_proxy and JAAS_action. The reason for their removal is that none of them were part of the ESB project. They are, therefore, no longer available to users.
The Web Service Console only used basic authentication. It now features form-based authentication, the use of which avoids the need to send the username/password pair on each request, making the system more secure.
The Oracle RAC required URLs to be presented in a specific format, which the Schema tool was unable to handle. Extensions have been added to the tool to provide compatibility with this format.
The EsbDeployment stop/start MBean functions would not restart the listeners. To fix this problem, reference to the controller is nulled upon stopping and a guard for null has been added to the method. As a result, the restart function now works as expected. A state for querying this has also been added.
JmsConnectionPool was performing a JNDI lookup of the connection factory for every session obtained from the connection pool. This lookup is now only done when the connection factory is first accessed or when the connection returns an error. This provides faster performance.
The files required for integration of the JBoss Enterprise SOA Platform with HP Systinet where not included. These files, jbossesb-transport-client-1.0.jar and jbossesb-transport-1.0.jar, are now included in the directory $SOA_ROOT/tools/systinet/.
The jBPM and jUDDI web consoles were included as WAR files in the earlier releases. The WAR files had to be unzipped ("exploded") before they could be configured. The consoles are now included in their "exploded" form to simplify this process.
ESB archives could fail to deploy if they contained XSD files that were not in the root directory of the archive. If the XSD file was in a sub-directory of the archive and contained <xs:import ../> statements, deployment would fail and thrown an exception (IllegalArgumentException). This was because the paths for import elements where resolved from the root of the archive and not from the location of the XSD file. This has been fixed and the paths for imported XSD files (including nested imports) are resolved correctly.
The included version of the JBoss Enterprise Application Platform has been updated to 5.0.1. This resolves a number of issues which can be found documented in the JBoss Enterprise Application Platform 5.0.1 Release Notes.
Support for Microsoft SQL Server and IBM DB2 databases has been added to the JBoss Enterprise SOA Platform database schema tool. Refer to the ESB Administration Guide and the Getting Started Guide for more information on its use.
The deployment descriptor (web.xml) of picketlink-sts.war in the security_saml quickstart contained configuration that could allow an attacker to bypass the application's security with a crafted HTTP request. The following lines have been removed from the file web.xml of this quickstart to fix this:
If this quickstart was used to create another application then the new application will need to be reviewed to ensure it does not also have the same issue.
JBoss Rules projects with JBoss Developer Studio 3 and JBoss Enterprise SOA Platform 4.3.CP04 required that the JAR files mvel2-2.0.12.jar xstream-1.2.2.jar to the class-path.
Those files are now included in each server profile. They can be found in $SOA_ROOT/server/$PROFILE/deployers/esb.deployer/lib/.
The default configuration of several of the included web applications could allow an attacker to bypass the application's security with a crafted HTTP request. The affected applications were: web-console, http-invoker, gpd-deployer, jbpm-console, contract, and uddi-console.
The following lines have been removed from the file web.xml of each application to fix this:


The Contract JSP application was not showing the WSDL for ESB archives that were deployed when the server launched. This was because the collection of the service contracts at launch time occurred too early. This has been resolved and the collection now occurs at the correct time.
JmsConnectionPool searched for associated JmsSessionPools by sequentially iterating over all JmsSessions. JmsSession now contains a reference to its associated pool so this search does not have to be done. This provides faster performance.
WSDL contracts suffered from a character encoding problem. This occurred when Russian character sets were used by the Contract JSP application. The WSDL contracts were also being truncated by the HttpGatewayServlet in this scenario. The software has now been changed to fully support Russian character encoding. As a result, the Russian alphabet can now be displayed and WSDL contracts are no longer truncated.
SqlTableGatewayListener did not correctly support transacted mode. This would result in a number of problems if it was configured with transacted="true" including the following:
  • Commits and rollbacks not being handled correctly.
  • Connections were not being released when creation of prepared statements failed.
  • Connections are not released after a database shutdown period.
This has been fixed and SqlTableGatewayListener now behaves as expected in both transacted and non-transacted modes. However the <local-tx-datasource> configuration must have a <check-valid-connection-sql> configuration or the unused connections will not be removed.
Using JMSRouter to send a message to a Topic would fail and throw an exception (ClassCastException). This has been fixed and works as expected.
A new DocumentBuilder was being created for each incoming message. This had a minor impact upon system performance. This has been resolved by eliminating the need for DOM parsing by simply wrapping the message payload string in a StreamSource and passing that to the validator instead. As a result, performance is now much faster.
The HttpGateway could not support multiple connectors if more than one was configured in jbossweb.sar/server.xml. The software now supports multiple connectors bound to different port addresses.
Deploying an ESB archive that used SOAProxy would fail if the schema location URL in the WSDL contained characters that would be invalid in a filename on the host. This occurred because the URL was used in the name of a temp file. The URL is no longer used as part of the filename and deployment is successful.
In order to prevent the jBPM database from growing to unmanageable sizes, the GraphSession.deleteProcessInstance is able to delete ended process instances. However, this functionality was not working correctly, meaning that some legacy data was left "orphaned" in the tables. This happened because only the references to the process execution were removed, not the variables themselves.
To fix this problem, variable instances are now deleted if logging is not enabled. If the logging service is enabled, the variable cannot be deleted immediately becauses the new VariableDeleteLog instance holds a reference to the variable. (These records are eventually removed upon process instance deletion.) As a result of this fixed, there are no longer orphaned files in the database.
JMSProviderAdapter is now supported by jBPM JCA inflow. This allows the jBPM JCA inflow to be referred to by JMS providers which are located in a different JNDI context to the current one, such as on a different server.
Documentation for this feature has been added to section 9.2.1 of the ESB Administration Guide.
JAXRRegistryImpl has had the following performance enhancements.
  • Classification schemes are now cached when retrieved so they can be reused without having to query the database again.
  • When deleting End Point References (EPRs), the string representation of the EPR to delete is now only generated once and reused for each EPR comparision instead of re-creating it each time.
  • The process for querying the current list of EPRs now reuses the associated bindings information returned with the overall service information instead of performing a separate query for this information.
Some users may encounter an error when running the webservice_proxy_security quick start. This occurs if the server is using a test certificate, which the client will not trust. To resolve this issue, install the certificate in the client. Instructions for doing so are found in the readme.txt file supplied with the quick start.
An authentication request's security context now contains additional functionality that allows it to check the service's domain. It can then invalidate the information if a different domain is being used to secure that service. This eliminates a low impact privilege escalation flaw whereby the execution of a service with a different domain could, potentially, have resulted in the pipeline being run with different sets of credentials, (one set from the first domain if the request were still valid and a second set from the other domain if it had expired.) (CVE-2010-2474.)
JBossASContextPropagation was using the class SecurityAssociation instead of SecurityContextAssociation. SecurityContextAssociation contains security domain information in addition to the information included in SecurityAssociation. The correct class is now used.
The RetryExecutor failed with an exception when it tried to query the database for the first "due job" when there was a large backlog of these jobs. This has been fixed by a change to make the maximum count applicable to all due jobs, not just suspended ones. As a result, this exception no longer occurs.
The deployment descriptor (web.xml) of the webservice_proxy_security quickstart contained configuration that could allow an attacker to bypass the application's security with a crafted HTTP request. The following lines have been removed from the file web.xml of this quickstart to fix this:
If this quickstart was used to create another application then the new application will need to be reviewed to ensure it does not also have the same issue.


ContextInstance.deleteVariable(name) did not delete variables from the database, and instead only removed references to the process execution. This was leading to orphaned records in the database. This method now removes the variables from the database if the logging service is disabled. If logging is enabled the new log VariableDeleteLog holds a reference to the variable and it is removed when the process instance is deleted.


The RuleFlow example "Conroy's Game of Life" has been added to the JBoss Rules Reference Guide, Section 8.8.
The RuleFlow example "Number Guess" has been added to the JBoss Rules Reference Guide, Section 8.9.

5. Known Issues

The following issues are known to exist in this release of the JBoss Enterprise SOA Platform and will be fixed in a subsequent release.

JBoss Enterprise SOA Platform

Seam applications that include their own jbpm-jpdl.jar cannot use the provided jBPM-ESB integration (e.g. EsbNotifier) within a jBPM process to invoke ESB services that are hosted on the same server. This is due to classloader issues between the jBPM classes in the Seam application and the jBPM ESB Services.
There are three possible workarounds:
  1. If possible, deploy the Seam application to a different server instance than the JBoss Enterprise SOA Platform instance that is hosting the ESB service.
  2. If invoking ESB Services is the only use of jBPM in the Seam application :
    • Remove the jbpm-jpdl.jar and jBPM process archive from the EAR
    • Deploy the jBPM process archive separately from the Seam application using the jBPM console.
  3. If jBPM is used by the Seam application for other purposes, e.g. Seam Pageflow :
    • Enable class namespace isolation within the Seam application.
    • Create a custom ActionHandler to call the ESB Service.
    • Make the custom ActionHandler available to the classloader.
    • Modify the jBPM process definition to invoke the custom ActionHandler.
Refer to http://community.jboss.org/wiki/WorkaroundforSeamESBjBPMClassloadingIssue for more details of how to implement the second workaround.
Refer to http://community.jboss.org/wiki/JbossClassLoadingUseCases for more information about JBoss Class Loading.

JBoss Operations Network

When you try to delete an ESB archive using the JON Console, the associated queues are not removed. They remain there, displaying as DOWN. Furthermore, if you try to delete these queues, an java.lang.IllegalStateException exception will occur.
When the server is started without the -c configuration switch, the profile named default is run. This is correct operation. Unfortunately, JON erroneously assumes that the production profile is run instead. JON also mistakenly assumes that the binding address is if this has not been specified. To ensure that JON recognizes the default profile and binds to the correct address of, always use the -c and -b parameters. By doing so, JON will recognize the platform.
https://jira.jboss.org/jira/browse/SOA-952, https://jira.jboss.org/jira/browse/SOA-1077, https://jira.jboss.org/jira/browse/SOA-1168
The JON plug-in's "Message Count" feature is incorrectly displaying a total number of messages for the ESB server, deployment, services and actions. It should actually be showing a rolling average.

JBoss Enterprise Service Bus

If SOAPProxy is configured to obtain the WSDL for a proxied service URL, a warning is logged, because the web service responds with a content length which either exceeds the limit or is unspecified.
Currently, the spring_aop quick start does not work with signed JARs. If you try to run ant deploy for this quick start, an org.jboss.deployers.client.spi.IncompleteDeploymentException will be thrown.
To work around this issue, replace the cglib JARs with unsigned versions.
When the Web Service proxy is used to invoke a one-way web service, it erroneously throws a run-time exception with HTTP Code 500, which is returned to the client together with a fault message. HTTP Code 500 is invalid in these situations as only Code 200 or 202 should ever be returned as the message was successfully transmitted to the ESB.
Currently, the default ESB handler class for the UDP Gateway is hard-coded into the XSD schema and cannot be changed or removed.
https://jira.jboss.org/jira/browse/JBESB-2911, https://jira.jboss.org/jira/browse/JBPAPP-3002
A web service's WSDL will be invalid and return a 404 error if the web service is deployed embedded within an ESB archive and the WAR does not contain the WEB-INF/jboss-web.xml file.
Currently, Scout creates a new AuthToken for every invocation that occurs through the BusinessQuery/BusinessLifecycle Managers. This results in rapid growth of the jUDDI authentication table.
A possibly way to work around this problem is to delete rows within certain timestamp parameters. For instance, all rows created more than ten minutes ago could be removed.

JBoss Developer Studio

Using the Full Publish option in the JBossAS view to republish a jboss-esb.xml project does not work.
To work around this issue, remove the project from the server and then add it again.
The ESB node properties for input/output variables grow larger than the jBPM panel when the latter is resized, to the point where the user must scroll left to see all of the buttons.
To work around this problem, click on a different node on the jBPM panel and then click back on the ESB Service node. Next, click on the input/output subpanel and it will be the correct size again.

6. Possible Issues When Migrating to 5

Read this section to learn about the differences between JBoss Enterprise SOA Platform 5.0 and previous versions that may cause difficulties when moving applications to version 5.
JAR files required by JBoss Rules projects are now included
A JBoss Rules project created with JBoss Developer Studio 3 for JBoss Enterprise SOA Platform 4.3 required that the JAR files mvel2-2.0.12.jar and xstream-1.2.2.jar were added to the classpath. This is no longer necessary because JBoss Enterprise SOA Platform 5 now includes these files in each server profile. They can be found in $SOA_ROOT/server/$PROFILE/deployers/esb.deployer/lib/.
Refer to https://jira.jboss.org/browse/SOA-2114 for additional information.
Changed behavior regarding JAR files in ESB archives
The JBoss Enterprise SOA Platform 5.0 requires that JAR files in ESB archives are placed in either the root directory of the archive, the /jars directory, or the /lib directory. Previous versions did not have this restriction.
Potential Performance Issues Related to Logging
Logging has changed in this release. Do not copy your customized logging definitions over from past releases or you may encounter performance problems.
Refer to https://jira.jboss.org/jira/browse/SOA-1754 to learn more about this issue.
Refer to the EAP Administration and Configuration Guide at http://www.redhat.com/docs/en-US/JBoss_Enterprise_Application_Platform/ to learn how logging has changed.
HttpResponse is not backwards compatible
The HttpResponse class in 5.0 is not backwards compatible with previous versions because of changes made to unify the ESB HTTP classes. This was done as a part of the new servlet-based HTTP gateway.
Applications and services that use HttpResponse will have to be updated before they can be deployed on JBoss Enterprise SOA Platform 5.0. The changes required are summarized in Table 2, “Refactoring requirements for HttpResponse”.

Table 2. Refactoring requirements for HttpResponse

Pre-5.0.x code 5.0.x code
org.jboss.soa.esb.actions.routing.http.HttpResponse org.jboss.soa.esb.http.HttpResponse
org.jboss.soa.esb.actions.routing.http.HttpHeader org.jboss.soa.esb.http.HttpHeader
HttpResponse.getHeaders() HttpResponse.getHttpHeaders()
Reusing Existing Databases
The JBoss Enterprise SOA Platform creates new databases for its components to use. Databases from community versions have not been tested and may not work. If the use of existing databases is needed, then contact Red Hat JBoss Support for advice.
Groovy Scripting
Groovy has undergone a major update from version 1.0 to 1.5.4. Be aware that many changes were made to the language and, whilst most scripts will still work, you may find that some will need minor work. Ensure that you test them as part of your migration process. See http://groovy.codehaus.org/Documentation for more information.
Smooks no longer supports the addToList option. Update any configurations that rely upon this option so that they instead use the newer <jb:bean> configuration namespace, which can handle lists. See the "Java Binding" chapter in the Smooks User Guide for more information.
The jBPM console now supports authentication
The non-secured version of the jBPM console is no longer needed for process deployment because the jBPM console now supports authentication for deployment. The process deployer is available at http://localhost:8080/gpd-deployer/ . This replaces the deployers from previous versions, http://localhost:8080/app/upload and http://localhost:8080/upload .

8. Obtaining Source Code

The source code for this and earlier JBoss Enterprise SOA Platform releases are available from the Red Hat JBoss Customer Support Portal at https://support.redhat.com/jbossnetwork/.