Database Alias and DB2 ODBC Drivers

One of my recent project required to use ODBC to access DB2 databases located on remote VMWare LabManager images. I am using a Windows PC (Vista) laptop to develop and test my project (LotusScript Data Object code) - a Lotus Notes/Domino DB2 integration using ODBC. The first step for me was to install the ODBC DB2 drivers since I did not have DB2 installed on my laptop.

Several installations options were offered to me for DB2 9.7:

• IBM Data Server Driver for ODBC and CLI (CLI Driver) : the smallest footprint - a 13MG zip file (installing the drivers manually might be a little bit tricky - see my next post on this)
• IBM DB2 (server + client tools)  : this would work but this much more than I need since DB2 is already installed on my remote LabManager image
• IBM Data Server Runtime Client : the best solution for me (34MB zip file), especially if I have installed other tools such as IBM Data Studio for managing my DB2 databases instances remotely.

The installation of  the IBM Data Server Runtime Client is very fast and straightforward. It installs the ODBC/CLI drivers and a small set of useful command line setup tools:

After this, we can create the Database Aliases using the Windows ODBC Data Source Administrator.
When you look at the Drivers tab, you should now see your DB2 ODBC drivers

To add a DB2 Data Source Name (DSN):

• select User or System and click on the Add... button.
• select the DB2 ODBC/CLI driver
• enter a Data source name and add an Alias if needed (click on the Add button next to your existing aliases if needed)
• enter Data Source parameters (Description, user ID, password) - click "Save password" checkbox  to save your login and password locally in your db2cli.ini file.
• enter your TCP/IP connection (port number is 50000 by default for me for DB2), the host name is the IP address of my DB2 server VMWare image.
• I did not have to change anything in the defaults of Security options and Advanced Settings.

From there you are ready to use your ODBC DSN ready to connect to your DB2 Database.

One issue you will encounter though will be how to delete an existing Database Alias from the DB2 ODBC tab either to modify an existing one or to remove an old one.
These appear in the drop down of the ODBC IBM DB2 Driver - Add popup window.

The truth is that even though you are accessing a remote DB2 server machine, these aliases are stored locally on your DB2 installation.
To remove the DB2 Database Aliases ODBC drivers, just start the IBM DB2 Command Line Processor and use the following command:

UNCATALOG DATABASE <database_alias>

In certain cases, you also need to refresh the directory cache. For this, just stop and restart the DB2 Management Service on your local Windows machine.

Healthcare REST APIs - JSON or XML?

I have been working recently on a REST API which produces subsets of Continuity of Care Documents (CCD). This REST API is used by an iPhone application which is targeted to physicians and nurses. Since I wanted to minimize the amount of data exchange between the server and the client, I originally used JSON as my data exchange format. The motivation to use JSON was to have a compact format that offers better performance than a more complex XML representation.

For example, the request to obtain lab-results from a CCD is as following:

GET /users/<user-id>/patients/<patient-id>/lab-results?hl7v3=true&max=<max>offset=&<offset>

The resulting of this request to the API is a JSON object containing a list of lab results:

{"lab-results":{
    "list":[{"lab-result":{"entry":"...",
                           "facility":"...",
                           "normalcy":"...",
                           "orderedBy":"...",
                           "status":"...",
                           "subject":"...",
                           "urgency":"..."}},
            {"lab-result":{...}},...],
    "count":"...",
    "offset":"...",
    "remain":"..."}}

A lab result HL7 V3 entry is returned as the following JSON object:

{"entry":{
    "organizer":{
        "code":{"displayName":"..."}},
        "components":[
            {"component":{...}},
            {"component":{...}},...],
        "notes":[...]}}}

A lab-result component itself:

{"component":{
    "observation":{
        "code":{"displayName":"..."},
        "effectiveTime":{"value":""},
        "value":...,
        "interpretationCode":{"code":"..."},
        "referenceRange":{
            "observationRange":{...}},
        "notes":[...]}}}

An observation value is returned as a JSON object containing either a string value, a unit and a type, or just some text.

{"value":{"unit":"...","value":"...",type:"..."}}

{"value":"..."}

