5.0.1 Release Notes

JBoss Enterprise SOA Platform 5

Late breaking & important information related to the 5.0.1

Abstract

These Release Notes contain important and late-breaking information related to the 5.0.1 release of the JBoss Enterprise SOA Platform.
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. Overview

JBoss Enterprise SOA Platform is a certified, tested, and supported platform for developing Enterprise Application Integration and Service Oriented Architecture solutions.
It integrates a number of stable and scalable open source frameworks and solutions including Hibernate, Seam, JBoss Transactions, JBoss Clustering, the JBoss Application Server, and JBoss Enterprise Service Bus (ESB) to provide an infrastructure for enterprise SOA applications.
These community developed and enterprise certified and supported products have been combined and tested to provide a solid, robust, and scalable platform. Powered by legendary JBoss innovation and backed by Red Hat engineering and quality assurance, JBoss Enterprise SOA Platform is the platform of choice for a new generation of enterprise applications.

2. New Features in 5.0

The JBoss Enterprise SOA Platform version 5.0 is a major release with many updated and new components.
Apache jUDDI v3
The JBoss ESB now uses Apache jUDDI version 3 as its UDDI registry. This new version implements the UDDIv3 specification and includes a subscription API in addition to a new web console.
New Administration Consoles
The JBoss Enterprise SOA Platform includes new several new consoles:
  • JBoss SOA Administration Console
  • Web Services Console (listing deployed services)
  • jUDDI Registry Console (UDDI Browser, publisher, subscription and search)
The new JBoss SOA Administration Console replaces the JBoss ESB Management Console from previous releases.
The JBoss Management Console is now considered deprecated but can still be accessed at http://localhost:8080/web-console.
Message Level Alerting
This new feature provides monitoring and alerting at both the action and service level. Any individual message that exceeds a defined processing time or size can generate an Message Alert that can be accessed using the JMX Console. The JBoss Operations Network Server (JON) ESB plugin collects the Message Alerts and generates JON Events.
This feature is demonstrated in the messagealerts quickstart.
New HTTP Gateway
The new HTTP gateway supports the HTTP methods of GET, PUT, POST and DELETE; provides full access to the URL arguments and query string; and allows the modification of response headers.
The new quickstart http_gateway demonstrates how to use basic authentication and how to map ESB exceptions to HTTP error codes.
New UDP Listener
A new UDP listener based on Apache Mina has been added and is demonstrated in the quickstart udp_gateway.
XSLT Transformer Action
The new XsltAction action provides dedicated support for XSLT transformations.
The use of XsltAction is demonstrated in the webservice_proxy_versioning quickstart.
For more complex transformations such as large message splitting and for native support of EDI, CSV, JSON, and Java related inputs/outputs you should use the Smooks transformer action.
New XPath and Regex Router Support
ContentBasedRouter now includes support for XPath and Regex (regular expressions) in addition to JBoss Rules.
The quickstart fun_cbr demonstrates all three options for content-based routing. See the service definitions of XPath_FunCBRService_ESB and Regex_FunCBRService_ESB in the jboss-esb.xml of this quickstart for an example of XPath and Regex respectively.
Schema Validation
A new XSD schema validation action has been added, SchemaValidationAction.
New Web Service Proxy Action
The new SOAPProxy action provides support for the invocation of external Web Service endpoints and the re-publication of WSDL through the ESB. The allows for location abstraction, service versioning, complex routing, and message and WSDL transformations.
Several new quickstarts have been added to illustrate some of the capabilities:
  • webservice_proxy_basic - exposing an external web service through the ESB.
  • webservice_proxy_routed - content-based routing to different external webservice endpoints.
  • webservice_proxy_security - using SSL and basic-auth.
  • webservice_proxy_versioning - handling external web service versioning.
Synchronous Service Invocation action
Synchronous service invocation from ESB services can now be performed using the new SyncServiceInvoker message routing action. The response from the invoked service is then available in the calling service's action pipeline.
Updated to Business Rules Engine v5
The Business Rules Engine (JBoss Rules) has been upgraded to version 5.
Technology Preview of SAML
Single Sign On (SSO) capabilities based on SAML tokens are provided using Picketlink v1.0 as a Technology Preview.
The quickstart security_saml demonstrates this capability.
JBoss Enterprise Application Server 5.0
The JBoss Enterprise Application Server 5.0 (JBoss EAP 5.0) is based on the JBoss AS 5.1.x family and is the latest release of the world's most popular application server. JBoss EAP 5.0 represents the state of the art with the second generation JBoss Microcontainer-based enterprise Java run-time.
In addition to supporting the latest Java EE specification (Java EE 5), JBoss EAP 5.0 integrates many of the best enterprise class services for advanced messaging, persistence, transactions, caching and high-availability.
JBoss Microcontainer
The JBoss Microcontainer is a refactoring of the modular JBoss JMX Microkernel. It is a lightweight kernel that manages the loading, lifecycle and dependencies between POJOs. Together with a Servlet/JSP container, an EJB container, deployers, and management utilities, the JBoss Microcontainer provides a standard Java EE 5 profile.
JBoss Cache
JBoss Cache provides replication for EJB and HTTP session state and supports distributed entity caching for JPA. It also provides superior performance and scalability with the new MultiVersion Concurrency Control (MVCC) locking scheme.
JBoss Web Services
JBoss Web Services is a framework that provides support for the latest JAX-WS specification as well as a plugin architecture for supporting alternative Web Services Stacks.

