View comments | RSS feed
Take a survey

Invoking LiveCycle ES > Invoking LiveCycle ES Using Web Services

Invoking LiveCycle ES Using Web Services
Most services located in the service container are configured to expose a web service, with full support for web service definition language (WSDL) generation. As a result, services can exchange and process the following SOAP messages:
SOAP request: Sent to LiveCycle ES by a client application requesting an action.
SOAP response: Sent to a client application by a service after a SOAP request is processed.
Using web services, you can perform the same operations that you can by using the Java API. A benefit of using web services to invoke LiveCycle ES is that you can create a client application in a development environment that supports SOAP and are not bound to a specific development environment or programming language. For example, you can create a client application using Microsoft Visual Studio .NET and C# as the programming language.
LiveCycle ES services are exposed over the SOAP protocol and are WSI Basic Profile 1.1 compliant. Web Services Interoperability (WSI) is an open standards organization that promotes web service interoperability across platforms. For information, see http://www.ws-i.org/.
LiveCycle ES supports the following web service standards:
Encoding: Supports only document and literal encoding (which is the preferred encoding according to the WSI Basic Profile).
SOAP with attachments: Supports both MIME and DIME (Direct Internet Message Encapsulation). These protocols are standard ways of sending attachments over SOAP. DIME is used primarily by .NET applications.
WS-Security: Supports a user name password token profile, which is a standard way of sending user names and passwords as part of the WS Security SOAP header. LiveCycle ES also supports HTTP basic authentication.
To invoke LiveCycle ES using web services, typically you create a proxy library that consumes the service WSDL. You can retrieve a service WDSL by specifying the following URL definition (items in square brackets are optional):
http://<your_serverhost>:<your_port>/soap/services/<service_name>?wsdl[&version=<version>][&async=true|false]
where:
your_serverhost represents the IP address of the J2EE application server hosting LiveCycle ES.
your_port represents the port that the J2EE application server uses.
service_name represents the service name.
version represents the target version of a service (the latest service version is used by default).
async specify the value true to enable additional operations for asynchronous invocation (false by default).
To retrieve a WSDL that belongs to a short-lived or long-lived process created in Workbench ES, replace [service name] with the name of the process. For example, to retrieve the WSDL that belongs to the CreatePDF short-lived process, specify the following WSDL definition:
	http://<your_serverhost>:<your_port>/soap/services/CreatePDF?wsdl
Note: For information about the example CreatePDF short-lived process, see Short lived process example.
The following table lists service WSDL definitions (assuming that LiveCycle ES is deployed on the local host and the post is 8080).
 
http://localhost:8080/soap/services/ BarcodedFormsService?wsdl
http://localhost:8080/soap/services/ ReaderExtensionsService?wsdl
http://localhost:8080/soap/services/ RightsManagementService?wsdl
Note: You can also view WSDL files that are located in the LiveCycle ES SDK directory at [install directory]\Adobe\LiveCycle8\Livecycle_ES_SDK\wsdl.
Services that cannot be accessed using web services
Although most services can be accessed using a WSDL, some services cannot be accessed in this manner. The following services cannot be invoked using web services:
Web service data types
One of the most important data types exposed in a web service is a BLOB type. This type is a mapping of the com.adobe.idp.Document class, which is used to send and retrieve data (for example, PDF files, Word documents, XML, and so on) to and from services. The BLOB type is defined in a service WSDL as follows:
<complexType name="BLOB">
 <sequence>
  <element maxOccurs="1" minOccurs="0" name="contentType" type="xsd:string" /> 
  <element maxOccurs="1" minOccurs="0" name="binaryData" type="xsd:base64Binary" /> 
  <element maxOccurs="1" minOccurs="0" name="attachmentID" type="xsd:string" /> 
  <element maxOccurs="1" minOccurs="0" name="remoteURL" type="xsd:string" /> 
 </sequence>
