Java and LotusScript mappings

Implementation code

The implementation code for a Web service is in its own public class:

• The class must be the one identified as "PortType class" in the Basics tab of the properties box.
• The class contains one public method, function, or sub for each operation in the Web service. The name of the method, function, or sub is the name of the operation in the WSDL document. Private methods, functions, and subs are not exposed.
• Input message parts are passed as parameters to the methods, functions, or subs. Output message parts are passed as method or function return values, or as parameters from methods or subs. Fault message parts specify service-specific return values, which an operation can issue when an error occurs.

When a consumer invokes an operation for a Web service, Domino invokes the corresponding method, function, or sub, passing the input message as parameters. When the method or function exits normally, Domino uses the return value or parameters as the output message for the operation.

Java declarations and initialization

The Java code may include the following import for fault data types, XML Schema data types, and holder classes not defined in standard Java packages.

import lotus.domino.types.*

The lotus.domino package contains the class WebServiceBase which contains the static method getCurrentSession. Use this method to get a Session object representing the Domino session, typically in the no-parameter constructor for the implementation class. The Domino Web services runtime engine invokes the implementation class no-parameter (default) constructor and ignores all other constructors. The default constructor may not be explicit, but when it is, it must be declared public. Other constructors may also be present, for use by the implementation.

Session.getAgentContext() gets the Web service context. The following AgentContext properties apply to Web services: getCurrentAgent() gets the current Web service; getCurrentDatabase() gets the current database. For getCurrentAgent(), the following Agent properties apply to the current Web service: getName(), getOwner(), getCommonOwner(), getOnBehalfOf(), getComment(), getHttpURL(), getNotesURL(), getParent(), and getLockHolders().

System.out prints to the server console and to log.nsf on the server.

LotusScript options, declarations, and initialization

The (Options) may include the following INCLUDE statement. The included file defines data types for mapping to those in the WSDL document.

%INCLUDE "lsxsd.lss"

The (Declarations) typically include Dim statements for NotesSession and NotesDatabase (for the current database) objects.

Use Sub NEW in the implementation class for code that is always executed prior to the invoked operation, such as setting the NotesSession object. Creating a new NotesSession object gets a Domino session. Sub NEW may not have arguments in its signature. The same restriction applies to Sub NEW for all classes received or returned by any Web Service method (including classes contained in other classes).

The following NotesSession properties apply to Web services: CurrentAgent gets the current Web service; CurrentDatabase gets the current database. For CurrentAgent, the following NotesAgent properties apply to the current Web service: Name, Owner, CommonOwner, OnBehalfOf, Comment, HttpURL, NotesURL, Parent, and LockHolders.

Messagebox prints to the server console and to log.nsf on the server.

The lsxsd.lss file defines the following classes: BOOLEAN_HOLDER, BOOLEANARRAY_HOLDER, BYTE_HOLDER, BYTEARRAY_HOLDER, DOUBLE_HOLDER, DOUBLEARRAY_HOLDER, INTEGER_HOLDER, INTEGERARRAY_HOLDER, LONG_HOLDER, LONGARRAY_HOLDER, NOTESDOMELEMENTNODE_HOLDER, NOTESDOMELEMENTNODEARRAY_HOLDER, SINGLE_HOLDER, SINGLEARRAY_HOLDER, STRING_HOLDER, STRINGARRAY_HOLDER, VARIANT_HOLDER, VARIANTARRAY_HOLDER. These classes are used for output and inout parameters. They have a public variable named "Value" that you can get and set. In addition, lsxsd.lss defines classes for XML Schema data types as well as holder classes for them, for example, XSD_BOOLEAN and XSD_BOOLEAN_HOLDER. See the XSD data types under "Data descriptions" as follows.

Data descriptions

The following basic data types map one-for-one between the WSDL document and the corresponding Java or LotusScript code. Except as noted, the LotusScript XSD data types are defined in lsxsd.lss and have the following function and sub:

string = GetValueAsString()
Call SetValueFromString(string)

