SOAP Comments

Advanced Customization > Info*Engine User’s Guide > SOAP Services > Info*Engine Task Invocation with SOAP > SOAP Comments

SOAP Comments

An Info*Engine SOAP task must contain a comment section that describes the input parameters and response type. This SOAP comment section is used by Info*Engine to generate a WSDL that describes the interface each Info*Engine task exposes to external SOAP clients. The generated WSDL can then be used by third-party software to verify input parameters and cast response types, or to generate client-side source code used to interact with the Info*Engine SOAP service. Certain tools supplied with Info*Engine make use of the WSDL to generate client side data access objects (DAOs) that can be used to invoke Info*Engine tasks and abstract all of the details involved in using SOAP as the communication protocol. For more information, see Generating DAOs.

The SOAP comment section can also be used to generate Javadoc-like documentation for tasks. For instructions on generating this documentation, and a link to the generating tool, see the document available in Windchill at the following URL:

http://<host>/<servlet>/infoengine/jsp/tools/doc/howto.html

where <servlet> is the application URL defined for the SOAP servlet.

This comment section should be included in all SOAP tasks, even if the task includes no input parameters and returns the default Info*Engine group as a response.

The comment section is as follows:

where description is an optional task description, and special_comments are the special SOAP comment lines.

Special SOAP comment lines can be included in the comment sections to specify input parameters and output values. These special comment lines are discussed in the next two sections.

@param

The @param comment line is used to specify input parameters. The comment line is specified in the following format:

@param type[] name comment

where:

• type is the data type of the parameter.

• [] indicates an array of values. There are no spaces between the parameter type and []. Arrays are available in the @FORM context group as multi-valued attributes. This allows for simple manipulation of multi-valued input with standard Info*Engine substitution syntax.

• name is the name of the parameter.

• comment is additional text describing the parameter. This comment is optional.

Some of the Info*Engine-specific data types are processed differently from the other data types in that they do not need scriptlet code to extract the input.

When a collection is given as a parameter, the collection itself is not given as input to the task. Instead, all groups within the input collection are placed in the VDB so that they can be used by the task. The task author is expected to know the names of the groups. For example:

@param INFOENGINE_COLLECTION input_collection A collection of Groups.

When a group is given as a parameter, that group is placed directly in the task’s VDB so that it can be used directly. Additionally, the group is renamed using the parameter name if the group supplied by the caller is named differently. The contents of the group parameter below are available in a task using form substitution such as $(input_group[]attribute[]):

@param INFOENGINE_GROUP input_group A group.

When an element or array of elements is supplied as input, they are placed in a group named using the parameter name and added to the VDB. The input element specified with the parameter below would be available in a task using form substitution such as $(input_element[0]attribute[]). In the following example the group named input_element would contain a single element:

@param INFOENGINE_ELEMENT input_element An element.

@return

The @return comment line is used to specify output or response type. If no @return comment line is present, then the Info*Engine SOAP service responds with a serialized Info*Engine XML representation of the output group. The output group must be named using the $(@FORM[]group_out[]) parameter value. The comment line is specified in the following format:

@return type[] substitution comment

where:

• type is the data type of the response.

• [] indicates an array of values. There is no white space between the response type and [].

• substitution is a form similar to the standard Info*Engine substitution syntax:

$(groupName[elementIndex]attributeName[attributeIndex])

where:

◦ groupName is the name of the output group.

◦ elementIndex is the position of the element. If not specified, the elementIndex value defaults to 0, the first element.

◦ attributeName is the name of the attribute.

◦ attributeIndex is the position of the attribute on the element. If not specified, the attributeIndex value defaults to 0, the first attribute.

To populate a return array, the asterisk character “*” must be present in either the elementIndex or attributeIndex portion of the substitution syntax, but not both, as two dimensional arrays are not supported. If “*” is specified as the attributeIndex, then the array is generated from a multi-valued attribute from within a single element of the output group. If “*” is specified as the elementIndex, then the array is generated using the first value of each attributeName from each element of the output group.

When returning a Java bean, the @return comment line is specified as above, with the following two exceptions:

• The attributeName[attributeIndex] portion of the substitution syntax is not present.

• To return an array of Java beans, the “*” character must be in the elementIndex location of the substitution syntax.

The Java bean (or array of Java beans) are populated based on attributes found in referenced elements of the output group. Attribute names in the response group correspond directly to the properties of the Java bean. Attribute names in the response group might need to be manipulated (for example, using the Change-Group webject) to force the group attribute names to match the corresponding properties of the Java bean.

When returning Info*Engine data using the Info*Engine-specific data types, the format for the @return parameter is as follows:

@return INFOENGINE_COLLECTION
@return INFOENGINE_GROUP $(group_Name)
@return INFOENGINE_ELEMENT $(groupName[elementIndex])
@return INFOENGINE_ATTRIBUTE $(groupName[]attributeName)

where:

• groupName is the name of the output group.

• elementIndex is the position of the element. If not specified, the elementIndex value defaults to 0, the first element.

• attributeName is the name of the attribute.

Simple Data Type Examples

The following examples do not represent the types of activities that Info*Engine tasks should be written to perform. Rather, they are intended to offer an example of how input and output parameters function.

Because these tasks contain scriptlet code that assumes strongly-typed input parameters, they therefore cannot be called directly from a web browser using the Info*Engine servlet because the @FORM data would not be properly typed. These special SOAP tasks can be successfully called only by SOAP clients that generate strongly-typed SOAP requests. If the request is not strongly typed, a ClassCastException occurs.

The following example specifies two integers as input parameters, and returns their sum:

<%@page language="java"%>

<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>


<%

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>

The following example returns the sum of an array of floats:

<%@page language="java"%>
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>


<%

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>

The following example queries an employee database and returns an array of all employee numbers:

<%@page language="java"%>
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>



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

These Java bean examples are using a JNDI adapter to create user objects in an LDAP directory. These user objects should not be confused with user objects that a Windchill can use.

The examples in this section use the following Java bean:

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

The following example looks up a user entry by user id (uid):

<%@page language="java"%>
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core" prefix="ie"%>



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

The following example searches for a list of users using an LDAP search filter:

<%@page language="java"%>
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core" prefix="ie"%>



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

The following example creates a user in an LDAP directory. The results are returned in Info*Engine XML format, as there is no @return comment specified:

<%@page language="java"%>
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core" prefix="ie"%>


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