Automatically Generated Resources

Table of Contents

Just by virtue of deploying the service, the WSO2 mashup server generates a number of descriptive artifacts and tools to make it easy to consume the web service you've just created.  These artifacts are linked from the management console for the service, or can be accessed directly from the endpoint URI associated with the service.  Typically the endpoint URI is http://{host ip}:7762/services/{service name}, where the service name is by default the name of the JavaScript file defining the service (minus the '.js').  By appending one of the following queries to the endpoint URI, different artifacts and tools can be accessed:

?wsdl2	WSDL 2.0 description of the service
?wsdl	WSDL 1.1 description of the service
?xsd	XML Schema description of the service
?stub	JavaScript or E4X stub for accessing the service
?tryit	Ajax client for simple, generic interactions with the service
?source	The JavaScript source code for the service
?doc	Documentation for the service

WSDL (?wsdl2, ?wsdl)

By appending '?wsdl2' to the endpoint URI, you can retrieve an automatically-generated WSDL 2.0 document describing the service.  For the helloworld service, try http://localhost:7762/service/helloworld?wsdl2. The WSDL describes the operations the service exposes, the structure of the XML that is sent and received by each operation, and how to communicate with the service to retrieve the XML content.  By default, six different types of endpoints are deployed.  Each of these endpoint types are represented by the WSDL 2.0 <endpoint> elements of the service, and by the <binding> elements which these endpoints refer to.  The default six types of endpoints are:

1. SOAP 1.2 over HTTP
2. SOAP 1.1 over HTTP
3. Plain old XML over HTTP
4. SOAP 1.2 over HTTPS
5. SOAP 1.1 over HTTPS
6. Plain old XML over HTTPS

One can also get a WSDL 1.1 description of the service by appending '?wsdl' to the endpoint URI.  For the helloworld service, try http://localhost:7762/service/helloworld?wsdl.

For more information on precisely how the Mashup Server generates WSDL, see JavaScript Annotations.

XML Schema (?xsd)

Although accessing '?wsdl' or '?wsdl2' gives you a service description that includes an XML Schema description of the XML structure, you can also ask for the XML Schema separately using the '?xsd' option.  For the helloworld service, try http://localhost:7762/services/helloworld?xsd.

JavaScript Stubs (?stub)

Most Web Service toolkits can successfully use the WSDL description to provide a nice programming model for accessing the service.  For instance, WSO2 Web Services Application Server (WSAS) provides a utility wsdl2java which generates Java code for interacting with the service in a manner friendly to Java programmers.

Similarly, the Mashup Server provides a tool for interacting with a service in a manner friendly to JavaScript programmers.  The '?stub' option returns a JavaScript file that can be included in a Web page or another mashup service to make interacting with the service easy and natural.  For example, if a web page is to interact with the hello world service, you only have to include the stub and you can use the WSRequest object -- available natively in the Mashup Server, or in the browser through an ActiveX control (IE), XPI plugin (Firefox), or a simple version in native JavaScript (shown below) -- to call the Web service simply and naturally.

<script type="text/javascript" src="/js/wso2/WSRequest.js"></script>
<script type="text/javascript" src="/services/helloworld?stub"></script>

<script type="text/javascript">

    function callhelloworld() {
        try {
            helloworldReturn = helloworld.hello();
        } catch (e) {
            alert(e)
        }
        // do this in IE
        alert(helloworldReturn.documentElement.xml);
        
        // Firefox-specific way to serialize XML
        alert(helloworldReturn.documentElement.textContent);
    }
</script>

....

<input type="button" value="say hello" onclick="callhelloworld()"></input>

 

The '?stub' option further more accepts additional parameters:

• lang: Whether the stub should use native E4X XML datatypes, or use DOM to represent XML.  The value 'e4x' indicates that native E4X datatypes should be used, the values 'js', 'ecmascript', and 'javascript' are synonymous terms for indicating that XML should be exposed through the DOM.
• service: When a WSDL 2.0 document from which the stub is generated contains more than one <service> element, this parameter can be used to select which service to build a stub for.  By default the first <service> is used.  When writing services in JavaScript, each file corresponds to a single service.

For more information on using stubs, especially on using them asynchronously, see Using Stubs.

Try-it (?tryit)

The first thing you might want to do with your new service is try it out.  The '?tryit' option provides a quick and easy way to exercise the service right out of the box.  The try-it window for a service might look something like this:

You can choose the operation you'd like to invoke from the list on the left hand side, fill in the necessary parameters, and invoke the operation to view the result.  If you need more typing space (for instance, the parameter takes a blob of XML) you can expand the size of the input field by clicking on the small icon in the lower right corner of each field.

A few notes about the Try-it page:

• The documentation from the documentation annotation is displayed, and good documentation makes the try-it much nicer to use.  I hope this encourages you to use the available documentation facilities!
• The input fields for the parameters initially show the XML Schema type of data that's expected.  'anyType' means an XML element.  Note that you are responsible for keeping the XML for these types of services well-formed.  You can also get this information from the tooltip.
• The try-it page is a full Ajax client and interacts with the service just as any other client would, so it's a good way to verify that a service not only works, but is reachable by the clients.
• The try-it page can dynamically switch between the available endpoints using the Choose endpoint list.  You can choose an appropriate endpoint, manually edit the endpoint address if necessary (e.g., to redirect messages through tcpmon), and if appropriate link to an alternate try-it that makes more endpoints available (when the try-it page is served up under HTTP, only HTTP endpoints appear, but if you get the try-it page from HTTPS, then HTTPS endpoints may appear instead.)
• The try-it page is fully asynchronous, so it doesn't block while a Web service is being invoked.  You could invoke several operations before one of them completes (though it doesn't have a way to see the results of the same operation invoked multiple times.)

Feel free to take the Try-it as the basis for a custom Ajax-style Web application to interact with your service.  You'll find the source code quite minimal.

API Documentation (?doc)

The documentation for a service, as defined in by the 'documentation' annotations, can be accessed with the '?doc' query.  The returned HTML format is intended for reference, printout, etc.

Source Code (?source)

The source code for a service can be accessed through the '?source' option.  By default, the source code is available for each service, but in a future release, we will allow you to prevent others from viewing, copying, adapting, or even fixing your code with an option in the administrative console.