The following LotusScript XSD classes are proxy classes: XSD_BASE64BINARY, XSD_DATE, XSD_DATETIME, XSD_HEXBINARY, and XSD_TIME. Like the other XSD classes, they have a public variable named "Value" that you can get and set. However, the "Value" variable is not of type String.

The information for the classes XSD_BASE64BINARY and XSD_HEXBINARY is passed in NotesStream format. These classes have the following function and sub:

NotesStream = GetValueAsNotesStream()
Call SetValueFromNotesStream(NotesStream)

The information for the classes XSD_DATE, XSD_DATETIME, and XSD_TIME is passed in NotesDateTime format. These classes have the following function:

NotesDateTime = GetValueAsNotesDateTime()

In Domino 7.0, the sub for these classes was:

Call SetValueFromNotesDateTime(NotesDateTime)

For Domino 8.0, the original method remains, for backward compatibility, but this is the new sub for these classes:

Call SetValueWithZoneFromNotesDateTime( NotesDateTime )

The new sub adds XSD timezone information to the resulting XML value. Users could, if desired, rewrite the implementation of SetValueFromNotesDateTime in LSXSD.LSS to call the newer method, since the signatures are the same.

The data types map both ways (WSDL document to code and vice-versa) except as noted.

Arrays

For Domino 7:

Arrays map to XML Schema <complexType> entities elements in WSDL, with the following attributes and subelements:

• name = "ArrayOf_xsd_" plus the name of the data type; for example, ArrayOf_xsd_int
• restriction base = "soapenc:Array"
• attribute ref = "soapenc:arrayType
• wsdl:arrayType = "xsd:" plus the data type plus "[]"; for example, xsd:int[]

For example, an array of type int (Java) or Long (LotusScript) generates the following WSDL:

<wsdl:types>
 <schema targetNamespace="urn:DefaultNamespace"
  xmlns="http://www.w3.org/2001/XMLSchema">
  <import namespace="http://schemas.xmlsoap.org/soap/encoding/" />
  <complexType name="ArrayOf_xsd_int">
   <complexContent>
    <restriction base="soapenc:Array">
     <attribute ref="soapenc:arrayType" wsdl:arrayType="xsd:int[]" />
    </restriction>
   </complexContent>
  </complexType>
 </schema>
</wsdl:types>

Arrays may also map to individual <element> entities in WSDL, where a maxOccurs attribute is present with a value greater than 1. This second form of array representation may appear in any externally-defined WSDL document, but will only appear in Designer-generated WSDL for a Java Web service, and only then for Java value type array members with indexed accessors.

For Domino 8:

Arrays map to the "soapenc:Array" pattern described previously principally for encoded services, i.e. for Web services with a SOAP message format of "RPC/encoded".

For "literal" services (i.e. rpc/literal, doc/literal, or wrapped SOAP message formats), arrays map to so-called "literal" arrays, i.e. <complexType>'s with a single <element> whose "maxOccurs" attribute value is "unbounded", e.g:

<wsdl:types>
 <schema targetNamespace="urn:DefaultNamespace"
  xmlns="http://www.w3.org/2001/XMLSchema">

   <complexType name="xsd_intArray">
     <element name="item" minOccurs="0" maxOccurs="unbounded" type="xsd:int"/>
   </complexType>

 </schema>
</wsdl:types>

The "literal" format shown here will also be generated in WSDL for Java Web service value type arrays with indexed member accessors.

Uninitialized Arrays

For Domino 8.0, empty arrays in a SOAP request (for a Web service provider) or SOAP response (for a Web service consumer) will deserialize into:

• a null array object -- for Java
• an uninitialized dynamic array -- for LotusScript

For Java, this is the same behavior as for Domino 7.x, but for LotusScript this differs from Domino 7.x, (which returns single-element arrays whenever possible). Domino 8.0 scripts that may be receiving empty arrays should be implemented to handle LotusScript error 200 when querying dynamic array contents.

Classes

