This recipe describes how to implement web services in Apache Axis2. We will show you how to implement the Axis2 annotated web service, and deploy it to the Axis2 server. We will explore the typical lifecycle of a web service.
We use the Eclipse IDE (Eclipse IDE for Java EE Developers Version) for the development of web services. We also need the Apache AXIS2 package for the web service deployment.
Note
Oracle also provides the Oracle Enterprise Pack for Eclipse for those who prefer the Eclipse IDE over the JDeveloper IDE. The package can be found at http://www.oracle.com/technetwork/developer-tools/eclipse/overview/index.html?ssSourceSiteId=ocomen.
The following steps present the creation, packaging, and deployment on the Axis2 server, and the testing procedures in the lifecycle of a web service:
- We will start by creating the project in Eclipse. In the New Java Project wizard, we just enter the project name, and then click on Finish, since we do not need anything special in the project.
- We add the POJO class into our project. For our example, we want to prepare a web service that will return the list of hotels that still have available rooms at the given period. We simply create a class with the following code:
import java.util.Calendar; public class BookHotel { public String[] availableHotels(Calendar from, Calendar to) { String[] result = {"Ramada Plaza", "Plaza", "Hilton"}; return result; } }
We simplified the business code of web service so that no database queries are performed.
- Now we need to decorate the code for our POJO (Plain Old Java Object) to become a web service. We annotate the class, name web service, and define the target namespace using JAX-WS as follows:
@WebService(targetNamespace = "http://www.packt.org/book/hotel", name = "HotelBooking")
- We also need to annotate the class method as follows:
@WebMethod(action = "urn:availableHotels", operationName = "availableHotels") public @WebResult(partName = "hotels") String[] availableHotels(@WebParam(partName = "fromDate") Calendar from, @WebParam(partName = "toDate") Calendar to)
We define the action and operations parameters via the
@WebMethodannotation. We annotate the returning variable with the@WebResultannotation. Finally, we annotate the parameters of the method with the@WebParamannotation.We are now ready to deploy our web service to the Axis2 module in the Oracle SOA Suite.
- For deployment purposes, we create an ant build file. We utilize the ant copy task for copying our web service class file to the server as follows:
<copy file = "./bin/BookHotel.class" todir = "<Axis2Server> /repository/pojo"/>
We can check the deployment status in the Axis2 management console. We see that our web service was successfully deployed as shown in the following screenshot:
- We test web service from Eclipse. We use Web Services Explorer. First, we select the WSDL pane, enter the WSDL location of the web service, and click on Go.
As a result of the web service execution, we see the complete SOAP envelope, with the response in the SOAP Body as follows:
<soapenv:Envelope xmlns:soapenv = "http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Body> <dlwmin:availableHotelsResponse xmlns:dlwmin = "http://www.packt.org/book/hotel" xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance"> <hotels xmlns:xs = "http://www.w3.org/2001/XMLSchema" xsi:type = "xs:string">Ramada Plaza</hotels> <hotels xmlns:xs = "http://www.w3.org/2001/XMLSchema" xsi:type = "xs:string">Plaza</hotels> <hotels xmlns:xs = "http://www.w3.org/2001/XMLSchema" xsi:type = "xs:string">Hilton</hotels> </dlwmin:availableHotelsResponse> </soapenv:Body> </soapenv:Envelope>
We get three hotels that have available rooms in the specified time frame.
Axis2 concentrates on developing web services based on POJO. That way the developer implements the business logic into a Java class, which is later annotated, and becomes a web service.
With annotations it is possible to fully describe the web service class. There is absolutely no need to add any additional description files. Axis2 also enables the deployment of the exploded web service package; that is web services that are not packed into the JAR file. We simply drag-and-drop the class file to the Axis2 server, which is also called the hot-deployable method.
The development of web service in this recipe had the requirement that the class had to be in the default package. That way we can build the class hierarchies at the default package level only, but we cannot organize the classes into the packages. But usually, we want to have our classes packed into the package. For that purpose, Axis2 requires that we provide the web service description file, named services.xml. The file contains the configuration describing the web service, such as the name of the web service, its operations, message receivers, target namespace, and so on.
We will now create another web service that will enable the hotels to trade the price of the room relative to the stocks traded on the stock exchange.
- We will create the data class for the room price. We will be able to check the bid, ask, and mid-price of the room as follows:
package org.packt.ws.axis; public class RoomPrice { private int ask = 0; private int bid = 0; private int mid = 0; } - Now, we will define the web service class that will retrieve the prices of the room as follows:
package org.packt.ws.axis; public class RoomPriceService { private RoomPrice price; public RoomPrice getPrice() { return price; } public void setPrice(RoomPrice price) { this.price = price; } } - Now, we must describe the web service before deploying it. For that purpose, we create
services.xml, and put it into theWEB-INFdirectory of the project as follows:<service name = "RoomPriceService" scope = "application"> <description> Prices of trading for room </description> <messageReceivers> <messageReceiver mep = "http://www.w3.org/2004/08/wsdl/in-out" class = "org.apache.axis2.rpc.receivers.RPCMessageReceiver"/> </messageReceivers> <parameter name="ServiceClass"> org.packt.ws.axis.RoomPriceService </parameter> </service>We see that
services.xmldefine the name of the web service. We also define how the interface interacts with the client via themessageReceiverelement. We have defined theIN-OUTtype of communication, since the client will call the web service and also receive information from the web service. - Prior to deploying the web service, we have to pack it in the AAR library (the name comes from Axis Archive). We will do this by modifying our
build.xmlfile; add lines for packing our files into AAR, and move it to the final server location as follows:<target name = "pack"> <echo message = "creating jar"/> <jar destfile = "build/RoomPriceService.aar"> <fileset dir = "classes"/> <fileset dir = "jar"/> <!—- contains META-INF dir --> </jar> </target>
We see the next project outlook in Eclipse as shown in the following screenshot:
