Enable https:// on tomcat in two steps.

With this tutorial, I will explain, how to enable SSL (Secure Socket Layer) on tomcat 7 in tow steps.
Step 01: Create .keystore file.

Run the following command to generate .keystore file from $JAVA_HOME/bin.

On windows :

%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA 

On linux:

$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA  

Step 02: Uncomment "SSL HTTP/1.1 Connector on port 8443" on $CATALINA_HOME/conf/server.xml and modify it as follows.

<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
              maxThreads="150" scheme="https" secure="true"
              clientAuth="false" sslProtocol="TLS" 
              keystoreFile="${user.home}/.keystore" keystorePass="123@com"/>

The "keystorePass" is the password which you provided when generating .keystore file. Now restart the tomcat.

By default port 8443 keeps listening https requests. Open a browser and check the following URL.

https://localhost:8443

If you see tomcat's home page, you are done.

How to expose an exsisting service as a web service ?

Introduction

This tutorial addresses a most practical scenario which is being faced by a developer. Most of the time, We may need to expose some of our existing services as web services. This situation can be encountered in different stages of project life cycle. If It is the initial stage, then You are almost safe and You can well prepare for that. But, What will happen, this requirement comes just after half of the development has finished or the system is running in production environment. 

This will be little tricky if the web services have not been taken into consideration for initial project architecture. You may involve with different kind of project architectures and use different kind of technologies. As a developer, You are not allowed to change some architectural stuff and configurations since there may be lots of dependencies. 

Most of the tutorials on the Internet explains the basic stuff of creating a web service. Some time, 'Hello world' application or sometime it may be simple calculator like that. These tutorials are good to have the basic understanding about the web services. But the real world scenario's are ten time complex than that and have to face difficulties when following those kind of tutorials. 

Practical scenario

With this tutorial, I am going to explain, How We really address a real world requirement that came through your supervisor. I am going to explain the same kind of scenario, which I faced recently. 

A health care organisation is running a plenty of pharmacies all around the island. They have a web application which handles all the inventories, pricing and billing, issuing pharmacy items etc. They needed to expose their pharmacy items prices through a web service so that their client application in the pharmacy can access those via the web service. 

Their web application has been developed within struts2, spring and hibernated integrated environment. It has all the spring managed DAO classes and also the service classes. The application uses spring's auto wiring technique, component scanning, transaction management etc. With these kind of background, I needed to expose pharmacy item prices as a web service. That is some of the methods from our current pharmacy service are needed to be exposed to outside via a web service.

I will show you, How to achieve this kind of requirement with a minimal modification to our existing project. 

Additional Libraries

I am going to implement the web service with JAX-WS. I have used JAX-WS 2.2 for my project. You can download the required JAX-WS version from here. This provides few tools that can be used to generate web service and it's client stuff. After downloading the required version of library, extract it some where in your local machine. I have placed it in my home folder. 

ie: /home/semika/jaxws-ri-2.2

Implementing web service

I already have spring managed service classes and DAO classes for pharmacy item which are being used internally by the web application. Those are not exposed to out side. Suppose, We need to expose findAll() method which returns a list of 'PharmacyItem' of 'PharmacyService' interface as a web service.

For Your convenience, I will show you the "PharmacyServiceImpl" java class which is used to perform normal pharmacy item operations. This is a usual spring mange bean. Keep in mind, methods of this class can only be used for internal operations of our web application currently. Those are not exposed as web services. 

PharmacyServiceImpl.java

/**
 * 
 */
package com.slauto.service.pharmacy.impl;

import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import com.slauto.exceptions.ServiceException;
import com.slauto.model.pharmacy.PharmacyItem;
import com.slauto.persist.pharmacy.api.PharmacyItemDao;
import com.slauto.service.pharmacy.api.PharmacyItemService;

/**
 * @author semika
 *
 */
@Service("pharmacyItemService") 
public class PharmacyItemServiceImpl implements PharmacyItemService {

  @Autowired
  private PharmacyItemDao pharmacyItemDao;
 
  @Override
  public List<Pharmacyitem> findAll() throws ServiceException {
     return pharmacyItemDao.findAllPharmacyItems();
  }
}

As You can see, I have auto wired instance of 'PharmacyItemDao' with in the implementation class. As We all know, this is a spring managed service implementation class.

Next, We will implement the web service end point class for above spring managed service bean to expose it's methods as a web service methods. For the clarity, I created a separate class as web service end point.

