Simple Web Service with JBoss AS

Introduction

What is a Web Service?

Web service is a application that provide client application to use server applications methods. Assume you have a simple java programme with several classes. You can use those classes only inside your programme( or you have to include them as lib files). If you develop your programme as web service and host it in a application server, then client programms can use those classes( actually the methods inside those classes) via a network. Special thin about web services is it is platform independent. That means you may develop your web service using java, but clients that use the web service need not to be java, it may be .Net or any other language. 

How it works

When we publish a web service to a application server, we can get a xml document called WSDL(there are several technologies, but for this article I make things simple). This is the key to the web service, it contains all the method signatures, what is the address that web service can access, what are the protocols used etc. When creating client side we use this document to specify way of communication with the server application. Then how the platform independence comes into action? When we sending messages we use a protocol, that means both sides knows what they are sending and receiving. When a client needs to request something from server it converts its message to that protocol, when server side get the request it converts it back to original version that the server application can understands. Same thing happens with the other way of communication. Most popular protocol is SOAP. You can read more from here

Things we need

• JDK 1.5 (or higher).
• JBoss App Server.
• Apache Maven (Read this how to install maven)
• IDE (I used Intellij Idea 12.0)

If you are using JBoss 5.0.0 or lesser version please make sure you install JBoss WS framework to your application server. Read this article to install those applications on to your pc.


For the rest of this article I assume you have installed and configured above things correctly.

Folder structure for web application (war)

Server can identify our application as web application, if we bundle the classes and other necessary files in the following manner. At the end of the this article I'm going to bundle all the necessary files into .war file using Maven build tool.

• classes folder contains all the classes in our application.
• lib folder contains all the libraries that need for the application
• web.xml file contains instructions to the server that which classes need to be loaded when web service is in action.
• for our discussion let's forget about other files/folders

Implementation

•  Create a java project (make sure you don't select any project modules such as web services, web services clients etc. for the first time we are going to start from the scratch)
• Then right click on the project name in Intellij and select add framework support, select maven and click ok.
• Now you have a clean maven java project. 

Now you have a project with pom.xml file. Folder structure should look like this.

• Right click on your java folder (in Intellij project tab) and select New > Package
• Give your package a name. ( I gave com.webservice)
• Now right click on main folder and select New>Directory. create a directory called webapp and inside that create a directory called WEB-INF (this is the folder that contains web.xml file so give names exactly as above)

Now we are ready to go.

Create a class in com.webservice package

This is the class that our web service methods are implemented.

Now we can implement methods for our web service. Let’s create helloworld method that returns a string.

Now we need to make this class a web service class and this method a web service method. We can do it by adding annotations.  Just before your class name add @WebClass and before your method name add @Webmethod. After adding those annotations it will not recognize by our program, put cursor on those words and press Alt+enter to import  javax.jws.WebMethod and javax.jws.WebService.

Here is the WebClass

 package com.webservice;  
 import javax.jws.WebMethod;  
 import javax.jws.WebService;  
 /**  
  * Created by IntelliJ IDEA.  
  * User: Chann  
  * Date: 1/15/14  
  * Time: 9:58 PM  
  * To change this template use File | Settings | File Templates.  
  */  
 @WebService  
 public class WebClass {  
     @WebMethod  
    public String helloWebService(String name){  
      return "Hello "+ name;  
    }  
 } 

Now create a file named web.xml inside WEB-INF folder and add followings to that file. This is the file that contains details about our web service to server. <servlet-class> tag defines the classes that are related to web service. Let’s postpone to discuss about url-patterns and other stuff.

 <web-app>  
   <servlet>  
     <servlet-name>HelloWebService</servlet-name>  
     <servlet-class>com.webservice.WebClass</servlet-class>  
   </servlet>  
   <servlet-mapping>  
     <servlet-name>HelloWebService</servlet-name>  
     <url-pattern>/*</url-pattern>  
   </servlet-mapping>  
 </web-app>  

Now it’s almost done coding our web service. Now we need to build these classes and package them to a war file to deploy in JBoss server

We use maven to build our project. We have a pom.xml file in our project. Let’s modify it to do our job.

We need to package our web service as a war file. That is done through the <packaging> tag.

 <project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0" xsi:schemalocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">  
   <modelversion>4.0.0</modelversion>  
   <groupid>groupId</groupid>  
   <artifactid>WebService</artifactid>  
   <version>1.0-SNAPSHOT</version>  
   <packaging>war</packaging>  
   <dependencies>  
     <dependency>  
       <groupid>com.sun.xml.bind</groupid>  
       <artifactid>jaxb-core</artifactid>  
       <version>2.2.8-b01</version>  
     </dependency>  
     <dependency>  
       <groupid>com.sun.xml.bind</groupid>  
       <artifactid>jaxb-impl</artifactid>  
       <version>2.2-promoted-b65</version>  
     </dependency>  
   </dependencies>  
   <build>  
     <plugins>  
       <plugin>  
         <artifactid>maven-war-plugin</artifactid>  
         <version>2.4</version>  
         <configuration>  
           <packagingexcludes>WEB-INF/lib/*.jar</packagingexcludes>  
         </configuration>  
       </plugin>  
     </plugins>  
   </build>  
 </project> 

we need to add the war plugin to make a war using maven. That is the reason to add maven-war-plugin to our pom.xml file. We need to add <packagingExcludes> tag to bundle our WEB-INF folder without addional jar files(some times it gives errors if we keep those jar lib files inside WEB-INF folder). And additionally we need to add two dependencies to work properly. Now we can make our project. Either click package in maven life-cycle in Intellij idea(in left side) or open project folder via cmd prompt ( open cmd prompt and navigate to project folder) and then type maven clean install, press enter. You can find the war file in target folder inside project folder.

Now you can put this war file inside JBoss>Server>default>deploy folder. And run the Start.bat file inside JBoss > bin folder to start the server.

Now your web service is in action.