Apache Axis2 java2wsdl Usage - Graphical Tool

It seems that quite a few people are having trouble using the java2wsdl tool that comes with Axis2. Using a command line tool can be tricky for some users... but wait there is a graphical tool for this too. WSO2 WSAS (Web Services Application Server) has a graphical tool that wraps the java2wsdl utility in Axis2. You can either try it out by downloading WSAS (WSO2 WSAS is open source and available under Apache License v2.0) or if you are in a hurry you could try the java2wsdl graphical tool online. This tool takes you through a wizard like approach and is much easier to use (The tool hosted online is based on WSO2 WSAS 2.3 which is in turn based on Axis2 1.3 with a few bug fixes). You could fine a lot more tools that could help you at http://wso2.org/tools.

For the geeks who do not want to use the graphical tool this is how the command line utility can be used. Simple executing the java2wsdl script without any arguments would show you its usage,

keith@keith:/opt/axis2-1.4.1/bin$ sh java2wsdl.sh
Using AXIS2_HOME: /opt/axis2-1.4.1
Using JAVA_HOME: /opt/software/java/jdk1.5.0_06
Usage: java2wsdl [options] -cn <fully qualified class name>

where [options] include:
-o <output location> output directory
-of <output file name> output file name for the WSDL
-sn <service name> service name
-l <soap address> address of the port for the WSDL
-cp <class path uri> list of classpath entries - (urls)
-tn <target namespace> target namespace for service
-tp <target namespace prefix> target namespace prefix for service
-stn <schema target namespace> target namespace for schema
-stp <schema target namespace prefix> target namespace prefix for schema
-st <binding style> style for the WSDL
-u <binding use> use for the WSDL
-nsg <class name> fully qualified name of a class that implements NamespaceGenerator
-sg <class name> fully qualified name of a class that implements SchemaGenerator
-p2n [<java package>,<namespace] [<java package>,<namespace]...
java package to namespace mapping for argument and return types
-p2n [all, <namespace>] to assign all types to a single namespace
-efd <qualified/unqualified> setting for elementFormDefault (defaults to qualified)
-afd <qualified/unqualified> setting for attributeFormDefault (defaults to qualified)
-xc class1 -xc class2... extra class(es) for which schematype must be generated.
-wv <1.1/2.0> wsdl version - defaults to 1.1 if not specified
-dlb generate schemas conforming to doc/lit/bare style

Most often that not you wont be using most of these options. Assuming that your,
output directory is /home/keith/projects/axis2_rest/resources/
output Filename is StudentService.wsdl
service name is StudentService
classes are in the directory /home/keith/projects/axis2_rest/classes
service implementation class is prg.apache.axis2.StudentService
you need WSDL 2.0

your usage of java2wsdl would be,

sh java2wsdl.sh -wv 2.0 -o /home/keith/projects/axis2_rest/resources/ -of StudentService.wsdl -sn StudentService -cp /home/keith/projects/axis2_rest/classes/ -cn org.apache.axis2.StudentService

REST and WSDL 2.0 Discussion continues

In response to my blog post on using WSDL 2.0 to describe RESTfull services and Sanjiva's challenge Stefan has put forward 5 questions for me. Here are the answers to them.

Question: How does one one describe representation formats other than XML?
Answer: This can be done using the whttp:inputSerialization (for input messages), whttp:outputSerialization (for outgoing messages) and whttp:faultSerialization (for outgoing faults). The WSDL 2.0 Adjuncts spec defines three types of serializations. They are application/x-www-form-urlencoded, application/xml and multipart/form-data. Axis2 supports all three of these as well as JSON messages (This is how you can send JSON messages using the Mashup Server). At WSO2 we are considering doing a JSON binding for WSDL. If we had that in place even this could be described in a standard manner.

Question: How is content negotiation supported?
Answer: WSDL cannot describe this (neither do I expect it to), but we do have content negotiation support in Axis2. Due to some practical limitations we had to make it an optional feature. This can be made available by adding the following parameter to the axis2.xml.

<parameter name="httpContentNegotiation">true</parameter>


Question: How does one describe whether a URI parameter is a query parameter, path element, or matrix parameter?
Answer: There are a few properties and defaulting rules that help you achieve this. As my example shows parameters can me made to go in the path or query section using templates. An example template for sending the parameter "name" in the path segment would be "student/{name}" while sending a parameter as a query parameter would be "student?name={name}". This section in the adjuncts spec give a brief idea as to where the parameters not cited would appear. If application/x-www-form-urlencoded serialization is used on a GET all parameters not cited in the template would go in as query parameters. There is a additional property in WSDL 2.0 that helps you control this too. If you specify whttp:ignoreUncited="true" then all uncited parameters will be dropped.

