Java と LotusScript のマッピング

実装コード

Web サービスの実装コードは Web サービス自体のパブリッククラスに置かれます。

クラスは、プロパティボックスの [基本] タブで [PortType class] として識別されていることが必要です。
クラスには、Web サービスの操作ごとに 1 つのパブリックメソッド、関数、サブルーチンが含まれます。メソッド、関数、サブルーチンの名前は WSDL 文書の操作名です。プライベートメソッド、関数、サブルーチンは公開されません。
入力メッセージパートはメソッド、関数、サブルーチンへのパラメータとして渡されます。出力メッセージパートはメソッドまたは関数の戻り値、またはメソッドかサブルーチンからのパラメータとして渡されます。障害メッセージパートはサービス固有の戻り値を指定します。これは、エラーの発生時に操作が発行できる値です。

利用者が Web サービスの操作を呼び出すと、Domino はパラメータとして入力メッセージを渡し、対応するメソッド、関数、サブルーチンを呼び出します。メソッドまたは関数が正常に終了すると、Domino は操作の出力メッセージとして戻り値またはパラメータを使用します。

Java の宣言と初期化

Java コードには、標準 Java パッケージには定義されていない障害データ型、XML Schema データ型、ホルダークラスに対する次の import が含まれることがあります。

import lotus.domino.types.*

lotus.domino パッケージには、静的メソッド getCurrentSession が入ったクラス WebServiceBase があります。通常は、このメソッドを実装クラスのパラメータなしコンストラクタで使用して、Domino セッションを表すセッションオブジェクトを取得します。Domino Web サービスのランタイムエンジンは実装クラスのパラメータなし (デフォルト) コンストラクタを呼び出し、他のすべてのコンストラクタを無視します。デフォルトコンストラクタは明示的ではないことがありますが、明示的にする場合、public を宣言する必要があります。実装で使用する他のコンストラクタも存在することがあります。

Session.getAgentContext() は Web サービスのコンテキストを取得します。次の AgentContext プロパティは Web サービスに適用されます。getCurrentAgent() はカレント Web サービスを取得します。getCurrentDatabase() はカレントデータベースを取得します。getCurrentAgent() の場合、getName()、getOwner()、getCommonOwner()、getOnBehalfOf()、getComment()、getHttpURL()、getNotesURL()、getParent()、getLockHolders() の各エージェントプロパティがカレント Web サービスに反映されます。

System.out はサーバーコンソールおよびサーバーの log.nsf に出力します。

LotusScript のオプション、宣言、初期化

(Options) には次の INCLUDE ステートメントが含まれることがあります。インクルードされるファイルでは、WSDL 文書のデータ型にマップするデータ型を定義します。

%INCLUDE "lsxsd.lss"

通常、(Declarations) には、NotesSession と NotesDatabase (カレントデータベース用) オブジェクトに対する Dim ステートメントが含まれます。

NotesSession オブジェクトの設定など、呼び出す操作の前に常に実行されるコードには実装クラスで Sub NEW を使用します。新しい NotesSession オブジェクトを作成すると、Domino セッションが取得されます。Sub NEW のシグネチャには引数がないことがあります。同じ制限は、Web サービスメソッドが受け取るか返すすべてのクラスの Sub NEW に適用されます (他のクラス内にあるクラスを含む)。

次の NotesSession プロパティは Web サービスに適用されます。CurrentAgent はカレント Web サービスを取得します。CurrentDatabase はカレントデータベースを取得します。CurrentAgent の場合、Name、Owner、CommonOwner、OnBehalfOf、Comment、HttpURL、NotesURL、Parent、LockHolders の各 NotesAgent プロパティがカレント Web サービスに適用されます。

Messagebox はサーバーコンソールおよびサーバーの log.nsf に出力します。

lsxsd.lss ファイルにより、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 の各クラスが定義されます。これらのクラスは、出力および入出力パラメータに使用されます。これらのクラスには、取得と設定が可能なパブリック変数「Value」があります。また、lsxsd.lss では、XML Schema データ型のクラスとホルダークラスも定義します (XSD_BOOLEAN と XSD_BOOLEAN_HOLDER など)。下記「データの説明」の XSD データ型を参照してください。

データの説明

次の基本データ型は、WSDL 文書と対応する Java または LotusScript のコード間で一対一にマップします。特に示されていない限り、LotusScript XSD データ型は lsxsd.lss に定義されており、次の関数とサブルーチンを備えています。

string = GetValueAsString()
Call SetValueFromString(string)

