8 Using the Imaging API as Pure Web Services
This chapter has the following sections:
8.1 About Using the Imaging API as Pure Web Services
Although the Native Java API is the most convenient way to leverage Imaging services, it is mostly a set of proxy and utility classes that wrap calls to the Imaging web services set. All of the functionality exposed by the native Java API is available using direct web service calls as well. Use of the API through direct web services requires an in depth understanding of WSDL documents and of environment specific techniques for invoking web services.
8.1.1 Locating Web Service WSDLs
Understanding how to invoke Imaging web services starts with knowing where to access the WSDL documentation. The following is a complete list of the Imaging service WSDL locations. The host name and port number will vary depending on your installation.
-
http://<ipmhost>:<port>/imaging/ws/ApplicationService?wsdl
-
http://<ipmhost>:<port>/imaging/ws/ConnectionService?wsdl
-
http://<ipmhost>:<port>/imaging/ws/DocumentContentService?wsdl
-
http://<ipmhost>:<port>/imaging/ws/DocumentService?wsdl
-
http://<ipmhost>:<port>/imaging/ws/ImportExportService?wsdl
-
http://<ipmhost>:<port>/imaging/ws/LoginService?wsdl
-
http://<ipmhost>:<port>/imaging/ws/PreferenceService?wsdl
-
http://<ipmhost>:<port>/imaging/ws/SearchService?wsdl
-
http://<ipmhost>:<port>/imaging/ws/SecurityService?wsdl
-
http://<ipmhost>:<port>/imaging/ws/TicketService?wsdl
8.2 Using Web Services in Stateless Sessions
The majority of Imaging web services are capable of operating in either stateless or stateful mode. In stateless mode, authentication credentials passed in each service request are used to transparently log the user in, perform the requested operation, and then log out before returning.
8.3 Using Web Services in a Stateful Session
In stateful operation, a call is first made to the LoginService.login operation to establish the user session with Imaging. Credentials to the login method are provided by the security policy currently in effect, or through HTTP Basic Auth if no policy is applied.
The jsessionid cookie returned by the log in operation is subsequently passed to call other services, thus maintaining session state from call to call. Note that web service security still requires that each call pass user credentials in order to comply with OWSM security policy enforcement. A call to LoginService.logout ends the user session.
As mentioned above, most Imaging services operate in either mode. The exception to this is the DocumentContentService. DocumentContentService operations are capable of leveraging a streaming Message Transmission Optimization Mechanism (MTOM) feature that is incompatible with OWSM security policies. Therefore, the stateful mode is required to wrap appropriate security around DocumentContentService operations.
8.4 Using the AXF Web Service
You can generate WSDL files for interfacing with the AXF Server services. The WSDL files provide the ability to pass data that can be understood by the AXF Server services, which enables access to the various commands within WebCenter Content.
8.4.1 Locating the AXF Web Service WSDL File
The AXF Web Service file can be found at the following location. The host name and port number will vary depending on your installation.
http://<host>:<port>/axf-ws2/AxfSolutionMediatorService?wsdl
Note:
The above URL is valid only for the IPM Server.
8.4.2 WSDL File Structure
WSDL files are formally structured with elements that contain a description of the data to be passed to the web service. This structure enables both the sending application and the receiving application to interpret the data being exchanged.
WSDL elements contain a description of the operation to perform on the data and a binding to a protocol or transport. This permits the receiving application to both process the data and interpret how to respond or return data. Additional sub elements may be contained within each WSDL element.
The WSDL file structure includes these major elements:
-
Data Types: Generally in the form of XML schema to be used in the messages.
-
Message: The definition of the data in the form of a message either as a complete document or as arguments to be mapped to a method invocation.
-
Port Type: A set of operations mapped to an address. This defines a collection of operations for a binding.
-
Binding: The actual protocol and data formats for the operations and messages defined for a particular port type.
-
Service and Port: The service maps the binding to the port and the port is the combination of a binding and the network address for the communication exchange.
8.4.3 Data Type
The Data Type <types> defines the complex types and associated elements. Web services supports both simple data types (such as string, integer, or boolean) and complex data types. A complex type is a structured XML document that contains several simple types or an array of subelements.
The following code fragment for the AxfRequest set defines the CommandNamesapce, solutionNamespace request Parameters, UserContext and username elements and specifies that they are strings.
<xs:complexType name="axfRequest"> <xs:sequence> <xs:element name="commandNamespace" type="xs:string" minOccurs="0" /> <xs:element name="conversationId" type="xs:string" minOccurs="0" /> <xs:element name="requestParameters"> <xs:complexType> <xs:sequence> <xs:element name="entry" minOccurs="0" maxOccurs="unbounded"> <xs:complexType> <xs:sequence> <xs:element name="key" minOccurs="0" type="xs:string" /> <xs:element name="value" minOccurs="0" type="xs:string" /> </xs:sequence> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="role" type="xs:string" minOccurs="0" /> <xs:element name="solutionNamespace" type="xs:string" minOccurs="0" /> <xs:element name="systemName" type="xs:string" minOccurs="0" /> <xs:element name="userContext"> <xs:complexType> <xs:sequence> <xs:element name="entry" minOccurs="0" maxOccurs="unbounded"> <xs:complexType> <xs:sequence> <xs:element name="key" minOccurs="0" type="xs:string" /> <xs:element name="value" minOccurs="0" type="xs:string" /> </xs:sequence> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="username" type="xs:string" minOccurs="0" /> </xs:sequence> </xs:complexType>
Similarly, the following code fragment for the AxfResponse set defines the ConversationId, Errorcode, ErrorMessage and response commands elements and specifies that they are strings.
<xs:complexType name="executeResponse"> <xs:sequence> <xs:element name="response" type="tns:axfResponse" minOccurs="0" /> </xs:sequence> </xs:complexType> <xs:complexType name="axfResponse"> <xs:sequence> <xs:element name="conversationId" type="xs:string" minOccurs="0" /> <xs:element name="errorCode" type="xs:string" minOccurs="0" /> <xs:element name="errorMessage" type="xs:string" minOccurs="0" /> <xs:element name="pid" type="xs:string" minOccurs="0" /> <xs:element name="responseCommands" type="tns:responseCommand" nillable="true" minOccurs="0" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> <xs:complexType name="responseCommand"> <xs:sequence> <xs:element name="command" type="xs:string" minOccurs="0" /> <xs:element name="value" type="xs:string" minOccurs="0" /> </xs:sequence> </xs:complexType>
8.4.4 Message
The Message <message> defines the data as arguments to be mapped to a method invocation.
<message name="execute"> <part name="parameters" element="tns:execute" /> </message> <message name="executeResponse"> <part name="parameters" element="tns:executeResponse" /> </message>
8.4.5 Port Type
The Port Type <portType> defines a collection of operations for a binding. The DocInfo.wsdl file provides the DocInfoSoap and the DocInfo operation name (method name) with I/O information for processing the message.
<portType name="AxfSolutionMediatorWS"> <operation name="execute"> <input message="tns:execute" /> <output message="tns:executeResponse" /> </operation> </portType>
8.4.6 Binding
The binding <binding> defines the actual protocol and data formats for the operations and messages for the particular port type.
<binding name="AxfSolutionMediatorPortBinding" type="tns:AxfSolutionMediatorWS"> <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document" /> <operation name="execute"> <soap:operation soapAction="execute" /> <input> <soap:body use="literal" /> </input> <output> <soap:body use="literal" /> </output> </operation> </binding>
8.4.7 Service and Port
The service <service> maps the binding to the port. The port is the combination of a binding and the network address for the communication exchange. The port is used to expose a set of port types (operations) on the defined transport.
<service name="AxfSolutionMediatorService"> <port name="AxfSolutionMediatorPort" binding="tns:AxfSolutionMediatorPortBinding"> <soap:address location="http://<MachineName>:<Port>/axf-ws2/AxfSolutionMediatorService" /> </port> </service>