Web services in Domino Designer

The Web Service Provider design element exists under "Code" in the Applications Navigator. The design element has a properties box with Basics, Security, and Advanced tabs, and an editor pane. The functional part of a Web service is a compiled program. A Web service also maintains a WSDL document that reflects the program interface. An imported WSDL document is maintained as is. If coding changes affect the interface, the WSDL document is regenerated when a Web service is saved. Note that when the WSDL document is regenerated for a LotusScript Web service, all LotusScript identifiers which become WSDL names appear in upper-case. This is because LotusScript is a case-insensitive language, and identifier names are maintained internally in uppercase only.

The web services provider design element can be locked and unlocked.

Basics tab

The Basics tab of the properties box contains:

  • Name, Alias, Comment -- Identify the Web service just as you would any other design element such as an agent.
  • Options -- You can check Warn if the WSDL interface is modified. This option is automatically selected when an Import WSDL action is performed.

  • PortType class -- Specify the class that contains the operations (the implementation code) for the port type. (You have to create the class first.)

Security tab

Security of Web services is the same as for agents:

  • Run as web user -- The Java or LotusScript code runs with the effective user name of the user invoking the Web service.
  • Run on behalf of -- The Java or LotusScript code runs on the authority of a specified user. However, the signer of the Web service must have unrestricted premissions on the server or have the permission to run on behalf of anyone.
  • Compile Java code with debugging information -- For Java agents, generates code suitable for debugging.
  • Allow remote debugging -- For LotusScript agents, generates code suitable for remote debugging.
  • Profile this web service -- Allows the collection of run-time statistics for profiling.
  • Set runtime security level (one of the following):
    • 1. Do not allow restricted operations
    • 2. Allow restricted operations
    • 3. Allow restricted operations with full administration permissions
  • Default access for this web service:
    • All readers and greater -- You can select or deselect this option.
    • Enumerated -- If the preceding is deselected, you can enumerate who you want to have default access.
    • Allow Public Access users to use this web service -- Allows default access to those who have public access to documents in the database.

Advanced tab

The beginning of the Advanced tab of the properties box specifies the programming model and SOAP message format. Select one of the following combinations. The default value is RPC programming model, Doc/literal format. The descriptions that follow explain how the options affect the WSDL document:

  • RPC programming model, RPC/encoded
    • For <wsdl:message>, <wsdl:part>: type= specifies an XSD type or a type defined in <wsdl:types>

    • For <wsdlsoap:binding>: style="rpc"
    • For <wsdl:operation>, <wsdl:input> and <wsdl:output>, <wsdlsoap:body>: encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
    • For <wsdl:operation>, <wsdl:input> and <wsdl:output>, <wsdlsoap:body>: use="encoded"
  • RPC programming model, RPC/literal
    • For <wsdl:message>, <wsdl:part>: type= specifies an XSD type
    • For <wsdlsoap:binding>: style="rpc"
    • For <wsdl:operation>, <wsdl:input> and <wsdl:output>, <wsdlsoap:body>: use="literal"
  • RPC programming model, Doc/literal
    • <wsdl:types> defines an element for each input and output
    • For <wsdl:message>, <wsdl:part>: element= specifies an element defined in <wsdl:types>
    • For <wsdlsoap:binding>: style="document"
    • For <wsdl:operation>, <wsdl:input> and <wsdl:output>, <wsdlsoap:body>: use="literal"
  • RPC programming model, Wrapped
    • <wsdl:types> defines a single complex element for each operation's inputs and a single complex element for each operation's outputs, with no attributes; each complex element is named for its corresponding operation

    • For <wsdl:message>, <wsdl:part>: element= specifies an element just defined in <wsdl:types> (each <wsdl:message> has a single <wsdl:part> where name="parameters")

    • For <wsdl:portType>, <wsdl:operation>: parameterOrder=""
    • For <wsdlsoap:binding>: style="document"
    • For <wsdl:operation>, <wsdl:input> and <wsdl:output>, <wsdlsoap:body>: use="literal"
  • Message programming model, document/literal

    • For <wsdl:message>: each has a name= attribute but no <wsdl:part> (The actual SOAP body schema is not public. It is a private contract between consumer and provider.)
    • For <wsdlsoap:binding>: style="document"
    • For <wsdl:operation>, <wsdl:input>, <wsdl:output>, and <wsdlsoap:body>: use="literal"
    • For <wsdl:operation>: these are generated only by service methods that specify the following interface: for LotusScript - Function methodName (doc As NotesDomDocumentNode) As NotesDomDocumentNode; for Java - org.w3c.dom.Document methodName (org.w3c.dom.Document doc)

    In general, use RPC to deserialize the data into concrete data types. Use Message for MOM (message oriented model) service operations that use specific parameter signatures to pass actual XML message syntax from the SOAP body rather than deserializing the data into concrete data types. See Which style of WSDL should I use? by Russell Butek at http://www.ibm.com/developerworks/webservices/library/ws-whichwsdl.