An observationRange is returned as a JSON value object containing a low and high value, or just some text.

{"observationRange":{
    "value":{
        "low":{"value":"..."},
        "high":{"value":"..."}}}}

{"observationRange":{"text":"..."}

All these JSON objects are marshalled from annotated Java POJOs using JBOSS RestEasy framework and Jackson:

XmlRootElement(name = "high")
public class HighValue {

 private String value = "";

 /**
  * Construct a new instance.
  */
 public HighValue() { }    // Empty constructor

 /**
  * Create a new {@code HighValue} during JAXB unmarshalling.
  * @param value
  *            String as value for the high value.
  */
 public HighValue(final String value) {
  if (value != null)
   this.value = value.trim();
 }

 /**
  * Get the {@code value} attribute.
  * @return {@code value} attribute value (may be {@code null}).
  */
 @XmlElement
 public String getValue() {
  return value;
 }

 /**
  * Set the {@code value} attribute.
  * @param value
  *            value to set.
  * @see #getValue()
  */
 public void setValue(final String value) {
  if (value != null)
   this.value = value.trim();
 }
}

This was fine initially since I was focusing on just lab results and I was using a specific back-end API that providing values to populate my POJOs. This solution started to become more complex when I was asked to generated a large set of CCD data types. As a result, the number of Java objects became quickly larger.

The other option I had was to use another internal API I could use which was already generated full or subset of CCD. However the resulting CCD format provided was in XML:

<component>
  <observation classCode="OBS" moodCode="EVN">
    <templateId root="2.16.840.1.113883.10.20.1.31"/>
    <templateId root="1.3.6.1.4.1.19376.1.5.3.1.4.13"/>
    <templateId root="2.16.840.1.113883.3.88.11.83.15"/>
    <id root="1"/>
      <code code="Remark" codeSystemName="L" displayName="Remark"/>
      <text>
        <reference value="#Observation_504ccbaf5ecea7b1096720"/>
      </text>
      <statusCode code="completed"/>
      <effectiveTime value="20091223231100"/>
        <value xsi:type="ST">Spec #106641063: 23 Dec 09  2311</value>
      <interpretationCode code="N" codeSystem="2.16.840.1.113883.5.83" codeSystemName="ObservationInterpretation" displayName="Normal"/>
  </observation>
</component>

I could of course just used it as it is and have my REST API return XML CCD subsets in XML:

GET /users/<user-id>/patients/<patient-id>/CCD&section=<section>

They are several issues with this:

• As you can see XML is much more complex to understand, parse and debug than JSON
• XML increases bandwidth consumption
• Browsers and client application (e.g. mobile devices) can consume JSON much more efficiently than XML

For me, the best solution was to have the internal API marshalling the CCD in both XML and JSON so I will not have to unmarshall the CCDs again into POJOS.

The good news for all of us is that you can use java tools such as JAXB which has adapters to support other formats than XML such as JSON. With Java annotations, this is very easy to implement.

Spring Dependency Injection with JBOSS : the CLASSPATH issue

When facing the problem of deploying web archives (war) to be configured through Spring dependency injection, you probably want to have generic applications that do not have to be recompile every time you deploy them on new configurations.

In my current project I need to configure a REST API with various parameters (host name, database paths, maximum of records per request). For this I use Spring dependency injection where the parameters are injected at run-time via a resource file located outside the war file, in a folder specified by the Windows CLASSPATH variable (my testing and production platforms are windows machine).

First I need to add a windows CLASSPATH system variable (in your system properties/environment variables)  if this variable does not exist. Then I add the resources.xml file directly in the folder specified by CLASSPATH. You can also use a sub-folder but you will need to hard-code the name of the folder in your spring config file - in my case applicationContext.xml located in ./src/main/webapp/WEB-INF/

<beans xmlns="http://www.springframework.org/schema/beans"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xmlns:context="http://www.springframework.org/schema/context"
 xsi:schemaLocation="
        http://www.springframework.org/schema/context 
        http://www.springframework.org/schema/context/spring-context-2.5.xsd
        http://www.springframework.org/schema/beans 
        http://www.springframework.org/schema/beans/spring-beans.xsd">
    <import resource="classpath:/resources.xml" />
</beans>

My resources.xml looks like this:

<beans xmlns="http://www.springframework.org/schema/beans"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xmlns:context="http://www.springframework.org/schema/context"
 xsi:schemaLocation="
        http://www.springframework.org/schema/context 
        http://www.springframework.org/schema/context/spring-context-3.0.xsd
        http://www.springframework.org/schema/beans 
        http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">
  <bean id="custService" 
                      scope="prototype"
                      class=".....">
   <property name="hostName" value="121.122.123.124"/>
   <property name="databasePath" value="..."/>
   <property name="maxRecordsPerRequest" value="1000"/>
  </bean>

</beans>

One issue you might encounter when you try to deploy your application on JBoss is that the web application server does not take into account the CLASSPATH out-of-the-box (I am using redhat EAP 5.0.X - production setting), but this might be also the case with JBOSS community edition.

Your war file will probably fail to deploy and you will find a bunch of errors in your log file ./jboss-as/server/<setting>/log/server.log  including:

org.springframework.beans.factory.parsing.BeanDefinitionParsingException: Configuration problem: 
Failed to import bean definitions from URL location [classpath:/resources.xml]
Offending resource: ServletContext resource [/WEB-INF/applicationContext.xml]; nested exception is org.springframework.beans.factory.BeanDefinitionStoreException:
IOException parsing XML document from class path resource [resources.xml]; 
nested exception is java.io.FileNotFoundException: 
class path resource [resources.xml] cannot be opened because it does not exist

What is missing is that you need to tell JBoss about your CLASSPATH variable.
Just edit ./jboss-as/bin/run.bat and add the CLASSPATH variable and you will be up and running in no time.

:RESTART
"%JAVA%" %JAVA_OPTS% ^
   -Djava.endorsed.dirs="%JBOSS_ENDORSED_DIRS%" ^
   -classpath "%JBOSS_CLASSPATH%;%CLASSPATH%" ^
   org.jboss.Main -b 0.0.0.0 -c production %*

RESTeasy JAX-RS embeddable server and SpringBeanProcessor

TJWS (Tiny Java Web Server and Servlet Container) is a very convenient miniature Java Web Server build as a servlet container with HTTPD servlet providing standard Web server functionality.

I have been using TJWS for testing a REST API to be deployed on JBoss application server. The advantage is that JUnit tests can run without the need to deploy a war file on JBoss. Since I have implemented the REST API with RESTEasy, I am using the embedded TJWS server part of the org.jboss.resteasy.plugins.server.tjws.TJWSEmbeddedJaxrsServer package.

The RESTEasy documentation (chapter 23) describes how to use the embedded container.

@Path("/")public class MyResource {

   @GET
   public String get() { return "hello world"; }
 
   public static void main(String[] args) throws Exception 
   {
      TJWSEmbeddedJaxrsServer tjws = new TJWSEmbeddedJaxrsServer();
      tjws.setPort(8081);
      tjws.getRegistry().addPerRequestResource(MyResource.class);
      tjws.start();
   }
}

As you can see, TJWS is very simple to use. You create an instance of the server, setup the port (this is very useful when for example certain ports are already used - I had to set a specific port for our Hudson continuous builds). Then you specify the class to test and you start the server.

In my JUnit tests, I start the server before each tests and stop it after the tests are completed:

private TJWSEmbeddedJaxrsServer server; 

@Before
    public void start() {
      
     server = new TJWSEmbeddedJaxrsServer();
     server.setPort(SERVER_PORT);
     server.getDeployment().getActualResourceClasses().add(MyResource.class);
     server.start();
    }

@After
    public void stop() {
     server.stop();
    }

Since I am using Spring I was interested to leverage the framework for dependency injection in order to configure certain server settings. However the RESTeasy documentation provides only some pseudo-code example:

public static void main(String[] args) throws Exception 
   {
      final TJWSEmbeddedJaxrsServer tjws = new TJWSEmbeddedJaxrsServer();
      tjws.setPort(8081);

      org.resteasy.plugins.server.servlet.SpringBeanProcessor processor = new SpringBeanProcessor(tjws.getRegistry(), tjws.getFactory();
      ConfigurableBeanFactory factory = new XmlBeanFactory(...);
      factory.addBeanPostProcessor(processor);

      tjws.start();
   }

I had to make some modifications to the code provided as follow:

@Before
    public void start() {
      
     server = new TJWSEmbeddedJaxrsServer();
     server.setPort(SERVER_PORT);
     server.getDeployment().getActualResourceClasses().add(MyResource.class);
     server.start();
     
     Resource resource = new FileSystemResource("src/test/resources/resources.xml");
     ConfigurableListableBeanFactory factory = new XmlBeanFactory(resource);
     SpringBeanProcessor processor = new SpringBeanProcessor(
             server.getDeployment().getDispatcher(),
             server.getDeployment().getRegistry(), 
             server.getDeployment().getProviderFactory());
     processor.postProcessBeanFactory(factory);
    }

Alternatively you can define your Spring resource file in a static string directly in your JUnit test class:

Resource resource = new ByteArrayResource(SPRING_BEAN_CONFIG_FILE.getBytes());

How to secure the JBoss JMX and Web Consoles?

Lately I have been using JBoss more and more as my deployment platform of choice. I am currently using the latest JBoss Enterprise Middleware solution (EAP version 5.0.1). This is a commercial version, but you can also use the community edition as well which offers most of the same features.

One of the issue I have encountered recently was how to secure the web based administration consoles?

As a matter of fact, the default installation offers a login and password for the admin console which is typically accessible on http://localhost:8080/admin-console if your web application runs locally, or more generally on http://<host>:<port>/admin-console.
However if you want to protect the JMX console (http://localhost:8080/jmx-console) and the JBoss Web console (http://localhost:8080/web-console) you have to make sure that certain files in your installation are setup correctly.


Generally, the JBoss community and RedHat are quite good at documenting the features of their products, but I was disappointed to find incomplete information in the main page on this subject.

This page explains that "the jmx-console and web-console are standard servlet 2.3 deployments that can
be secured using J2EE role based security.  Both also have a skeleton setup to allow one to easily enable security using username/password/role mappings found in the jmx-console.war and web-console.war deployments in the corresponding WEB-INF/classes users.properties and roles.properties files".

Until this point, it is quite clear. The difficulty starts with a vague description where to find the files in questions :

To secure the JMX Console using a username/password file -

• Locate the  directory.  This will normally be in  directory..
  

The author probably assumes that the various locations are obvious to everyone. Let me be more precise and generous in details:

First you will need to know which profile/configuration you are running. JBoss EAP has six configurations based on your needs:

• all (everything, including clustering support and other enterprise extensions)
• default (for application developers)
• minimal (the strict minimum)
• production (everything but optimized for production environments)
• standard (tested for Java EE compliance)
• web (experimental lightweight configuration) 

If you did not specify your profile explicitly at starting time (run.sh -c )you most likely use the default profile.





You can check which profile is running by looking at your JBoss EAP Admin Console. The name of the profile/configuration is indicated at the top of the server hierarchy.

By the way, the various applications that you will likely developed (war, ear, rar or jar files) will be deployed under the corresponding folders under the Applications node.

First you might want to change the login and password of the admin console itself before adding those for the JMX and Web consoles?


One important "meta" file is login-config.xml which is located under \jboss-as\server\ 

 




This file specify for a specific profile (e.g. default) the security-domain values for the consoles:

<application-policy name = "jmx-console">
    <authentication>
      <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
        flag="required">
        <module-option name="usersProperties">props/jmx-console-users.properties</module-option>
        <module-option name="rolesProperties">props/jmx-console-roles.properties</module-option>
      </login-module>
    </authentication>
  </application-policy> 

<application-policy name = "web-console">
    <authentication>
      <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
        flag="required">
        <module-option name="usersProperties">web-console-users.properties</module-option>
        <module-option name="rolesProperties">web-console-roles.properties</module-option>
      </login-module>
    </authentication>
  </application-policy>

In other words, this file can help you locate and map how authentication (login and password in users.properties file) and authorization (access control in roles.properties file) is specified.

Since these consoles are themselves web applications, you will need to look at exploded war files under your profile, under the deploy folder.

Securing the JMX Console:

• Locate the folder jmx-console.war under ./server/<config>/deploy
• Open the file ./server/<config>/deploy/mx-console.war/WEB-INF/web.xml
• Verify that the <security-constraint> section is not commented (in this section, you should see specified  the roles for authorization (see below)

<security-constraint>
     <web-resource-collection>
       <web-resource-name>HtmlAdaptor</web-resource-name>
       <description>An example security config that only allows users with the
         role JBossAdmin to access the HTML JMX console web application
       </description>
       <url-pattern>/*</url-pattern>
     </web-resource-collection>
     <auth-constraint>
       <role-name>JBossAdmin</role-name>
     </auth-constraint>
   </security-constraint>

• Locate the file: .\server\<config>\conf\props\jmx-console-users.properties (if the file name has not been changed in login-config.xml) 
• change admin=admin to your new <new_login>=<new_password>

The authentication method is specified in the following section:

 <login-config>
      <auth-method>BASIC</auth-method>
      <realm-name>JBoss JMX Console</realm-name>
   </login-config>

   <security-role>
      <role-name>JBossAdmin</role-name>
   </security-role>

Securing the Web Console:

• Login credentials are the same as used for the JMX console - in : .\server\<config>\conf\props\jmx-console-users.properties 
• change admin=admin to your new <new_login>=<new_password> 

For more information and this topic you can also look at Securing the JMX Console and Web Console (HTTP).

Response objects and the use of GenericEntity class with RESTEasy

Recently during the implementation of a REST API, I wanted to return a complex response containing a list of objects (Patients). The issue was that the RESTEasy build-in JAXB MessageBodyWriter could not directly handle lists of JAXB objects (Java has trouble obtaining generic type information at runtime).

I was recently in a situation where I had to create a complex response to a HTTP POST for my REST API. I am using JAXB /JSON support from RESTEasy.

I found some element of answer in the book "RESTFul Java with JAX-RS" from Bill Burke (pp 102). However the code snippet had a couple of errors:

  • the GenericEntity object cannot be passed to the Response.ok() method directly (a ResponseBuilder is required).

  • references to GenericEntity needs to be parameterized.

My use case is a little more complex than in the book. I am receiving a user-name and password from a POST (e.g. a form submit). I then perform the authentication and returns a list of Patient objects in a JSON/GZIP compressed format (instead a list of Customer objects) together with an authentication token.





The resulting code looks like this:

   @POST
   @Path("/token")
   @Consumes("application/x-www-form-urlencoded")
   @Produces("application/json")
   @GZIP
   public Response getPatientsWithToken(@FormParam("username") String username, @FormParam("password") String password) {
  
        Login login = new Login(username, password);
        // ... perform authentication here ....
    
        // Build the returning patient list
        List<Patient> returnList = new ArrayList<Patient>();
        returnList.addAll(patients.values());
        Collections.sort(returnList);
      
        GenericEntity<List<Patient>> entity = new GenericEntity<List<Patient>>(returnList){};
      
        // Create the response
        ResponseBuilder builder = Response.ok(entity);
        return builder.build();
   }

Of course you will have to import the following classes as well:

import javax.ws.rs.core.GenericEntity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.Response.ResponseBuilder;

Open APIs: State of the Market, May 2010

Today, I was looking at the presentation from John Musser related to Open APIs (see below). Even though these statistics comes mainly from mashup and consumer applications, I was surprised by the fact that REST APIs are gaining market shares over SOAP APIs so rapidly.

In B2B and in the enterprise world in general SOAP is often the top choice. The advantages for SOAP often mentioned are:

• Type checking (via the WSDL files)
• Availability of development tools

On the other hand, REST offers the following:

• Lightweight and easy to build
• Human Readable Results
• Extensibility
• Scalability

In Health Care, SOAP is still widespread and prevalent. However there are some interesting projects such as NHIN Direct Health Information Exchange where the relevance of REST vs other API protocols are discussed.

It will be interesting to see what will be the outcome of such discussions.

Open APIs: State of the Market, May 2010

View more presentations from jmusser.