Writing an Info*Engine-based Web Service
The methods for writing an Info*Engine-based web service have not changed since web services were first supported with Info*Engine release 7.0. The only area in which JAX-WS-based web services are now different is the support for SOAP with attachments. For more information, see Using SOAP Attachments.
In addition to writing an Info*Engine-based web service, you can write a Java-based web service. This is illustrated with released examples found in <Windchill>/prog_examples/jws, which is discussed in “Truststores and Keystores” in the Understanding the Security Requirements section.
An Info*Engine web service consists of a set of Info*Engine tasks, each representing a web service method that is associated with a type identifier. In the case of a web service, the type identifier is used simply as a way to logically group a set of Info*Engine tasks together to form a web service, and can be thought of as analogous to a Java class that exposes only static methods (each method being the Info*Engine task supporting the corresponding web service operation).
At runtime, Info*Engine requires that the type identifier and corresponding Info*Engine tasks be registered with the Info*Engine configuration in the LDAP. You can do this manually, but since the process can be involved and is potentially error prone, Info*Engine is released with Apache Ant tooling that packages and installs the Info*Engine tasks backing your web service. These utilities are integrated with the Apache Ant framework.
This section walks you through writing a simple Info*Engine task-based web service and client using the following steps:
1. Create a project (this is a simple directory structure) to hold your web service tasks and client source.
2. Write a few very basic tasks.
3. Secure and deploy your JAX-WS web service, which consists of deploying your Info*Engine tasks and corresponding servlet.
Before You Begin
Before you can complete the steps in this section, you must meet the following prerequisites:
• All commands are assumed to be run from a windchill shell.
• It is assumed that you have run the Apache Ant script documented earlier in “Truststores and Keystores” in the Understanding the Security Requirements section.
• The example commands assume a Unix environment. If you are in a Windows environment, then you must alter the operating system-specific commands to suit your environment (for example, using \ rather than / in paths).
Create a Project
Released with the web service framework are tools to simplify authoring new web services and clients.
This project example creates a simple web service that performs basic math operations.
 |
