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>
