<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Jaggery - Delicious Javascript</title>
    <meta name="description" content="">
    <meta name="author" content="">

    <!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
    <!--[if lt IE 9]>
    <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->

    <!-- Le styles -->
    <link href="../css/bootstrap.css" rel="stylesheet">
    <style type="text/css">
        body {
            padding-top: 60px;
        }
    </style>
    <link href="../css/prettify.css" rel="stylesheet">
    <!-- Le fav and touch icons -->
    <link rel="shortcut icon" href="../images/favicon.ico">
    <link rel="apple-touch-icon" href="../images/apple-touch-icon.png">
    <link rel="apple-touch-icon" sizes="72x72"
          href="../images/apple-touch-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="114x114"
          href="../images/apple-touch-icon-114x114.png">
</head>

<body>

<%
    include('/includes/topnavi.jag');
%>

<div class="container-fluid" style="width: 960px; margin: auto;">
<div class="row">
    <div class="span16">
        <div class="page-header">
            <h1>
                Documentation
                <small>API documentation for Jaggery.js</small>
            </h1>
        </div>
    </div>
</div>

<div class="row">
<div class="span4">
    <div class="well">
        <%
        include('/includes/navi.jag');
%>

    </div>

</div>
<div class="span12">
<div class="content" id="email" name="email">
<h3>WSRequest</h3>

            <pre class="prettyprint linenums">
&lt%
    function invokeGetVersion(){
	var log = new Log();
        var ws = require('ws');

        var version = new ws.WSRequest();
        var options = new Array();
        options.useSOAP = 1.2;
        options.useWSA = 1.0;
        options.action = "urn:getVersion";
        var payload = null;
        var result;

        try {
            version.open(options,"http://stratoslive.wso2.com/services/Version", false);
            version.send(payload);
            result = version.responseE4X;
        } catch (e) {
            log.error(e.toString());
            return e.toString();
        }
        return result;
    }

    print(invokeGetVersion());
%&gt
</pre>
<%
var wsCode = '&lt%'
+ '\n function invokeGetVersion() {'
+ '\n	var log = new Log();'
+ '\n 	var ws = require("ws");'
+ '\n'
+ '\n 	var version = new ws.WSRequest();'
+ '\n 	var options = new Array();'
+ '\n 	options.useSOAP = 1.2;'
+ '\n 	options.action = "urn:getVersion";'
+ '\n 	var payload = null;'
+ '\n 	var result;'
+ '\n'
+ '\n 	try {'
+ '\n 		version.open(options,"http://stratoslive.wso2.com/services/Version", false);'
+ '\n 		version.send(payload);'
+ '\n 		result = version.responseE4X;'
+ '\n 	} catch (e) {'
+ '\n 		log.error(e.toString());'
+ '\n 		return e.toString();'
+ '\n	}'
+ '\n 	return result;'
+ '\n }'
+ '\n'
+ '\n print(invokeGetVersion());'
+ '\n %&gt';

var codeSnip = encodeURIComponent(wsCode)
var urlString = '../tryitframe.jag?code='+codeSnip;

include('/includes/tryit_but.jag');
%>
<div id="pageLinks">
                <a class="navilink" href="#overview">Overview</a>
                <a class="navilink" href="#members">Members</a>
                <a class="navilink" href="#operations">Operations</a>
                </div>
                 <section id="overview">


                <h4>Overview</h4>
                <p class="description">TThe WSRequest object is similar to the XMLHTTPRequest object. It's usage typically involves specifying the endpoint
    address and setting up options on how to frame the message, invoking the operation with a specific XML payload, and
    then checking and extracting information from the result. </p>

                </section>

                <section id="members">
                <h4>Members</h4>


<table class="clsStd member-table">

<tbody>

<tr>

    <th>Member</th>
    <th>Type</th>
    <th>Description</th>

</tr>

<tr>

    <td><code>EventListener onreadystatechange </code>
    </td>
     <td>EventListener</td>
    <td>This property can be set to a function object, which is invoked when the state of an asynchronous request
        changes (e.g. the request completes).
    </td>

</tr>

