webservice.js

javascript 很酷的类库

        // we subclass because we need operation-specific properties on this DataSource,
        // where it may be shared as the inputs or part of the inputs for another operation
        var fetchDS = isc.DS.create({
            // critical so this DS can find this WebService
            serviceNamespace : this.serviceNamespace,

            inheritsFrom : resultType,

            operationBindings : [
                isc.addProperties({
                    operationType: "fetch", 
                    wsOperation:operationName,
                    recordName:resultType
                }, operationBindingProperties)
            ]
        });

        return fetchDS;
    },

    //> @method webService.setLocation() [A]
    // Set location can be used when the actual URL where a service will be accessible isn't
    // known until runtime, or changes at runtime, hence can't be embedded in the service
    // definition.
    // <P>
    // With an operation parameter, <code>setLocation()</code> can be used to set a distinct
    // URL for each web service operation.  This is a development-time only feature that allows
    // XML flat files to be placed at various URLs on a server, to serve as spoofed responses
    // for each web service operation.
    //
    // @param location (URL) URL where web service can be contacted
    // @param [operation] (String) optional operation name to set the location for, for
    //                             debugging only
    // @group webService
    // @visibility xmlBinding
    //<
    setLocation : function (location, operation) { 
        if (operation) this.getOperation(operation).dataURL = location;
        else this.dataURL = location; 
    }
});

isc.WebService.addClassMethods({
    services : {},
    
    //> @classMethod WebService.get()
    // Retrieve a WebService object by the targetNamespace declared on the &lt;wsdl:definitions&gt;
    // element in the WSDL file from which the WebService was derived.
    //
    // @param serviceNamespace (String) uri from the "targetNamespace" attribute of the
    // &lt;wsdl:definitions&gt; element in the WSDL file
    // @return (WebService) the requested WebService, or null if not loaded
    //
    // @group webService
    // @visibility xmlBinding
    // @example wsdlBinding
    //<
    get : function (serviceNamespace) {
        return this.services[serviceNamespace];
    }
});

isc.WebService.getPrototype().toString = function () {
    return "[" + this.Class + " ns=" + this.serviceNamespace + "]";
};

