Using Java CAPS Java CAPS Field Technical Tips

“Progress” notwithstanding, Healthcare environments still extensively use the HL7 v2.x Delimited messages for conveyance of patient and patient-related information between applications. The GlassFish ESB provides support for HL7 v2.x messaging in the form of the HL7 Encoder, which allows conversion between HL7 v2 Delimited and HL7 v2 XML message formats, and in the form of the HL7 Binding Component, which allow connectivity between the GlassFish ESB-based healthcare solutions and healthcare applications that support HL7 over TCP connectivity.

In this document I will walk through the process of generating HL7 v2.3.1 delimited messages from pipe-delimited records containing patient information, sending and receiving HL7 v2.3.1 delimited messages using the HL7 Binding Component, parsing HL7 v2.3.1 delimited messages and writing HL7 v2 delimited messages to a file. To create and process HL7 messages I show how create a custom ADT A04 XML Schema and a custom “any HL7 v2 message” XML Schema. This gives me an opportunity to use the File Binding Component (File BC), the HL7 BC, the HL7 Encoder, the Custom Encoder and the BPEL Service Engine (BPEL SE). This also gives me an opportunity to demonstrate a HL7 v2.3.1 delimited message sender solution and to demonstrate a HL7 v2.3.1 delimited message receiver solution. At the end of the process we will have a file containing HL7 v2 delimited ADT A04 messages, which we will use in related writeups. 

Here is the document: 02_PatientSvc_MakeHL7v2DelimDataFromCustomDelimRecords_0.4.pdf

Here is the companion archive containing input files, the output file and the projects: 02_PatientSvc_MakeHL7v2DelimDataFromCustomDelimRecords_0.3.zip

The writeup document has been updated and version changed to 0.4.

This Quick Note discusses a simple solution to the use case provided by Leonard Barkley. The question goes like this:

“I dont have any idea how to implement BPEL process but the BPEL deployed as a subscriber of a topic. usually I implement the BPEL process and deployed it as web service.”

We produce a simple GlassFish ESB v2.1-based solution which reads a file, sends its content to a JMS Topic and another simple GlassFish ESB v2.1-based solution which subscribes to the same JMS Topic, receives the message and writes it to a file. Both solutions will use BPEL to implement the simple logic, though it is possible to implement both solutions without BPEL, so we have File BC -> BPEL SE -> JMS BC -> JMS Provider (Topic) -> JMS BC -> BPEL SE -> File BC.

Here is the note: QuickNote003_forLeonardBarkley.pdf

Hire is an archive with the project group containing all the projects developed in the Note: JMSTopicSampleProjGrp.zip

As Leonard Barkley pointed out to me, having implemented the sample, the Note is incorrect on Pages 23 and 24. The JMSSubscriber_JMSIn WSDL should use the Receive type, not Send type as the docuent states. The solution still works, it appears, but the configuration as documented is confusing. Thanks Leonard.

The Portlet developed in the previous blog gives plain facility details. A richer Portlet could use the facility address to show the facility location on a Map.

Here I will walk through development of a Visual Web JSF Mashup Portlet, which will use a Web Service as a data provider to get facility details and a Google Maps REST Service to get the Google map displaying facility location. I use the NetBeans 6.5.1 IDE, part of the GlassFish ESB v2.1 installation, the Portal Pack 3.0.1 NetBeans Plugin and the JSF Portal Bridge provided by the Web Space Server 10. The Portlet will use JSF components provided by Project Woodstock. The Google Map service is integrated into NetBeans IDE. Technologies will be introduced in a practical manner.

It took me some effort to work out how to add a Google Map to a Portlet so I though I will share the experience.

This is not a tutorial on JavaServer Faces, Visual Web JSF, Project Woodstock, Portlet development or Google Maps usage.

Here is the document: 01_FacilityService_WebSpacePortletWithGoogleMap.pdf

Here is an archive containing all the projects developed in this and the last 3 blog entries: 01_FacilityService_all_project.zip

As provided, the ui_facility table has a bunch of addresses which are fairly silly and will never get a proper map. This MySQL script has a bunch of SQL update statements to replace these addresses with real addresses that are mappable.

