高级自定义 > Info*Engine User's Guide (《Info*Engine 用户指南》) > SOAP Services
  
SOAP Services
SOAP (Simple Object Access Protocol) is a lightweight, XML-based protocol for exchanging information and making remote procedure calls in a distributed, decentralized environment.
For general information about SOAP, use the following link:
http://www.w3.org/TR/SOAP
The following topics discuss legacy SOAP services, provide information for writing tasks with SOAP, and explain how SOAP requests work within an Info*Engine Java Platform, Enterprise Edition (Java EE) connector. A step-by-step example on how to a write a Java SOAP client is also included.
Legacy Services
When running Windchill, it is recommended that you use the SimpleTaskDispatcher servlet rather than the RPC servlet. The two servlets behave identically externally, but in the case of a Windchill installation, the SimpleTaskDispatcher delegates directly to the SimpleTaskDispatcher service running in your MethodServer. As a result, this servlet performs better than the standalone Info*Engine RPC servlet.
In the following topics, wherever there is a reference to the RPC servlet address, you can simply replace “RPC” with “SimpleTaskDispatcher” in that URL.
For example:
http://<host>/Windchill/servlet/RPC
can be replaced with
http://<host>/Windchill/servlet/SimpleTaskDispatcher
* 
If your site is using form-based authentication, programmatic clients attempting to access the RPC or SimpleTaskDispatcher servlet must use the /protocolAuth URL prefix. For example:
http://<host>/Windchill/protocolAuth/servlet/SimpleTaskDispatcher
or
http://<host>/Windchill/protocolAuth/servlet/RPC
For more information about form-based authentication, see Authentication.
SOAP RPC Servlet
Info*Engine provides a SOAP Remote Procedure Call (RPC) servlet that receives SOAP requests from a SOAP client and sends responses back to the client. The servlet gathers the information sent from the client (consisting of the methods to execute and other request information) and processes the methods by executing tasks that people at your site have created explicitly for use with the SOAP client. These tasks are used to execute task webjects, and the servlet allows SOAP clients to invoke these specially-written Info*Engine business tasks. For more information about the required SOAP task format, see Writing Tasks for Use with SOAP.
The Info*Engine SOAP RPC servlet can be used to pass data to and from a SOAP client that has been developed using the Info*Engine Java EE connector or some other third-party SOAP client. For more information, see Info*Engine J2EE Connector.
The SOAP RPC servlet automatically generates Web Services Definition Language (WSDL) for a given SOAP service when it receives an HTTP GET request (for example, when using a standard web browser to access the servlet directly). When issuing a GET request to the RPC servlet, you must supply the CLASS query argument, and can optionally supply the VERSION and STYLE query arguments. The CLASS query argument specifies the CLASS of the given SOAP service for which you would like WSDL generated. The VERSION and STYLE parameters are used to decide what type of WSDL you would like to have generated. For more information about the STYLE and VERSION parameters, see the webject description in Generate-WSDL section in Management Webjects.
For example, if you generate the default WSDL for an Info*Engine SOAP service that you authored under the following type identifier:
com.myCompany.myService
You might request the WSDL as follows:
http://<host>/Windchill/servlet/RPC?CLASS=com.myCompany.myService
If you are attempting to integrate your SOAP service with a third-party Service Oriented Architecture (SOA) platform for the task of attempting to call your SOAP methods from within a Business Process Execution Language (BPEL) orchestration, you would want Info*Engine to behave in a WS-I compliant manner to ease integration. In such a situation you would likely request your WSDL as follows:
http://<host>/Windchill/servlet/RPC?CLASS=com.myCompany.myService
&VERSION=1.1&STYLE=document
The Info*Engine Java Platform, Enterprise Edition (Java EE) connector uses WSDL to generate client-side source code to simplify interactions with Info*Engine.
The Microsoft SOAP Toolkit uses WSDL to define, validate, and constrain the remote classes and methods that clients can call, the parameters that are supported by each method, and the kinds of results that are returned. For more information, and to download the Microsoft SOAP Toolkit, use the following URL:
http://www.microsoft.com/downloads
Other third-party clients can also use WSDL to generate source code or to drive interactions with Info*Engine.
The following diagram illustrates how a SOAP client interacts with Info*Engine:
When a SOAP request is made, the web server processes the HTTP request and directs it to the SOAP RPC servlet. The SOAP RPC servlet accesses the LDAP repository in your Windchill Directory Server to identify which task should be executed. In the LDAP directory, you have created task delegates that identify tasks that are to be executed for the methods the SOAP client can execute. The SOAP RPC servlet passes the name of the task and the other request information on to an Info*Engine server, which executes the task.
After the Info*Engine server executes the task, an appropriate response is sent to the SOAP client. The response sent to the SOAP client is based on the data returned by the Info*Engine task. A task authored for invocation by a SOAP client can return the following:
A primitive value, for example int, float, date, and so on.
A Java bean.
An array of primitive values.
An array of Java beans.
An Info*Engine collection, group, element, attribute, or group XML as a string.
If an Info*Engine group is returned and the SOAP task does not explicitly state its return type, the group is returned to the SOAP client as a single string that contains the Info*Engine XML representation of that group, named using the input $(@FORM[]group_out[0]).
If an error is detected, a SOAP fault is returned to the client. This fault can then be processed by the SOAP client using its own implementation-specific mechanisms. For example, Info*Engine Java EE connector clients receive SOAP faults as Java exceptions; Visual Basic clients can make use of instance variables such as faultcode, faultstring, faultactor, and detail.
SOAP Requests
SOAP requests are defined by the SOAP client, which sends the request to the web server, which then passes the request on to the SOAP RPC servlet. The SOAP RPC servlet can be found in the following location:
http://<host>/Windchill/servlet/RPC
where Windchill is the web application defined for the SOAP RPC servlet.
When sending a SOAP request, an Info*Engine SOAP client must specify a method to be executed and the class that supports the method. This information can be conveyed to the SOAP service in multiple ways:
In the SOAPAction HTTP header in a URI (Uniform Resource Identifier) of the form:
uri:ie-soap-rpc:class!method
where method is the method to be executed and class is the class that supports the method.
On the CLASS and METHOD query arguments.
If CLASS is specified as a query argument and METHOD is not, then the SOAP service attempts to resolve the method name by looking to the SOAPAction HTTP header and then the SOAP message body. If METHOD is specified as a query argument and CLASS is not, then the SOAP service attempts to resolve the class name by looking to the SOAPAction HTTP header.
* 
GET requests to the SOAP service must contain a CLASS parameter, and return the WSDL document for the specified class. POST requests to the SOAP service are handled as SOAP requests.
The association between the method name sent by the SOAP client and the Info*Engine task that gets executed is maintained in an LDAP repository as a task delegate entry. The class sent by the SOAP client corresponds to a type identifier entry maintained in an LDAP repository. Type identifiers represent object types (or classes) and contain task delegates (or methods). The Info*Engine server that processes the task invocation is represented by a repository, which declares its repository type.
Repository types represent types of information systems and maintain what object types they can act upon. Repository types contain type identifiers. The repository is stored in the Windchill Directory Server that is used by Info*Engine. For more information on repositories, repository types, type identifiers and task delegates, see About the Delegate Administration Utility.