Classes (sometimes called value types) that pass to or from a Web service operation usually map to XML Schema <complexType> elements in WSDL, with subelements representing each exposed data member. For example:

      <xsd:complexType name="telephone">
        <xsd:sequence>
            <xsd:element name="areaCode" type="xsd:int"/>
            <xsd:element name="exchange" type="xsd:int"/>
            <xsd:element name="number" type="xsd:string"/>
        </xsd:sequence>
      </xsd:complexType>

For LotusScript, exposed class data members are those members declared public.

For Java, exposed class data members are either members that are public, or members that have public get and set methods characteristic of a Java Bean. Recognizable Java value type classes must have a public default constructor (no arguments).

Enumerations

Enumerations map to XML Schema <simpleType> elements in WSDL, with the following characteristics:

• restriction subelement with "base" attribute for the underlying type
• enumeration facets (subelements, one or more), each specifying a member of the enumeration

For example, an enumeration of vegetables containing members of type String generates the following WSDL:

      <xsd:simpleType name="vegetableType">
        <xsd:restriction base="xsd:string">
            <xsd:enumeration value="Carrot"/>
            <xsd:enumeration value="Lettuce"/>
            <xsd:enumeration value="Ketchup"/>
        </xsd:restriction>
      </xsd:simpleType>

Both LotusScript and Java implementations of an enumeration reflect a specific pattern comprised of:

• a constant for each enumeration member value
• a class for representing any enumeration member
• a collection of the enumeration member class instances, representing the enumeration itself
• initializer code that populates the enumeration just prior to Web service method invocation

All identifying characteristics (bolded in the examples) must be present in the implementation for any WSDL generation to detect and correctly represent an enumeration.

Faults

