Invoking LiveCycle using DIME

You can invoke LiveCycle services using SOAP with attachments. LiveCycle supports both MIME and DIME web service standards. DIME lets you send binary attachments, such as PDF documents, along with invocation requests instead of encoding the attachment. The Invoking LiveCycle using DIME section discusses invoking the following LiveCycle short-lived process named MyApplication/EncryptDocument using DIME.

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.

This process is not based on an existing LiveCycle process. To follow along with the code examples, create a process named MyApplication/EncryptDocumentusing Workbench. (See Using Workbench.)

Remarque : Invoking LiveCycle service operations using DIME is deprecated. It is recommended that you use MTOM. (See Invoking LiveCycle using MTOM.)

Creating a .NET project that uses DIME

Creating Apache Axis Java proxy classes that use DIME

Creating a .NET project that uses DIME

To create a .NET project that can invoke a LiveCycle service using DIME, perform the following tasks:

  • Install Web Services Enhancements 2.0 on your development computer.

  • From within your .NET project, create a web reference to the LiveCycle service.

Installing Web Services Enhancements 2.0

Install Web Services Enhancements 2.0 on your development computer and integrate it with Microsoft Visual Studio .NET. You can download Web Services Enhancements 2.0 from the Microsoft Download Center.

From this web page, search for Web Services Enhancements 2.0 and download it onto your development computer. This download places a file named Microsoft WSE 2.0 SPI.msi on your computer. Run the installation program and follow the online directions.

Remarque : Web Services Enhancements 2.0 supports DIME. The supported version of Microsoft Visual Studio is 2003 when working with Web Services Enhancements 2.0. Web Services Enhancements 3.0 does not support DIME; however, it supports MTOM.

Creating a web reference to a LiveCycle service

After you install Web Services Enhancements 2.0 on your development computer and create a Microsoft .NET project, create a web reference to the LiveCycle service. For example, to create a web reference to the MyApplication/EncryptDocument process and assuming that LiveCycle is installed on the local computer, specify the following URL:

    http://localhost:8080/soap/services/MyApplication/EncryptDocument?WSDL

After you create a web reference, the following two proxy data types are available for you to use within your .NET project: EncryptDocumentService and EncryptDocumentServiceWse. To invoke the MyApplication/EncryptDocument process using DIME, use the EncryptDocumentServiceWse type.

Remarque : Before creating a web reference to the LiveCycle service, ensure that you reference Web Services Enhancements 2.0 in your project. (See “Installing Web Services Enhancements 2.0”.)

Reference the WSE library

  1. In the Project menu, select Add Reference.

  2. In the Add Reference dialog box, select Microsoft.Web.Services2.dll.

  3. Select System.Web.Services.dll.

  4. Click Select and then click OK.

Create a web reference to a LiveCycle service

  1. In the Project menu, select Add Web Reference.

  2. In the URL dialog box, specify the URL to the LiveCycle service.

  3. Click Go and then click Add Reference.

Remarque : Ensure that you enable your .NET project to use the WSE library. From within the Project Explorer, right-click the project name and select Enable WSE 2.0. Ensure that the check box on the dialog box that appears is selected.

Invoking a service using DIME in a .NET project

You can invoke a LiveCycle service using DIME. Consider the MyApplication/EncryptDocument process that accepts an unsecured PDF document and returns a password-encrypted PDF document. To invoke the MyApplication/EncryptDocument process using DIME, perform the following steps:

  1. Create a Microsoft .NET project that enables you to invoke a LiveCycle service using DIME. Ensure that you include Web Services Enhancements 2.0 and create a web reference to the LiveCycle service.

  2. After setting a web reference to the MyApplication/EncryptDocument process, create an EncryptDocumentServiceWse object by using its default constructor.

  3. Set the EncryptDocumentServiceWse object’s Credentials data member with a System.Net.NetworkCredential value that specifies the LiveCycle user name and password value.

  4. Create a Microsoft.Web.Services2.Dime.DimeAttachment object by using its constructor and passing the following values:

    • A string value that specifies a GUID value. You can obtain a GUID value by invoking the System.Guid.NewGuid.ToString method.

    • A string value that specifies the content type. Because this process requires a PDF document, specify application/pdf.

    • A TypeFormat enumeration value. Specify TypeFormat.MediaType.

    • A string value that specifies the location of the PDF document to pass to the LiveCycle process.

  5. Create a BLOB object by using its constructor.

  6. Add the DIME attachment to the BLOB object by assigning the Microsoft.Web.Services2.Dime.DimeAttachment object’s Id data member value to the BLOB object’s attachmentID data member.

  7. Invoke the EncryptDocumentServiceWse.RequestSoapContext.Attachments.Add method and pass the Microsoft.Web.Services2.Dime.DimeAttachment object.

  8. Invoke the MyApplication/EncryptDocument process by invoking the EncryptDocumentServiceWse object’s invoke method and passing the BLOB object that contains the DIME attachment. This process returns an encrypted PDF document within a BLOB object.

  9. Obtain the attachment identifier value by getting the value of the returned BLOB object’s attachmentID data member.

  10. Iterate through the attachments located in EncryptDocumentServiceWse.ResponseSoapContext.Attachments and use the attachment identifier value to obtain the encrypted PDF document.

  11. Obtain a System.IO.Stream object by getting the value of the Attachment object’s Stream data member.

  12. Create a byte array and pass that byte array to the System.IO.Stream object’s Read method. This method populates the byte array with a data stream that represents the encrypted PDF document.

  13. Create a System.IO.FileStream object by invoking its constructor and passing a string value that represents a PDF file location. This object represents the encrypted PDF document.

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

  15. Write the contents of the byte array to the PDF file by invoking the System.IO.BinaryWriter object’s Write method and passing the byte array.