In some views SOA is represented as a series of 4 layers: Presentation Layer (SOA 1), Business Process Layer (SOA 2), Business Service Layer (SOA 3) and Technical Layer (SOA 4). Typically each layer higher up in the hierarchy consumes services exposed by the layer under it. So the Presentation Layer would consume services provided by the Business Process or Business Service Layers. Service interfaces are described using Web Services Description Language (WSDL), sheltering service consumers from details of service implementation. Web Services are seen as the technical means to implement the decoupled functional layers in a SOA development. Decoupling allows implementations of business functionality at different layers to be swapped in and out without disturbing other layers in the stack. The SOA 1, Presentation Layer, is often implemented as JSR-168-compliant or JSR-286-complaint Portlets, exposed through a standards-based Portal.

The business idea is that patients are looked after in various healthcare facilities. Applications need to allow selection of a facility and to access facility details for display to human operators. A relational holds details of facilities which are a part of the healthcare enterprise. Facility list and details are available through a web service. This web service will be used to construct the JSR-286-comliant Portlet that provides a user view into the facilities and facility details. This Portlet will be deployed to the Sun FOSS Web Space Server 10 Portal.

Previous documents in this series, “GlassFish ESB v 2.1   Creating a Healthcare Facility Web Service Provider”, at http://blogs.sun.com/javacapsfieldtech/entry/glassfish_esb_v_2_1 and “NetBeans 6.5.1 and GlassFish v 2.1 - Creating a Healthcare Facility Visual Web Application”, http://blogs.sun.com/javacapsfieldtech/entry/netbeans_6_5_1_and, walked the reader through the process of implementing a GlassFish ESB v2.1-based web service which returns facility list and facility details, and a Visual Web JSF Web Application which used that Web Service to display facility list and details.
In this document I will walk through the process of developing a JSR-286-compliant Visual Web JSF Portlet, deployed to the Sun Web Space Server 10 Portal, which will use the Web Service as a data provider. We will use the NetBeans 6.5.1 IDE, which comes as part of the GlassFish ESB v2.1 installation, the Portal Pack 3.0.1 NetBeans Plugin and the JSF Portal Bridge infrastructure provided by the Web Space Server 10. The Portlet will be implemented as a Visual Web JavaServer Faces Portlet using JSF components provided by Project Woodstock. The Portlet will introduce the technology in a practical manner and show how a web service can be used as a data provider, decoupling the web application from the data stores and specifics of data provision.

Note that this document is not a tutorial on JavaServer Faces, Visual Web JSF, Project Woodstock components or Portlet development. Note also that all the components and technologies used are either distributed as part of the NetBeans 6.5, as part of the GalssFish ESB v2.1, as part of the Web Space Server 10 or are readily pluggable into the NetBeans IDE. All are free and open source.

Here is teh document: 01_FacilityService_WebSpacePortlet.pdf

In some views SOA is represented as a series of 4 layers: Presentation Layer (SOA 1), Business Process Layer (SOA 2), Business Service Layer (SOA 3) and Technical Layer (SOA 4). Typically each layer higher up in the hierarchy consumes services exposed by the layer under it. So the Presentation Layer would consume services provided by the Business Process or Business Service Layers. Service interfaces are described using Web Services Description Language (WSDL), sheltering service consumers from details of service implementation. Web Services are seen as the technical means to implement the decoupled functional layers in a SOA development. Decoupling allows implementations of business functionality at different layers to be swapped in and out without disturbing other layers in the stack.

The business idea is that patients are looked after in various healthcare facilities. Frequently applications need to allow selection of a facility and to access facility details for display to human operators. A relational database is used to hold the details of facilities which are a part of the healthcare enterprise. To shelter application developers from the details of the data store facility list and details are made available as a multi-operation web service. This web service will be used to construct the web application that provides a user view into the facilities and facility details.

The previous document in this series, “GlassFish ESB v 2.1   Creating a Healthcare Facility Web Service Provider”, at http://blogs.sun.com/javacapsfieldtech/entry/glassfish_esb_v_2_1, walked the reader through the process of implementing a GlassFish ESB v2.1-based, multi-operation web service which returns facility list and facility details. In this document I will walk through the process of developing a Visual Web Application which will use the Web Service as a data provider. We will use the NetBeans 6.5.1 IDE, which comes as part of the GlassFish ESB v2.1 installation. The application will be implemented as a Visual Web JavaServer Faces Application using JSF component provided by Project Woodstock. This application will introduce the technology in a practical manner and show how a multi-operation web service can be used as a data provider, decoupling the web application from the data stores and specifics of data provision.

Note that this document is not a tutorial on JavaServer Faces, Visual Web JSF, Project Woodstock components or Web Application development. Note also that all the components and technologies used are either distributed as part of the NetBeans 6.5, as part of the GalssFish ESB v2.1 or are readily pluggable into the NetBeans IDE. All are free and open source.

