JAX-WS Example With JBossWS – Server-Side

Uncategorized

Introduction

In previous article, a very simple Web Application was presented. In any complex environment, there will often be multiple tiers within an application or environments hosting code/services for different teams. A common way of communicating within such environments is through SOAP-based Web Services (referred to simply as Web Services.

There is much literature sprinkled across the Internet about Web Services. It will not be repeated here. Since Thinkmiddleware.com is concerned about Java and JEE, we’re going to look at SOAP-based Web Services using these technologies. So, tutorial will be the first part of a series introducing Java-based Web Services. It’s important to understand that you don’t have to use Java to use Web Services. But, for our purposes, that is exactly what we will be doing.

I may have lied in the last paragraph when I said I was going to skip all of the detail. I’m going to introduce just enough detail to understand what we are going to do here.

The Web Service used as the basis of this example originally came from here.

SOAP-based Web Services Specifications

A collection of specifications comes together to provide the foundation of Web Services:

  • HTTP – Everyone should be familiar with the HTTP Protocol. HTTP v1.1 is descrbed in RFC 2616. HTTP is one of several possible transport layer protocols that SOAP can use. HTTPS, SMTP, JMS, FTP are others.
  • SOAP – The SOAP specification is sponsored by W3C (World Wide Web Consortium). SOAP defines an “enveloping” strategy for Web Services calls. What does that mean? It defines part of the messaging protocol that a Web Service client and server have to understand in order to communicate.
  • XML — XML is another one of those standards that everyone has heard of. The XML Spec is also maintained by the W3C organization. XML is a universal data representation format/language that is used extensively by Web Services. This is also part of the messaging protocol/layer. At the end of the day, Web Services are exchanging XML documents.
  • WSDL – The Web Services Description Language is also a W3C specification. WSDL describes Web Services; it tells a Web Service client everything (or most things, at least) it needs to know in order to call a Web Service. Every Web Service has an associated WSDL.
  • WS-* – There is a large family of Web Services specifications that provide for security, reliable messaging, detailed descriptions of Web Services, etc. For our purposes, it is enough to know that these specifications exist and in order to build non-trivial applications, a subset of these specs will be used.

So, HTTP, XML, SOAP, and WSDL provide the foundations of Web Service client-server communication. These specifications provide a universal set of data types, protocols, and rules-of-play. But, we need more. Every language that can by used to implement a Web Service on the server-side or call a Web Service from the client-side requires a set of rules to map “native” datatypes to SOAP datatypes and a library(s) to handle the network communication, data transformations, and provide for implementing all of the WS-* specifications.

Java Specifications for SOAP Web Services

There are a set of Specifications that bridge the gap between the “abstract” Web Service specifications listed above and the Java language (and JEE platform).

  • JAX-WS – The JAX-WS Specification is a JCP (Java Community Process) spec that defines how Java code should interact with SOAP-based Web Services. JAX-WS stands for Java API for XML-Based Web Services.  The earlier version of this spec was called JAX-RPC.
  • JAXB – The Java Architecture for XML Binding (JAXB) specification is defined by JSR-222 (another JCP spec). JAXB defines the the mappings between Java data/object-types and SOAP/XML datatypes. These mappings are used by JAX-WS.

SOAP Runtime Libraries

So, now we’ve got specifications that define all of the details of letting Java code talk to Web Services (and vice-versa). Now, we need an implementation of these specifications. There are many options.

  • Axis2
  • JBossWS
  • IBM SOAP Runtime

In another obvious twist, since ThinkMiddleware.com has been building all of it’s Web Application examples on JBoss, we’re going to go with JBossWS.

Development Methodology

There are two general approaches to developing Web Services: Contract-First or Code-First. With Contract-First Web Services development, the WSDL and XML Schema (data structures passed in and out of the Web Service) are defined before any code is written.  Then, tools are used to generate server-side Proxy classes where Web Service code would be placed. In Code-First Web Services development, as one might imagine, the code is written first (in the form of a POJO in the simplest case, but could be EJB Stateless Session Beans as well), then a WSDL is generated by tools later.

This example is going to write a POJO first.

Web Service Example Using JBossWS

The POJO code

The following Java class will implement our Web Service:

package com.tm.jaxws;

@javax.jws.WebService

public class Echo

{

public String echo(String input)

{

System.out.println(“Echo PoJo: ” + input);

return input;

}

}

So, we can see here that this com.tm.jaxws.Echo class is more or less an ordinary Java class (a.k.a a POJO). It has a single method defined called echo(); true to its name, this class takes a single string argument and returns the same string. For demonstration purposes, it also prints to Standard Out the value of the string.

Java 1.5 vs. Java 1.6

If Java 1.6 is being used, read this document and do as it says. Otherwise, no actions need to be taken.

Web.xml

The web.xml file for this Web Application contains:

<web-app xmlns=”http://java.sun.com/xml/ns/j2ee”

xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”

xsi:schemaLocation=”http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd”

version=”2.4″>

<servlet>

<servlet-name>Echo</servlet-name>

<servlet-class>com.tm.jaxws.Echo</servlet-class>

</servlet>

<servlet-mapping>

<servlet-name>Echo</servlet-name>

<url-pattern>/services/Echo</url-pattern>

</servlet-mapping>

</web-app>

Application.xml

As is the custom on Thinkmiddleware.com, all Web Application example will be packaged in an EAR file. So, the application.xml file for this application will contain:

<?xml version=”1.0″ encoding=”UTF-8″?>

<application xmlns=”http://java.sun.com/xml/ns/j2ee”

xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xsi:schemaLocation=”http://java.sun.com/xml/ns/j2ee

http://java.sun.com/xml/ns/j2ee/application_1_4.xsd”

version=”1.4″>

<display-name>Thinkmiddleware.com JAX-WS Example</display-name>

<module>

<web>

<web-uri>jaxws.war</web-uri>

<context-root>jaxws_server</context-root>

</web>

</module>

</application>

Build

The following environment script was used to setup the compilation environment:

JAVA_HOME=PATH_TO_JAVA_6_JDK_HOME

PATH=$JAVA_HOME/bin:$PATH

CLASSPATH=.:INSTALL_PATH/jboss-4.2.3.GA/client/servlet-api.jar:INSTALL_PATH/jboss-4.2.3.GA/server/default/lib/jbosssx.jar:INSTALL_PATH/jboss-4.2.3.GA/client/jboss-annotations-ejb3.jar

export JAVA_HOME PATH CLASSPATH

This Ant build.xml script is used to compile the application and build the EAR file.

Assuming that you’ve unzipped the JAR file given at the bottom of this tutorial, the following command will build the EAR file:

[ user@machine jaxws_server]$ ant

Buildfile: build.xml

init:

[mkdir] Created dir: PATH_TO_EXAMPLE/jaxws_server/build

[mkdir] Created dir: PATH_TO_EXAMPLE/jaxws_server/build/war

[mkdir] Created dir: PATH_TO_EXAMPLE/jaxws_server/build/war/META-INF

[mkdir] Created dir: PATH_TO_EXAMPLE/jaxws_server/build/classes

[mkdir] Created dir: PATH_TO_EXAMPLE/jaxws_server/build/ear

[mkdir] Created dir: PATH_TO_EXAMPLE/jaxws_server/build/ear/META-INF

compile:

[javac] Compiling 1 source file to PATH_TO_EXAMPLE/jaxws_server/build/classes

war:

[war] Building war: PATH_TO_EXAMPLE/jaxws_server/build/war/jaxws.war

ear:

[copy] Copying 1 file to PATH_TO_EXAMPLE/jaxws_server/build/ear/META-INF

[copy] Copying 1 file to PATH_TO_EXAMPLE/jaxws_server/build/ear

[jar] Building jar: PATH_TO_EXAMPLE/jaxws_server/build/jaxws.ear

BUILD SUCCESSFUL

Total time: 2 seconds

Deploy

The resulting EAR file will be placed $EXAMPLE_DIR/build/. This application can be deployed to a running JBoss container by either copying it manually into the $SERVER_HOME/deploy directory or updating the following line in build.xml:

<copy file=”${build}/jaxws.ear” todir=”../../jboss-4.2.3.GA/server/default/deploy”/>

to point the ‘todir’ parameter at your container’s $SERVER_HOME/deploy directory. Then, type “ant deploy”.

If you see the following line in the container output:

2009-10-05 22:04:32,755 INFO [org.jboss.deployment.EARDeployer] Started J2EE application: file: $JBOSS_INSTALL_DIR/jboss-4.2.3.GA/server/default/deploy/jaxws.ear

then, the application deployed successfully.

Download

All source code and setup files for this project can be downloaded here.