Distributed transaction sample - part 4 (the final part) - the samples

This is the final part of the Distributed transactions sample log. It gives you the sample projects, some ideas on running the sample, and some hints on tracing what is happening exactly.

Enabling persistence in Java CAPS

Before we continue with the samples: To enable transactional behaviour in Java CAPS 6 BPEL, persistence must be enabled. How to enable BPEL persistence in Java CAPS 6 is described here.

The .NET sample project

You can download the .NET sample project here. Unzip the downloaded file to a convenient place.

In the service part of the .NET sample project, in the App.config file you will find the XML that configures the service. The WSDL produced for the service is directly dependent on the information in this config file. To find information about the various parts of the XML, you can start at Microsoft's .NET documentation for this subject. This documentation contains a full reference of all elements in the XML file.

The code for the sample service is found in file service.cs. The code is simple. As you will see, log messages are written to the command window where the service runs as soon as something arrives and is done. Stuff is also done in the Oracle database, so that transactional operation can be demonstrated.

The .NET sample project must be modified to fit your environment. Don't worry, the modifications are small and straightforward. To make the modifications start Visual C#, and open the .NET project in the location where you unzipped the downloaded file.

To change the port the sample service listens on (in the downloaded file it is port 9000), open App.config in the service part of the project. Perhaps you also want to change the host name (localhost in the downloaded file) to something else.

Another thing you will quite likely have to change, is the Oracle connectivity information (found on line 11 of the App.config file in the downloaded project). .NET uses sql*net, and therefore you will find a TNS name in App.config. You'll also find an Oracle user id and password. You must change these things to the values appropriate to connect to the Oracle database in your environment.

To build the service after making changes, right-click on service and select Rebuild.

To run the service in debug mode, right-click on service, select Debug, and then select Start new instance.

To run the service in non-debug mode go to the bin directory of the project and double-click sample-svc.exe. The messages appearing in the command window are the same when running in debug or non-debug mode.

To stop a running instance, press Enter when in the command window where the service runs.

Scripts to create, clear, and delete the user and table required by the sample in an Oracle database can be found in the file you can download here. This file can be unzipped at a convenient place. Quite likely you will need to make some (small) changes - such as the location of the datafile for the tablespace - before running the scripts.

Java CAPS sample project

The Java CAPS sample project (a NetBeans project) can be downloaded here. Unzip the downloaded file to a convenient location.

Start your Java CAPS GlassFish server and ensure that BPEL persistence is enabled (see earlier in this entry). Start NetBeans (the one that comes with Java CAPS 6), and open the downloaded projects. You will find several projects (refer to earlier episodes of this log for more information on how the project relate to each other):

• bp-transactional-bpmain: this is the main BPEL process, the one that calls the EJB web service proxy
• bp-transactional-bpproxy: this is the proxy BPEL process, used to ensure that bpMain runs in a transaction
• casa-transactional-bp-bp-ext-ejb: this is the composite application that contains bpProxy and bpMain and calls the EJB web service proxy as an external web service
• ejb-transactional-wsproxy: this is the EJB web service proxy. It accepts requests in SOAP 1.1 and calls the .NET service using SOAP 1.2
• ejb-transactional-wstest: this is a test EJB. It takes the same actions as the main BPEL process. This EJB can be invoked as a web service

To get going, you should try to get the ejb-transactional-wsproxy project working. This project can be called directly from SoapUI, because it has its own web service. To get started:

• ensure that the Oracle database is running
• ensure that the .NET service is running
• in NetBeans deploy the ejb-transactional-wsproxy project
• in SoapUI, create a new project from the WSDL created when ejb-transactional-wsproxy was deployed. By default you will find the WSDL at URL http://localhost:8080/wsProxyService/wsProxy?wsdl. If your Java CAPS GlassFish server listens on another port, you should use that port instead.
• in SoapUI you will now see the various operations provided by the wsProxy web service. You can fill in parameters for requests, invoke the requests, and see if the web service work

If you invoke requests and get good results back, the BPEL processes can be added. To add the BPEL processes:

• in NetBeans check the bpProxy endpoint in the CASA editor for the casa-transactional-bp-bp-ext-ejb project. If the port number specified in the endpoint for bpProxy is already in use change it to a port not in use at your system
• in NetBeans deploy the casa-transactional-bp-bp-ext-ejb project