It is assumed that a GlassFish ESB v2.1-based infrastructure, supplemented by the Sun WebSpace Server 10 Portal functionality and a MySQL RDBMS instance, are available for development and deployment of the web application discussed in this paper. It is further assumed that the web service, developed using instructions in “GlassFish ESB v 2.1 - Creating a Healthcare Facility Web Service Provider”, at http://blogs.sun.com/javacapsfieldtech/entry/glassfish_esb_v_2_1, is available and deployed to the infrastructure. The instructions necessary to install this infrastructure are discussed in the blog entry “Adding Sun WebSpace Server 10 Portal Server functionality to the GlassFish ESB v2.1 Installation” at http://blogs.sun.com/javacapsfieldtech/entry/adding_sun_webspace_server_10, supplemented by the material in blog entry “Making Web Space Server And Web Services Play Nicely In A Single Instance Of The Glassfish Application Server”, at http://blogs.sun.com/javacapsfieldtech/entry/making_web_space_server_and.

Here is the document - 01_FacilityService_WebApplication.pdf

In some views SOA is represented as a series of 4 layers: Presentation Layer (SOA 1), Business Process Layer (SOA 2), Business Service Layer (SOA 3) and Technical Layer (SOA 4). Typically each layer higher up in the hierarchy consumes services exposed by the layer under it. So the Presentation Layer would consume services provided by the Business Process or Business Service Layers. Service interfaces are described using Web Services Description Language (WSDL), sheltering service consumers from details of service implementation. Web Services are seen as the technical means to implement the decoupled functional layers in a SOA development. Decoupling allows implementations of business functionality at different layers to be swapped in and out without disturbing other layers in the stack.
In this document I will walk through the process of developing a SOA Composite Application, exposed as a Web Service, which will make available simple business functionality using a multi-operation service. We will use the GalssFish ESB v2.1 infrastructure. The service will use the SOAP/HTTP Binding Component, the Database Binding Component and the BPEL 2.0 Service Engine. This simple service will introduce the components and discuss how a multi-operation web service can be constructed using the GalssFish ESB.
The business idea is that patients are looked after in various healthcare facilities. Frequently applications need to allow selection of a facility and to access facility details for display to human operators. A relational database is used to hold the details of facilities which are a part of the healthcare enterprise. To shelter application developers from the details of the data store facility list and details will be made available as a multi-operation web service. This web service will be used elsewhere to construct a portlet that can be used in an enterprise portal.

The document is available as 01_FacilityService_GFESBv21.pdf

Late breaking news: The MySQL JDBC Driver, which I used in the example, mysql-connector-java-5.1.7-bin.jar, and which is distributed with the GlassFish ESB v2.1, causes connection pool exhaustion and other issues with the example. If you experience these issues pleases download the latest MySQL JDBC Driver, mysql-connector-java-5.1.7-bin.jar as at now, from http://dev.mysql.com/downloads/connector/j/5.1.html and replace the original in domains/domain1/lib/ext.

It is likely that, at some point or another, a SOA-based solution will require a graphical user interface. In a typical 4 layer SOA stack SOA 1, the Presentation Layer, is delivered as a series of Web Applications, by preferences through a Portal-based solution. Sun Web Space Server 10 is a Free and Open Source Portal solution that can be readily integrated into a SOA infrastructure, for example one based on the GlassFish ESB v2.1 – the Free and Open Source ESB. How Web Space Server can be added to the GlassFosh ESB v2.1 infrastructure is discussed in the blog entry “Adding Sun WebSpace Server 10 Portal Server functionality to the GlassFish ESB v2.1 Installation”, at http://blogs.sun.com/javacapsfieldtech/entry/adding_sun_webspace_server_10. Web Space Server takes over the web container, in a manner of speaking, causing all web references to be redirected through to the portal infrastructure. This makes it impossible to interact with web services deployed to the instance of GlassFish. Web Services and Web Space Server do not play nicely together when installed in the manner discussed in the Blog.

This document provides instructions which will allow Web Services and Web Space Server to play nicely in the same instance of GlassFish by changing the servlet context which the Web Space Server manages from / to a different one. This will allow all other servlet contexts to be treated qas though the Web Space Server was not installed and will allow the two sets of functionality to coexist.

