Creating web service consumers

To create a web service consumer

Each created web service consumer contains a single Web Service, as defined by a single WSDL document.

1. Identify the Web Service that you'd like to use and its associated WSDL document.
2. Choose Create - Design - Web Service Consumer
3. Enter the name of the web service consumer.
   Note: Each web service consumer in a database must have a unique name. This is true for multilingual databases as well; you cannot differentiate between multiple web service consumers of the same name using the $Language field of the design note.
4. Choose one of the following languages:
   • LotusScript
   • Java
5. Enter or browse to the location of the local WSDL file, or enter the URL that points to the WSDL file.
6. Click OK.

This operation will create either LotusScript or Java code that represents the service that is described in the WSDL document. The code that is generated, including the names of classes, fields, their types and functions or sub are all derived from the WSDL document. It will generate one or more PortType classes and may generate any number of Value type classes.

A PortType class defines a set of operation in a web service.

PortType classes in LotusScript can be identified because they inherit from the class called "PortTypeBase" and are defined in LSXSD.LSS.

PortType classes in Java can be identified because they extend the class lotus.domino.types.PortTypeBase. Each porttype class also has two additional related classes called the Service and ServiceLocator and together they are used to instanciate the PortType class in Java.

Value Type classes are all the other types that are generated from the creation of a web service consumer, and are used to carry application data. They are used in the operations declared in the PortType classes. It is possible that a WSDL document does not declare any value types.

It is possible to share ValueTypes (but not PortType classes) between multiple web service consumers. The PortType classes must stay with the web service consumer element they were originally generated in. If you do move Value Types between web service consumers you will find that:

• LSXSD.LSS must be included exactly once.
• The WSDL associated with the combined web service consumer will be the WSDL you originally used to create that web service consumer, so if you "Export" or "View" the WSDL, it will not contain information about all the new web services called from there.
• If you re-import a WSDL into the web service consumer, your customizations will be overwritten.
• The portType class used must be the one generated with the web service consumer. It cannot be cut and pasted into a different web services consumer.

To use a web service consumer in an agent

In order to call a web service via a web service consumer, your code must first include the web service consumer (with the LotusScript "USE" statement, or with the 'Edit Project' dialog for Java). Then, just instantiate the generated web service consumer class that is a subclass of PortTypeBase (in Java the full name is lotus.domino.types.PortTypeBase). The methods in this class correspond directly to the operations of the targeted web service, which can then be invoked by your code.

Combining web service consumers for greater efficiency

There is an additional feature intended to facilitate the use of multiple web service consumers, in the form of a text file maintained in the user's Notes data directory. The file, called "WSNamespace.mappings", is generated by Domino Designer when importing a WSDL document into a web service consumer, and records the WSDL namespaces and their associated LotusScript constants. Consumer WSDL import generates such constants as a mechanism for associating generated classes, including the imported Web service portType class, to their corresponding namespaces, as specified in the WSDL document itself. This approach allows a class to be associated with its defining namespace while minimizing possible import failures due to violations of the maximum length for a LotusScript identifier.

For example, the following WSDL complex type:

<schema targetNamespace="urn:myCompanyNamespace">

  <complexType name="MyCompanyPersonRecord">
    	<element name="Name" type="xsd:string"/>
    	<element name="Address" type="xsd:string"/>
  </complexType>

</schema>

...might import into a LotusScript web service consumer as:

  Const n0 = "urn:myCompanyNamespace"        'generated namespace constant

  class MyCompanyPersonRecord_n0             'namespace-qualified class, 
                                             'associated via its "_n0" suffix
    public Name_ As String
    public Address As String
  end class

...and also generate the following entry into the WSNamespaces.mappings text file:

  n0=urn:myCompanyNamespace

Any subsequent importing of WSDL documents into LotusScript web service consumers using this same Domino Designer installation will then re-use the "n0" namespace constant to represent the "urn:myCompanyNamespace" namespace, in order to maintain consistent namespace definitions and class associations across multiple web service consumers. The file can also be edited in a text editor to include pre-determined constant-to-namespace mappings to be applied during subsequent WSDL import. For the example here, this ensures that any WSDL document containing or referring to the MyCompanyPersonRecord complexType within the "urn:myCompanyNamespace" namespace will always import as "MyCompanyPersonRecord_n0", allowing such classes to be moved to some commonly-shared script library of their own.