2.1. Technology Previews

JBoss Enterprise SOA Platform 5.0 includes the following features 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, may not be functionally complete, and 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.

3. Components of the 5.0.1 Release

The JBoss Enterprise SOA Platform 5.0.1 Release includes the following component versions:

Table 1. JBoss Enterprise SOA Platform Component Versions

Component Version
JBoss EAP 5.0
JBoss ESB 4.7
JBoss Rules 5.0.1
JBoss jBPM 3.2.7.CR3
Apache jUDDI 3.0.1
PicketLink 1.0

4. 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/.

5. Documentation

The documentation for the JBoss Enterprise SOA Platform is available online at http://www.redhat.com/docs/en-US/JBoss_SOA_Platform and contains the following documents:
  • Release Notes
  • Getting Started Guide
  • ESB Administration Guide
  • ESB Programmer's Guide
  • ESB Services Guide
  • JBoss Rules 5 Reference Guide
  • jBPM Reference Guide
  • Smooks User Guide
Documentation for the JBoss Enterprise Application Platform (EAP) is available online at http://www.redhat.com/docs/en-US/JBoss_Enterprise_Application_Platform/.

7. 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/.

8. Issues resolved in the 5.0.1 release

The following issue has been resolved for the 5.0.1 release of the JBoss Enterprise SOA Platform:
https://jira.jboss.org/jira/browse/JBPAPP-3952
A security issue in the JMX Console configuration has been identified that allows an attacker to bypass security authentication.
The JMX Console configuration only specified an authentication requirement for requests that used the GET and POST HTTP "verbs". An attacker could create a HTTP request that did not specify GET or POST and it would be executed by the default GET handler without authentication. This release contains a JMX Console with an updated configuration that no longer specifies the HTTP verbs. This means that the authentication requirement is applied to all requests.
For additional information on this vulnerability refer to: http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2010-0738
All users are advised to upgrade to this release to resolve this issue.
If an immediate upgrade is not possible or the server deployment has been customized then the fix can be applied by editing the deployment descriptor (WEB-INF/web.xml) of the JMX Console WAR. Details of how to apply the fix can be found at http://kbase.redhat.com/faq/docs/DOC-30741. Customers are advised to contact Red Hat JBoss Support for advice before making these changes.
Red Hat would like to thank Stefano Di Paola and Giorgio Fedon of Minded Security for responsibly reporting the CVE-2010-0738 issue.

9. Known Issues in this release

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

9.1. JBoss Enterprise SOA Platform

https://jira.jboss.org/jira/browse/SOA-1825
Multiple warning messages are written to the server.log file when the Administration Console is started. It is safe to ignore these messages, some of which come from Seam classes, whilst others emanate from the console, indicating that the native component cannot be utilized to perform "discovery" operations.
https://jira.jboss.org/jira/browse/SOA-1673
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.
https://jira.jboss.org/jira/browse/SOA-1915
Do not use the CXF technical preview with this release of the JBoss Enterprise SOA Platform. There has been no verification that it works. This is a preview of technology that provides support for the Apache CXF Web Services Stack.
In addition, if this technical preview is installed over the JBoss Enterprise SOA Platform server installation, the only fallback is to remove the SOA Platform completely and reinstall it from scratch.
https://jira.jboss.org/jira/browse/JBPAPP-3618
The JBoss Native package for JBoss Enterprise Application Platform 5.0.0 is incompatible with the version of JBoss Web used in JBoss Enterprise SOA Platform 5.0.1. It will cause a JVM crash if used.

9.2. jBPM

https://jira.jboss.org/jira/browse/SOA-1596
The jBPM Console will throw an exception when used to view a running process instance if the process definition used <fork> with <state>, <task> or <node async="true">.
To workaround this issue:
  • Open the file jbpm-console.war/app/t_tokens.xhtml in an editor.
  • Find the XML element:
    <gd:sort source="#{token.availableTransitions}" target="#{transitions}" entryVar="e" 
        argument="#{e.name}"/>
  • Change the XML element to:
    <gd:sort if="#{!empty token.availableTransitions}" 
        source="#{token.availableTransitions}" target="#{transitions}" entryVar="e" 
        argument="#{e.name == null ? '' : e.name}"/>