XSD_BASE64BINARY、XSD_DATE、XSD_DATETIME、XSD_HEXBINARY、XSD_TIME の各 LotusScript XSD クラスは、プロキシクラスです。他の XSD クラスと同様、これらのクラスには、取得と設定が可能なパブリック変数「Value」があります。しかし、「Value」変数は String 型ではありません。

XSD_BASE64BINARY と XSD_HEXBINARY クラスの情報は NotesStream 形式で渡されます。これらのクラスには、次の関数とサブルーチンがあります。

NotesStream = GetValueAsNotesStream()
Call SetValueFromNotesStream(NotesStream)

XSD_DATE、XSD_DATETIME、XSD_TIME の各クラスの情報は NotesDateTime 形式で渡されます。これらのクラスには、次の関数があります。

NotesDateTime = GetValueAsNotesDateTime()

Domino 7.0 では、これらのクラスには次のサブルーチンがありました。

Call SetValueFromNotesDateTime(NotesDateTime)

Domino 8.0 では、この元のメソッドは下位互換性を保つためにそのまま残されていますが、次のサブルーチンがこれらのクラスの新しいサブルーチンです。

Call SetValueWithZoneFromNotesDateTime( NotesDateTime )

この新しいサブルーチンでは、XSD タイムゾーンの情報が結果の XML 値に追加されます。署名が同じであるため、ユーザーは、必要な場合、LSXSD.LSS の SetValueFromNotesDateTime の実装を書き直して、新しいメソッドを呼び出すことができます。

特に示されていない限り、データ型は双方向にマップされます (WSDL 文書とコード間)。

WSDL	Java	LotusScript
xsd:any (要素)	org.w3c.dom.Element	NotesDomElementNode (バックエンドクラス)
xsd:anyType	java.lang.Object	XSD_ANYTYPE
		Variant (WSDL へのみ)
xsd:anyURI	lotus.domino.types.URI	XSD_ANYURI
soapenc:base64	byte[] (WSDL からのみ)	ByteArray_Holder (WSDL からのみ)
soapenc:base64Binary	byte[] (WSDL からのみ)	ByteArray_Holder (WSDL からのみ)
xsd:base64Binary	byte[]	ByteArray_Holder
		XSD_BASE64BINARY
soapenc:boolean	java.lang.Boolean (WSDL からのみ)	XSD_BOOLEAN (WSDL からのみ)
xsd:boolean	boolean 型	Boolean 型
	java.lang.Boolean (WSDL へのみ)	XSD_BOOLEAN (WSDL へのみ)
soapenc:byte	java.lang.Byte (WSDL からのみ)	XSD_BYTE (WSDL からのみ)
xsd:byte	byte 型	XSD_BYTE
	java.lang.Byte (WSDL へのみ)
xsd:date	java.util.Date	XSD_DATE
xsd:dateTime	java.util.Calendar	XSD_DATETIME
soapenc:decimal	java.math.BigDecimal (WSDL からのみ)	XSD_DECIMAL (WSDL からのみ)
xsd:decimal	java.math.BigDecimal	XSD_DECIMAL
soapenc:double	java.lang.Double (WSDL からのみ)	XSD_DOUBLE (WSDL からのみ)
xsd:double	double 型	Double 型
	java.lang.Double (WSDL へのみ)	XSD_DOUBLE (WSDL へのみ)
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 (WSDL からのみ)	XSD_FLOAT (WSDL からのみ)
xsd:float	float 型	Single
	java.lang.Float (WSDL へのみ)	XSD_FLOAT (WSDL へのみ)
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 (WSDL からのみ)	XSD_INT (WSDL からのみ)
xsd:int	int 型	Long 型
	java.lang.Integer (WSDL へのみ)	XSD_INT (WSDL へのみ)
soapenc:integer	java.math.BigInteger (WSDL からのみ)	XSD_INTEGER (WSDL からのみ)
xsd:integer	java.math.BigInteger	XSD_INTEGER
xsd:language	lotus.domino.types.Language	XSD_LANGUAGE
soapenc:long	java.lang.Long (WSDL からのみ)	XSD_LONG (WSDL からのみ)
xsd:long	long 型	XSD_LONG
	java.lang.Long (WSDL へのみ)
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 (WSDL からのみ)	XSD_SHORT (WSDL からのみ)
xsd:short	short 型	Integer
	java.lang.Short (WSDL へのみ)	XSD_SHORT (WSDL へのみ)
soapenc:string	java.lang.String (WSDL からのみ)	String (WSDL からのみ)
xsd:string	java.lang.String	String
		XSD_STRING (WSDL へのみ)
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 (WSDL へのみ)
xsd:unsignedInt	lotus.domino.types.UnsignedInt	XSD_UNSIGNEDINT
xsd:unsignedLong	lotus.domino.types.UnsignedLong	XSD_UNSIGNEDLONG
xsd:unsignedShort	lotus.domino.types.UnsignedShort	XSD_UNSIGNEDSHORT