Faults communicate error conditions back to the caller, and may be emitted by any Web service method. They may be explicit to the WSDL contract (specified in the WSDL document for one or more service operations), or just implicit to the WSDL contract (implemented-only, as part of some Service method's signature).

Explicit faults appear in WSDL as optional <wsdl:fault> elements specified for an operation, appearing alongside <wsdl:input> and <wsdl:output> elements. For example:

<wsdl:operation name="getStockQuote">
   <wsdl:input message="getStockQuoteRequest"/>
   <wsdl:output message="getStockQuoteResponse"/>
   <wsdl:fault name="InvalidSymbolFault" message="InvalidSymbolFaultMessage"/>
</wsdl:operation>

A <wsdl:fault> element is typed by its message attribute, just like an operation's <wsdl:input> or <wsdl:output> element.

Accordingly, a WSDL fault, through its associated message part type(s), maps to some class in the LotusScript or Java implementation, which is sub-classed from either WS_FAULT (LotusScript) or lotus.domino.types.Fault (Java).

This implementation fault subclass maps to the data members defined for the WSDL fault's associated message, in exactly the same manner as implementation value types (see "Classes") map to their associated WSDL constructs, usually WSDL <complexType>'s.

For example, given the following WSDL complexType (specified here as the type for the example "InvalidSymbolFaultMessage" referenced previously):

      <wsdl:types>
        <xsd:schema ...>

          <xsd:complexType name="InvalidSymbolFault">
            <xsd:sequence>
              <xsd:element  name="TickerSymbol" type="xsd:string"/>
              <xsd:element name="ApplicationCode" type="xsd:int:/>
            </xsd:sequence>
          </xsd:complexType>

        </xsd:schema>
      </wsdl:types>
...
      <wsdl:message name="InvalidSymbolFaultMessage" type="InvalidSymbolFault"/>

This complexType maps to LotusScript as:

Class InvalidSymbolFaultMessage As WS_FAULT

Public TickerSymbol As String
Public ApplicationCode As Integer

Sub NEW
End Sub

End Class

and maps to Java as:

public class InvalidSymbolFaultMessage extends lotus.domino.types.Fault { private java.lang.String tickerSymbol; private int applicationCode; public InvalidSymbolFaultMessage() { } public InvalidSymbolFaultMessage(java.lang.String tickerSymbol, int applicationCode) { this.tickerSymbol = tickerSymbol; this.applicationCode = applicationCode; } public java.lang.String getTickerSymbol() { return this.tickerSymbol; } public int getApplicationCode() { return this.applicationCode; } // helper methods... }

When a Web service operation has no need to send additional, service-specific, data back to the caller, then explicit WSDL faults are not needed - an implicit fault will suffice, instead.

Implicit faults are always possible, are issued by the Web service framework for a variety of invocation errors, but may be emitted, too, by any service method exposed in the implementation PortType class.

Note, too, that adding or removing implicit faults from an implementation method signature is not treated as a change to the Web service contract, and so does not by itself cause WSDL regeneration when the Web service is saved.

Service method fault handling is the same for both explicit and implicit faults. All identifying characteristics are bolded in the examples.

Lists

The XML Schema list type is a form of <simpleType> whose values are represented as a single, white-space delimited list. For example, the following sequence of vegetables (each token separated by a space character):

Carrot Lettuce Ketchup

is a legal value for an instance of this list type:

      <xsd:simpleType name="listOfVegetables">
        <xsd:list itemType="xsd:string"/>
      </xsd:simpleType>

List values lend themselves to implementation as arrays, and therefore map to array-like implementations in both LotusScript and Java. The identifying characteristics for WSDL generation are bolded in the example.

Namespaces

XML Schema uses namespace qualifiers to differentiate among like-named but differently-defined constructs, especially data types, for example:

  <types>
    <xsd:schema targetNamespace="urn:MyAddressBook"
                xmlns:xsd="http://www.w3.org/2001/XMLSchema">

      <xsd:complexType name="telephone">
        <xsd:sequence>
            <xsd:element name="areaCode" type="xsd:int"/>
            <xsd:element name="exchange" type="xsd:int"/>
            <xsd:element name="number" type="xsd:string"/>
        </xsd:sequence>
      </xsd:complexType>

Here, the "telephone" data type is specified to be part of the "MyAddressBook namespace.

Domino Java Web service implementations represent mapped namespaces as Java packages, and so the "telephone" data type would map to the following Java package and class:

package MyAddressBook;

public class Telephone  {
...
}

LotusScript Web service implementations have no package construct to use in this manner, and the legal length for a LotusScript identifier is limited, compared to Java. So WSDL XML Schema namespaces are mapped either as namespace constants together with short suffixes appended to LotusScript class names, or as a single, "DefaultNamespace" constant, applied as the default namespace.

For example, the "telephone" data type would import from WSDL to LotusScript as the following:

Const n1 = "MyAddressBook"  'string constant value can be many characters long
Class Telephone_n1
...
End Class

It could also be specified using the "DefaultNamespace" constant, as:

Const DefaultNamespace = "MyAddressBook"
Class Telephone                               'no suffix specified
...
End Class

Unsupported constructs

For this release, the following WSDL or XML Schema constructs have limited or no supported mappings to LotusScript or Java, and are rejected (or ignored, if indicated) by the Designer "Import WSDL" feature:

• anyAttribute element
• choice element, if nested, optional, or maxOccurs > 1 (arrays)
• redefine element
• sequence element, if maxOccurs > 1 (arrays)
• union simple type
• vector and map (APACHESOAP namespace) - no LotusScript mappings
• MIME attachments
• simple type facets - ignored (except for enumeration)
• attribute, element default values - ignored
• mixed content (character data alongside complex type subelements) -- ignored

Similarly, the following LotusScript and Java constructs have no supported mappings to WSDL XML Schema, and are rejected by the Designer "Export WSDL", "Show WSDL", or "Save" features, when exposed as some Web service operation argument or return type:

• LotusScript list and currency data types
• LotusScript class Sub NEW and DELETE (constructor/destructor) arguments
• LotusScript LSX objects
• backend classes (except for NotesDomDocumentNode for use with message programming model)
• most Java non-Bean classes