//> @groupDef wsdlBinding 
// SmartClient supports automated integration with WSDL-described web services.  This support
// consists of:
// <ul>
// <li> creation of SOAP XML messages from JavaScript application data, with automatic
// namespacing, and support for both "literal" and "encoded" SOAP messaging, and "document" and
// "rpc" WSDL-SOAP bindings
// <li> automatic decode of SOAP XML messages to JavaScript objects, with strong typing (eg an
// XML schema "date" type becomes a JavaScript Date object)
// <li> +link{XMLTools.loadXMLSchema,import of XML Schema} (contained in WSDL, or external),
// including translating XML Schema "restrictions" to ISC +link{Validator,Validators}
// </ul>
// <P>
// WSDL services can be contacted by using +link{XMLTools.loadWSDL()} or the
// +link{group:loadWSDLTag,&lt;isc:loadWSDL&gt; JSP tag} to load the service definition, then
// invoking methods on the resulting +link{WebService} object.
// <P>
// +link{WebService.callOperation()} can be used to manually invoke operations for
// custom processing (example using +explorerExample{wsdlOperation,public zipcode service},
// examples using .NET at
// +externalLink{/examples/databinding/dotNET/temperatureConvert.jsp,/examples/databinding/dotNET/temperatureConvert.jsp}).
// <P>
// <b>Fetch-only DataSource binding</b>
// <P>
// To bind a component to a web service operation, call
// <P>
// &nbsp;&nbsp;+link{WebService.getFetchDS(),WebService.getFetchDS(<i>operationName,elementName</i>)}
// <P>
// to obtain a DataSource which describes the structure of an XML element or XML Schema type
// named <i>elementName</i>, which appears in the response message for the operation named
// <i>operationName</i>.  A component bound to this DataSource will show fields corresponding
// to the structure of the chosen XML element or type, that is, one field per subelement or
// attribute.  +link{ListGrid.fetchData(),fetchData()} called on this DataSource (or on a
// component bound to it) will invoke the specified web service operation, using the
// +link{Criteria} passed to fetchData() to fill out the input message via
// +link{dataSource.xmlSerialize()}, and using the specified XML element from the response
// message as data.
// <P>
// Similarly, +link{WebService.getInputDS,WebService.getInputDS(<i>operationName</i>)} returns
// a DataSource suitable for binding to a form that a user will fill out to provide inputs to
// the specified web service operation.  Typical use is to let the user fill in the form, then
// pass the results of +link{dynamicForm.getValues(),form.getValues()} to
// +link{listGrid.fetchData(),fetchData()} as criteria.
// <P>
// If the input message to the web service has extra nesting, consider using
// the +link{operationBinding.useFlatFields,useFlatFields} property to simplify the inputs
// required for <code>fetchData()</code>, and/or to simplify form databinding via
// +link{dataBoundComponent.useFlatFields,component.useFlatFields}.
// <P>
// Note that the WSDL tab in the Developer Console can provide a clean, simplified view of any 
// WSDL file, making it easier to pick out the appropriate <code>operationName</code> and
// <code>elementName</code> parameters to pass to <code>getFetchDS()</code> and other
// +link{WebService} methods.
// <P>
// Take a look at the +explorerExample{wsdlBinding,Google SOAP Search example} and the
// +externalLink{/examples/databinding/dotNET/customerSearch.jsp,.NET example}
// (/examples/databinding/dotNET/customerSearch.jsp).
// <P>
// <b>Binding with Customized Presentation</b>
// <P>
// Because XML Schema lacks key presentation metadata such as user-viewable titles, typically
// you cannot directly use the DataSources derived from XML Schema embedded in a WSDL file to
// drive visual component DataBinding in your final application.
// <P>
// You can create a DataSource that has custom fields <b>and</b> invokes a web
// service operation by setting +link{dataSource.serviceNamespace} to match the targetNamespace
// of the +link{WebService} (found on the <code>&lt;definitions&gt;</code> element from the
// WSDL file), and setting +link{operationBinding.wsOperation,wsOperation} to the name of the
// web service operation to invoke.  <code>fetchData()</code> called on such a DataSource will
// invoke the web service operation named by +link{operationBinding.wsOperation,wsOperation},
// just like a DataSource returned by +link{webService.getFetchDS()}.
// <P>
// In contrast to <code>getFetchDS()</code>, creating a DataSource in this way gives you the
// opportunity to:
// <ul>
// <li> declare arbitrary fields, with SmartClient presentation attributes such as titles and
// formatters
// <li> extract any data from the response message, via
// +link{operationBinding.recordXPath,operationBinding.recordXPath} and 
// +link{dataSourceField.valueXPath,field.valueXPath}, and transform it with
// +link{dataSource.transformResponse,transformResponse()}
// <li> transform the inbound data, if necessary, in order to add metadata such as
// +link{dsRequest.startRow} for paging, or a sessionId for a service requiring authentication
// </ul>
// These techniques are shown in the +explorerExample{wsdlBinding,Google SOAP Search example}.
// <P>
// <b>XML Schema Reuse</b>
// <P>
// Having loaded a WSDL file, all of the XML Schema definitions within the service definition
// get translated to SmartClient +link{DataSource,DataSources} and
// +link{SimpleType,SimpleTypes} via the rules described by +link{XMLTools.loadXMLSchema()},
// and are available to you via +link{webService.getSchema()} and +link{dataSourceField.type}. 
// <P>
// You can use the +link{dataSource.inheritsFrom} property to create DataSources that extend
// from XML schema definitions, then add presentation metadata not found in XML schema.
// <P>
// Even if you choose to declare all fields manually, you can leverage XML Schema
// &lt;simpleType&gt; definitions by setting +link{DataSourceField.type,field.type} to the name
// of an XML Schema simple type embedded in the WSDL file.
// <P>
// <b>Round Trip Binding [fetch -> edit -> save]</b>
// <P>
// For full read-write integration with a service that supports the basic
// +link{group:dataSourceOperations,DataSource operations} on persistent data, 
// +link{OperationBinding,OperationBindings} can be declared for each DataSource operation, and
// the +link{operationBinding.wsOperation,wsOperation} property can be used to to bind each
// +link{group:dataSourceOperations,DataSource operation} (fetch, update, add, remove) to a
// corresponding web service operation.
// <P>
// For example, this code accomplishes part of the binding to the 
// +externalLink{http://www.google.com/search?q=sforce+partner+wsdl,SalesForce partner web services}
// (additional code is required to handle authentication and other details):
// <pre>
// isc.DataSource.create({
//    serviceNamespace : "urn:partner.soap.sforce.com",
//    operationBindings : [
//        { operationType:"fetch", wsOperation:"query", recordName: "sObject" },
//        { operationType:"update", wsOperation:"update", recordName: "SaveResult" },
//        { operationType:"add", wsOperation:"create", recordName: "SaveResult" },
//        { operationType:"remove", wsOperation:"delete", recordName: "DeleteResult" }
//    ],
//    ...
// }); 
// </pre>
// NOTE: additional code is required to handle authentication and other details, see the
// complete code in isomorphicSDK/examples/databinding/SalesForce.
// <P>
// In this usage, any DSRequest performed on this DataSource invokes the web service operation
// named by the <code>wsOperation</code> property on the corresponding operationBinding, and
// +link{dsRequest.data} is serialized via +link{dataSource.xmlSerialize()} to form the input
// message to send to the web service.  For example, if a +link{DynamicForm.saveData()} is
// invoked and triggers a DSRequest with operationType:"add", the DataSource above will invoke
// the "create" operation, and +link{DynamicForm.getValues(),form.values} will become
// +link{dsRequest.data} and be serialized to form the input message of the "create" web
// service operation.
// <P>
// Typical usage is:
// <ol>
// <li> declare a DataSource that represents the fields of the object as you want them
// represented in the UI.  This DataSource is considered the "entity DataSource".  It may
// extend from an XML Schema complex type via +link{dataSource.inheritsFrom}.
// <li> use +link{operationBinding,operationBindings} to configure the entity DataSource to
// call the appropriate web service operations for each DataSource operation, and extract
// results via
// +link{operationBinding.recordXPath,recordXPath}/+link{operationBinding.recordName,recordName}
// <li> bind components as follows:
// <ul>
// <li> bind +link{listGrid,grids} to the entity DataSource
// <li> bind +link{SearchForm,SearchForms} to the input message of the fetch operation
// (obtained via +link{WebService.getInputDS,webService.getInputDS("operationName")}.  This is
// done because search inputs are frequently unrelated to the structure of the objects being
// searched for
// <li> bind forms use for editing ("add" and "update" operations) to the entity DataSource
// </ul>
// <li> use
// +link{dataSource.transformRequest,transformRequest}/+link{dataSource.transformResponse,transformResponse}, 
// +link{operationBinding.useFlatFields} and +link{operationBinding.responseDataSchema} to
// handle inconsistencies between the WSDL operations and the data you want in the presentation
// layer.
// </ol>
// A complete example of binding to the SalesForce "partner" web service, including
// authentication via SOAP headers, saving data and cache sync, inline editing, validation
// error handling and data paging, can be found in [webroot]/examples/databinding/SalesForce.
// <P>
// This requires a SalesForce account.  SalesForce currently offers 
// +externalLink{http://www.google.com/search?hl=en&q=salesforce+developer+account,free developer accounts}.
// Please note: this application deals with <b>live data</b> and if you using inline editing
// <b>it will save to SalesForce</b>.
// <P>
// <b>Deployment</b>
// <P>
// For best performance, using the +link{group:loadWSDLTag,&lt;isc:loadWSDL&gt; JSP tag}
// is recommended, as it automatically caches a translated form of the WSDL file.  If you are
// not using the SmartClient server, the WSDL tab in the Developer Console allows you
// to save a .js file representing a WebService object, which can then be loaded and cached
// like a normal JavaScript file.
// <P>
// <B>Creating New WSDL Services</B>
// <P>
// If you have no existing WSDL web service but would like to use web services for integration,
// you can implement the "SmartClientOperations" web service described by the
// ${isc.DocUtils.externalLink(isc.Page.getIsomorphicDir()+"system/schema/SmartClientOperations.wsdl","WSDL file")} 
// included in the SDK.  This simple, 4 operation web service can support any number of
// DataSources.  In this case, you create your DataSources as client-side instances of
// +link{WSDataSource} (general client-side DataSource creation is described under
// +link{group:dataSourceDeclaration,Creating DataSources}).  To change the URL where ISC
// expects to find the SmartClientOperations web service, use +link{WebService.setLocation()}
// like so:<pre>
//      var service = isc.WebService.get("urn:operations.smartclient.com");
//      service.setLocation("myURL");
// </pre>
// <P>
// To implement a web service <b>starting from a WSDL file</b>:
// <ul>
// <li>In the .NET framework, you will use the Web Services Description Language Tool 
// +externalLink{http://www.google.com/search?q=wsdl.exe,(wsdl.exe)} to generate C# stubs that
// you will add business logic to
// <li>In Java, +externalLink{http://ws.apache.org/axis/,Apache Axis} can be used to generate
// Java stubs for implementing a web service
// <li>In Perl, the +externalLink{http://soaplite.com,SOAP:Lite} module can be used to
// implement web services without code generation
// <li>for PHP, the NuSoap module can likewise be used to implement web services without code
// generation
// </ul>
//
// @visibility xmlBinding
// @treeLocation Client Reference/Data Binding
// @title WSDL Binding
//<