WebServiceServlet (WSS) user guide

17.9.2010 Copyright(c) Michael Kankkonen www.vnetcon.org

Content
Index.......................................................................................................................................3 WSS WebServiceServlet.......................................................................................................3 License...................................................................................................................................3 Live picture of WSS wsdl on Google App Engine .................................................................3 Quiq start for creating WSS Web Serivce..............................................................................4 Create Google App Engine project without GWT..............................................................4 Create MyWebService.java file into package org.vnetcon.wss.test..................................4 Create Employee.java file into package org.vnetcon.wss.test..........................................4 Add following configuration to just created web.xml..........................................................5 add wss-0.5b.jar to projects classpath. ............................................................................5 Create schema file for classes you use in your Web Service. .........................................5 Start Google App Engine development server..................................................................6 1 .point your browser at http://localhost:8888/wss........................................................6 2. To see the wsdl for your webservice add ?wsd to url................................................6 3. to see xsd used with this webservice add ?xsd=1 to url...........................................6 Now your done. .................................................................................................................6 Creating client java code for calling WSS Web Service from client side...............................7 wsimport.............................................................................................................................7 Example client....................................................................................................................7 WSS little deeper...................................................................................................................8 What Web Service actually is?..........................................................................................8 Why I have to create schema file for WSS?......................................................................8 How web methods are called?..........................................................................................8 Supported datatypes and java classes..............................................................................9 How to use complex java objects like byte[], ArrayList, HashMap?..................................9 About class annotations.....................................................................................................9 WSS vs. Standard Web Service..........................................................................................10 Misc......................................................................................................................................10 About namespaces..........................................................................................................10 About method names.......................................................................................................10 About content...................................................................................................................10 XMLGregorianCalendar, Qname, Duration behavior......................................................10 About coding....................................................................................................................10 Deploying to Google App Engine.....................................................................................11

Index
User Guid for developers to create WSS (WebServiceServlet) based WebServices.

WSS WebServiceServlet
WSS is a regular servlet that can be run on any servlet container like Google App Engine, Tomcat, Glassfish etc. WSS acts to outer world like any simple regular Web Service.

License
WSS is licensed under GPL.

Live picture of WSS wsdl on Google App Engine

Below is a live picture of WSS actually running on Google App Engine. The wsdl in following picture is from example application described in this document later.

Quiq start for creating WSS Web Serivce

These steps are recorded from our tests creating WSS Web Service from scratch as end user. We used Eclipse and Google App Engine web project as project type. We assume that you are already familiar with developing servlets.

Create Google App Engine project without GWT

Create the project using following package: org.vnetcon.wss.test

Create MyWebService.java file into package org.vnetcon.wss.test

package org.vnetcon.wss.test; import org.vnetcon.wss.test.dao.Employee; public class MyWebService { public MyWebService(){ } public String addEmployee(Employee emp){ return "ok: emplyee added"; } }

Create Employee.java file into package org.vnetcon.wss.test

package org.vnetcon.wss.test.dao; import javax.xml.bind.annotation.XmlRootElement; import javax.xml.bind.annotation.XmlType; @XmlRootElement @XmlType(name="Employee") public class Employee { String fname; public Employee(){ } public void setFirstName(String value){ this.fname = value; } public String getFirstName(){ return this.fname; } }

Add following configuration to just created web.xml

