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.

Note: This process is not based on an existing LiveCycle process. To follow along with the code example, create a process named MyApplication/EncryptDocument using Workbench. (See Using Workbench.)

When this process is invoked, it performs the following actions:

  1. 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.

  2. 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 named outDoc.

Note: MTOM support was added in LiveCycle, version 9.
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:

http://localhost:8080/soap/services/MyApplication/EncryptDocument?WSDL&lc_version=9.0.1

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:

http://localhost:8080/soap/services/RightsManagementService?WSDL&lc_version=9.0.1

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:

  1. Create a .NET project using Microsoft Visual Studio 2008.

  2. In the Project menu, select Add Service Reference.

  3. In the Address dialog box, specify the WSDL to the LiveCycle service. For example,

    http://localhost:8080/soap/services/MyApplication/EncryptDocument?WSDL&lc_version=9.0.1
  4. 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 steps:

  1. Create a Microsoft .NET project.

  2. Create a MyApplication_EncryptDocumentClient object by using its default constructor.

  3. 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:

    http://hiro-xp:8080/soap/services/MyApplication/EncryptDocument?blob=mtom 

    You 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.
  4. Create a System.ServiceModel.BasicHttpBinding object by getting the value of the EncryptDocumentClient.Endpoint.Binding data member. Cast the return value to BasicHttpBinding.

  5. Set the System.ServiceModel.BasicHttpBinding object’s MessageEncoding data member to WSMessageEncoding.Mtom. This value ensures that MTOM is used.

  6. Enable basic HTTP authentication by performing the following tasks:

    • 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.

    The 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;
  7. 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.

  8. 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 the file.

  9. 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.

  10. 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 to read.

  11. Populate the BLOB object by assigning its MTOM data member with the contents of the byte array.

  12. 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.

  13. 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.

  14. 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 member.

  15. Create a System.IO.BinaryWriter object by invoking its constructor and passing the System.IO.FileStream object.

  16. 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.

Note: 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.

// Ethnio survey code removed