What do you really mean by matrix parameters?

Question: Is there a way to describe response codes?
Answer: WSDL 2.0 does not allow you to specify the http response code of a outgoing message. Too bad we missed this (I wonder whether the working group had discussed this issue though). I guess this is the one thing that WSDL 2.0 missed. Hence I opened a issue against the spec. But WSDL 2.0 allows you to set http codes on fault messages. For e.g on a fault you could say whttp:code="402".

Question: What about describing hypermedia? :-)
Answer: In my example you would have noticed that I actually return a set of links to where the actual resource exist when invoking some operations. For e.g getAllCustomers would return links to the actual customers. I agree that there is something missing in here, a way to describe that accessing this link returned, would fetch you the customers details (Probably an annotation in the schema could describe this).

Stefan had mentioned the following in his post

"One of the interesting aspects is the try out page, which is generated from the WSDL. Essentially this means that metadata is used to generate the self-descriptive form; somewhat backwards from a REST perspective, but understandable given that the goal was to have an external description in the first place."

Yes the WSDL captures all the metadata of your service. Don't you think that there is a definite advantage in having a standard description for your service? This would enable users to build tools that would make life easy when accessing such services. The tryit is an good example of this. You could even build a UI for a service using a generated JavaScript stub. The UpgradeChecker sample on mooshup is a good example for this.

Its good to have a constructive discussion around REST, SOAP and WSDL rather than try to proclaim that one of them is the way to go and the other does not have a place.

Sending IM Messages via Yahoo using the Mashup Server

[Note: also published on the Mooshup.com blog.]

If you try to send IM messages using a yahoo account in the WSO2 Mashup Server you may encounter the following error.

Fault: Cannot find yahoo library in the class path. Please make sure its in the classpath.

The reason for this could either of the following,

• The yahoo Library in not in your classpath - Download the latest version from YMSG
• You have the yahoo library in your classpath but its an old version. You need to have the latest version in your classpath to get this working.
  

Now that you have the latest version of the Yahoo messaging library in your classpath its time to test it out.
Here is a simple client for sending a IM message via yahoo,

function IMExample(){
   var im = new IM("yahoo");
   im.login("username","password");
   im.sendMessage("keithgodwinchapman","Hi, This was sent from the WSO2 Mashup Server!");
   im.disconnect();
}

For more details on sending IM messages using the WSO2 Mashup Server please refer the "Sending Instant Messages via Mashup Server" article.

You may have noticed that this sample is very similar to Sending MSN messages using the Mashup Server.
It is indeed the only difference is the argument you pass into the constructor of the IM host object. Have fun sending IM's using the WSO2 Mashup Server!

RESTfull Mashup with WSDL 2.0 - WSO2 Mashup Server

I was looking around for REST stuff related to Axis2 and stumbled upon one of Stefan Tilkov’s blog post (An old one at that). In that post Stefan had asked somebody to show a WSDL 2.0 document that describes this RESTfull scenario.

Too bad I didn't come across this back then, but as the saying goes better late than never. WSDL 2.0 can describe this scenario easily and I thought of writing a WSDL 2.0 document for this scenario (I've made one change to the URLS used in the scenario, instead of customer/{id}/orders I've used customerorders/{id}. This is not due to a limitation in WSDL 2.0 but rather the implementation of Axis2).

I put all these details together and built a little Mashup (which I named RESTDemo) that runs on the WSO2 Mashup Server. Of course the WSO2 Mashup Server has the ability to build RESTfull Mashups. In order to make it accessible to others I've uploaded it to Mooshup.com our community site.

Note : I have made some assumptions on how an Order and a Customer will be described. My assumptions is that an Order is described by an id (String), customerID (String), details (String), amount (Double), items (String array). A customer will be described as id (String), name (String), address (String), email (String).

The main objective of putting this Mashup together was to demonstrate that this RESTfull scenario can be described using WSDL 2.0. The WSDL 2.0 for this mashup can be accessed from the Mashup page, you could choose either the annotated view or the raw view.