After making this change, the exception will not occur. The change does not affect functionality.

9.3. JBoss Operations Network

https://jira.jboss.org/jira/browse/SOA-1916
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.
https://jira.jboss.org/jira/browse/JOPR-419
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 0.0.0.0 if this has not been specified. To ensure that JON recognizes the default profile and binds to the correct address of 127.0.0.1, always use the -c and -b parameters. By doing so, JON will recognize the platform.
https://jira.jboss.org/jira/browse/SOA-1656
The ability to set up a message's individual processing time in JON for alerts does not work by default.
To work around this problem, firstly add the alerting feature (alertTimeThreshold and alertLengthThreshold) to the ESB deployment.
Having done so, you must then set up alerts for events filtered from the server log. Do this using the JON GUI.
Another issue with JON event logging is that the alerts mechanism may be delayed in starting for an indefinite period of time (possibly between fifteen and fifty minutes in some cases.) Whilst this delay is occurring, all JON Alerts are lost and will never be seen. (However, WARN messages, emanating from the SOA Platform Server Console, will be displayed in the EVENTS view.)
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.

9.4. JBoss Enterprise Service Bus

https://jira.jboss.org/jira/browse/SOA-1600
jUDDI v3 uses Hibernate to create its database. This is different to the other ESB components, which use SQL scripts. This will be standardized in a future release.
https://jira.jboss.org/jira/browse/SOA-1875
When a new BusinessEntity with two names is published, the jUDDI Browser will display two businesses instead of one. This is because the user interface treats business names as strings and does not check them for uniqueness: the keys are the only unique identifiers.
https://jira.jboss.org/jira/browse/JBESB-3147
There is an inconsistency between the FTP Gateway Listener and the FTP Notifier. The FTP Gateway Listener can accept non-alpha numeric characters whilst the FTP Notifier cannot. In the latter case, fields must be URL encoded. For instance, a # character must be entered as %23 to work in the Notifier. If you enter an illegal character, the Notifier will not work.
https://jira.jboss.org/jira/browse/JBESB-3028
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.
https://jira.jboss.org/jira/browse/SOA-1660
When sending messages, the alerts will appear in the JMX Console. If you then log into the Administration Console, the java.lang.NullPointerException will appear once per minute. This exception only appears in the log; it is not visible in the JMX Console itself.
Note that you can use the JMX Console to display message alerts (jboss.esb:service=MessageAlerts). However, if the SOA Platform is monitored by JON or if the Administration Console has been accessed, message alerts will disappear when the Mbean view is refreshed because the MessageAlerts queue will be emptied.
https://jira.jboss.org/jira/browse/JBESB-3038
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.
https://jira.jboss.org/jira/browse/JBESB-3035
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.
https://jira.jboss.org/jira/browse/SOA-1564
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.
https://jira.jboss.org/jira/browse/JBESB-2442
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.
https://jira.jboss.org/jira/browse/JBESB-2085
The default configuration for the SOA Platform includes the setting java.awt.headless set to true. This is required for the embedded console to function. However both the groovy_gateway Quickstart and the Hypersonic database manager require that this value be set to false and therefore will not work. If you require either of these items you can change this setting in run.conf, but doing this will disable the embedded console.
https://jira.jboss.org/jira/browse/SOA-1562
Currently, a new DocumentBuilder is created for each incoming message. This has a minor impact upon system performance.

9.5. JBoss Rules and BRMS

https://jira.jboss.org/jira/browse/SOA-1874
The JBoss Enterprise SOA Platform 5.0.1 is not compatible with the JBoss Enterprise BRMS Platform 5.0.0. Use JBoss Enterprise BRMS Platform 5.0.1.
https://jira.jboss.org/jira/browse/SOA-1707
The BRP Rule Agent is designed to use a local cached copy of a rules package if the BRMS is offline. At the moment, when this happens, error messages are generated, which might confuse users. These messages can be ignored as the locally cached copy is, in fact, being used successfully.

9.6. JBoss Developer Studio

https://jira.jboss.org/jira/browse/JBIDE-5597
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.
https://jira.jboss.org/jira/browse/JBIDE-5596
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.
https://jira.jboss.org/jira/browse/JBIDE-5659
The ESB examples packaged with JBoss Developer Studio 3.0 do not work correctly with JBoss Enterprise SOA Platform 5.0.

10. Possible Issues Migrating to 5.0

Read this section to learn about the differences between JBoss Enterprise SOA Platform 5.0 and previous versions that may cause difficulties when moving your applications to version 5.0.
As a matter of best practice, Red Hat recommends that you test all of your existing applications on this new version of the JBoss Enterprise SOA Platform before deploying it in your production environment.
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
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 .