Examples: Web services data descriptions

Example 1: Enumerations

This example illustrates an enumeration of vegetables containing members of type String. All identifying characteristics (bolded in the examples) must be present in the implementation for any WSDL generation to detect and correctly represent an enumeration.

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>

LotusScript enumeration pattern

[Declarations]
'member value constants:
Const VegetableType_carrot$ = "Carrot"  
'constant name prefix matches enum class name
Const VegetableType_lettuce$ = "Lettuce"
Const VegetableType_ketchup$ = "Ketchup"


'member instances:
Dim Carrot_VegetableType As VegetableType 
'instance name suffix matches enum class name
Dim Lettuce_VegetableType As VegetableType
Dim Ketchup_VegetableType As VegetableType


'LotusScript list of members:
Dim Enum_VegetableType List As VegetableType 
' prefix "Enum_" includes a trailing underscore



'enumeration class:
Class VegetableType 
'class name matches list name suffix and list type
	Public Value As String    'first public property; 
	                          'type matches constants type
	Sub NEW
	End Sub
	'initializer:
	Sub Initialize (elem As String)
		Let Value = elem
		Set Enum_VegetableType(Cstr(Value)) = Me
	End Sub
	'optional helper functions
	Function Equals (you As VegetableType) As Boolean...
	Function ToString As String...
End Class