The credit for this solution goes to users@webspace.dev.java.net, in particular Srikanth Konjarla, Deepak Gothe and Allan Foster.

 Here is the document, MakingWebSpaceServerAndWebServicesPlayNicely.pdf.

The GlassFish ESB Suite can be used to develop and deploy Composite Applications, a cornerstone of SOA. It has the integration, connectivity and management functionality necessary to develop artifacts in the lower 3 of the 4 SOA Layers. To complete the stack, and provide artifacts in the SOA 1 (Presentation Layer) requires additional technologies. One assumes that a web-based user interface is what one would choose to develop a presentation layer of the composite application. One assumes further that the Composite Applications with the Web-based User Interface will be exposed through a standards-compliant Portal infrastructure as standards-compliant portlets, rather then stand-alone web applications.

This document walks through the process of installing the Sun WebSpace Server 10 Portal to the GlassFish ESB v2.1 installation and addition of Portal Pack tooling to the NetBeans 6.5 tooling packaged with the GalssFish ESB v2.1.

Adding_WebSpaceSewrver10_to_GlassFishESB_v2.1.pdf

Just now I had an occasion to work with an integration solution intended to process lots of records. By lots I mean over 1 million smallish records. My customary platform to experiment on is Windows XP. Lots of reasons for that, most of them historical – I have tools I know and like and so on. While trying to work with such a volume of data I noticed a number of “interesting” things, which I thought I should share. These things are related to both the platforms (Windows vs. Linux), the tools and the architectural decisions.

I needed lots off data to test the solution I was contemplating, which involved XML processing, to see how constructing and parsing XML affects solution performance. To make it easier to compare timing differences I though I should use lots of records.

The discoveries are discussed in Right tools for the job.pdf.

Occasionally one needs to pick up and process a large number of files, on the order of hundreds or thousands. With the Batch Inbound eWay/JCA Adapter it is not possible to pick up more then one file per poll. The Batch Local File, if triggered by some event other then an appearance of a file in a directory, perhaps a Scheduler trigger of a manual trigger, with correctly designed logic can process many files in a single invocation.

The document, ProcessingHundredsOfFileWithBatchAdapter.pdf, discusses how Batch Local File-based solution can be constructed to effectively process hundreds of files in a single pass.

Every now and then one needs to secure communications between parties. Some would say it is necessary to do that all the time and perhaps it is. The issues are the complexity and expense. The complexity comes from having to configure a bunch of tools to support things like encryption and digital signatures for more then a single party. The expense comes from typically having to purchase cryptographic instruments from well known Certification Authorities, and keep on purchasing them all over again every 1 or 2 years. This discussion introduces a class library that offers a set of simple methods for constructing and sending secure electronic mail using the Secure Multipurpose Internet Mail Extensions (S/MIME), the Bounce Castle Cryptographic Libraries and the Java programming language. The intent is to allow a Java CAPS developer, or a Java developer, to add Secure Electronic Mail functionality quickly and easily, and without having to make too much of a time investment learning about PKI-based security and related matters. This addresses the complexity issue. The expense issue is addressed in my Blog Entry, “Producing Free, Private X.509 Certificates for use with PKI-based Solutions”, at http://blogs.sun.com/javacapsfieldtech/entry/producing_free_private_x_509. That blog discusses how to roll out a private Certification Authority and obtain X.509 Certificates., and other cryptographic objects, for free.

This document discusses the use of cryptographic software and manipulation of cryptographic objects. Using or discussing cryptography software is illegal in some parts of the world. It is you responsibility to ensure that you comply with any import/export and use laws that apply to you.

SendingSecureEMailUsingJavaCAPS.pdf

When working with PKI-based security solutions one typically requires one or more X.509 Certificates and related private keys. X.509 Certificates are typically purchased from well known Certification Authorities, such Verisign, for a fair amount of money and are valid for 1 or 2 years. It is not perhaps widely known that one can create a perfectly functional X.509 Certificate and use it in PKI-based solutions by oneself, free of charge and valid for an arbitrary amount of time. While tools are available to both generate key pairs and create X.509 Certificates, the how of it is somewhat obscure.  This document discusses the use of the OpenSSL software in creation of private PKI objects such as Key Pairs and X.509 Certificates and PKCS#12 Keystores. It discusses the use of Windows-based scripts, developed by the author, that make the process painless and quick.

This document discusses the use of cryptographic software and manipulation of cryptographic objects.  Using or discussing cryptography software is illegal in some parts of the world. It is you responsibility to ensure that you comply with any import/export and use laws that apply to you.