配列

Domino 7 の場合:

配列は WSDL で次の属性とサブ要素を持つ XML Schema <complexType> エンティティ要素にマップされます。

name = "ArrayOf_xsd_" にデータ型名を加えたもの (ArrayOf_xsd_int など)
restriction base = "soapenc:Array"
attribute ref = "soapenc:arrayType
wsdl:arrayType = "xsd:" にデータ型と「[]」を加えたもの (xsd:int[] など)

例えば、int 型 (Java) または Long 型 (LotusScript) の配列は次の 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>

配列は WSDL の個々の <element> エンティティにマップされることもあります。その場合、1 より大きい値を持つ maxOccurs 属性が存在します。この 2 番目の配列表現形式は外部定義された任意の WSDL 文書に現れることがありますが、Designer で生成された WSDL では、Java Web サービスに対して、インデックス付きアクセサーを持つ Java 値型の配列メンバーに対してのみ使用されます。

Domino 8 の場合:

配列は、主にエンコードされたサービスの場合、つまり「RPC/エンコード」の SOAP メッセージ形式の Web サービスの場合は、上記で説明されている「soapenc:Array」パターンにマッピングされます。

「リテラル」サービス (つまり、RPC/リテラル、Doc/リテラル、ラップの SOAP メッセージ形式) の場合は、配列は「リテラル」配列 (「maxOccurs」属性の値が「unbounded」で、単一の <element> を持つ <complexType>) にマップされます。次はその例です。

<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>

また、ここで示す「リテラル」形式は、インデックス付きメンバーアクセサーを持つ Java Web サービス値型配列の WSDL でも生成されます。

初期化されていない配列

Domino 8.0 では、SOAP 要求 (Web サービスプロバイダの場合) または SOAP 応答 (Web サービスコンシューマの場合) 内の空の配列は、非直列化され次の配列になります。

空の配列オブジェクト -- Java の場合
初期化されていない動的配列 -- LotusScript の場合

Java の場合は、これは Domino 7.x の場合と同じ動作ですが、LotusScript の場合は、(可能な場合はいつでも単一要素の配列を返す) Domino 7.x とは異なります。空の配列を受け取る可能性のある Domino 8.0 のスクリプトは、動的配列の内容を照会する際に LotusScript エラー 200 を処理するよう実装する必要があります。

クラス

通常、Web サービス操作との間で渡すクラス (値型とも呼ばれます) は、WSDL で各公開データメンバーを表すサブ要素を持つ XML Schema <complexType> 要素にマップされます。以下に例を示します。

      <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>

LotusScript の場合、公開クラスのデータメンバーはパブリックと宣言されたメンバーです。

Java の場合、公開クラスのデータメンバーはパブリックであるメンバー、または Java Bean の特性である public get および set メソッドを持つメンバーです。認識可能な Java 値型クラスには、デフォルトのパブリックコンストラクタ (引数なし) が必要です。

列挙

列挙は、WSDL で次の特性を持つ XML Schema <simpleType> 要素にマップされます。

基になる型の「base」属性を持つ restriction サブ要素。
enumeration ファセット (1 つ以上のサブ要素)。それぞれ列挙のメンバーを指定します。

例えば、String 型のメンバーが入った野菜の列挙は次のような 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 と Java 実装には、次の項目から構成される特定のパターンが反映されます。

列挙メンバー値ごとの定数
列挙メンバーを表すクラス
列挙自体を表す列挙メンバークラスインスタンスの集合
Web サービスメソッド呼び出しの直前に列挙を設定するイニシャライザーコード

WSDL 生成で列挙を検出し、正しく表すためには、実装にすべての識別特性 (例では太字) が存在している必要があります。

注: Java 列挙パターンで Java Bean set: メソッドを使用することはできません。このメソッドは 1 つのパラメータを持つ setValue メソッドであり、パラメータの型は getValue メソッドの戻り値の型に一致します。

障害

障害では、呼び出し元にエラー状態を伝達します。任意の Web サービスメソッドから発信できます。障害は WSDL コントラクトに明示的であったり (WSDL 文書でサービス操作に指定)、WSDL コントラクトに暗黙的であったりします (サービスメソッドのシグネチャの一部として実装のみ)。

明示的障害は、<wsdl:input> および <wsdl:output> 要素と共に、操作に指定される省略可能な <wsdl:fault> 要素として WSDL に表されます。以下に例を示します。