<servlet> <servlet-name>WebServiceServlet</servlet-name> <servlet-class>org.vnetcon.xml.ws.servlet.WebServiceServlet</servlet-class> <init-param> <param-name>WebServiceClass</param-name> <param-value>org.vnetcon.wss.test.MyWebService</param-value> </init-param> <init-param> <param-name>SchemaFilePath</param-name> <param-value>/org/vnetcon/wss/test/schema1.xsd</param-value> </init-param> </servlet> <servlet-mapping> <servlet-name>WebServiceServlet</servlet-name> <url-pattern>/wss/*</url-pattern> </servlet-mapping>

You may remove the "startup servlet config" from web.xml and also delete the "startup servlet java file" from project

add wss-0.5b.jar to projects classpath.

Make sure you have it in your war/WEB-INF/lib folder too.

Create schema file for classes you use in your Web Service.
In this example case for Employee.java 1. 2. 3. 4. open dos command prompt navigate to your projects src folder type: schemagen org.vnetcon.wss.test.dao.Employee copy created schema1.xsd to your war/WEB-INF/classes/org/vnetcon/wss/test directory

Start Google App Engine development server

Start your development server so you can access the WSS servlet with your browser and wsimport and client application.

1 .point your browser at http://localhost:8888/wss

If everything went fine you should see WebService start page.

2. To see the wsdl for your webservice add ?wsd to url

http://localhost:8888/wss?wsdl Please note that Google Crome don't show xsm content at all like Mozilla or IE do.

3. to see xsd used with this webservice add ?xsd=1 to url

http://localhost:8888/wss?xsd=1 Please note that Google Crome don't show xsm content at all like Mozilla or IE do.

Now your done.

All you have to do is to create client side for this service :) To do this open dos prompt and type wsimport -keep http://localhost:8888/wss?wsdl The -keep parameter saves generated .java files. Without it you will get only .class fiiles. this will create automatically java classes you can import to your project and start making webservice calls from your application.

Creating client java code for calling WSS Web Service from client side
The most common way to do this is to autogenerate the code using IDE's build in functionalities. Here we do it on command line using java's wsimport program.

wsimport
Create Web Service client code with two easy step 1. Open dosprompt and navigate to directory where you want to generate client code 2. type: wsimport -keep http://localhost:8888/wss?wsdl Now your done. If everything went well you should have generated code in your direcotry which you can import to your project.

Example client
Below is a simple client program where our example WSS Web Service call is made from client code. Note that wsimport generated code is imported to this client code.
package org.vnetcon.wss.testclient; import org.vnetcon.wss.test.Employee; import org.vnetcon.wss.test.MyWebService; import org.vnetcon.wss.test.MyWebServiceService; public class WSSExampleClient { public static void main(String[] args){ try{ MyWebServiceService mwss = new MyWebServiceService(); MyWebService myws = mwss.getMyWebServicePort(); Employee emp = new Employee(); String s = myws.addEmployee(emp); System.out.println("WebService returned: " + s); }catch(Exception e){ e.printStackTrace(); } } }

WSS little deeper

Here are some notes about WSS littel deeper that just from quiq start point of view. These are ment to help users understand WSS's behaviour little bit deeper and give some guidelines how to solve possible challanges.

What Web Service actually is?

For WSS Web Service is a regular java class which public methods are treated as Web Service methods. Normal Web Services are declared with @WebService annotation but because this annotation can not be used on Google App Engine this annotation is replaced with web.xml configuration (WebServiceClass -parameter).

Why I have to create schema file for WSS?

Web Service calls are xml based. WSDL and XSD=1 are used to identify what kind of xml messages WSS will send and accept. Easiest way to declare complex classes as xml is to use JAXB. WSS uses JAXB generated xsd file as base when creating wsdl and xsd=1 inforamtion for clients.

How web methods are called?

WSS uses java reflection for invoking methods from declared java class. Shortly the process is following: 1. 2. 3. 4. 5. 6. WSS receives client call (SOAP + XML message) WSS parses from message method name and parameters parameters are unmarshaled using JAXB to native java objects WebService method call is done sing reflection method call Methods return value is marshaled using JAXB JAXB return xml is packed into soap message which will be send as reply to client

Supported datatypes and java classes

WSS supports all primitive java types. Below is a list of xsdjava mapping WSS use for these. In this list are also "native like" java classes that are treated in xml as primitive types. Java String BigInteger int long short BigDecimal float double boolean byte QName XMLGregorianCalendar Duration Schema string integer int long short decimal float double boolean byte QName dateTime duration

How to use complex java objects like byte[], ArrayList, HashMap?

WSS don't support these types directly. Instead you should create wrapper class around these types and let JAXB take care of creating proper xml for these types.

About class annotations

All your classes that you use in web service must be declared with annotations and must be added to schema file using schemagen. If you have several classes e.g Employee, Address, Location you can add all them to same schemafile running schamagen as following schamegen Employee Address Location Each class must have @XmlRootElement annotation and XmlType annotation. XmlType annotation must have name="Classname" where Classname is exactly same name that the class (e.g. @XmlType(name="Employee")

WSS vs. Standard Web Service

WSS is not a standard Web Service with ws-security (just noticed that this is called also WSS :) ), advanced soap messaging and all features standard web services might offer. WSS is a simple frontend for invoking methods using java reflection and jaxb and it looks like Web Service to outer world.

Misc
About namespaces
When you create your web service you might have different packages on your code (e.g. mainpackage, dao package, util package etc.). When WSS generates wsdl and xsd=1 information to client all these classes are put to same namespace which is your webservice package. In general this means that you must not have classes with same name even they are in different packages.

About method names

In java you can have same method name several time in same class if the parameters are different. Unfotunately this don't work in WSS (and I think in Web Services in general). If you have same method names the wsimport will give you an error message about this. In general this means that you must use different method names for each public method in your Web Service class.

About content
WSS uses regular expression when cleaning namespaces from xml. This might cause some unwanted behaviour if your data contains xml like text (e.g. <sfda:). If you need to send xml in your messages we suggest you create a wrapper class where you put your xml as binary data when making web service calls.

XMLGregorianCalendar, Qname, Duration behavior

WSS creates these classes using the constructor that take string as parameter. Retrieved data will be give without any modifications to this constructor.

About coding
WSS generates for each method both parameters and return messages in wsdl. So you should always return something from your methods. We think that this is in general good to do so the caller will always get some kind of information about the method call and if it was successful.

Deploying to Google App Engine

If you can run your web service on development environment but for some reason your web service don't work on Google App Engine the most likely reason for this is that you have not schema file in deployment package or you have configured it wrong.