PharmacyItemServiceEndPoint.java

package com.slauto.service.ws;
import javax.jws.WebMethod;
import javax.jws.WebService;

import org.springframework.context.ApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;

import com.slauto.exceptions.DataAccessException;
import com.slauto.model.pharmacy.PharmacyItem;
import com.slauto.service.pharmacy.api.PharmacyItemService;

/**
 * @author semika
 *
 */
@WebService(serviceName="pharmacyItemService") 
public class PharmacyItemServiceEndPoint {
 
  @WebMethod
  public List<Pharmacyitem> findAll() throws DataAccessException {
     ApplicationContext context = new ClassPathXmlApplicationContext("applicationContext.xml"); 
     PharmacyItemService pharmacyItemService = (PharmacyItemService)context.getBean("pharmacyItemService");
     return pharmacyItemService.findAll();
  }
}

As You can see here, I am using "pharmacyItemService" bean which is used by our web application to access the relevant service method. The "pharmacyItemService" is a usual spring mange bean which is used to perform day to day pharmacy item operation. Nothing special on that. Specially note that @WebService and @WebMethod annotation which indicates this class works as a web service end point.

Here, I am getting service class instance via application context. Further, We can auto wire web service end point classes with spring by extending end point classes from "SpringBeanAutowiringSupport"  provided by spring. In that case, We do not need to create application context instance as I have done above. I could not make that work, that is why, I used the above technique.

With "SpringBeanAutowiringSupport", when deploying web service (explain bellow), I encountered an exception which was hard  for me to resolve that. So I choose this technique. Any way, I do not like, what I have used above :) .

Generating web service

I am using a apt, wsgen and wsimport tools provided by JAX-WS to generate the portable artefacts used in JAX-WS services. The relevant ant targets for the 'build.xml' file will be as follows. 

Your may need following property declared at the top of the 'build.xml' file.

Property:

<property name="tomcat.home"        value="/home/semika/apache-tomcat-7.0.25" />
<property name="jaxws.home"         value="/home/semika/jaxws-ri-2.2" />
<property name="build.classes.home" value="${basedir}/WEB-INF/classes" />
<property name="java.home"          value="/home/semika/java/jdk1.6.0_30">

Class path:

<path id="project.class.path">
   <pathelement location="${java.home}/../lib/tools.jar" />
   <fileset dir="${jaxws.home}/lib">
        <include name="*.jar" />
   </fileset>
   <pathelement location="${basedir}/WEB-INF/classes" />
   <fileset dir="${basedir}/WEB-INF/lib" includes="*.jar" />
</path>

JAX-WS apt tool target:

<target name="apt" depends="javac">
   <taskdef name="apt" classname="com.sun.tools.ws.ant.Apt">
       <classpath refid="project.class.path" />
   </taskdef>
   <apt fork="true"
        debug="true"
        verbose="true"
        destdir="${basedir}/WEB-INF/classes"
        sourcedestdir="${basedir}/WEB-INF/src"
        sourcepath="${basedir}/WEB-INF/src">
        <classpath>
            <path refid="project.class.path" />
        </classpath>
        <option key="r" value="${basedir}/WEB-INF" />
        <source dir="${basedir}/WEB-INF/src">
            <include name="**/*.java"/>
        </source>
   </apt>
</target>

If you want to know further about apt tool provided by JAX-WS, look into this. When running apt target, it scans the source path (src folder) and generates the required *.class and *.java files for the classes annotated with @WebService. In this case, for 'PharmacyItemServiceEndPoint.java'. If You look into the package where 'PharmacyItemServiceEndPoint' is in, You can see, it has a new package called 'jaxws' created. Inside that package, I could see following three java files. 

DataAccessExceptionBean.java
FindAll.java
FindAllResponse.java

These classes are generated by the tool and it varies based on your service implementation and dependent classes which you are involving to your web service. Actually, you don't need to much worry about these generated stuff.

Similarly, You can see the relevant *.class files under /WEB-INF/classes folder.

JAX-WS wsgen tool target:

<target name="wsgen" depends="apt"> 
    <taskdef name="wsgen" classname="com.sun.tools.ws.ant.WsGen">
         <classpath path="project.class.path"/>
    </taskdef>
  
    <wsgen 
          xendorsed="true"
          sei="com.slauto.service.ws.PharmacyItemServiceEndPoint"
          destdir="${basedir}/WEB-INF/classes"      
          resourcedestdir="${wsdl.dir}"
          sourcedestdir="${basedir}/WEB-INF/src"      
          keep="true"
          verbose="true"
          genwsdl="true">
          <classpath refid="project.class.path"/>
    </wsgen>