<wsdl:operation name="getStockQuote">
   <wsdl:input message="getStockQuoteRequest"/>
   <wsdl:output message="getStockQuoteResponse"/>
   <wsdl:fault name="InvalidSymbolFault" message="InvalidSymbolFaultMessage"/>
</wsdl:operation>

操作の <wsdl:input> または <wsdl:output> 要素と同様、<wsdl:fault> 要素は message 属性によって型が設定されます。

したがって、WSDL 障害は関連メッセージの「パート」型により、LotusScript または Java の実装のクラスにマップされます。このクラスは、WS_FAULT (LotusScript) または lotus.domino.types.Fault (Java) のサブクラスです。

実装の値型 (「クラス」を参照) が関連する WSDL 構成体 (通常は WSDL <complexType>) にマップされるのと同様に、この実装の障害サブクラスは WSDL 障害の関連メッセージに定義されたデータメンバーにマップされます。

例えば、次の WSDL complexType があるとします (ここでは、例の「InvalidSymbolFaultMessage」の型として指定)。

      <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"/>

この complexType は次のように LotusScript にマップされます。

Class InvalidSymbolFaultMessage As WS_FAULT

Public TickerSymbol As String
Public ApplicationCode As Integer

Sub NEW
End Sub

End Class

Java には次のようにマップされます。

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... }

Web サービスの操作が呼び出し元にサービス固有の追加データを送信する必要がない場合、明示的な WSDL 障害は必要なく、暗黙的障害で十分です。

暗黙的障害は常に使用でき、Web サービスフレームワークによってさまざまな呼び出しエラーに対して発行されます。しかし、実装 PortType クラスに公開されたサービスメソッドによって発行されることもあります。

また、実装メソッド署名への暗黙的障害の追加または削除は、Web サービスコントラクトの変更とは扱われないため、それ自体では Web サービスの保存時に WSDL は再生成されません。

サービスメソッドの障害処理は明示的および暗黙的障害のどちらに対しても同様に行われます。例ですべての識別特性は太字になっています。

名前空間

XML Schema では、名前空間修飾子を使用して、名前が似ているが定義が異なる構成体 (特にデータ型) を区別します。次に例を示します。

  <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>

ここで、「telephone」データ型は MyAddressBook 名前空間の一部として指定されています。

Domino Java Web サービスの実装ではマップされた名前空間を Java パッケージとして表します。したがって、「telephone」データ型は次の Java パッケージとクラスにマップされます。

package MyAddressBook;public class Telephone  {
...
}

LotusScript Web サービス実装にはこのように使用するパッケージ構成体がありません。また、LotusScript 識別子の有効な長さは Java に比べて制限されています。したがって、WSDL XML Schema 名前空間は、名前空間定数と LotusScript クラス名に追加された短い接尾辞として、またはデフォルト名前空間に適用される 1 つの「DefaultNamespace」定数としてマップされます。

例えば、「telephone」データ型は次のように WSDL から LotusScript にインポートされます。

Const n1 = "MyAddressBook"  'string constant value can be many characters long
Class Telephone_n1...
End Class

また、次のように「DefaultNamespace」定数を使用して指定することもできます。

Const DefaultNamespace = "MyAddressBook"
Class Telephone                               'no suffix specified
...
End Class

未サポート構成体

このリリースでは、次の WSDL または XML Schema 構成体で、LotusScript または Java へのマッピングは制限されているかサポートされていません。また、Designer の「WSDL のインポート」機能では拒否 (指定した場合は無視) されます。

anyAttribute 要素
choice 要素。ネストされるか、省略可能、または maxOccurs > 1 (配列) の場合
redefine 要素
sequence 要素。maxOccurs > 1 (配列) の場合
union 単純型
vector と map (APACHESOAP 名前空間) -- LotusScript マッピングなし
MIME 添付ファイル
単純型「ファセット」 -- 無視 (列挙を除く)
属性、要素の「デフォルト」値 -- 無視
「混合した」内容 (文字データと複合型サブ要素) -- 無視

同様に、次の LotusScript と Java 構成体では WSDL XML Schema へのマッピングがサポートされていません。また、Web サービス操作の引数または戻り値の型として公開されたとき、Designer の「WSDL のエクスポート」、「WSDL の表示」、「保存」の機能で拒否されます。

LotusScript の list と currency データ型
LotusScript クラス Sub NEW および DELETE (コンストラクタとデストラクタ) の引数
LotusScript LSX オブジェクト
バックエンドクラス (「メッセージ」プログラミングモデルで使用する NotesDomDocumentNode を除く)
Bean 以外 の大部分の Java クラス