Creating JBossWS Web Services with JBoss 4.2.3GA and JDK1.5

Continuing from the last post, today we will learn about creating a Simple Web Service using jBossWS (a JAX-WS implementation) and deploy it on JBoss Server. Also, we will see how can we create a WS-Client using in-build utilities and consume the web service with ease.

Prerequisites:

1. Intermediate knowledge of Java, some experience with XML would help, though not necessary.
2. Basic Know-how of a web-application
3. Setting up the required environment.

Getting Started:

Create a New Java Project. Name it anything you like. Create appropriate structure for a web application like we create an output folder named ‘web’ and create ‘WEB-INF’ in it, which will hold the deployment descriptor ‘web.xml’. The initial structure of our web application looks as follows:

With JBossWS, to create a web service is as easy as creating a Java class and exposing a method and create its entry in the deployment descriptor. Lets first create an entry in web.xml for the the EndpointServlet class and configure it for the Java class containing the Web Service implementation as shown below:Here, we specify EndpointServlet (comes bundled with JBossWS stack) which is used to publish/deploy your web service over JBoss. We also provide its mapping giving the url-pattern of the web service.

Lets see how our Java Class which contains the web service would look like:

Notice that we have noticed JAX-WS Annotations to decorate our class. The @WebService annotations tells us that this class contains methods exposed by a web service and @WebMethod annotation points out exactly which method is exposed.

To make sure that your code compiles, you must include the JAR’s that come with JBossWS native stack. Therefore, we add the following JAR’s to the lib folder of WEB-INF and also configure it on the build-path of the project so that you do not get compilation error in Eclipse.

• jaxb-api.jar
• jbossws-native-jaxws-ext.jar
• jbossws-native-jaxws.jar
• jbossws-native-saaj.jar

So, thats all you need to do in order to expose your web service. Lets now publish this web service on JBoss. To do so, we will package it as a WAR file using ANT. I have used the following ANT script to create WAR for my web service.

Now, you can copy this war file to the deploy directory of your JBoss Installation. Restart your server and check the logs to see whether it is deployed successfully or not.

[TomcatDeployer] deploy, ctxPath=/jaxWS,
warUrl=.../tmp/deploy/tmp5621016708388909925jaxWS-exp.war/
[WSDLFilePublisher] WSDL published to: file:/E:/JBoss/jboss-4.2.3.GA
/server/default/data/wsdl/jaxWS.war/HelloWorldService300665606.wsdl

So, that tells you that your web service has been deployed. To double check, you can always check the JBoss web service console on this url: http://localhost:8085/jbossws/services It shows you a list of all endpoints deployed currently, something like below:

Lets also have a look at a snippet of generated WSDL, though explaining this is out of scope of this entry.

JAX-WS provides supports for all Java in-build data types as well as for complex user-defined objects. The WSDL that is generated on publishing the web service contains all the information about the parameters accepted by the web service and also about the format in which the data is returned. Thus, this WSDL is more of a contract on which the communicating parties must agree before communicating.

Client Generation:

Now, we consume this web service by creating client using utilities provided by JBossWS stack ( Examples include wsconsume, wsget, wsrunclient etc )

>>> wsconsume –k http://localhost:8085/jaxWS/prodsWS?wsdl

wsconsume will parse the WSDL and –k option will generate the java classes which will be used by the client using JAXB framework.

Now, we will create a TestClient (to test our webservice), which will finally consume the web service.



As expected, on running this client, it will print “Hello My Name is Agraj” as output. Please note that in order to run this client successfully, you must add few more client jars to the project.

The final structure of the web application (web service + client) looks like following:

So, that’s all I want to talk about web services today, I hope it was of some help. Please post your views or corrections as comments.

Note: You may encounter a few problems while developing web services using JBossWS and JDK 1.6 since there are some compatibility issues and conflicting jars that create problems. Your best friend in such a case is Google :-)

JAX-WS Web Services with JBoss (JBossWS)

Today, Web Services are an essential part of every developer’s toolkit not only because they have diverse and varied applications but because they are easy to create and consume and work like a charm. Whether it is about inter-communication between legacy applications and new ones or there might be a scenario in which two applications (programmed in different languages) need to interact, Web Services come to your rescue. In short, Web Services are everywhere and you cannot imagine your life without them, especially if you are a Web Developer.