Quick Start: Invoking a service using DIME in a .NET project

Creating Apache Axis Java proxy classes that use DIME

You can use the Apache Axis WSDL2Java tool to convert a service WSDL into Java proxy classes so that you can invoke service operations. Using Apache Ant, you can generate Axis library files from a LiveCycle service WSDL that lets you invoke the service. (See Creating Java proxy classes using Apache Axis.)

The Apache Axis WSDL2Java tool generates JAVA files that contain methods that are used to send SOAP requests to a service. SOAP requests received by a service are decoded by the Axis-generated libraries and turned back into the methods and arguments.

To invoke the MyApplication/EncryptDocument service (which was built in Workbench) using Axis-generated library files and DIME, perform the following steps:

  1. Create Java proxy classes that consume the MyApplication/EncryptDocument service WSDL using Apache Axis. (See Creating Java proxy classes using Apache Axis.)

  2. Include the Java proxy classes into your class path.

  3. Create a MyApplicationEncryptDocumentServiceLocator object by using its constructor.

  4. Create a URL object by using its constructor and passing a string value that specifies the LiveCycle service WSDL definition. Ensure that you specify ?blob=dime at the end of the SOAP endpoint URL. For example, use

    http://hiro-xp:8080/soap/services/MyApplication/EncryptDocument?blob=dime.
  5. Create an EncryptDocumentSoapBindingStub object by invoking its constructor and passing the MyApplicationEncryptDocumentServiceLocator object and the URL object.

  6. Set the LiveCycle user name and password value by invoking the EncryptDocumentSoapBindingStub object’s setUsername and setPassword methods.

    encryptionClientStub.setUsername("administrator"); 
    encryptionClientStub.setPassword("password");    
  7. Retrieve the PDF document to send to the MyApplication/EncryptDocument service by creating a java.io.File object. Pass a string value that specifies the PDF document location.

  8. Create a javax.activation.DataHandler object by using its constructor and passing a javax.activation.FileDataSource object. The javax.activation.FileDataSource object can be created by using its constructor and passing the java.io.File object that represents the PDF document.

  9. Create an org.apache.axis.attachments.AttachmentPart object by using its constructor and passing the javax.activation.DataHandler object.

  10. Attach the attachment by invoking the EncryptDocumentSoapBindingStub object’s addAttachment method and passing the org.apache.axis.attachments.AttachmentPart object.

  11. Create a BLOB object by using its constructor. Populate the BLOB object with the attachment identifier value by invoking the BLOB object’s setAttachmentID method and passing the attachment identifier value. This value can be obtained by invoking the org.apache.axis.attachments.AttachmentPart object’s getContentId method.

  12. Invoke the MyApplication/EncryptDocument process by invoking the EncryptDocumentSoapBindingStub object’s invoke method. Pass the BLOB object that contains the DIME attachment. This process returns an encrypted PDF document within a BLOB object.

  13. Obtain the attachment identifier value by invoking the returned BLOB object’s getAttachmentID method. This method returns a string value that represents the identifier value of the returned attachment.

  14. Retrieve the attachments by invoking the EncryptDocumentSoapBindingStub object’s getAttachments method. This method returns an array of Objects that represent the attachments.

  15. Iterate through the attachments (the Object array) and use the attachment identifier value to obtain the encrypted PDF document. Each element is an org.apache.axis.attachments.AttachmentPart object.

  16. Obtain the javax.activation.DataHandler object associated with the attachment by invoking the org.apache.axis.attachments.AttachmentPart object’s getDataHandler method.

  17. Obtain a java.io.FileStream object by invoking the javax.activation.DataHandler object’s getInputStream method.

  18. Create a byte array and pass that byte array to the java.io.FileStream object’s read method. This method populates the byte array with a data stream that represents the encrypted PDF document.

  19. Create a java.io.File object by using its constructor. This object represents the encrypted PDF document.

  20. Create a java.io.FileOutputStream object by using its constructor and passing the java.io.File object.

  21. Invoke the java.io.FileOutputStream object’s write method and pass the byte array that contains the data stream that represents the encrypted PDF document.