SettingUpCryptoToolsAndObjects.pdf

Java CAPS 5.x came with its own, built-in version control system, which many people liked and many despised. Java CAPS 6 Repository still has that version control system. Unlike the repository-based components standard NetBeans components, EJBs, and the JBI-based components, developed through the OpenESB Project and supported, for a fee, in the GlassFishESB product, must use an external version control system, if they are to be placed under version control.

This note discusses how a Subversion VCS can be installed on a Windows platform and used to provide version control for non-Repository components in Java CAPS 6 product and for projects in the GlassFishESB product and OpenESB project.

Clearly, non-Windows platforms can be similarly configured to support Subversion.

This Note, http://mediacast.sun.com/users/Michael.Czapski-Sun/media/Subversion_with_OpenESB_GlassFishESB_or_JavaCAPS6/details, is a step-by-step guide to getting Subversion installed and configured to work with NetBeans 6.1. It is not a tutorial on version control.

This Quick Note discusses a solution to the use case provided by Marcus Davies.

I am trying to read HL7 from JMS (preferably stcms) and populate an outbound XML data structure (different to the XML generated by the decoder).
I have been thinking of doing one of the following […]:
1.    Use a Concrete JMS WS using the HL7 encoders to unmarshal the HL7 and use JAXB to populate the outbound XML.  Unfortunately this does not appear to connect to the stcms queue as I can not see any receivers
2.    Use a JCA MDB to read from the stcms JMS queue - this works but I don’t think I can use the HL7 encoder like this
3.    Use and MDB to read from JMS, manually unmarshal the HL7 and use JAXB to populate the data structure
Ideally I would like to use the HL7 encoders.  Do you think the first approach should work?

Number 1 will not work as at end of February 2009 because the JMS BC does not properly decode the HL7 delimited message. This is a know issue. I don't know what the status of this is. The only BCs that know how to deal with HL7 delimited, that I know of, are the File BC and the HL7 BC.

Number 2 should work. I did not personally try it. You can invoke an encoder library from Java. Have a look at http://wiki.open-esb.java.net/Wiki.jsp?page=UseEncodersInJavaSE.

Number 3 should work but it will be very laborious.

I have a Number 4, which uses a HL7 OTD and a custom XSD-based OTD in a JCA EJB. You may or may not like it but it’s the best thing to do if you can not use BPEL 2.0 to do the mapping and you don’t want to build a repository-based solution (which would be the best for your case anyway).

The solution involves the use of:
1.    HL7 2.3.1 OTD Library (Java CAPS 6 Repository)
2.    JMS JCA to trigger a MDB with a HL7 Delimited message
3.    JMS JCA to write result message out
4.    JCA MDB to do the processing
5.    OTDImporter to provide HL7 2.3.1 OTD and custom XSD-based OTD to the EJB for “convenient” mapping

Brief steps to implement this solution are given in Quick Note 002 at http://mediacast.sun.com/users/Michael.Czapski-Sun/media/QuiclNote002_For_Marcus_Davies.pdf/details. Archive containing project exports and sample data is provided at http://mediacast.sun.com/users/Michael.Czapski-Sun/media/QuickNote002.zip/details. The code will work in Java CAPS 6 Update 1.

This Quick Note discusses a solution to the use case provided by Richard Kuiter.

An input file contains the following records:

H100000000000014099120ASN00507  
L1140991200000008261850826185738
L1140991200000008261850826185738
L1140991200000008261850826185738
L1140991200000008261850826185738
L1140991200000008261850826185738
L1140991200000008261850826185738
H100000000000014099126ASN00531  
L1140991260000008262690826269662
L1140991260000008262690826269662
L1140991260000008262690826269662
L1140991260000008262690826269662
L1140991260000008262690826269662

It is required that each block of records starting with the H1 (header) record and containing all the following L1 (line) records, be written to a different file.

The solution involves the use of:
1.    Batch Inbound eWay to locate the input file and provide its name and location to a Java Collaboration Definition
2.    Batch Local File eWay to provide an Input Stream to the Batch Record eWay
3.    Batch Record eWay to break up the input stream into records delimited by carriage return+new line
4.    Batch Local File eWay to write each block of records to a file with a distinct name

Brief steps to implement this solution are given in the full Quick Note at http://mediacast.sun.com/users/Michael.Czapski-Sun/media/QuickNote_001/details. The collaboration code will work in Java CAPS 5 and 6 Repository.