The all important section in the WSDL is the HTTPBinding , cause this is where all the information for accessing this service via REST lies. Ideally I would have loved to make the content-type (whttp:inputSerialization in WSDL 2.0 terms) of a few of the operations application/x-www-form-urlencoded (WSDL 2.0 defaults it to application/xml) . But unfortunately as of now the Mashup Server does not offer a mechanism to do this. I've already opened a JIRA so that this could be added.

You might also want to try out our RESTfull mashup. Simply goto its tryit page in order to try it out (The tryit page allows you to test your mashup and a drop down at the top allows users to select the endpoint they want to access, in our case we may prefer to choose the HTTPEndpoint cause this is all about REST). Now this is where the benefit of a standard description (WSDL 2.0) for our RESTfull mashup kicks in. The tryit page is auto generated off the WSDL 2.0 doc (It has all the information as to how this mashup can be accessed, let it be SOAP 1.1, SOAP 1.2 or REST). The tryit page invokes the service using a auto generated JavaScript Stub.

Let me now explain as to why I had to change the URL mapping for get all customer orders. Axis2 (Which is what the WSO2 Mashup Server is built on) dispatches to the correct operation (when REST is used) using the http method and the URL of the request (The service is always found using the request URL). Now when we try to figure out the operation the request is headed to we basically do some pattern matching, and thats done against the first constant part we get off the httpLocation. In the scenario given it allows a GET on customer/{id}/orders as well as customer/{id}. Now if I used these two templates as it is, there would have been dispatching issues, hence I decided to change the second template.

This has become quite a long blog post. If you are interested in knowing how WSDL 2.0 can be used to describe RESTfull services stay tuned to my blog. I plan to write more on this topic in the time to come. Also there is a RESTfull services on Axis2 tutorial which is just around the corner.

Note : Mooshup is running the 1.5.1 version of the WSO2 Mashup Server (released before Axis2 1.4.1). There fore its REST URLs are of the format http://mooshup.com/services/keith/RESTDemo.HTTPEndpoint/customer/123, in the next version which will be based on Axis2 1.4.1 the URLs of the form http://mooshup.com/services/keith/RESTDemo/customer/123 would also work.

XML Schema - Import or Include?

I'm sure people who work with XML Schema or WSDL for that matter have hit this issue at some point. The dilemma weather to use Include or Import? I came across this article that helps solve this problem. Hope that it will come in handy for you too.

Basket Ball @ WSO2 in Full Swing

Work while you work,
Play while you play,
This is the way
To be happy each day.

Thats exactly what we do at WSO2, although we do play a bit while we work as well ;).

We are having a Basket Ball tournament at WSO2 these days. The tournament is in full swing as we draw near to the business end of the tournament, the Finals and Third place play offs. Quite a few of our guys (Tyrell, Ruwan Janapriya, Saliya) have been busy taking photos as well.

As with any tournament we've had our fair share of Injuries too. Sameera - a twisted ankle, Chanaka - a cracked lip, Sanjaya Ratnaweera - a dislocated wrist and the latest victim Sumedha with a sprained ankle. Oh and I almost missed poor Devaka who is suffering from a Sore finger and a sore toe ;).

I'm sure this first aid tips that Sumedha had got from his doctor would come in handy in the coming weeks.

Attachments - MTOM, SWA and Base64Binary Compared

Sending Attachments in Web Services is a common use case and there are various ways in which this objective could be achieved. Sending the Attachments as MTOM (SOAP Message Transmission Optimization Mechanism), SWA (SOAP with Attachments), or Base64Binary are some of your options.

Here is a simple comparison between these 3 options.

• base64Binary sends the attachments as base64 inline in the SOAP message. i.e. The Attachment in embedded in the SOAP Message. Bloats the message by 33%.
  
• SWA sends the Attachment outside the SOAP message (The SOAP message contains a reference to the attachment). But the SOAP infoset does not contain the attachment
• MTOM Provides the best of both world. The Attachment is sent outside the SOAP message with a reference to it but the attachment appears as if it is embedded in the SOAP message (The SOAP infoset contains the attachment)

Due to the fact that attachments sent using MTOM appear as it the attachment is part of the SOAP message it allows you to use other WS-* QOS (Quality of Service) attributes. For e.g MTOM messages can be signed and encrypted using WS-Security. Thus this provides a mechanism to send Secured Attachments without the need for additional specs.

Axis2 as well as (WSO2 WSAS) supports all three of the above mechanisms. In a later post I will describe how each of the above can be used and how the actual wire messages look.