To test the entire process with all components in place:

• In SoapUI create a new project from the WSDL created by deploying the composite application. By default you'll find the WSDL at URL http://localhost:23081/bpProxyService/bpProxyPort?wsdl. If you have another port specified in the endpoint in the CASA, use that port instead
• In SoapUI the operations with parameters will be present. Fill in parameters, issue requests, and see if it all works

Tracing and logging in MSDTC

When you are running tests to see if it all works, you may want to trace MSDTC and WS-AT.

This file contains some experimental scripts and other files to do this. Unzip the file to a convenient location. Some MSDTC and WS-AT scripts (from the downloaded zip file) and other stuff:

• script create-wsattrace-w.cmd: this sets up a trace logger for WS-AT. This script must be run once only
• script trace-msdtc.cmd: activates the trace and then pauses so you can run your test. When your test is done, press any key in the window where the script runs. The script will then stop the trace and deactivate the trace logger. The result of this trace is found in c:\logs\msdtc (if wanted, this location can, of course, be changed in the script). The traces created are stored in files with names like wsat-nnnnnn.etl files. These files can be opened by the Service Trace Viewer. This viewer is found at C:\Program Files\Microsoft SDKs\Windows\v6.1\Bin\SvcTraceViewer.exe (setting up a shortcut makes things easier). These files contain lots of information. If errors have occurred they are clearly shown in the System Trace Viewer. Those error entries can help to find out the reason why something does not work.
• script convert-dtc-log.cmd: read the dtctrace.log file produced by MSDTC and WS-AT tracing when enabled via MSDTC configuration (see the previous episode for how to configure MSDTC). The dtctrace.log files are found in C:\WINDOWS\system32\MsDtc\Trace.
  I have not found any useful information in this file up to now.
• The WsatTrace.etl file, found in C:\WINDOWS\system32\MsDtc\Trace, can be read by the Service Trace Viewer (see above). This file can contain useful information. Be sure to set the most extensive trace options in MSDTC and WS-AT configuration.
• Additionally, extra tracing can be obtained by doing the following:
• • open registry editor and navigate to
    Hkey_Local_Machine\SOFTWARE\Microsoft\WSAT\3.0\
  • Right-click value
    ServiceModelDiagnosticTracing
Or create this value if it doesn't exist (it is a DWORD value)
  • Change the value to
    31
(decimal) to get the most verbose tracing.
    

Tracing and logging in GlassFish

Of course you may also want to see some more details on what is going on at the GlassFish side. Here are some things you can do to get extra information:

• to get SSL handshake debugging information in GlassFish, add the following to domain.xml (add it where the other <jvm-options> are):
  <!-- Add for debugging ssl handshake -->
<jvm-options>-Djavax.net.debug=ssl,handshake,trustmanager</jvm-options>
• to see client/server messages after pipe processing add the following to domain.xml (add it where the other <jvm-options> are):
  <jvm-options>-Dcom.sun.xml.ws.assembler.server=true</jvm-options>
• to get more info on web services transaction processing:
• • in asadmin -> Application Server -> logging -> log levels, set:
    javax.enterprise.resource.webservices.jaxws.wstx FINEST (or FINE)

And, of course, you can add your own logging in the BPEL processes and EJBs. Some logging is already present in the sample projects.

Documentation starting point

For the JBI components in Java CAPS 6 you can find documentation on the OpenESB site.

A starting point for development information for .NET (the sample uses WCF, the Windows Communication Foundation) is found on the Microsoft MSDN site.

Finishing off

I am not a Microsoft .NET expert. The samples and remarks I make about .NET may not give the best way to do things in .NET. They worked for me when creating this example. If you know better ways of doing things in .NET, then, by all means, use them.

This concludes the Distributed transaction sample log.

I hope I did not forget too many things, and I hope this log will be useful to some.

Posted at 03:28PM Jan 09, 2009 by marjo in Distributed transaction  |  Comments[1]

Distributed transaction sample: part 3 - preparation

Preparing Oracle and Windows for the distributed transaction. There's also some talk about transaction coordinators in this entry.

