JavaScript Web Service Annotations

Table of Contents

There are a number of annotations that you can insert into your JavaScript Mashup service that enrich the descriptions and tools generated by the mashup service. We encourage you to use these annotations liberally. The WSO2 Mashup Server defines a set of properties that can be applied to the Global object, representing the service as a whole, or to individual functions. In javaScript, functions are actually objects, and any object can have additional properties dynamically added to it. The set of common properties to set on an object is described below. There are two groups of annotations. Some annotations are used at service level while the others are used at an operation level. The documentation annotaion is used at both service and operation level.

Documentation Annotation

Documentation properties can be added either to the global object, or to individual function objects.

                this.documentation = <div>The <b>simple</b> service has a single operation - <i>echo</i>.</div>;

                echo.documentation = "The echo operation accepts a blob of XML and returns it to the caller unchanged."
                function echo(xmlblob) {
                    return xmlblob;
                }
            

The documentation can have either a string value, as shown in the echo.documentation property above, or it can have an XML. The documentation property serves several purposes:

1. It provides structured documentation within the service. While you could use javaScript comments instead, using a documentation property to describe the service and its operations makes it possible to distinguish between comments describing the implementation, and comments documenting the behavior of the service, and to re-use the latter.
2. The documentation for the service (this.documentation) appears in the WSDL as a top-level <documentation> element. The documentation for each operation (echo.documentation in the above example) appears as <documentation> elements on each Interface Operation.
3. The documentation is displayed in the Try-it page.
4. The documentation is also displayed in the ?doc page.

Visible Annotation

By default, each function in a javaScript service file is exposed as an operation. But often functions should be 'private', for the benefit of other functions and not an entry point that the author wishes to expose to a client. When the 'visible' property has the Boolean value false, the function is not exposed as an operation (e.g., it doesn't appear in the WSDL, Try-it, etc.)

                function equals(lefthand, righthand) {
                    return (lefthand == righthand && typeEquals(lefthand, righthand));
                }

                typeEquals.visible = false;
                function typeEquals(lefthand, righthand) {
                    return (typeof(lefthand) == typeof(righthand));
                }
            

In the above example, there is an implicit "equals.visible = true;".

InputType and OutputType Annotations

Please refer documentation on JavaScript Data Binding for details.

HTTPMethod, HTTPLocation and IgnoreUncited Annotations

Please refer documentation on Writing RESTful Services for details.

Init, Destroy and Undispatched Annotations

Please refer documentation on Service Lifecycle Support for details.

Other Annotations

For advanced usage, there are a number of other properties that can be used:

• this.targetNamespace: places the components of the description (WSDL 2.0, WSDL 1.1) in a specific namespace. By default, the targetNamespace is http://services.mashup.wso2.org/{service name}, which is of course not guaranteed to be unique.
• this.schemaTargetNamespace : sets the schema target namespace, which will be used as the namespace for any wrapper elements generated by the mashup server. By default the targetnamespace is http://services.mashup.wso2.org/{servicename}?xsd.
• this.serviceName : exposes the service under an alternate name (in the WSDL, try-it, documentation, etc.) By default the serviceName is the name of the JavaScript file (minus the '.js'.)
• {function}.safe :indicates whether repeated calls to the operation cause side effects. For example, two calls to a 'bill me' operation would normally result in two charges, while two calls to a 'current activity' operation would not cause any harmful side-effects. The safe annotation maps to the wsdlx:safe attribute, and helps determine whether GET or POST is the most appropriate HTTP method to use.
• {function}.operationName : exposes the function as an operation under an alternate name (in the WSDL, try-it, documentation, etc.). By default, the operationName is the name of the function.