com.smartgwt.client.docs

Interface WsdlBinding

public interface WsdlBinding

WSDL Binding

Smart GWT supports automated integration with WSDL-described web services. This support consists of:

• 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
• automatic decode of SOAP XML messages to JavaScript objects, with strong typing (eg an XML schema "date" type becomes a JavaScript Date object)
• import of XML Schema (contained in WSDL, or external), including translating XML Schema "restrictions" to ISC Validators

WSDL services can be contacted by using XMLTools.loadWSDL() or the <isc:loadWSDL> JSP tag to load the service definition, then invoking methods on the resulting WebService object.

WebService.callOperation() can be used to manually invoke operations for custom processing (example using public zipcode service, examples using .NET at /examples/databinding/dotNET/temperatureConvert.jsp).

Fetch-only DataSource binding

To bind a component to a web service operation, call

WebService.getFetchDS(operationName,elementName)

to obtain a DataSource which describes the structure of an XML element or XML Schema type named elementName, which appears in the response message for the operation named operationName. 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. fetchData() called on this DataSource (or on a component bound to it) will invoke the specified web service operation, using the Criteria passed to fetchData() to fill out the input message via DataSource.xmlSerialize(), and using the specified XML element from the response message as data.

Similarly, WebService.getInputDS(operationName) 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 form.getValues() to fetchData() as criteria.

If the input message to the web service has extra nesting, consider using the useFlatFields property to simplify the inputs required for fetchData(), and/or to simplify form databinding via component.useFlatFields.

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 operationName and elementName parameters to pass to getFetchDS() and other WebService methods.

Binding with Customized Presentation

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.

You can create a DataSource that has custom fields and invokes a web service operation by setting DataSource.serviceNamespace to match the targetNamespace of the WebService (found on the <definitions> element from the WSDL file), and setting wsOperation to the name of the web service operation to invoke. fetchData() called on such a DataSource will invoke the web service operation named by wsOperation, just like a DataSource returned by WebService.getFetchDS().

In contrast to getFetchDS(), creating a DataSource in this way gives you the opportunity to:

• declare arbitrary fields, with Smart GWT presentation attributes such as titles and formatters
• extract any data from the response message, via operationBinding.recordXPath and field.valueXPath, and transform it with transformResponse()
• transform the inbound data, if necessary, in order to add metadata such as DSRequest.startRow for paging, or a sessionId for a service requiring authentication

These techniques are shown in the Google SOAP Search example.

XML Schema Reuse

Having loaded a WSDL file, all of the XML Schema definitions within the service definition get translated to Smart GWT DataSources and SimpleTypes via the rules described by XMLTools.loadXMLSchema(), and are available to you via WebService.getSchema() and DataSourceField.type.

You can use the DataSource.inheritsFrom property to create DataSources that extend from XML schema definitions, then add presentation metadata not found in XML schema.

Even if you choose to declare all fields manually, you can leverage XML Schema <simpleType> definitions by setting field.type to the name of an XML Schema simple type embedded in the WSDL file.

Round Trip Binding [fetch -> edit -> save]

For full read-write integration with a service that supports the basic DataSource operations on persistent data, OperationBindings can be declared for each DataSource operation, and the wsOperation property can be used to to bind each DataSource operation (fetch, update, add, remove) to a corresponding web service operation.

For example, this code accomplishes part of the binding to the SalesForce partner web services (additional code is required to handle authentication and other details):

  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" }
     ],
     ...
  }); 
  

NOTE: additional code is required to handle authentication and other details, see the complete code in smartclientSDK/examples/databinding/SalesForce.

In this usage, any DSRequest performed on this DataSource invokes the web service operation named by the wsOperation property on the corresponding operationBinding, and DSRequest.data is serialized via DataSource.xmlSerialize() to form the input message to send to the web service. For example, if a DynamicForm.saveData() is invoked and triggers a DSRequest with operationType:"add", the DataSource above will invoke the "create" operation, and form.values will become DSRequest.data and be serialized to form the input message of the "create" web service operation.

Typical usage is:

1. 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 DataSource.inheritsFrom.
2. use operationBindings to configure the entity DataSource to call the appropriate web service operations for each DataSource operation, and extract results via recordXPath/recordName
3. bind components as follows:
   • bind grids to the entity DataSource
   • bind SearchForms to the input message of the fetch operation (obtained via webService.getInputDS("operationName"). This is done because search inputs are frequently unrelated to the structure of the objects being searched for
   • bind forms use for editing ("add" and "update" operations) to the entity DataSource
4. use transformRequest/transformResponse, OperationBinding.useFlatFields and OperationBinding.responseDataSchema to handle inconsistencies between the WSDL operations and the data you want in the presentation layer.

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.

This requires a SalesForce account. SalesForce currently offers free developer accounts. Please note: this application deals with live data and if you using inline editing it will save to SalesForce.

Deployment

For best performance, using the <isc:loadWSDL> JSP tag is recommended, as it automatically caches a translated form of the WSDL file. If you are not using the Smart GWT 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.

Creating New WSDL Services

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 WSDataSource (general client-side DataSource creation is described under Creating DataSources). To change the URL where ISC expects to find the SmartClientOperations web service, use WebService.setLocation() like so:

       var service = isc.WebService.get("urn:operations.smartclient.com");
       service.setLocation("myURL");
  

To implement a web service starting from a WSDL file:

• In the .NET framework, you will use the Web Services Description Language Tool (wsdl.exe) to generate C# stubs that you will add business logic to
• In Java, Apache Axis can be used to generate Java stubs for implementing a web service
• In Perl, the SOAP:Lite module can be used to implement web services without code generation
• for PHP, the NuSoap module can likewise be used to implement web services without code generation

See Also:

DataSource.getServiceNamespace(), DataSource.getSchemaNamespace()