note: The Java CAPS and EJB parts of the sample application run in Sun GlassFish Enterprise Server (which comes with Java CAPS 6). To save a lot of typing I'll refer to it as GlassFish. An open source version of GlassFish is also available, and the sample can be run with that server as well. The open source version of GlassFish is included in OpenESB. The sample presented here should also work with OpenESB, but I have not tested that.

SoapUI

In the previous entry, about software installation and such, I forgot to mention installation of SoapUI. SoapUI is a tool that can be used to initiate web services. It can be downloaded here. On my system I have installed version 2.0.2.

SoapUI comes as a stand-alone application (that's the version I use), and as a plug-in for various environments. As Java CAPS 6 comes with NetBeans, you can install the NetBeans plug-in if you want to. For the stand-alone version, download the installer, and run it.

Oracle database

The Oracle database on my system is running with instance name oradb. The database runs on the local system (localhost) on the default Oracle port (1521. The table needed for the sample is stored in schema log (Oracle user log). If you want to use another instance name, another user, or run with an Oracle database on another system or on another port, you will have to change the WCF service. If you set up your database with the same properties, you can use the provided WCF sample without change.

One simple table is needed in the Oracle database. In the zip file found here you will find database scripts to create the log user (with password log) and its table, to clear the table, and to remove the user and its table. Please note that you must edit the creation script to provide the correct location for the location of the file containing the Oracle tablespace for the log user. Of course you can also change other things in the script, such as the user name and password. If you do make such changes, you must alter the WCF service application to reflect those.

The scripts can be executed with the Oracle SQL Developer tool, installed as part of the Oracle client (see the previous log entry for more on installing Oracle).

Transaction Coordinators

The example distributed transaction demonstrates a transaction where the activities are operations invoked via web services. Transactional behaviour in this sort of system uses the WS-AtomicTransaction (WS-AT) coordination type. In this sample, web services run in several different software environments. Each of those environments has its own transaction coordinator as shown in the picture below:

When bpProxy invokes bpMain, it will first register a new transaction with its transaction coordinator (TC). bpProxy runs in GlassFish, so the main TC for this transaction is the GlassFish one. bpMain is an atomic BPEL process. That means that when bpMain starts, it enlists in (joins) the existing transaction. It becomes part of that transaction. bpMain invokes several operations in ejbProxy. Operations in ejbProxy are specified to require an existing transaction, and therefore each of these operations also enlists in the existing transaction. Because up to now all activities took place in the GlassFish application server, the GlassFish TC is used by all these activities.

ejbProxy invokes operations on the WCF service. Each of these operations enlists in the existing transaction. However, this time a different TC, MSDTC (Microsoft Distributed Transaction Coordinator) is used. When an operation is invoked on the WCF service, MSDTC detects that a transaction is already active. In the WCF application the operations are specified as requiring an existing transaction. MSDTC communicates with the GlassFish TC, and together the coordinators ensure that the distributed transaction is dealt with in the proper way, with the GlassFish TC as the main TC. If the transaction would have been started by a WCF component, MSDTC would be the main TC.

The WCF service invokes Oracle. The Oracle activities participate in the existing transaction. Because the Oracle Data Access Components were installed, as mentioned in the previous entry, Oracle uses MSDTC to participate in the existing transaction.

When the last request has been processed by bpMain, control returns to bpProxy. The transaction is ended. Depending on previous events, the transaction is either committed (made permanent) or rolled back. The main TC (the GlassFish one in this case) would communicate to all participating TCs to ensure that all activities that have been executed in the transaction are committed or rolled back.

If bpProxy, bpMain, and ejbProxy would run in several GlassFish application servers, each would have registered with its own GlassFish TC. If other systems and environments would participate in the transaction, their TCs would be used (of course only systems that adhere to WS-AT can participate). The TC where the transaction was started would become the main TC. No matter how many TCs are involved, they would communicate to ensure proper management of the distributed transaction.

Certificates

Transaction coordinators need secure communication to ensure that no illegal parties get unrightfully involved in a transaction. To facilitate this, they use SSL as their communication protocol. Each TC authenticates the one(s) it communicates with by X.509 certificates.

To make this authentication possible, the public keys of the TCs must be present in the keystore of their counterparts. In our case we have two TCs. The GlassFish TC needs the public key of the MSDTC, and MSDTC needs the public key of the GlassFish TC. Each environment also has its own private key. During the SSL protocol certificates are exchanged and authenticated. The TCs use mutual authentication. When SSL keys are exchanged, public keys are used to encrypt data. The private key matching the public one is the only key that can be used to decrypt the data encrypted by using the public key. A simplified picture of the use of certificates (see the SSL protocol for how it really works):

The keys for GlassFish where created automatically when the domain was created during Java CAPS installation. For MSDTC the key must be created. Creating keys in Windows is done with the makecert command. A complete key consists of a private key and a public one. The private key must not be shared with other parties.

In certificate systems, a certificate must be authorised by a trusted certificate. These trusted certificates are called Certificate Authorities (CA). In our sample system we do not have an external CA. We can work in two ways: we can create one certificate that can then must be stored in both the CA keystore and the certificates keystore. Or we can create an authoritative certificate for our own little sample world, and sign the other certificate(s) we create with this CA certificate. Now the authoritative certificate should be stored in the CA keystore. When that is done, all certificates signed with the authoritative certificate will automatically be trusted. In this example, we will use the second method.

Please note that the commands in the procedure below may not always fit on one line. Please ensure that you issue the complete command, ignoring any line breaks.

• open a command Window
• navigate to the directory where you want to store your certificate files (preferably an empty directory)
• to save ourselves a lot of typing, let's set the location of the Windows SDK binary directory in an environment variable:
  set EXEC_DIR="C:\Program Files\Microsoft SDKs\Windows\v6.1\Bin"
• to create the authoritative certificate issue the following command:
  %EXEC_DIR%\makecert TempCA.cer -sv TempCA.pvk -a sha1 -n "CN=TempCA" -r -sky signature -pe -len 2048 -sr CurrentUser -ss My
• to create a certificate for msdtc, signed with the certificate created before issue command:
  %EXEC_DIR%\makecert.exe msdtc-ssl.cer -sv msdtc-ssl.pvk -a sha1 -n "CN=statler.muppets.local" -ic TempCA.cer -iv TempCA.pvk -sky exchange -pe -len 2048 -sr CurrentUser -ss My
  note: it is important to replace "statler.muppets.local" with the fully qualified domain name of he machine where your WCF service runs, because during the SSL handshake the FQDN of the machine sending the certificate and the CN in the certificate are compared, and the connection fails if they are not
• to package the msdtc certificate with its private key in a .pfx file (needed later) issue command:
  %EXEC_DIR%\pvk2pfx.exe -pvk msdtc-ssl.pvk -spc msdtc-ssl.cer -pfx msdtc-ssl.pfx -po changeit
  note: the password for the pfx file created will be "changeit"

The certificate for the GlassFish domain will also be needed in later steps. Portecle is used to export the certificate.

• start Portecle
• open the keystore for the GlassFish domain created when installing Java CAPS 6. The keystore and cacert files are found in the config directory for the domain (for example c:\jcaps6\appserver\domains\domain1\config)
  note: Portecle will prompt for the keystore password. The default password for the keystore is "changeit" (if you changed it during installation of Java CAPS 6, type your password instead of "changeit")
• right-click on the s1as certificate
• select export from the popup menu
• leave the dialog that appears unchanged, and click the OK button
• name the export file s1as.cer
• click the Export button to save the certificate in a convenient location (possibly the location where you created the msdtc certificates)

This looks like:

Now all certificates needed are stored in .cer files.

In GlassFish the MSDTC certificate (public key) is needed, and MSDTC needs GlassFish's public key and the key we created for MSDTC before (its private key).

While still in Portecle, we can import the msdtc-ssl certificate in the GlassFish keystore and cacerts files.

• open the keystore.jks file
• on the menu select Tools->Import Trusted Certificate...
• select the msdtc-ssl.cer file created earlier
• open the cacerts.jks file
• on the menu select Tools->Import Trusted Certificate...
• select the msdtc-ssl.cer file created earlier

The MSDTC certificate is now imported in the GlassFish keystore and root certificates file, ready for use by SSL.

To store the GlassFish public key and the MSDTC private key in MSDTC's keystore do the following:

• open the Certificates mmc snap-in (described in the previous entry)
• navigate to Certificates (Local Computer)\Trusted Root Certificate Authorities\Certificates
• right-click on Certificates (in the tree on the left) and select All Tasks -> Import...
• in the wizard that appears click Next
• click the Browse... button
• browse to the s1as.cer file exported before from GlassFish (using Portecle) and select that file
• click Next in the Certificate Import Wizard dialog
• without changing the options click Next again
• now click Finish
• click OK in the notification that the import is done
• right-click the newly added certificate. The name of the certificate will be the FQDN of your machine ("statler.muppets.com" in my case)
• select Properties
• set the Friendly Name to "s1as", type a description if you want to, and click OK
  note: this is an important step, because all certificates will be listed with the FQDN found in the certificate. If you don't change the friendly name, you'll not be able to tell the various certificates apart in several configuration tasks that follow
• repeat this procedure (from All Tasks -> Import...)
• this time select the TempCA.cer file, created earlier
• set the friendly name to "Temporary Certificate Authority"

This looks like this:

Setting the friendly name (and possibly the description) in the properties:

The Root Certificate Authorities are now imported and available to Windows. Now the certificates themselves must be imported. To import the GlassFish certificate, continue where we were before the pictures, and:

• navigate to Certificates (Local Computer)\Personal\Certificates
• right-click on Certificates (in the tree on the left) and select All Tasks -> Import...
• in the wizard that appears click Next
• click the Browse... button
• browse to the s1as.cer file exported before from GlassFish (using Portecle) and select that file
• click Next in the Certificate Import Wizard dialog
• without changing the options click Next again
• now click Finish
• click OK in the notification that the import is done

To import the MSDTC private key do the following (it s similar, but not exactly the same):

• right-click on Certificates (in the tree on the left) and select All Tasks -> Import...
• in the wizard that appears click Next
• click the Browse... button
• change "Files of type" to "Personal Information Exchange (*.pfx;*.p12)
• browse to the msdtc-ssl.pfx file created before and select that file
• click Next in the Certificate Import Wizard dialog
• type the password for the msdtc-ssl.pfx file ("changeit" if you did not change it), and check "Mark this key as exportable" (this last option is just for convenience) and click Next
• without changing the options click Next again
• now click Finish
• click OK in the notification that the import is done

All the necessary certificates are now available for MSDTC. Now MSDTC must be configured to use its certificate, and to allow GlassFish as its counterpart.

MSDTC configuration

To configure MSDTC, do the following:

• go to Start->Programs->Administrative Tools->Component Services (if you don't have Administrative Tools in Programs, you can enable it by right-clicking on the task bar and then customising the task bar)
• click on Component Services. A sub-entry called Computers will appear
• expand the Computers entry
• right-click on Computer and select Properties...
• in the window that appears, select the MSDTC tab
• click the Security Configuration... button
• in the window that comes up enable all check boxes (you can leave the Allow Remote Administration box unchecked if you want to)
• click OK
• if a message box appears that asks if it is OK to stop and restart the MS DTC service, click Yes
• select the WS-AT tab
• check the Enable WS-Atomic Transaction network support check box
• select a port that is not in use by other processes on your system (on my system I use 8001)
• click the Select... button for Endpoint certificate to select the endpoint certificate to use by MSDTC
• in the list of certificates, select the msdtc-ssl certificate (this is where the friendly name comes in handy! If you had not set the friendly name, you wouldn't be able to tell which if the certificates to select)
• click OK
• click the Select... button for Authorized certificates to select which certificates MSDTC will accept
• ensure that the s1as certificate is authorised (in the picture you will see all certificates authorised). Certificates are authorised by checking the check box in front of them. Friendly names allow you to distinguish the certificates.
• click OK
• if a message box appears that asks if it is OK to stop and restart the MS DTC service, click Yes
• click OK again
• if a message box appears that asks if it is OK to stop and restart the MS DTC service, click Yes

The windows described above look like this:

MS DTC is now configured, and ready to participate in our transactions.

Posted at 01:21PM Jan 05, 2009 by marjo in Distributed transaction  |  Comments[0]