[global Sub's]
'initialization (called from Sub NEW of the PortType class)
Sub VegetableType_Initialize
Set Carrot_VegetableType = New VegetableType
Call Carrot_VegetableType.Initialize(VegetableType_Carrot)
	Set Lettuce_VegetableType = New VegetableType
	Call Lettuce_VegetableType.Initialize(VegetableType_Lettuce)
	Set Ketchup_VegetableType = New VegetableType
	Call Ketchup_VegetableType.Initialize(VegetableType_Ketchup)
End Sub

'optional helper functions
Function VegetableType_FromValue (value As String) As VegetableType...
Public Function VegetableType_FromString (value As String) As VegetableType...

Java enumeration pattern

public class VegetableType  {
   private java.lang.String _value_;
   private static java.util.HashMap _table_ = new java.util.HashMap();

// Constructor
protected VegetableType(java.lang.String value) {
_value_ = value;
_table_.put(_value_,this);
}


// enum values; type matches private "value" data member type:
public static final java.lang.String  _Carrot  = "Carrot";
public static final java.lang.String  _Lettuce = "Lettuce";
public static final java.lang.String  _Ketchup = "Ketchup";

public static final VegetableType  Carrot = new VegetableType(_Carrot);
public static final VegetableType  Lettuce = new VegetableType(_Lettuce);
public static final VegetableType  Ketchup = new VegetableType(_Ketchup);


// return type matches the type of the private "value" data member:
public java.lang.String getValue() { return _value_;}
    

// parameter type matches "getValue" return type: 
public static VegetableType fromValue( java.lang.String value) 
   throws java.lang.IllegalVegetableException {
VegetableType enum = (VegetableType)
_table_.get(value);
if (enum==null) throw new java.lang.IllegalVegetableException();
return enum;
}


public static VegetableType fromString( java.lang.String value )
   throws java.lang.IllegalVegetableException {
return fromValue(value);
}

public java.lang.String toString() { return _value_;}
    
   public boolean equals(java.lang.Object obj) {return (obj == this);}
   public int hashCode() { return toString().hashCode();}
}

Example 2: Faults

This example shows service method fault handling is the same for both explicit and implicit faults:

LotusScript fault (explicit)

Class FaultServicePortType

Function getStockQuote( tickerSymbol As String, 
Fault1 As InvalidSymbolFaultMessage ) As Single

...
	' WS_FAULT base class properties
	Call Fault1.setFault(True)        ' required for fault activation
	Call Fault1.setFaultString("getQuote InvalidTickerFaultMessage")  
                                      ' optional fault message

	' fault subclass properties
	Let Fault1.TickerSymbol = tickerSymbol
	Let Fault1.ApplicationCode = "12345"

End Function

End Class

LotusScript fault (implicit)

Function getStockQuote( tickerSymbol As String, Fault1 As WS_FAULT ) As Single
...
	' WS_FAULT base class properties
	Call Fault1.setFault(True)               ' required for fault activation
	Call Fault1.setFaultString("getQuote InvalidTickerFaultMessage")
   	'optional fault message
End Function

Java fault (explicit)

public class FaultServicePortType {

   public float getStockQuote( java.lang.String tickerSymbol ) throws
   InvalidSymbolFaultMessage {
...
   throw new InvalidSymbolFaultMessage( tickerSymbol, 12345 );
   }
}

Java fault (implicit)

public float getStockQuote( java.lang.String tickerSymbol ) throws lotus.domino.types.Fault {
   ...
   java.lang.Exception e = new java.lang.Exception("Thrown exception");
   throw lotus.domino.types.Fault.makFault(e);     // static factory method
}

or even simpler:

public float getStockQuote( java.lang.String tickerSymbol ) throws java.lang.Exception {
   ...
   throw new java.lang.Exception("Thrown exception");
}

Example 3: Lists

This example illustrates a list of vegetables, consisting of the three items Carrot, Lettuce, and Ketchup.

WSDL

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

LotusScript list pattern

Class ListOfVegetables As XSD_LIST   'list base class
	Public value() As String         'one public array property; 
	                                 'array type maps to a SimpleType

	'mandatory helper member and methods for de/serialization:
	Private initialized As Boolean
	Sub setListValueFromString (idx As Integer, value As String)
		If idx < 0 Then Error ErrArgOutOfRange
		If Not initialized Then
			Redim Me.value(0 To idx)
			Let initialized = True
		Else
			If idx > Ubound(Me.value) Then Redim Preserve Me.value(0 To idx)
		End If
		Let Me.value(idx) = Cstr(value)  
                            'cast must produce a value( ) array element type
	End Sub
	
	Function getListValueAsString (idx As Integer) As String
		If Not initialized Then Error ErrArgOutOfRange
		getListValueAsString = Cstr(value(idx))
	End Function
	
	Function getListLength () As Integer
		If Not initialized Then
			getListLength = 0
		Else
			getListLength = Ubound(value)+1
		End If
	End Function

End Class

Let Me.value(idx) = Cstr(value)

is replaced by two statements:

Set Me.value(idx) = New XSD_NCNAME 'creates an instance of the simple type class

Call Me.value(idx).setValueFromString(value)

Similarly, the last statement in Sub getListValueAsString is replaced by:

getListValueAsString = value(idx).getValueAsString

Java list pattern

public class ListOfVegetabless implements lotus.domino.types.SimpleType {  
									 // SimpleType interface
	private java.lang.String[] value;	 // private instance member, array, 
									 // named "value"
									 // array type maps to a simple type
	// default constructor
	public ListOfWords() {
	}
	// constructor that accepts the private array member
	public ListOfWords(java.lang.String[] value) {
		this.value = value;
	}
	// simple type String constructor
	public ListOfWords(java.lang.String value) {
		StringTokenizer st = new StringTokenizer(value, "\r\n\t ");
		this.value = new java.lang.String[st.countTokens()];
		for(int i = 0; st.hasMoreTokens(); i++) {
			this.value[i] = new java.lang.String(st.nextToken());
		}
	}
	// simple type toString method for serializing the array value
	public java.lang.String toString() {
		if (value == null)
			return null;
		String ret = new String();
		for (int i = 0; i < value.length; i++) {
			ret += value[i].toString();
			if ((i+i) < value.length)
				ret += " ";
		}
		return ret;
	}
	// public getter method for private array member	
	public java.lang.String[] getValue() {
		return value;
	}
	// public setter method for private array member
	public void setValue(java.lang.String[] value) {
		this.value = value;
	}
	// optional helper methods
	public synchronized boolean equals(java.lang.Object obj) {...}
	public synchronized int hashCode() {...}
}