PROGRAMMING DOMINO FOR WEB APPLICATIONS


Java and LotusScript mappings
Example

Implementation code

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


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.


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.


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” below.

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:


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:


The information for the classes XSD_DATE, XSD_DATETIME, and XSD_TIME is passed in NotesDateTime format. These classes have the following function:
In Domino 7.0, the sub for these classes was:
For Domino 8.0, the original method remains, for backward compatibility, but this is the new sub for these classes:
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.

WSDLJavaLotusScript
xsd:any (element)org.w3c.dom.Element NotesDomElementNode (backend class)
xsd:anyTypejava.lang.ObjectXSD_ANYTYPE
Variant (to WSDL only)
xsd:anyURIlotus.domino.types.URIXSD_ANYURI
soapenc:base64byte[] (from WSDL only)ByteArray_Holder (from WSDL only)
soapenc:base64Binarybyte[] (from WSDL only)ByteArray_Holder (from WSDL only)
xsd:base64Binarybyte[]ByteArray_Holder
XSD_BASE64BINARY
soapenc:booleanjava.lang.Boolean (from WSDL only) XSD_BOOLEAN (from WSDL only)
xsd:booleanbooleanBoolean
java.lang.Boolean (to WSDL only)XSD_BOOLEAN (to WSDL only)
soapenc:bytejava.lang.Byte (from WSDL only) XSD_BYTE (from WSDL only)
xsd:bytebyteXSD_BYTE
java.lang.Byte (to WSDL only)
xsd:datejava.util.DateXSD_DATE
xsd:dateTimejava.util.CalendarXSD_DATETIME
soapenc:decimaljava.math.BigDecimal (from WSDL only) XSD_DECIMAL (from WSDL only)
xsd:decimaljava.math.BigDecimalXSD_DECIMAL
soapenc:doublejava.lang.Double (from WSDL only) XSD_DOUBLE (from WSDL only)
xsd:doubledoubleDouble
java.lang.Double (to WSDL only)XSD_DOUBLE (to WSDL only)
xsd:durationlotus.domino.types.DurationXSD_DURATION
xsd:ENTITYlotus.domino.types.EntityXSD_ENTITY
xsd:ENTITESlotus.domino.types.EntitiesXSD_ENTITIES
soapenc:floatjava.lang.Float (from WSDL only) XSD_FLOAT (from WSDL only)
xsd:floatfloatSingle
java.lang.Float (to WSDL only)XSD_FLOAT (to WSDL only)
xsd:gDaylotus.domino.types.GDayXSD_GDAY
xsd:gMonthlotus.domino.types.GMonthXSD_GMONTH
xsd:gMonthDaylotus.domino.types.GMonthDayXSD_GMONTHDAY
xsd:gYearlotus.domino.types.GYearXSD_GYEAR
xsd:gYearMonthlotus.domino.types.GYearMonthXSD_GYEARMONTH
xsd:hexBinarylotus.domino.types.HexBinaryXSD_HEXBINARY
xsd:IDlotus.domino.types.IdXSD_ID
xsd:IDREFlotus.domino.types.IDRefXSD_IDREF
xsd:IDREFSlotus.domino.types.IDRefsXSD_IDREFS
soapenc:intjava.lang.Integer (from WSDL only) XSD_INT (from WSDL only)
xsd:intintLong
java.lang.Integer (to WSDL only)XSD_INT (to WSDL only)
soapenc:integerjava.math.BigInteger (from WSDL only) XSD_INTEGER (from WSDL only)
xsd:integerjava.math.BigIntegerXSD_INTEGER
xsd:languagelotus.domino.types.LanguageXSD_LANGUAGE
soapenc:longjava.lang.Long (from WSDL only) XSD_LONG (from WSDL only)
xsd:longlongXSD_LONG
java.lang.Long (to WSDL only)
xsd:Namelotus.domino.types.NameXSD_NAME
xsd:NCNamelotus.domino.types.NCNameXSD_NCNAME
xsd:negativeIntegerlotus.domino.types.NegativeIntegerXSD_NEGATIVEINTEGER
xsd:NMTOKENlotus.domino.types.NMTokenXSD_NMTOKEN
xsd:NMTOKENSlotus.domino.types.NMTokensXSD_NMTOKENS
xsd:nonNegativeIntegerlotus.domino.types.NonNegativeIntegerXSD_NONNEGATIVEINTEGER
xsd:nonPositiveIntegerlotus.domino.types.NonPositiveIntegerXSD_NONPOSITIVEINTEGER
xsd:NOTATIONlotus.domino.types.NotationXSD_NOTATION
xsd:normalizedStringlotus.domino.types.NormalizedStringXSD_NORMALIZEDSTRING
xsd:positiveIntegerlotus.domino.types.PositiveIntegerXSD_POSITIVEINTEGER
xsd:QNamejavax.xml.namespace.QNameXSD_QNAME
soapenc:shortjava.lang.Short (from WSDL only) XSD_SHORT (from WSDL only)
xsd:shortshortInteger
java.lang.Short (to WSDL only)XSD_SHORT (to WSDL only)
soapenc:stringjava.lang.String (from WSDL only) String (from WSDL only)
xsd:stringjava.lang.StringString
XSD_STRING (to WSDL only)
xsd:timelotus.domino.types.TimeXSD_TIME
xsd:tokenlotus.domino.types.TokenXSD_TOKEN
xsd:unsignedBytelotus.domino.types.UnsignedByteByte
XSD_UNSIGNEDBYTE (to WSDL only)
xsd:unsignedIntlotus.domino.types.UnsignedIntXSD_UNSIGNEDINT
xsd:unsignedLonglotus.domino.types.UnsignedLongXSD_UNSIGNEDLONG
xsd:unsignedShortlotus.domino.types.UnsignedShortXSD_UNSIGNEDSHORT

Arrays
For Domino 7:

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


For example, an array of type int (Java) or Long (LotusScript) generates the following WSDL:
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 above 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:


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:


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:

For example, an enumeration of vegetables containing members of type String generates the following WSDL:
Both LotusScript and Java implementations of an enumeration reflect a specific pattern comprised of: All identifying characteristics (bolded in the examples) must be present in the implementation for any WSDL generation to detect and correctly represent an enumeration.

Note the Java enumeration pattern prohibits the presence of a Java Bean set: method, i.e. a setValue method with one parameter, where the parameter type matches the getValue method return type).

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”, above) 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 above):


This complexType maps to LotusScript as:
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):


is a legal value for an instance of this list type:
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:


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 above “telephone” data type would map to the following Java package and class:


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 above “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:

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:

Example