Invoking LiveCycle using MTOM
You can invoke LiveCycle services by using the
web service standard MTOM. This standard defines how binary data,
such as a PDF document, is transmitted over the Internet or intranet.
A feature of MTOM is the use of the XOP:Include element.
This element is defined in the XML Binary Optimized Packaging (XOP)
specification to reference the binary attachments of a SOAP message.
The discussion here is about using MTOM to invoke the following
LiveCycle short-lived process named MyApplication/EncryptDocument.
This process is not based on an existing LiveCycle process. To follow along with the code example, create
a process named MyApplication/EncryptDocument
Workbench. (See Using Workbench
When this process is invoked, it performs the following actions:
Obtains the unsecured PDF document that is passed to
the process. This action is based on the SetValue operation.
The input parameter for this process is a document process
variable named inDoc.
Encrypts the PDF document with a password. This action is
based on the PasswordEncryptPDF operation. The
password encrypted PDF document is returned in a process variable
Note: MTOM support was added in LiveCycle,
Important: JAX WS-based applications that use the
MTOM transmission protocol are limited to 25MB of sent and received
data. This limitation is due to a bug in JAX-WS. If the combined
size of your sent and received files exceeds 25MB, use the the SwaRef
transmission protocol instead of the MTOM one. Otherwise, there
is a possibility of an OutOfMemory exception.
The discussion here is about using MTOM withthin a Microsoft
.NET project to invoke LiveCycle services. The .NET framework
used is 3.5, and the development environment is Visual Studio 2008.
If you have Web Service Enhancements (WSE) installed on your development
computer, remove it. The .NET 3.5 framework supports a SOAP framework
named Windows Communication Foundation (WCF). When invoking LiveCycle by using MTOM, only WCF (not WSE) is supported.
Creating a .NET project that invokes a service using MTOM
You can create a Microsoft .NET project that can invoke
a LiveCycle service using web services. First, create a
Microsoft .NET project by using Visual Studio 2008. To invoke a
LiveCycle service, create a Service Reference to the LiveCycle service that you want to invoke within your project. When
you create a Service Reference, specify a URL to the LiveCycle service:
Replace localhost with the IP address of the
J2EE application server hosting LiveCycle. Replace MyApplication/EncryptDocument with
the name of the LiveCycle service to invoke. For example,
to invoke a Rights Management operation, specify:
The lc_version option ensures that LiveCycle functionality, such as MTOM, is available. Without specifying
the lc_version option, you cannot invoke LiveCycle using MTOM.
After you create a Service Reference, data types associated with
the LiveCycle service are available for use within your
.NET project. To create a .NET project that invokes a LiveCycle
service, perform the following steps:
Create a .NET project using Microsoft Visual Studio 2008.
In the Project menu, select Add Service Reference.
In the Address dialog box, specify the WSDL to the
LiveCycle service. For example,
Click Go and then click OK.
Invoking a service using MTOM in a .NET project
Consider the MyApplication/EncryptDocument process
that accepts an unsecured PDF document and returns a password-encrypted
PDF document. To invoke the MyApplication/EncryptDocument process
(which was built in Workbench) by using MTOM, perform the following
Create a Microsoft .NET project.
Create a MyApplication_EncryptDocumentClient object
by using its default constructor.
Create a MyApplication_EncryptDocumentClient.Endpoint.Address object
by using the System.ServiceModel.EndpointAddress constructor.
Pass a string value that specifies the WSDL to the LiveCycle service and the encoding type:
do not need to use the lc_version attribute. This
attribute is used when you create a service reference. However,
ensure that you specify?blob=mtom.
Note: Replace hiro-xp with the IP address of the J2EE application servier hosting LiveCycle.
Create a System.ServiceModel.BasicHttpBinding object
by getting the value of the EncryptDocumentClient.Endpoint.Binding data
member. Cast the return value to BasicHttpBinding.
Set the System.ServiceModel.BasicHttpBinding object’s MessageEncoding data
member to WSMessageEncoding.Mtom. This value ensures
that MTOM is used.
Enable basic HTTP authentication by performing the following
Assign the LiveCycle user name to the
data member MyApplication_EncryptDocumentClient.ClientCredentials.UserName.UserName.
Assign the corresponding password value to the data member MyApplication_EncryptDocumentClient.ClientCredentials.UserName.Password.
Assign the constant value HttpClientCredentialType.Basic to the
data member BasicHttpBindingSecurity.Transport.ClientCredentialType.
Assign the constant value BasicHttpSecurityMode.TransportCredentialOnly to
the data member BasicHttpBindingSecurity.Security.Mode.
following code example shows these tasks.
//Enable BASIC HTTP authentication
encryptProcess.ClientCredentials.UserName.UserName = "administrator";
encryptProcess.ClientCredentials.UserName.Password = "password";
b.Security.Transport.ClientCredentialType = HttpClientCredentialType.Basic;
b.Security.Mode = BasicHttpSecurityMode.TransportCredentialOnly;
b.MaxReceivedMessageSize = 4000000;
b.MaxBufferSize = 4000000;
b.ReaderQuotas.MaxArrayLength = 4000000;
Create a BLOB object by using its constructor.
The BLOB object is used to store a PDF document
to pass to the MyApplication/EncryptDocument process.
Create a System.IO.FileStream object by
invoking its constructor. Pass a string value that represents the
file location of the PDF document and the mode in which to open
Create a byte array that stores the content of the System.IO.FileStream object.
You can determine the size of the byte array by getting the System.IO.FileStream object’s Length property.
Populate the byte array with stream data by invoking the System.IO.FileStream object’s Read method.
Pass the byte array, the starting position, and the stream length
Populate the BLOB object by assigning its MTOM data
member with the contents of the byte array.
Invoke the MyApplication/EncryptDocument process
by invoking the MyApplication_EncryptDocumentClient object’s invoke method. Pass
the BLOB object that contains the PDF document.
This process returns an encrypted PDF document within a BLOB object.
Create a System.IO.FileStream object by
invoking its constructor and passing a string value that represents
the file location of the secured PDF document.
Create a byte array that stores the data content of the BLOB object
that was returned by the invoke method. Populate
the byte array by getting the value of the BLOB object’s MTOM data
Create a System.IO.BinaryWriter object by
invoking its constructor and passing the System.IO.FileStream object.
Write the contents of the byte array to a PDF file by invoking
the System.IO.BinaryWriter object’s Write method
and passing the byte array.
Most LiveCycle service operations have
a MTOM quick start. You can view these quick starts in a service’s
corresponding quick start section. For example, to see the Output
quick start section, see Output Service API Quick Starts