SOAP による Infor*Engine タスク呼び出し
SOAP リクエストを通じて Info*Engine タスクを呼び出すには、以下の条件を満たす必要があります。
• タスクは、論理 CLASS 引数に対応するタスクルートディレクトリの下位のディレクトリパスに置く必要があります。これにより、クラスがサポートするタスク (またはメソッド) を論理的および階層的に整理された状態で維持できます。タスクに関連付けられたタスク代理エントリがタスクを正しく参照するかぎり、タスクルート内の任意の場所にタスクを配置できます。タスクは、タスク階層内の任意の場所に配置できます。
• タスクは、SOAP リクエスト内で使用される CLASS を反映した名前のタイプ識別子内に、タスク代理として登録される必要があります。タスク委任は、委任管理ユーティリティまたは提供されたツールを使用して手動で作成できます。
• タスクに入力パラメータが必要であるか、タスクが Info*Engine グループ以外のレスポンスを返す場合、SOAP マークアップコメント内に特別な SOAP コメント行を含める必要があります。詳細については、セクション「SOAP コメントの挿入」を参照してください。
|
|
@return コメントを省略しても指定してもクライアントにとっては同じ結果が得られますが、PTC では以下のコメントを含めることを推奨しています。
@return INFOENGINE_GROUP $(output)
@return コメントを指定しないと、データは XML 表現でシリアル化されて String としてレスポンスにそのまま引き継がれるので、クライアントは SOAP の戻り値を逆シリアル化してから内部で XML を処理することになります。なるべく @return 行を指定して Info*Engine Group タイプを返すようにしてください。これによって、より有用なインタフェースが作成され、効率が向上します。
|
サポートされるデータタイプ
Info*Engine SOAP RPC サーブレットは、プリミティブ型、Java クラス、特殊な Info*Engine クラスを含む以下のデータタイプをサポートします。
• boolean, java.lang.Boolean
• double, java.lang.Double
• long, java.lang.Long
• float, java.lang.Float
• int, java.lang.Integer
• short, java.lang.Short
• byte, java.lang.Byte
• string, java.lang.String
• dateTime, java.util.Date
• java.math.BigDecimal
また、以下の Info*Engine 固有のデータタイプは、Info*Engine データ構造を SOAP リクエスト内に埋め込まれた XML として転送する目的でもサポートされています。
• INFOENGINE_COLLECTION
• INFOENGINE_GROUP
• INFOENGINE_ELEMENT
• INFOENGINE_ATTRIBUTE
各タイプのパラメータは、同等の Java クラスとしてサポートタスクに提供されます。これらのデータタイプの値が 1 つの場合、その値を入力パラメータまたは出力値として使用できます。
|
|
厳密にタイプ指定された入力パラメータを SOAP サービスで指定するには、厳密にタイプ指定された SOAP リクエストを SOAP クライアントで指定する必要があります。Microsoft SOAP Toolkit などの一部のサードパーティ製クライアントでは、厳密にタイプ指定された SOAP リクエストを指定しないので、結果的にすべての入力パラメータが文字列としてタスクに提供されます。
|
基本データタイプおよび基本データタイプの配列に加えて、Info*Engine SOAP では、Java Beans 形式の複雑なタイプも個別に、また配列内でサポートします。また、インデックシングプロパティおよびネステッド Beans もサポートします。ネステッド Beans を返すには、複雑な Info*Engine グループを生成する必要があります。現在、Info*Engine Webject は複雑なネステッドグループを生成しないので、複雑なグループは手動で作成する必要があります。
実行時に Beans をインスタンス化、検証、および操作可能にするには、Info*Engine サーバーおよび SOAP RPC サーブレットの CLASSPATH の中に Java Beans のクラスが含まれている必要があります。同様に、SOAP で通信するクライアント側で Info*Engine Java EE コネクタなどの Info*Engine クラスを使用する場合、クライアントの CLASSPATH の中にも Java Beans のクラスが含まれている必要があります。Info*Engine Java EE コネクタの詳細については、
Info*Engine Java EE コネクタを参照してください。
SOAP コメント
Info*Engine SOAP タスクには、入力パラメータやレスポンスタイプについて記述したコメントセクションが必要です。Info*Engine は、この SOAP コメントセクションを使用して、各 Info*Engine タスクが外部 SOAP クライアントに対して公開するインタフェースを記述する WSDL を生成します。サードパーティ製ソフトウェアは、生成された WSDL を使用して、入力パラメータの検証とレスポンスタイプのキャスト、または Info*Engine SOAP サービスとの通信に使用されるクライアント側ソースコードを生成できます。Info*Engine で提供される一部のツールは、WSDL を利用してクライアント側のデータアクセスオブジェクト (DAO) を生成し、これを使用して Info*Engine タスクを呼び出して、通信プロトコルとしての SOAP の使用に関連するすべての詳細情報を抽象化します。詳細については、
DAO の生成を参照してください。
また、SOAP コメントセクションは、Java ドキュメンテーションのようなドキュメントをタスクに生成する場合にも使用できます。このドキュメントの生成方法および生成ツールへのリンクについては、以下の URL にアクセスして、Windchill で利用できるドキュメントを参照してください。
http://<ホスト>/<サーブレット>/infoengine/jsp/tools/doc/howto.html
ここで、<サーブレット> は SOAP サーブレットに対して定義されたアプリケーション URL です。
|
|
このコメントセクションは、入力パラメータがなく、デフォルトの Info*Engine グループをレスポンスとして返すタスクも含め、すべての SOAP タスクに含める必要があります。
|
コマンドセクションは以下のとおりです。
<!--com.infoengine.soap.rpc.def
description
special_comments
-->
ここで、description はオプションのタスクの説明、special_comments は以下で説明する特別な SOAP コメント行です。
コメントセクションに特別な SOAP コメント行を挿入し、入力パラメータと出力値を指定できます。特別なコメント行については、この後の 2 つのセクションで説明します。
@param
@param コメント行を使用して、入力パラメータを指定します。コメント行は、以下のフォーマットで指定します。
@param type[] name comment
ここで、
• type はパラメータのデータタイプです。
• [] は値の配列を示します。パラメータタイプと [] の間に空白はありません。配列は、複数の値を指定できる属性として @FORM コンテキストグループで使用可能です。配列を使用すると、標準の Info*Engine 代入構文を使用して、複数値の入力を簡単に操作できます。
• name はパラメータの名前です。
• comment はパラメータを説明するテキストです。これはオプションのパラメータです。
|
|
一部の Info*Engine 固有のデータタイプは、入力データの抽出にスクリプトレットコードを必要としないほかのデータタイプとは異なる方法で処理されます。
|
コレクションがパラメータで与えられる場合、コレクション自体はタスクに入力として与えられません。代わりに、入力コレクション内のすべてのグループがタスクで使用できるように VDB 内に配置されます。タスクの著作者はグループの名前を知っていると見なされます。以下に例を示します。
@param INFOENGINE_COLLECTION input_collection A collection of Groups.
グループがパラメータで与えられる場合、直接使用できるように、タスクの VDB 内に直接配置されます。さらに、呼び出し側でグループに別の名前を指定した場合は、グループ名がパラメータ名で置き換えられます。下記のグループパラメータのコンテンツは、タスク内で $(input_group[]attribute[]) などのフォーム置換式を使用することによって使用できます。
@param INFOENGINE_GROUP input_group A group.
要素または要素の配列が入力値として提供されている場合、パラメータ名を使用して名付けられたグループに配置され、VDB に追加されます。下記のパラメータで指定されている入力要素は、$(input_element[0]attribute[]) などのフォーム置換を使用してタスク内で使用できます。以下の例では、"input_element" というグループに単一の要素が含まれます。
@param INFOENGINE_ELEMENT input_element An element.
@return
@return コメント行を使用して、出力またはレスポンスタイプを指定します。@return コメント行が存在しない場合、Info*Engine SOAP サービスは、出力グループのシリアライズされた Info*Engine XML 表現を返します。出力グループの名前には、$(@FORM[]group_out[]) パラメータ値を使用する必要があります。コメント行は、以下のフォーマットで指定します。
@return type[] substitution comment
ここで、
• type はレスポンスのデータタイプです。
• [] は値の配列を示します。レスポンスタイプと [] の間に空白はありません。
• substitution は以下に示すように標準の Info*Engine 代入構文に類似しています。
$(groupName[elementIndex]attributeName[attributeIndex])
ここで、
◦ groupName は出力グループの名前です。
◦ elementIndex は要素の位置です。指定しない場合、elementIndex の値はデフォルト値である最初の要素を示す 0 になります。
◦ attributeName は属性の名前です。
◦ attributeIndex は要素の属性の位置です。指定しない場合、attributeIndex の値はデフォルト値である最初の属性を示す 0 になります。
返される配列に値を挿入するには、代入構文の elementIndex または attributeIndex のいずれかの部分にアスタリスク (*) を指定する必要があります。ただし、2 次元配列はサポートされていないので、両方には指定できません。アスタリスク (*) を attributeIndex として指定した場合、出力グループの単一要素内にある複数の値を指定できる属性から配列が生成されます。アスタリスク (*) を elementIndex として指定した場合、出力グループの各要素にある各 attributeName の最初の値を使用して配列が生成されます。
Java Beans を返す場合、以下の 2 つの例外を除き、@return コメント行を上記のとおりに指定します。
• 代入構文の attributeName[attributeIndex] の部分がありません。
• Java Beans の配列を返すには、代入構文の elementIndex の場所にアスタリスク (*) を指定する必要があります。
Java Beans または Java Beans の配列には、出力グループの参照要素で見つかった属性に基づいて値が挿入されます。レスポンスグループの属性名は、Java Beans のプロパティに直接対応します。Change-Group Webject などを使用してレスポンスグループの属性名を操作し、グループの属性名を対応する Java Beans のプロパティと一致させることが必要な場合があります。
Info*Engine 固有のデータタイプを使用して Info*Engine データを返す場合、@return パラメータのフォーマットは以下のようになります。
@return INFOENGINE_COLLECTION
@return INFOENGINE_GROUP $(group_Name)
@return INFOENGINE_ELEMENT $(groupName[elementIndex])
@return INFOENGINE_ATTRIBUTE $(groupName[]attributeName)
ここで、
• groupName は出力グループの名前です。
• elementIndex は要素の位置です。指定しない場合、elementIndex の値はデフォルト値である最初の要素を示す 0 になります。
• attributeName は属性の名前です。
簡単なデータタイプの例
以下の例は、Info*Engine タスクを記述して実行する必要があるアクティビティの種類を示すものではありません。この例の目的は、入出力パラメータがどのように機能するかを示すことです。
|
|
これらのタスクには、厳密にタイプ指定された入力パラメータを前提としたスクリプトレットコードが含まれているので、Info*Engine サーブレットを使用して Web ブラウザで直接呼び出すことはできません。これは、@FORM データが正しくタイプ指定されないことが原因です。厳密にタイプ指定された SOAP リクエストを生成する SOAP クライアントでのみ、これらの特別な SOAP タスクを呼び出すことができます。リクエストが厳密にタイプ指定されていない場合、ClassCastException が発生します。
|
以下の例は、2 つの整数を入力パラメータとして指定し、それらの合計を返します。
<%@page language="java"%>
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<!--com.infoengine.soap.rpc.def
this task takes two integers and adds them together
@param int x
@param int y
@return int $(output[]sum[])
-->
<%
Integer x = (Integer)getParam ( "x" );
Integer y = (Integer)getParam ( "y" );
String element = "sum=" + (x.intValue()+y.intValue());
%>
<ie:webject name="Create-Group" type="GRP">
<ie:param name="ELEMENT" data="<%=element%>"/>
<ie:param name="GROUP_OUT" data="output"/>
</ie:webject>
以下の例は、float の配列の合計を返します。
<%@page language="java"%>
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<!--com.infoengine.soap.rpc.def
this task sums an array of floats
@param float[] toSum
@return float $(output[0]sum[0])
-->
<%
java.util.Vector floats = getParams ( "toSum" );
Float [] toSum = new Float[floats.size()];
floats.copyInto ( toSum );
float sum = 0.0;
for ( int i = 0; toSum != null && i < toSum.length; i++ )
sum +=toSum[i].floatValue();
String element = "sum=" + sum;
%>
<ie:webject name="Create-Group" type="GRP">
<ie:param name="ELEMENT" data="<%=element%>"/>
<ie:param name="GROUP_OUT" data="output"/>
</ie:webject>
以下の例は、従業員データベースを照会し、すべての従業員番号の配列を返します。
<%@page language="java"%>
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<!--com.infoengine.soap.rpc.def
this task queries an employee database and returns an array of all
employee numbers
@return string[] $(output[*]empno[])
-->
<ie:webject name="Query-Objects" type="OBJ">
<ie:param name="INSTANCE" data="jdbcAdapter"/>
<ie:param name="CLASS" data="EMP"/>
<ie:param name="WHERE" data="()"/>
<ie:param name="GROUP_OUT" data="output"/>
</ie:webject>
Java Beans の例
|
|
これらの Java Beans の例では、LDAP ディレクトリでユーザーオブジェクトを作成する場合に JNDI アダプタを使用しています。これらのユーザーオブジェクトを、Windchill で使用できるユーザーオブジェクトと混同しないでください。
|
このセクションの例では、以下の Java Beans を使用します。
package my.org;
// exposes properties:
// cn, sn, dn, uid and indexed property mail
// properties could be any primitive types or java beans
// but for the sake of an LDAP example things are just strings
import java.util.Vector;
public class Person {
private String cn;
private String sn;
private String dn;
private String uid;
private Vector mails = new Vector ( 1 );
public void setCn ( String n ) { cn = n; }
public String getCn () { return cn; }
public void setSn ( String n ) { sn = n; }
public String getSn () { return sn; }
public void setDn ( String n ) { dn = n; }
public String getDn () { return dn; }
public void setUid ( String n ) { uid = n; }
public String getUid () { return uid; }
public void setMail ( int index, String m ) {
if ( index == mails.size() )
mails.addElement ( m );
else
mails.setElementAt ( m, index );
}
public String getMail ( int index ) {
return (String)mails.elementAt ( index );
}
public void setMail ( String vals[] ) {
mails.clear();
for ( int i = 0; vals != null && i < vals.length; i++ )
mails.addElement ( vals[i] );
}
public String [] getMail () {
if ( mails.isEmpty() ) return null;
String arr [] = new String[mails.size()];
mails.copyInto ( arr );
return arr;
}
}
以下の例は、ユーザー ID (uid) でユーザーエントリを検索します。
<%@page language="java"%>
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core" prefix="ie"%>
<!--com.infoengine.soap.rpc.def
looks up a user entry by uid
@param string uid
@return my.org.Person $(output[0])
-->
<ie:webject name="Query-Objects" type="OBJ">
<ie:param name="INSTANCE" data="com.myCompany.myHost.ldap"/>
<ie:param name="BASE" data="ou=People,o=Company"/>
<ie:param name="SCOPE" data="subtree"/>
<ie:param name="FILTER" data="uid=$(@FORM[]uid[])"/>
<ie:param name="GROUP_OUT" data="output"/>
</ie:webject>
<ie:webject name="Change-Group" type="GRP">
<ie:param name="GROUP_IN" data="output"/>
<ie:param name="GROUP_OUT" data="output"/>
<ie:param name="RENAME" data="'object'='dn'"/>
</ie:webject>
以下の例は、LDAP サーチフィルタを使用してユーザーリストを検索します。
<%@page language="java"%>
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core" prefix="ie"%>
<!--com.infoengine.soap.rpc.def
searches for a list of users by an LDAP search filter
@param string filter
@return my.org.Person[] $(output[*])
-->
<ie:webject name="Query-Objects" type="OBJ">
<ie:param name="INSTANCE" data="com.myCompany.myHost.ldap"/>
<ie:param name="BASE" data="ou=People,o=Company"/>
<ie:param name="SCOPE" data="subtree"/>
<ie:param name="FILTER" data=" $(@FORM[]filter[])" default="uid=*"/>
<ie:param name="GROUP_OUT" data="output"/>
</ie:webject>
<ie:webject name="Change-Group" type="GRP">
<ie:param name="GROUP_IN" data="output"/>
<ie:param name="GROUP_OUT" data="output"/>
<ie:param name="RENAME" data="'object'='dn'"/>
</ie:webject>
以下の例は、LDAP ディレクトリにユーザーを作成します。@return コメントが指定されていないので、結果は Info*Engine XML フォーマットで返されます。
<%@page language="java"%>
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core" prefix="ie"%>
<!--com.infoengine.soap.rpc.def
creates a user in LDAP. returns I*E XML.
@param string dbuser
@param string passwd
@param my.org.Person toCreate
-->
<%
my.org.Person toCreate = (my.org.Person)getParam ( "toCreate" );
String dn = toCreate.getDn();
String uid = "uid=" + toCreate.getUid();
String cn = "cn=" + toCreate.getCn();
String sn = "sn=" + toCreate.getSn();
String [] mails = toCreate.getMail();
StringBuffer sb = new StringBuffer();
for ( int i = 0; mails != null && i < mails.length; i++ )
sb.append ( "mail=" )
.append ( mails[i] )
.append ( ( i < (mails.length-1) ) ? ";" : "" );
%>
<ie:webject name="Create-Object" type="ACT">
<ie:param name="INSTANCE" data="com.myCompany.myHost.ldap"/>
<ie:param name="DBUSER" data="$(@FORM[]dbuser[])"/>
<ie:param name="PASSWD" data="$(@FORM[]passwd[])"/>
<ie:param name="DN" data="<%=dn%>"/>
<ie:param name="FIELD" data="objectClass=inetOrgPerson"/>
<ie:param name="FIELD" data="objectClass=person"/>
<ie:param name="FIELD" data="<%=uid%>"/>
<ie:param name="FIELD" data="<%=cn%>"/>
<ie:param name="FIELD" data="<%=sn%>"/>
<ie:param name="FIELD" data="<%=sb.toString()%>" delim=";"/>
<ie:param name="GROUP_OUT" data="output"/>
</ie:webject>
SOAL リクエストの BLOB アタッチメント
添付資料を SOAP リクエストで使用して、少量のバイナリデータをアップロードおよびダウンロードできます。
SOAP リクエストにデータを添付するとき、"javax.activation.DataSource" および "java.io.InputStream" という 2 つの特殊なデータタイプが使用されます。これらの特殊なデータタイプでは、バイナリのコンテンツタイプをオプションでリストする、特殊フォーマットの SOAP コメントがサポートされています。コンテンツタイプを指定すると、予想されるコンテンツデータのタイプや返されるコンテンツデータのタイプを含む、より完全な WSDL を生成できます。たとえば、以下のような任意の有効なコンテンツタイプを指定できます。
• image/.gif
• image/.jpeg
• application/octet-stream
コンテンツタイプを指定しない場合は、デフォルト値である application/octet-stream が使用されます。
javax.activation.DataSource
クライアントがバイナリデータを添付することを示します。このデータタイプは @param SOAP コメントでのみ使用されます。
以下のフォーマットを使用します。
@param javax.activation.DataSource file {contentType:content_type}
ここで、content_type はバイナリデータのコンテンツタイプです。
java.io.InputStream
タスクがバイナリデータで応答することを示します。このデータタイプは @return SOAP コメントでのみ使用されます。
以下のフォーマットを使用します。
@return java.io.InputStream {contentType:content_type}
ここで、content_type はバイナリデータのコンテンツタイプです。レスポンスが添付資料である場合、代入構文は指定されません。
Info*Engine では、添付資料とデータの両方を返すことはサポートしていません。タスクが SOAP に BLOB を生成すると、SOAP レスポンスに空のレスポンス要素が含まれます。
BLOB のアップロードの例
以下のタスクでは、BLOB をデータベース行に追加します。
<%@page language="java" session="false"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<!--com.infoengine.soap.rpc.def
upload a blob
@param string filename - the filename to store
@param javax.activation.DataSource file - the file to store
(should be gif or jpeg)
-->
<ie:unit>
<ie:webject name="Do-Sql" type="ACT">
<ie:param name="INSTANCE" data="soapJDBCAdapter"/>
<ie:param name="SQL" data="DELETE FROM BLOBTABLE WHERE
name='$(@FORM[]filename[0])'"/>
<ie:param name="CLASS" data="BLOBTEST"/>
<ie:param name="GROUP_OUT" data="deleteResult"/>
<ie:param name="BLOB_COUNT" data="0"/>
</ie:webject>
<ie:failure/>
</ie:unit>
<ie:webject name="Do-Sql" type="ACT">
<ie:param name="INSTANCE" data="soapJDBCAdapter"/>
<ie:param name="SQL" data="INSERT INTO BLOBTABLE VALUES
('$(@FORM[]filename[0])', NULL)"/>
<ie:param name="CLASS" data="BLOBTEST"/>
<ie:param name="GROUP_OUT" data="insertResult"/>
<ie:param name="BLOB_COUNT" data="0"/>
</ie:webject>
<ie:webject name="Put-Blob-Stream" type="OBJ">
<ie:param name="INSTANCE" data="soapJDBCAdapter"/>
<ie:param name="CLASS" data="BLOBTABLE"/>
<ie:param name="ATTRIBUTE" data="FILECONTENT"/>
<ie:param name="WHERE" data="(NAME='$(@FORM[]filename[0])')"/>
<ie:param name="GROUP_OUT" data="$(@FORM[]group_out[])"
default="output"/>
</ie:webject>
BLOB のダウンロードの例
以下のタスクでは、BLOB をデータベース行から取得します。
<%@page language="java" session="false"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<!--com.infoengine.soap.rpc.def
download a blob
@param string filename - the file name of the blob/image to
download (value from ListBlobs call)
@return java.io.InputStream a stream that contains the blob
-->
<ie:webject name="Send-Blob-Stream" type="OBJ">
<ie:param name="INSTANCE" data="soapJDBCAdapter"/>
<ie:param name="CLASS" data="BLOBTABLE"/>
<ie:param name="ATTRIBUTE" data="FILECONTENT"/>
<ie:param name="MIMETYPE" data="'application/octet-stream'"/>
<ie:param name="WHERE" data="(NAME='$(@FORM[]filename[0])')"/>
<ie:param name="FILENAME" data="test.doc"/>
<ie:param name="GROUP_OUT" data="$(@FORM[]group_out[])"
default="output"/>
</ie:webject>