</target>

The wsgen tool will generate the WSDL file for our end point web service class. After running this target, have a look on ${wsdl.dir} location. You can see our WSDL file has been generated. If you want to know further about wsgen tool provided by JAX-WS, look into this. 

Deploying Web service

I wanted to deploy the web service with the usual server start up. SoI had to add the following configuration into the web.xml file.

<listener>
      <listener-class>
              com.sun.xml.ws.transport.http.servlet.WSServletContextListener
      </listener-class>
</listener>
<servlet>
      <servlet-name>pharmacyItemService</servlet-name>
      <servlet-class>
         com.sun.xml.ws.transport.http.servlet.WSServlet
      </servlet-class>
      <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
      <servlet-name>pharmacyItemService</servlet-name>
      <url-pattern>/pharmacyItemService</url-pattern>
</servlet-mapping>

As I told you before when deploying the web service with the end point class extended from "SpringBeanAutowiringSupport", it gives an exception. That is why, I decided to get the service bean via application context. If you manage this situation, please just post it.

And also, You need to create sun-jaxws.xml under the WEB-INF folder and declare the web service end point as follows.

<?xml version="1.0" encoding="UTF-8"?>
<endpoints xmlns="http://java.sun.com/xml/ns/jax-ws/ri/runtime" version="2.0">    
  <endpoint
      name="pharmacyItemService"
      implementation="com.slauto.service.ws.PharmacyItemServiceEndPoint"
      url-pattern="/pharmacyItemService"/>
</endpoints>

I am using apache tomcat 7.0.25 to deploy the web service. You will need to tell tomcat where it can find JAX-WS libraries when the tomcat is starting up. You can edit the 'catalina.properties' file located in CATALINA_HOME/conf folder. Look for the common.loader property. It will mostly look like follows.

common.loader=${catalina.base}/lib,${catalina.base}/lib/*.jar,${catalina.home}/lib,${catalina.home}/lib/*.jar

Modify it as follows.

common.loader=${catalina.base}/lib,${catalina.base}/lib/*.jar,${catalina.home}/lib,${catalina.home}/lib/*.jar,/home/semika/jaxws-ri-2.2/lib/*.jar

As You can see, I have added my JAX-WS library path at the end of comma separated list. These classes are made visible to both tomcat internal classes and to all web applications deployed in the tomcat container. Now, You can copy your .war file into tomcat's webapps folder and start the tomcat. Your web service should be deployed. To confirm your web service is deployed properly, You can check for it's WSDL. For WSDL file, You should check the URL in following format.

http://localhost:8080/<your context name>/pharmacyItemService?wsdl

If You can see your WSDL file on the browser, You are done, You have success fully deployed the web service.

Generating Web service client

Now, We have a deployed web service. Next, We will see how to write client class to access the web service with java program. You can create a simple java project and use the following build.xml file there. I have placed the complete build.xml file for client generation. I am using wsimport tool coming with JAX-WS to generate the web service client artefacts.

<?xml version="1.0" encoding="utf-8" ?>
<project name="WS-client" default="wsimport" basedir=".">
 
 <property name="jaxws.home"  value="/home/semika/jaxws-ri-2.2" />
 <property name="java.home" value="/home/semika/java/jdk1.6.0_30"/>
 
 <path id="jaxws.classpath">
  <pathelement location="${java.home}/../lib/tools.jar" />
  <fileset dir="${jaxws.home}/lib">
        <include name="*.jar" />
     </fileset>
 </path>
 
 <target name="wsimport"> 
  <taskdef name="wsimport" classname="com.sun.tools.ws.ant.WsImport">
        <classpath path="jaxws.classpath"/>
  </taskdef>
  <wsimport   xendorsed="true"
              debug="true"
       verbose="true"
              keep="true"
       destdir="src"
       package="com.slauto.service"
       wsdl="http://localhost:8080/slautomanage/pharmacyItemService?wsdl">
  </wsimport>
 </target>
</project>

If You want to know further about wsimport tool, you can look into this. After running the above target, just have a look on the package where you have specified under wsimport attributes. You will see set of java files generated. You can compile and bundle these into a single client.jar file and can be used with any of the java project which need this web service. 

I have created very simple java class to fetch the pharmacy items information through the web service. 

Client.java

package com.slauto.client;

import java.util.List;

import com.slauto.service.PharmacyItem;
import com.slauto.service.PharmacyItemService;
import com.slauto.service.PharmacyItemServiceEndPoint;

/**
 * @author semika
 *
 */