</complexType>
If a service requires a BLOB type as an input value, you must create an instance of the BLOB type in your application logic and assign values to fields that belong to the BLOB instance as follows:
1.
To pass data as text encoded in a Base64 format, set the data in the BLOB.binaryData field. You may also set the data's content MIME type in the BLOB.contentType field.
2.
To pass data in a MIME or DIME attachment, attach the data to the SOAP request using the SOAP framework's native API and set the attachment ID in the BLOB.attachmentID field.
3.
If data is hosted on a web server and accessible over an HTTP URL, set the HTTP URL in the BLOB.remoteURL field. Note that this URL should be accessible from the server.
If the service returns a BLOB type, by default, the result data is hosted on the application server and its URL is returned in the BLOB.remoteURL field. The only exception is when the service takes a BLOB instance as an input value and the data is supplied with a MIME or DIME attachment. In this situation, the result data is returned as a MIME or DIME attachment (the output attachment type will match the input attachment type), and the output BLOB.attachmentID field contains the result attachment identifier.
To override the default output BLOB behavior, extend the SOAP Invocation URL with a suffix as follows:
http://<your_serverhost>:<your_port>/soap/services/<service name>?blob=base64|dime|mime|http
1.
Set the blob suffix to base64 to return the data in the BLOB.binaryData field.
2.
Set the blob suffix to dime or mime to return the data as a corresponding attachment type with the attachment identifier returned in the BLOB.attachmentID field. Use the SOAP framework's proprietary API to read the data from the attachment.
3.
Set the blob suffix to http to keep the data on the application server and return the URL pointing to the data in the BLOB.remoteURL field.
Caution: It is strongly recommended that you do not exceed 30 MB when populating a BLOB object by invoking its setBinaryData method. Otherwise, you may encounter an OutofMemory exception.
The following table lists Java data types and shows the corresponding web service data type.
 
The DATE type, which is defined in a service WSDL as follows:
<element maxOccurs="1" minOccurs="0" name="calendar" type="xsd:dateTime" />
The java.util.Date value is set or returned in the DATE.date field.
The DATE type, which is defined in a service WSDL as follows:
<element maxOccurs="1" minOccurs="0" name="calendar" type="xsd:dateTime" />
The java.util.Calendar value is set or returned in the DATE.calendar field.
<element maxOccurs="1" minOccurs="0" name="document" type="xsd:string" />
<element maxOccurs="1" minOccurs="0" name="element" type="xsd:string" />
The org.wc3.dom.Document value is set or returned in the XML.document field.
<element maxOccurs="1" minOccurs="0" name="document" type="xsd:string" />
<element maxOccurs="1" minOccurs="0" name="element" type="xsd:string" />
The org.wc3.dom.Element value is set or returned in the XML.element field.
Accessing multiple services using web services
Due to namespace conflicts, data objects cannot be shared between multiple service WSDLs. Different services may share data types and, therefore the services share the definition of these types in the WSDLs. For example, you cannot add two .NET client assemblies that contain a BLOB data type to the same .NET client project. If you attempt to do so, you will generate a compile error.
The following list specifies data types that cannot be shared between multiple service WSDLs:
To avoid this problem, it is recommended that the services WSDL’s are compiled together with a special /sharetypes command line option. For example:
wsdl /sharetypes http://localhost:8080/soap/services/RightsManagementService?wsdl http://localhost:8080/soap/services/DirectoryManagerService?wsdl
This command produces a single CS file containing no duplicate data types. For information, see Creating a .NET client assembly.

Comments


Blue Nuit said on Mar 17, 2008 at 12:21 PM :
Are there any samples using DIME or MIME attachments?

This page says: "Set the blob suffix to dime or mime to return the data as a corresponding attachment type with the attachment identifier returned in the BLOB.attachmentID field. Use the SOAP framework's proprietary API to read the data from the attachment."

I can add the attachment using something like:
URL serviceURL = new URL("http://tranquility:8080/soap/services/FormAndData?blob=dime");

//Use the binding stub with the locator
FormAndDataSoapBindingStub formAndDataClient = new FormAndDataSoapBindingStub(serviceURL, locate);


String attachmentID = "xmlData";

Call clientCall = formAndDataClient._getCall();
formAndDataClient._setProperty(Call.ATTACHMENT_ENCAPSULATION_FORMAT, Call.ATTACHMENT_ENCAPSULATION_FORMAT_DIME);

//Assuming getUploaded data returns a byte[] and mimeType is set
DataHandler buildFile = new DataHandler(getUploadedData(request), mimeType);

formAndDataClient.addAttachment(buildFile);

BLOB xmlAttachment = new BLOB();
xmlAttachment.setAttachmentID(attachmentID);


But I cannot figure out how to set the attachment ID into the Data handler.
raheshc said on Jul 30, 2009 at 2:30 AM :
Hi

Anybody please give sample code for any of the functionalities implemented using PHP.


thanks

Rahesh

 

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/livecycle/es/sdkHelp/programmer/sdkHelp/invokingSOAP.27.1.html