So, without wasting any more time on Web Services as there are many good resources for introducing them (see resources below), lets see how to create the environment needed to develop these Web Services. (Sometimes, I feel that creating an environment for developing and deploying Java apps is more tedious process than actually coding for the application :-) )

What is JAX-WS ?

JAX-WS stands of Java API for XML – Web Services; it is the latest standard/specification created for development and maintenance of web services. It is a successor to JAX-RPC and you can read here about the differences between the two. JAX-WS bring along many improvements, but for one, it is too easy to create, deploy and consume than its earlier counterpart.

What is JBossWS ?

We will use JBoss Application Server to deploy our application and hence we will use their Web Service Stack. JBossWS (JBoss Web Services) is in short, an implementation of JAX-WS specification.

Software that we require:

1. JDK 1.5 and above (We use JDK 1.6)
2. JBoss Application Server (We will use JBoss5.1.0 with JDK 1.6)
3. JBossWS Web Service Stack (We use JBossWS Native Stack)
4. Ant (Java Build/Automation Tool)

So, lets set up the environment around us so that we can easily create new and happening web services.

Step 1

Download and Install JDK on your machine (if not already installed). Also set your environment variable JAVA_HOME to the installed JDK location. Also add it to PATH environment variable. To check if this step is done properly, check by typing on command line:
>>> java –version

It will show you something like this (your current java version) and because you set the PATH variable, you can do this from anywhere:

 

Step 2

Download and install ANT (a Java based Build Tool). If you are new to ANT, check my earlier blog entry about ANT to gain more insight. Again, set ANT_HOME to installation path and also include ANT_HOME in PATH variable. To check, type on console:
>>> ant -version

It will show the current version of ANT installed, something like this

 

Step 3

Download JBoss 5.1.0 with JDK 1.6 from here and install it on your system. Now, set JBOSS_HOME = {Installation path}
check by starting and stopping server. Pretty simple so far.

Step 4 

Download JBossWS Web Service Stack. Note that JBoss application server alone is not enough to deploy your web-services so you need additional jars that help you create, deploy, maintain and consume your JBossWS Web Services.

Download the binary distribution of JBossWS-Native 3.2.1 GA from here. Now, lets see how to install this pack.
Installing jbossWS pack requires:

1. Copy ant.properties.example to ant.properties (Creating a backup)

2. Change following in ant.properties (this file is used by build.xml)

   a) Location of your JBoss
      jboss510.home=E:/JBoss/jboss-5.1.0.GA

(since we are using JBoss5.1.0 so replacing that constant with real value)

3. Now run the ant script from command line specifying the target according to the version of JBoss you are using.

   >> ant deploy-jbossXXX  (replace XXX with your version of jboss)
   >> ant deploy-jboss510

It will run the build.xml file and execute all the tasks mentioned in it in the specified manner. If at the end, it prints BUILD SUCCESSFUL, then it means that you have successfully installed the web service pack. :-)

To confirm that it has installed correctly, check the following url (assuming that JBoss works on 8080 for you): http://localhost:8080/jbossws/

If you see a picture similar to what is embedded here, it means that JBossWS Web Service Pack is installed successfully on your system and you are ready to create more. This URL acts as a console to manage your currently deployed web services.

Note:

It is not necessary that you need JBoss to deploy JAX-WS Web Services. With the advent of JDK1.6, you can also use Tomcat server to host these web services as JDK1.6 is already shipped with JAX-WS jars, although the procedure to create and deploy such services will differ from that of JBossWS. 

In the next blog entry, I would give an example of creating a simple web service using JBossWS Web Services. The actual purpose of this blog entry is to prepare you for the big picture !!

Resources:

1. Introduction to Web Services (Must read for any Beginner)
2. Web Services Architecture
3. JAX-WS Reference Implementation (a really detailed one !!)
4. Comparison between JAX-WS and JAX-RPC
5. Download JDK1.6
6. Download ANT
7. Download JBoss Application Server
8. Download JBossWS-Native (Web Service Stack)