public class Client {

 /**
  * @param args
  */
  public static void main(String[] args) {
  
        PharmacyItemService p = new PharmacyItemService();
        PharmacyItemServiceEndPoint ep = p.getPharmacyItemServiceEndPointPort();
        List<PharmacyItem> pharmacyItems = ep.findAll();
  
        for (PharmacyItem pharmacyItem : pharmacyItems) {
           System.out.println(pharmacyItem.getCode()); 
        }
     }
  }

It is wonderful isn't it ?. You will see list of pharmacy item codes displayed just after running this class. These pharmacy information are coming through web service deployed by a web application developed with heavily complicated environment.
That is it from this tutorial. I hope this will be helpful for you and if you pick something up from this tutorial, don't forget to put a comment. 

Use primitives over boxed primitives whenever you have the choice - Java

Just with the reading of this post's title, some of you may be confused because, some of the java developers have used to use boxed primitives (Wrapper class objects of primitives) without a specific reason. But, We should be care of using primitives rather than the boxed primitives when We have a choice. I will explain Why, We should choose primitives.

There are differences between primitives and boxed primitives though You did not pay attention too much on that.

Primitives are simpler and faster, and they have only their values. Primitives are generally more time- and space-efficient than boxed primitives. But the boxed primitives have different identities though they have same value. Consider the following code which most of the java developers are well known and understandable.

 Integer first = new Integer(41);
 Integer second = new Integer(41);
  
 if (first == second) {
      System.out.println("Equal");  
 }

As You well known, the above code will not print the "Equal" since it performs an identity comparison on the two object references. Applying == operator on boxed primitives always gives wrong output. To fix the above problem, either You can use Integer's equal() method or getting integer values from Integer's intValue() method. Now, You consider the following code.

Integer first = new Integer(41);
Integer second = new Integer(41);
       
if (first > second) {
     System.out.println("First is greater than Second");  
} else {
     System.out.println("First is not greater than Second");
}

Can you spot the output of above code? The above code will print the else condition. In this case, it did not perform the identity comparison like == comparison. It compared the actual values and gave the correct output. So When evaluating this kind of comparison, Integer instances are auto-unboxed;that is, it extracts their primitive values. I know, You have used this kind of comparison plenty of times. Think, You really knew about this. So We must choose primitives or boxed primitives when We have a choice. 

Next, We will move to another difference. You know that, When We declare a variable with primitive type, it always has functional values. But boxed primitives can have 'null' values which sometime can raise exception. Consider the following example.

package com.semika.mail;

public class BoxPrimitiveTest {
 
static Integer x;
static int y;

public static void main(String[] args) {

   if (x == 0) {
        System.out.println("X is Zero");  
   }
  
   if (y == 0) {
        System.out.println("Y is Zero");  
   }
}
}

What will be the output of the above program. The above code will not run and it will throw an exception. As You can see, variable 'x' is declared with boxed primitive type. It has 'null' value when evaluating the x==0 expression. When a null object reference is auto-unboxed,You get a NullPointerException. 

Next, I will explain the harm of mixing both box primitives and primitives in a single operation. When You mix primitives and boxed primitives in a single operation, the boxed primitive is auto-unboxed which results severe performance problems. Consider the following class.

class LineItem {
 
double price;

public double getPrice() {
    return price;
}

public void setPrice(double price) {
    this.price = price;
}
}

Suppose, You want to iterate list of 'LineItem' and calculate the total value. Note that 'price' variable is declared with a primitive type. Look into the following code of calculating total cost.

Double totoalCost = 0.0; 
  
for (LineItem lItem : lineItemList) {
    totoalCost += lItem.getPrice();
}

The above code makes a server performance problem. Since, You have declared 'totoalCost' variable to be of the boxed primitive type Double instead of primitive type double. The program compiles and run without an error or warning.But the variable is repeatedly boxed and unboxed, causing the observed performance degradation.

Finally, the developer should never ignore the distinction between primitives and boxed primitives. You have to choose what to use.