Java CAPS Tip : Configuring SJSAS For MSMQ XA Transactions

Following on from my MSMQ blog entry, "Reading MSMQ Messages with high TPS",  I was required to reproduce the scenario running in a SJSAS 8.2 Environment. Since this is not the standard Java CAPS 5.1.3 Runtime Application Server we need to configure is specifically to work with the appropriate queue systems. Although a number of documents exist informing you how to do this the key information does not exist at present in an online format. So I have decided to put this entry together based on a number of the engineering documents so that I can easily access the information when required.


Configuring SJSAS 8.2 U6 For Java CAPS 5.1.3

Because the original Java CAPS 5.1.3 Integration Server is based on the SJSAS 8.0 release moving your Java CAPS 5.1.3 application to SJSAS 8.2 is not to difficult. What we will need to do is add some extra configuration components that are automatically included in the standard Java CAPS Integration Server. This section takes you through a specific example that allows you to run the "Reading MSMQ Messages with high TPS" on a SJSAS 8.2 instance.

Server Policies

Before we can run the Java CAPS components on SJSAS the domains server.prolicy file must be modified to add the following:

grant {
// Java CAPS needs access to the class loader
permission java.lang.RuntimePermission "getClassLoader";
// Java CAPS needs custom classloaders in some cases
permission java.lang.RuntimePermission "createClassLoader";
// Java CAPS policy requirement
permission "setPolicy";
permission "getPolicy";
permission "getProperty.policy.url.\*";
permission "setProperty.policy.url.\*";
// Java CAPS for the SAP eway
permission java.lang.RuntimePermission "setContextClassLoader";
// Java CAPS uses the MBeanServer
permission "\*";
permission "\*", "\*";
permission "register";
// Java CAPS Log4J support (obsolete) (log4j file roll-over needs delete)
permission "<<ALL FILES>>", "delete";
// Java CAPS Odette eWay support requires execute permission
permission "<<ALL FILES>>", "execute";
// Java CAPS HTTP eWay
permission java.lang.RuntimePermission "setFactory";
// Java CAPS tcpip inbound eway added "accept,resolve" to SocketPermission
// Java CAPS BPEL debugger added "listen" to SocketPermission
permission "\*", "connect,listen,accept,resolve";
// Java CAPS needs these permissions so the Bouncy Castle provider can be used
permission "insertProvider.BC";
permission "removeProvider.BC";
permission "putProviderProperty.BC";
// Java CAPS needs this permission so the JMX remote connector can be used
permission "getSubject";
// Java CAPS: Hessian connector for JMX4J for EM; also for BPEL debugger
permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
// Java CAPS: for BPEL debugger
permission "enableSubstitution";
// Java CAPS: for EM to use SSL
permission "setHostnameVerifier";
permission "getSSLSessionContext";
permission java.util.logging.LoggingPermission "control";
permission java.util.PropertyPermission "\*", "read,write";

Connector Modules and Web Applications

In addition to modifying the server.policy file a number of Java CAPS components (rars, jars and wars) need to be installed into the Application Server and they can be obtained from the Respository downloads page.  Using the SJSAS Admin Console deploy the following:
  • Connector Modules
    • logging.rar
    • raunifiedjms.rar
  • Web Applications
    • SeeBeyondSunOneDeployer.war

You will need the the raunifiedjms.rar provided with the JMSJCA HotFix 2162933 or later.


You can configure the transaction service in the Application Server in the following ways:
  1. To configure the transaction service using the Administration Console, open the Transaction Service component under the relevant configuration. For details, see the Sun Java System Application Server Platform Edition 8.2 Administration Guide.
  2. To configure the transaction service, use the asadmin set command to set the following attributes:
    • server.transaction-service.automatic-recovery = true
    • server.transaction-service.heuristic-decision = rollback
    • server.transaction-service.keypoint-interval = 131072 (See Note 2)
    • server.transaction-service.retry-timeout-in-seconds = 600
    • server.transaction-service.timeout-in-seconds = 0
    • server.transaction-service.tx-log-dir = domain-dir/logs
    • You can also set these properties:
    • = false
    • = 600
    • = 3600 (See Note 2 and 3)
    • = false
You can use the asadmin get command to list all the transaction service attributes and properties. For details, see the Sun Java System Application Server Platform Edition 8.2 Reference Manual.

If all resources involved in a global transaction are XA, then you must set use-last-agent-optimization to false; To enable automatic recovery, you must set automatic-recovery to true; to enable automatic recovery on the fly, you must set pending-txn-cleanup-interval property to a positive value(in seconds); Otherwise, the Application Server will only initiate self recovery during startup.

If there was a resource that has failed and has left transactions in-doubt and the keypoint interval is passed and then the app server is restarted, then on restart the tx logs will have been pruned. At this point it is possible that a lost of any information about the transactions that were in-doubt at the time and thus causes the app server to roll them back.  If it was a message that was being placed onto a queue, at the time of the pruning of the tx logs and the restart, then this has the effect of losing the message. This is a corner case that has never been seen or reported on app server to date, but is a remote possibility. To reduce this possibility, our initial recommendation is the below:
  • Keypoint interval set to 131072
  • pending_txn_interval set to 3600
i.e. The app server only keypoints infrequently and the recovery happens every hour.

The app server only keeps the transaction records of last ‘keypoint-interval’ transactions. To avoid any transaction loss, tune the key point interval and pening_txn_interval so that the recovery takes place before the keypoint interval is reached.

Configuring Connection Pool

General properties for the Java Message Service (JMS) service apply only to the application server's default JMS provider, Sun Java System Message Queue. All other messaging providers that are plugged into the application server via resource adapters can be configured through the Connector Resources screens.

A Connector Resource used by SJSAS is a program object that provides an application with a connection to an enterprise information system (EIS). A Connector Resource that must use global resource adapter as explained below to enable recovery on start up. You have to configure the resource pools for all the external resources used in the application to enable app server transaction recovery.

To configure the connection to your JMS server you will need to log into the SJSAS admin Console and navigate to Common Tasks -> Resources -> Connectors -> Connector Connection Pools and Click New to create a New Connection Pool. The following are the required responses/properties for WMQ, STCMS and Sun JMQ.

Page 1
Name : WMQOutboundJMSPool
Resource Adapter: raunifiedjms
Name : STCMSOutboundJMSPool
Resource Adapter: raunifiedjms
Name : JMQOutboundJMSPool
Resource Adapter: raunifiedjms
Page 2
Connection Definition: javax.jms.QueueConnectionFactory or javax.jms.TopicConnectionFactory
Connection Definition: javax.jms.QueueConnectionFactory or javax.jms.TopicConnectionFactory Connection Definition: javax.jms.QueueConnectionFactory or javax.jms.TopicConnectionFactory
Page 3
Transaction Support: XA Transaction
Add Properties:

CLIENT Mode (Default)

ConnectionURL = <wmq://[hostname]:[port]?QueueManager=[QMname]>
UserName= <mquser>
Password= <mqpassword>

BINDING Mode (Default)

ConnectionURL = <wmq://[hostname]:[port]?QueueManager=[QMname]&TransportType=JMSC.MQJMS_TP_BINDINGS_MQ>
UserName= <mquser>
Password= <mqpassword>

Transaction Support: XA Transaction
Add Properties:

ConnectionURL = <stcms://[hostname]:[port]>
UserName= <stcmsuser>
Password= <stcmspassword>

Transaction Support: XA Transaction
Add Properties:

ConnectionURL = <mq://[hostname]:[port]>
UserName= <mquser>
Password= <mqpassword>

From the Admin Console create a Connector Resource (Common Tasks -> Resources -> Connectors -> Connector Resources) as dollows :
  • JNDI Name : WMQOutboundJMS | STCMSOutboundJMS | JMSOutboundJMS
  • Pool Name : WMQOutboundJMSPool | STCMSOutboundJMSPool | JMSOutboundJMSPool (From the Drop-down / names as above)
  • Targets : Select the domains, cluster or server instances where the connector will reside.

SJSAS Configurtion Options

JVM Option







This will mean that prior to handing a connection back to the application the application server will only validate it every n seconds.  (n being the idle timeout value for the pool.)
This will improve performance but may mean that the AS instance will hand back DB/JMS connections that are invalid for a period of time.



Setting it to true (the default) means that the application server will start up more quickly.  However, if certain services fail to startup due to a timeout or a config in the app server forcing it to use certain nio or socket libraries then setting this to false will enable the server to startup correctly. 

Transaction Service




Required as Oracle does not adhere to the XA specification so this flag is required to enable recovery to function correctly.




Changes the XAResource timeout. In some cases, the XAResource default timeout can cause transactions to be aborted, so it is desirable to change it.

600 is a starting value.

The timeout is usually set in such a way that the external resource time out is more than the application server time out, so that there is no chance for the external resource is already timed out before the app server commits/rollbacks the transaction.




If not all resources in a global transaction are XA compliant then setting this flag will mean that up to one non-XA resource can be involved in the global transaction.  I don't believe it is needed as all resources involved here are XA. 

The last agent optimization and file-based logging used in SunOne AS 8.1 cannot be used together.



Must be false or not set

The default is false so not setting it is OK.
If set to true then the app server will not log the status of the global transactions into the tx log file.  This gives a slight performance improvement but will result in all in-doubt transactions being rolled back, potentially
losing messages.




This flag will cause the app server to perform XA recovery every nnn seconds.  This will automate the recovery of in-doubt transactions so will assist in keeping the time by which the resources are out of sync/inconsistent to a minimum.  Starting value of 3600 means automatic recovery occurs every hour.

Building Java CAPS for SJSAS Deployment

You can build a CAPS project to be deployed to Sun Java System Application Server by using Sun SeeBeyond Enterprise Designer.

Build Steps

  1. Log in to Enterprise Designer.
  2. In the Project Explorer, create a Project.

  3. In the Environment Explorer, create an Environment.
  4. Right-click the Repository name and click New Environment.
  5. Right-click the Environment, point to New, and click Logical Host.
  6. Right-click the Logical Host, point to New, and click Sun Java System Application Server.

  7. Right-click the Sun Java System Application Server and click Properties.
  8. Set the Integration Server URL property to the URL that you set when you installed Sun Java Enterprise System (for example,
  9. Set the user name and password that you created when you installed Sun Java Enterprise System. Click OK.

  10. If the Project requires the use of a message server, you can add a Sun SeeBeyond JMS IQ Manager. For detailed information on how to configure the message server, see the Sun SeeBeyond eGate Integrator JMS Reference Guide.
  11. Click OK.

  12. In the Project Explorer, create a Deployment Profile.
  13. Click Automap to automatically map the components. You can also map the components manually.

  14. Click Build. A dialog box indicates that the project build was successful.
  15. Click OK.

  16. An EAR file appears in the Sun_JavaCAPS_install_dir\\edesigner\\builds directory (for example, C:\\JavaCAPS51\\edesigner\\builds\\Project1Deployment1\\LogicalHost1\\SunJavaSystemApplication Server1\\Project1Deployment1.ear).

    The EAR file is the application file, which you can deploy by using the Sun Java System Application Server Admin Console or Sun SeeBeyond Enterprise Manager.


Post a Comment:
Comments are closed for this entry.

As a member of the Oracle A-Team we specialise in enabling and supporting the Oracle Fusion Middleware communities.


« July 2016