The Advanced tab of the properties box also contains:

  • Include operation name in SOAP action -- This setting affects the "soapAction" attribute of <wsdl:operation> under <Wsdl:binding> for each operation:
    • Deselect for soapAction=""
    • Select for soapAction="nameOfOperation" (where nameOfOperation is the same as the "name" attribute for <operation>)

    The default setting of this option is enabled.

  • Port type name -- Specify the name of the port type for accessing the service. This specification corresponds to the "name" attribute for <wsdl:portType> in the WSDL document. Domino allows one port type per service.
  • Service element name -- Specify the name of the service. This specification corresponds to the "name" attribute of <wsdl:service> in the WSDL document.
  • Service port name -- Specify the port for accessing the service. This specification corresponds to the "name" attribute of <wsdl:port> under <wsdl:service> in the WSDL document. Domino allows one port per service.

Editor pane

The editor pane of the Web service consists of either Java or LotusScript code.

  • Data types -- The Java or LotusScript code defines a class for each data aggregate. In the WSDL document, these classes appear as <complexType> elements, and also <simpleType> elements with enumeration restrictions (facets). Primitive data types and arrays of primitive data types are mapped directly as specified as follows under Java and LotusScript mappings.
  • Implementation (or PortType) class -- The Java or LotusScript code defines a class that contains a public method, function, or sub for each operation in the Web service. In the WSDL document, these operations appear as <wsdl:operation> elements under <wsdl:portType>. The name of the class must match PortType class in the Basics tab of the properties box (the term PortType comes from the W3C specification for WSDL documents).

    In the simple case where an operation has one output part that is not also an input part: the parameters in the Java or LotusScript code map to the <wsdl:input> message for the operation; the return value maps to the <wsdl:output> message. In other cases, for Java: output parts and inout parts map to parameters that are classes that implement the interface javax.xml.rpc.holders.Holder (StringHolder, FloatHolder, and so on); for LotusScript: output and inout parts similarly map to HOLDER classes defined in lsxsd.lss (STRING_HOLDER, SINGLE_HOLDER, and so on).

    Operations may also return errors to the caller, either through a fault sub-class that corresponds to some <wsdl:fault> message specified for the operation in the WSDL document, or through direct use of the WS_FAULT base class (LotusScript), or the lotus.domino.types.Fault or java.lang.Exception classes (Java).

    When you create a new Java Web service, a skeleton implementation class named Untitled is created.

    If you import a WSDL document into a Web service, an implementation class is generated based on the WSDL content. The public prototype methods, functions, and subs in the class correspond to the Web service operations defined for the first <port> element of the first <service> element in the WSDL document. Other classes or types referenced in the prototype methods may also be generated from the WSDL document, along with their public data members. If you change a prototype interface, the corresponding WSDL document changes when the Web service is saved. You can monitor and prevent such changes with the Warn if the WSDL interface is modified property.

    If you create an implementation class from scratch, its prototype methods, functions, and subs determine the messages and operations defined in the WSDL document.

  • Libraries -- LotusScript code can be stored in libraries. The following restrictions apply to Domino 7.x Web services-only. Namespace constants must be in the same location as the implementation class. Enumeration classes and associated List objects and constants must be in the same location as the implementation class. These restrictions do not apply to Web services created using Domino Designer 8.0.

  • Java caveats -- Java code is cached and shared over multiple instances of a Web service, enhancing performance but imposing the following restraints: do not use static data as changes made by one instance affect all instances; avoid synchronization as the scope of the classes and objects being synchronized may cross instances.