<tr>

    <td><code>readyState </code>
    </td>
   <td>Unsigned Short</td>
    <td>The current state of the object, which can be one of
        the following values:
        <br><br>
        <ul>
            <li>0: The object has not been initialized by calling the
                open() method.
                <br><br>
            </li>
            <li>1: The object has been initialized successfully, but
                the send() method has not been called.
                <br><br>
            </li>
            <li>2: The request is pending
                <br><br>
            </li>
            <li>3: The request is partially complete (some data has
                been received, and may be available in the responseText property.
                <br><br>
            </li>
            <li>4: The request is complete, all data has been
                received.
                <br><br>
                Of these, typically only the last (readyState == 4) is used.
            </li>
        </ul>
    </td>

</tr>

<tr>

    <td><code>responseXML</code>
    </td>
    <td>Document</td>
    <td>The parsed XML message representing the response from the service. (Currently this is same as responseE4X, but
        this will be fixed to return a DOM document in the future versions)
    </td>

</tr>

<tr>

    <td><code>responseE4X </code>*
    </td>
    <td>XML</td>
    <td>The parsed E4X XML message representing the response from the service.</td>

</tr>


<tr>
    <td><code>responseText</code>
    </td>
    <td>String</td>
    <td>The raw text representing the XML (or non-XML) response. If the responseXML property is empty, you can check the
        responseText property to see if a non-XML response was received.
    </td>
</tr>


<tr>

    <td><code>error </code>
    </td>
   <td>WebService Error</td>
    <td>When an asynchronous operation failed to complete successfully (including internal errors, or protocol errors
        such as SOAP faults) the error property is a WebServiceError object
    </td>

</tr>

</tbody>
</table>
                </section>
<section id="operations">
    <h4>Operations</h4>

    <table class="clsStd operations-table">
    <tbody>
    <tr>
        <th>Operation</th>
        <th>Returns</th>
        <th>Description</th>
    </tr>
    <tr>

    <td><code>open ( object options | String httpMethod, String url [, boolean async [, String
        username [, String password]]])</code></td>
    <td>None</td>
    <td>This method prepares the WSRequest object to invoke a
        Web service. It accepts the following parameters:
        <br><br>
        <ul>
            <li><em>options (array)</em>: an array of
                options for formulating the message. These options correspond
                to the message framing required by the service as documented in the
                service's WSDL and/or documentation.
            </li>
        </ul>
        The following is a
            list of supported options

        <ul>
            <li>useSOAP - Specify the SOAP version to be used or whether not to use SOAP. Supported
                values are "1.1" | "1.2" | "false"
            </li>
            <li>HTTPMethod - The HTTP method to be used. Supported
                values are "GET" | "POST" | "PUT" | "DELETE"
            </li>
            <li>useWSA - Weather WS-Addressing needs to be used.
                Supported
                values are "1.0" | "submission" | "true". If the version of
                WS-Addressing is specified and useWSA is set to true the "1.0" version
                is used.
            </li>
        </ul>
       When WS-Addressing
            is been used the following options will also be processed


        <ul>
            <li>action - Will be used as the wsa:to value. Can be
                used to specify to address that the message will be sent to.
            </li>
            <li>from - Will be used as the
                wsa:from value. Can be used to specify the address the request
                was sent from.
            </li>
            <li>replyTo -
                Will be used as the wsa:replyTo value. Can be used to specify the
                address the response should be sent to.
            </li>
            <li>faultTo - Will be
                used as the wsa:faultTo value. Can be used to specify the address a
                fault should be sent to.
            </li>
        </ul>
        <ul>
            <li>action - If useWSA is false will be used as the
                SOAPAction.
            </li>
            <li>mep - Allows you to control the Message Exchange Pattern for an
                invocation. Supported values are in-only (need to send a request and do
                not care about the response) and in-out (request - response). Defaults
                to in-out.
            </li>
            <li>username - This will be used as the username to invoke the service with HTTP
                Basic Authentication enabled.
            </li>
            <li>password - This will be used as the password to
                invoke the service with HTTP Basic Authentication
                enabled.
            </li>
            <li>HTTPLocation - Used to specify the URL pattern of
                the operation been invoked. Refer http://wso2.org/library/3715 for
                details.
            </li>
            <li>HTTPLocationIgnoreUncited - Specifies weather
                parameters not cited in the HTTPLocation should be ignored.
            </li>
            <li>HTTPQueryParameterSeparator - Specifies the query
                parameter seperator to be used. Defaults to &amp;.
            </li>
            <li>HTTPInputSerialization
                - Specifies the message format of the request. The Mashup Server can be
                extended to support custom serialization. The following are supported
                by this distribution. application/x-www-form-urlencoded,
                multipart/form-data, application/json, application/json/badgerfish,
                application/soap+xml, text/xml, application/xml
            </li>
            <li>HTTPContentEncoding - Used to speficy the
                content-encoding of the request. Supported values are "gzip" |
                "compress"

            </li>
            <li>rampart - This property is used to specify rampart configurations for to be used with the service
                policies. The object pointed by "rampart" key should be in the following format.
                    <pre class="prettyprint">{
        user : "admin", //username for to use UT and other scenarios
        userPassword : "admin", //in UT, this is the user password, else private key
        keyPassword : "client",
        userCertAlias : "client",
        stsAlias : "sts",
        encryptionUser : "server",
        timestampTTL : "10000",
        timestampMaxSkew : "10",
        timestampPrecisionInMilliseconds : "100",
        signatureCrypto : {
            type : "jks", //keystore type
            file : "client.jks", //keystore file relative to resource folder
            password : "client", //keystore password
            enableCryptoCaching : true,
            cacheRefreshInterval : 3000
        },
        encryptionCrypto : {
            type : "jks",
            file : "client.jks",
            password : "client",
            enableCryptoCaching : true,
            cacheRefreshInterval : 3000
        },
        decryptionCrypto : {
            type : "jks",
            file : "client.jks",
            password : "client"
        },
        stsCrypto : {
            type : "jks",
            file : "client.jks",
            password : "client"
        },
        kerberosConfig : {
            /**
            "key" : "value" properties, you can also use ${resources.dir}
            in property values
            */
            "client.principal.name" : "client",
            "client.principal.password" : "client",
            "service.principal.name" : "service",
            "java.security.auth.login.config" : "jassconfig",
            "javax.security.auth.useSubjectCredsOnly" : "true",
            "kdc.des.aes.factor" : "4",
            "java.security.krb5.conf" : "/home/ruchira/wso2/conf"
        }
    }
    </pre>

            </li>
            <li>policy - This property is used to specify a custome policy. An XML object should be assigned. You can
                use ${resources.dir} in keystore paths and Kerberos configurations to get the path of the resources
                directory. i.e. When you specify a path to a keystore in your resources directory, you can use this.
                Then it will be replaced with the correct path at the server.
            </li>
            <li>HTTPHeaders - Used to specify custom HTTP headers to be send with the request. This should be an array
                of elements. The value for this property should be in the following format. Both name and value
                properties should be strings.
                <pre class="prettyprint">options["HTTPHeaders"] = [ { name : "HEADER1", value : "VALUE1"}, { name : "HEADER2", value : "VALUE2"}, .....]; </pre>

            </li>
            <li>
                SOAPHeaders - Used to specify custom SOAP headers to be send along with the SOAP message. This should be
                an array of elements. You can specify a header as an XML object or just as an object in the following
                structure. valueObject could be either a string or an XML object
                    <pre class="prettyprint">options["HTTPHeaders"] = [
        &lt;MyHeader1 xmlns="http://example.com"&gt;headerValue&lt;/MyHeader1&gt;,
        ...................................
        {qName : new QName("http://example.com", "MyHeader2"), value : valueObject},
        ...................................
    ]; </pre>
            </li>
        </ul>
        <ul>
            <li><em>httpMethod</em>(string): the
                httpMethod to be used when the operation is invoked.
            </li>
            <li><em>url</em>(string): a URL
                representing where to send the message.
                <br><br>
            </li>
            <li>
                <em>async</em>
                (boolean): a boolean flag
                representing whether the operation should be invoked asynchrounously or
                not. Defaults to true.
            </li>
            <li>username - This will be used as the username to invoke the service with HTTP
                Basic Authentication enabled.
            </li>
            <li>password - This will be used as the password to
                invoke the service with HTTP Basic Authentication
                enabled.
            </li>
        </ul>
        To be specific here are the various ways which the open fucntion can be
        used in
        <br><br>
        <ul>
            <li>open(httpMethod, url, async);</li>
            <li>open(options, url, async);</li>
            <li>open(httpMethod, url, username);</li>
            <li>open(options, url, username);</li>
            <li>open(httpMethod, url, username, password);</li>
            <li>open(options, url, username, password);</li>
            <li>open(httpMethod, url, async, username);</li>
            <li>open(options, url, async, username);
            </li>
        </ul>

    </td>

    </tr>
    <tr>

        <td><code>send ( XML payload | XMLString payload )</code>
        </td>
        <td>None</td>
        <td>This method invokes the Web service with the requested
            payload. To be used when the WSRequest object was configured using the
            open method.
            <br><br>
            <ul>
                <li><em>payload</em>: an XML object or a
                    string containing the XML source for the request.
                </li>
            </ul>

        </td>

    </tr>
    <tr>

        <td><code>openWSDL ( String wsdlURL, ?boolean async, [Object options,[QName serviceName, [String
            endpointName]]]) </code>
        </td>
        <td>None</td>
        <td>This
            method can be used to invoke a external web service which advertices a
            WSDL. Using this method had many advantages over using the open method.
            <br><br>
            <ol type="1">
                <li>The user does not need to know how to frame the
                    request.
                    i.e. Whcih SOAP version to use? What should be the request be sent to?
                    How do I configure WS-Security? and so on
                </li>
                <li>Can be used to invoke services that are secured using
                    WS-Security
                </li>
            </ol>
            This method acceps the following parameters
            <br><br>
            <ul>
                <li>
                    <span style="font-style: italic;">wsdlURL</span>
                    (string) - The url at which the WSDL is available at. Currently
                    supports WSDL 1.1
                </li>
                <li>
                    <em>async</em>
                    (boolean): A boolean flag
                    representing whether the operation should be invoked asynchrounously or
                    not.
                </li>
                <li><em>options (array)</em>: An array of
                    options needed to parse in information to invoke secured services.
                </li>
            </ul>
            <div>The following is a
                list of supported options
                <br><br>
            </div>
            <ul>
                <li>username
                    - Used to specify the username if the service needs a
                    username token to carry out any WS-Security related
                    operations.
                </li>
                <li>password
                    - Used to specify the password if the service needs a password
                    token to carry out any WS-Security related operations.
                </li>
                <li>encryptionUser
                    - Used to specify the alias of the certificate to use in Encryption if
                    the service needs the request to be encrypted.
                </li>
                <li>mep - Allows you to control the Message Exchange Pattern for an
                    invocation. Supported values are in-only (need to send a request and do
                    not care about the response) and in-out (request - response). Defaults
                    to in-out.
                </li>
            </ul>
            <ul>
                <li>
                                        <span style="font-style: italic;">serviceName
                                            (QName)
                                        </span>
                    - The QName of the service to be invoked. Could be usefull if the WSDL
                    has multiple services. If not specified the ffirst service in the WSDL
                    is used.
                </li>
                <li>
                                        <span style="font-style: italic;">endpointName
                                            (String)
                                        </span>
                    - The name of the endpoint to use wehn invoking the service. Could be
                    usefull if the service has multiple endpoints and you prefer to use a
                    particular one. If not specified the first SOAP endpoint is used.
                </li>
            </ul>

        </td>

    </tr>

    <tr>

        <td><code>send ( String operationName | QName operationName, XML payload | XMLString payload ) </code>
        </td>
        <td>None</td>
        <td>This method invokes the specified operation of the Web
            service with the requested
            payload. To be used when the WSRequest object was configured using the
            openWSDL method.
            <br><br>
            <ul>
                <li><span style="font-style: italic;">operationName
                                        (String</span>) - The name of the operation to be invoked
                    <em></em>
                </li>
                <li>
                    <em>payload</em>
                    : an XML object or a
                    string containing the XML source for the request.
                </li>
            </ul>
        </td>

    </tr>
    
    </tbody>

    </table>

</section>

</div>
<!-- /email div -->
<br>
<br>
</div>

</div>
<%
include('/includes/footer.jag');
%>

</div>

<!-- /container -->
<%
include('/includes/scripts.jag')
%>
	<script>	
		
		$(document).ready(function(){
        $('#ws').toggleClass('active')
		$('#docs').addClass('active')
        })
	</script>
</body>
</html>
