PROGRAMMING DOMINO FOR WEB APPLICATIONS
Implementation code
The implementation code for a Web service is in its own public class:
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.
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.
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:
Call SetValueFromString(string)
The information for the classes XSD_BASE64BINARY and XSD_HEXBINARY is passed in NotesStream format. These classes have the following function and sub:
Call SetValueFromNotesStream(NotesStream)
The data types map both ways (WSDL document to code and vice-versa) except as noted.
Arrays map to XML Schema <complexType> entities elements in WSDL, with the following attributes and subelements:
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:
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 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:
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):
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):
Namespaces XML Schema uses namespace qualifiers to differentiate among like-named but differently-defined constructs, especially data types, for example:
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:
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:
Example