This service is for illustration purposes only and is not the type of thing you would typically use Info*Engine to accomplish.
|
Create your project using the <Windchill>/bin/adminTools/WebServices/new-project.xml Apache Ant build script. This script can be used to create a client project, a service project, or both:
% cd <Windchill>
% mkdir prog_examples/jws/MyProject
% ant -Dproject.dir=<Windchill>/prog_examples/jws/MyProject -Dservlet.name=MathService
-Dsecurity.policy=userNameAuthSymmetricKeys -Dservice.type.id=org.myorg.MathService
-Dmain.class=org.myorg.MathClient
-f bin/adminTools/WebServices/new-project.xml create
% mkdir prog_examples/jws/MyProject
% ant -Dproject.dir=<Windchill>/prog_examples/jws/MyProject -Dservlet.name=MathService
-Dsecurity.policy=userNameAuthSymmetricKeys -Dservice.type.id=org.myorg.MathService
-Dmain.class=org.myorg.MathClient
-f bin/adminTools/WebServices/new-project.xml create
|
|
The project.dir property is an absolute path so that the project is created in the appropriate location. To see what input options are supported by the new-project.xml build script, you should run it with no arguments. For example:
ant -f bin/adminTools/WebServices/new-project.xml
|
This creates the following structure within the prog_examples/jws/MyProject directory:
• src/
The base directory for your web service (server-side).
• src/build.xml
The build script used to build and deploy your web service.
• src/tasks/org/myorg/MathService
A subdirectory where you can create your Info*Engine tasks. This is only a suggestion; you can create another directory hierarchy that suits your needs if desired. The tools package your service using the type identifier you specified on the service.type.id property when creating the project.
• src_client/
The base directory for your web service client.
• src_client/build.xml
The build script used to build your web service client.
• src_client/org/myorg/MathClient.java
The beginnings of your web service client.
Review the contents of the two generated build.xml scripts to gain some understanding on how they work.
To further familiarize yourself with the framework from within the src and src_client directories, run the following ant commands:
% ant -p
% ant usage
% ant usage
The first command displays the public targets for the associated build script with their descriptions. The second command provides a detailed description of how you can tailor your build script if you find it necessary to do so. For most basic projects this should not be necessary.
Write the Info*Engine Tasks for Your Web Service
This step creates four simple tasks (Add.xml, Divide.xml, Multiply.xml, Subtract.xml) in the following locations with the given source. Note that these tasks are very simple and primarily contain documentation.
Add.xml
Source: <Windchill>/prog_examples/jws/MyProject/src/tasks/org/myorg/MathService/Add.xml
<%@page language="java"%>
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core" prefix="ie"%>
<%@taglib uri="/com/infoengine/tlds/iejstl.tld" prefix="c"%>
<!--com.infoengine.soap.rpc.def
Generates the sum of two integers.
<p>Supply two integers, a and b. You can subtract
integers using the {@link Subtract} method.
@param int a The first integer.
@param int b The second integer.
@return int ${output[0]result[0]} The sum of a and b.
@see Multiply
@see Divide
@see Subtract
-->
<ie:webject name="Create-Group" type="GRP">
<ie:param name="GROUP_OUT" data="output"/>
</ie:webject>
<!-- just so non-web service clients could call this task
coerce a to an int, in case it isn’t already -->
<c:set var="A" value="${0+@FORM[0]a[0]}" />
<c:set var="${output[0]result}" value="${A+@FORM[0]b[0]}" />
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core" prefix="ie"%>
<%@taglib uri="/com/infoengine/tlds/iejstl.tld" prefix="c"%>
<!--com.infoengine.soap.rpc.def
Generates the sum of two integers.
<p>Supply two integers, a and b. You can subtract
integers using the {@link Subtract} method.
@param int a The first integer.
@param int b The second integer.
@return int ${output[0]result[0]} The sum of a and b.
@see Multiply
@see Divide
@see Subtract
-->
<ie:webject name="Create-Group" type="GRP">
<ie:param name="GROUP_OUT" data="output"/>
</ie:webject>
<!-- just so non-web service clients could call this task
coerce a to an int, in case it isn’t already -->
<c:set var="A" value="${0+@FORM[0]a[0]}" />
<c:set var="${output[0]result}" value="${A+@FORM[0]b[0]}" />
Divide.xml
Source: <Windchill>/prog_examples/jws/MyProject/src/tasks/org/myorg/MathService/Divide.xml
<%@page language="java"%>
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core" prefix="ie"%>
<%@taglib uri="/com/infoengine/tlds/iejstl.tld" prefix="c"%>
<!--com.infoengine.soap.rpc.def
Generates the result of dividing two integers.
<p>Supply two integers, a and b. You can multiply
integers using the {@link Multiply} method.
@param int a The first integer.
@param int b The second integer.
@return float ${output[0]result[0]} The sum of a and b.
@see Multiply
@see Divide
@see Subtract
-->
<ie:webject name="Create-Group" type="GRP">
<ie:param name="GROUP_OUT" data="output"/>
</ie:webject>
<!-- just so non-web service clients could call this task
coerce a to an float, in case it isn’t already -->
<c:set var="A" value="${0.0+@FORM[0]a[0]}" />
<c:set var="${output[0]result}" value="${A/@FORM[0]b[0]}" />
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core" prefix="ie"%>
<%@taglib uri="/com/infoengine/tlds/iejstl.tld" prefix="c"%>
<!--com.infoengine.soap.rpc.def
Generates the result of dividing two integers.
<p>Supply two integers, a and b. You can multiply
integers using the {@link Multiply} method.
@param int a The first integer.
@param int b The second integer.
@return float ${output[0]result[0]} The sum of a and b.
@see Multiply
@see Divide
@see Subtract
-->
<ie:webject name="Create-Group" type="GRP">
<ie:param name="GROUP_OUT" data="output"/>
</ie:webject>
<!-- just so non-web service clients could call this task
coerce a to an float, in case it isn’t already -->
<c:set var="A" value="${0.0+@FORM[0]a[0]}" />
<c:set var="${output[0]result}" value="${A/@FORM[0]b[0]}" />
Multiply.xml
Source: <Windchill>/prog_examples/jws/MyProject/src/tasks/org/myorg/MathService/Multiply.xml
<%@page language="java"%>
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core" prefix="ie"%>
<%@taglib uri="/com/infoengine/tlds/iejstl.tld" prefix="c"%>
<!--com.infoengine.soap.rpc.def
Generates the product of two integers.
<p>Supply two integers, a and b. You can divide
integers using the {@link Divide} method.
@param int a The first integer.
@param int b The second integer.
@return int ${output[0]result[0]} The sum of a and b.
@see Multiply
@see Divide
@see Subtract
-->
<ie:webject name="Create-Group" type="GRP">
<ie:param name="GROUP_OUT" data="output"/>
</ie:webject>
<!-- just so non-web service clients could call this task
coerce a to an int, in case it isn't already -->
<c:set var="A" value="${0+@FORM[0]a[0]}" />
<c:set var="${output[0]result}" value="${A*@FORM[0]b[0]}" />
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core" prefix="ie"%>
<%@taglib uri="/com/infoengine/tlds/iejstl.tld" prefix="c"%>
<!--com.infoengine.soap.rpc.def
Generates the product of two integers.
<p>Supply two integers, a and b. You can divide
integers using the {@link Divide} method.
@param int a The first integer.
@param int b The second integer.
@return int ${output[0]result[0]} The sum of a and b.
@see Multiply
@see Divide
@see Subtract
-->
<ie:webject name="Create-Group" type="GRP">
<ie:param name="GROUP_OUT" data="output"/>
</ie:webject>
<!-- just so non-web service clients could call this task
coerce a to an int, in case it isn't already -->
<c:set var="A" value="${0+@FORM[0]a[0]}" />
<c:set var="${output[0]result}" value="${A*@FORM[0]b[0]}" />
Subtract.xml
Source: <Windchill>/prog_examples/jws/MyProject/src/tasks/org/myorg/MathService/Subtract.xml
<%@page language="java"%>
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core" prefix="ie"%>
<%@taglib uri="/com/infoengine/tlds/iejstl.tld" prefix="c"%>
<!--com.infoengine.soap.rpc.def
Generates the difference of two integers.
<p>Supply two integers, a and b. You can add
integers using the {@link Add} method.
@param int a The first integer.
@param int b The second integer.
@return int ${output[0]result[0]} The sum of a and b.
@see Multiply
@see Divide
@see Subtract
-->
<ie:webject name="Create-Group" type="GRP">
<ie:param name="GROUP_OUT" data="output"/>
</ie:webject>
<!-- just so non-web service clients could call this task
coerce a to an int, in case it isn't already -->
<c:set var="A" value="${0+@FORM[0]a[0]}" />
<c:set var="${output[0]result}" value="${A-@FORM[0]b[0]}" />
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core" prefix="ie"%>
<%@taglib uri="/com/infoengine/tlds/iejstl.tld" prefix="c"%>
<!--com.infoengine.soap.rpc.def
Generates the difference of two integers.
<p>Supply two integers, a and b. You can add
integers using the {@link Add} method.
@param int a The first integer.
@param int b The second integer.
@return int ${output[0]result[0]} The sum of a and b.
@see Multiply
@see Divide
@see Subtract
-->
<ie:webject name="Create-Group" type="GRP">
<ie:param name="GROUP_OUT" data="output"/>
</ie:webject>
<!-- just so non-web service clients could call this task
coerce a to an int, in case it isn't already -->
<c:set var="A" value="${0+@FORM[0]a[0]}" />
<c:set var="${output[0]result}" value="${A-@FORM[0]b[0]}" />
Deploy Your Web Service
When this project was created, a parameter named security.policy was supplied, for which the value of userNameAuthSymmetricKeys was explicitly passed. Therefore, for this example you must provide both a username and a password to your web service client.
To generate and deploy your web service, run the following commands:
% cd <Windchill>/prog_examples/MyProject/src
% ant
% ant
|
|
Windchill does not need to be active to run the Apache Ant script.
|
At this point start (or restart) Windchill to finish deployment.
When run with no arguments, the Apache Ant script packages, installs, and deploys your web service:
• The service is packaged, compiled, and installed in Windchill. In the case of an Info*Engine task-based service, your tasks are packaged into a PTCTAR file and installed. In this example, the resulting PTCTAR file is:
<Windchill>/prog_examples/jws/MyProject/dist_server/mathservice.ptctar
If your web service requires Java objects, then you can simply create the package hierarchy and source for those objects within the src directory. The script automatically compiles and package those classes for you. Classes associated with your web service are packaged in <Windchill>/codebase/WEB-INF/lib within a JAR file that reflects the servlet name of your service.
• The <Windchill>/bin/adminTools/WebServices/build.xml script is then run to generate and compile the server-side artifacts, as well as secure and deploy the web service. This build script can also be run on its own, depending on your needs. For more information, see Using the Web Service Deployment Build Script.
|
|
If you use the Apache Ant framework you should not need to run this build script manually. The Apache Ant framework can also be used to deploy an existing legacy web service that is already installed on your system. In this case the src directory contains only the build.xml script and no task source.
|
Now that your service is deployed and Windchill is running, you can review your web service WSDL by visiting a URL similar to the following:
http://<host>/Windchill/servlet/MathService?wsdl
If you are writing a Java client, as described in Writing a Java-based Web Service Client, then you do not need to know how to access the WSDL. However, you must access it if you plan to integrate your service with another web service client.
Undeploy Your Web Service
If you want to undeploy your web service from your installation, simply run the undeploy target for the src/build.xml script of your project. For example:
% cd <Windchill>/prog_examples/MyProject/src
% ant undeploy
% ant undeploy
The undeploy target completes the following actions:
• Removes the servlet configuration from web.xml
• Removes the web service configuration from sun-jaxws.xml
• Removes the security policy configuration file
• Removes the JAR file supporting your web service
• Uninstalls the Info*Engine tasks (if your service is based on Info*Engine tasks)
Info*Engine Web Service Parameters and Task Documentation
You should familiarize yourself with the process of properly documenting Info*Engine tasks. Visit the documentation for your new web service online at the following URL:
http://<host>/Windchill/infoengine/jsp/tools/doc/index.jsp
|
|
This utility provides documentation for several installed tasks registered under type identifiers. Most of these tasks are not written to be accessed as web services, and should not be used as such.
|
From the Repository Types pane in your web browser, select com.ptc.windchill. From the Classes pane, select your org.myorg.MathService service type identifier. The documentation that appears is based on the contents of the tasks you deployed. For more information on writing task documentation, see:
http://<host>/Windchill/infoengine/jsp/tools/doc/howto.html
For more information on writing SOAP tasks, see SOAP Services.