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.
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.
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" below.
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.
WSDL |
Java |
LotusScript |
xsd:any (element) |
org.w3c.dom.Element |
NotesDomElementNode (backend class) |
xsd:anyType |
java.lang.Object |
XSD_ANYTYPE |
Variant (to WSDL only) |
||
xsd:anyURI |
lotus.domino.types.URI |
XSD_ANYURI |
soapenc:base64 |
byte[] (from WSDL only) |
ByteArray_Holder (from WSDL only) |
soapenc:base64Binary |
byte[] (from WSDL only) |
ByteArray_Holder (from WSDL only) |
xsd:base64Binary |
byte[] |
ByteArray_Holder |
XSD_BASE64BINARY |
||
soapenc:boolean |
java.lang.Boolean (from WSDL only) |
XSD_BOOLEAN (from WSDL only) |
xsd:boolean |
boolean |
Boolean |
java.lang.Boolean (to WSDL only) |
XSD_BOOLEAN (to WSDL only) |
|
soapenc:byte |
java.lang.Byte (from WSDL only) |
XSD_BYTE (from WSDL only) |
xsd:byte |
byte |
XSD_BYTE |
java.lang.Byte (to WSDL only) |
||
xsd:date |
java.util.Date |
XSD_DATE |
xsd:dateTime |
java.util.Calendar |
XSD_DATETIME |
soapenc:decimal |
java.math.BigDecimal (from WSDL only) |
XSD_DECIMAL (from WSDL only) |
xsd:decimal |
java.math.BigDecimal |
XSD_DECIMAL |
soapenc:double |
java.lang.Double (from WSDL only) |
XSD_DOUBLE (from WSDL only) |
xsd:double |
double |
Double |
java.lang.Double (to WSDL only) |
XSD_DOUBLE (to WSDL only) |
|
xsd:duration |
lotus.domino.types.Duration |
XSD_DURATION |
xsd:ENTITY |
lotus.domino.types.Entity |
XSD_ENTITY |
xsd:ENTITES |
lotus.domino.types.Entities |
XSD_ENTITIES |
soapenc:float |
java.lang.Float (from WSDL only) |
XSD_FLOAT (from WSDL only) |
xsd:float |
float |
Single |
java.lang.Float (to WSDL only) |
XSD_FLOAT (to WSDL only) |
|
xsd:gDay |
lotus.domino.types.GDay |
XSD_GDAY |
xsd:gMonth |
lotus.domino.types.GMonth |
XSD_GMONTH |
xsd:gMonthDay |
lotus.domino.types.GMonthDay |
XSD_GMONTHDAY |
xsd:gYear |
lotus.domino.types.GYear |
XSD_GYEAR |
xsd:gYearMonth |
lotus.domino.types.GYearMonth |
XSD_GYEARMONTH |
xsd:hexBinary |
lotus.domino.types.HexBinary |
XSD_HEXBINARY |
xsd:ID |
lotus.domino.types.Id |
XSD_ID |
xsd:IDREF |
lotus.domino.types.IDRef |
XSD_IDREF |
xsd:IDREFS |
lotus.domino.types.IDRefs |
XSD_IDREFS |
soapenc:int |
java.lang.Integer (from WSDL only) |
XSD_INT (from WSDL only) |
xsd:int |
int |
Long |
java.lang.Integer (to WSDL only) |
XSD_INT (to WSDL only) |
|
soapenc:integer |
java.math.BigInteger (from WSDL only) |
XSD_INTEGER (from WSDL only) |
xsd:integer |
java.math.BigInteger |
XSD_INTEGER |
xsd:language |
lotus.domino.types.Language |
XSD_LANGUAGE |
soapenc:long |
java.lang.Long (from WSDL only) |
XSD_LONG (from WSDL only) |
xsd:long |
long |
XSD_LONG |
java.lang.Long (to WSDL only) |
||
xsd:Name |
lotus.domino.types.Name |
XSD_NAME |
xsd:NCName |
lotus.domino.types.NCName |
XSD_NCNAME |
xsd:negativeInteger |
lotus.domino.types.NegativeInteger |
XSD_NEGATIVEINTEGER |
xsd:NMTOKEN |
lotus.domino.types.NMToken |
XSD_NMTOKEN |
xsd:NMTOKENS |
lotus.domino.types.NMTokens |
XSD_NMTOKENS |
xsd:nonNegativeInteger |
lotus.domino.types.NonNegativeInteger |
XSD_NONNEGATIVEINTEGER |
xsd:nonPositiveInteger |
lotus.domino.types.NonPositiveInteger |
XSD_NONPOSITIVEINTEGER |
xsd:NOTATION |
lotus.domino.types.Notation |
XSD_NOTATION |
xsd:normalizedString |
lotus.domino.types.NormalizedString |
XSD_NORMALIZEDSTRING |
xsd:positiveInteger |
lotus.domino.types.PositiveInteger |
XSD_POSITIVEINTEGER |
xsd:QName |
javax.xml.namespace.QName |
XSD_QNAME |
soapenc:short |
java.lang.Short (from WSDL only) |
XSD_SHORT (from WSDL only) |
xsd:short |
short |
Integer |
java.lang.Short (to WSDL only) |
XSD_SHORT (to WSDL only) |
|
soapenc:string |
java.lang.String (from WSDL only) |
String (from WSDL only) |
xsd:string |
java.lang.String |
String |
XSD_STRING (to WSDL only) |
||
xsd:time |
lotus.domino.types.Time |
XSD_TIME |
xsd:token |
lotus.domino.types.Token |
XSD_TOKEN |
xsd:unsignedByte |
lotus.domino.types.UnsignedByte |
Byte |
XSD_UNSIGNEDBYTE (to WSDL only) |
||
xsd:unsignedInt |
lotus.domino.types.UnsignedInt |
XSD_UNSIGNEDINT |
xsd:unsignedLong |
lotus.domino.types.UnsignedLong |
XSD_UNSIGNEDLONG |
xsd:unsignedShort |
lotus.domino.types.UnsignedShort |
XSD_UNSIGNEDSHORT |
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:
<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 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.
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 (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 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:
<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:
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 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):
<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.
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.
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 above "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 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
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:
See examples