Oracle Business Intelligence Publisher Online Help Release 10.1.3.4 Part Number E12602-01

Contents

Previous

Next

Using the Delivery Manager APIs

Introduction

The Delivery Manager is a set of Java APIs that allow you to control the delivery of your BI Publisher documents. Use the Delivery Manager to:

• Deliver documents through established delivery channels (e-mail, fax, printer, WebDAV, FTP, Secure FTP, AS2, or HTTP) or custom delivery channels

• Track the status of each delivery

• Redeliver documents

Using the Delivery Manager

To use the Delivery Manager follow these steps:

1. Create a DeliveryManager instance

2. Create a DeliveryRequest instance using the createRequest() method

3. Add the request properties (such as DeliveryRequest destination). Most properties require a String value. See the supported properties for each delivery channel for more information.

4. Set your document to the DeliveryRequest.

5. Call submit() to submit the delivery request.

One delivery request can handle one document and one destination. This facilitates monitoring and resubmission, if necessary.

DeliveryRequest allows you to set the documents in three ways as follows:

• Set InputStream of the document to DeliveryRequest. The DeliveryRequest will read the InputStream when you call submit() for the first time. The DeliveryRequest does not close the InputStream so you must ensure to close it.

• Set the file name of the document to DeliveryRequest.

The Delivery Manager supports streamlined delivery when you set the direct mode. See Direct and Buffering Modes.

The follow delivery channels are described in this document:

• E-mail

• Printer

• Fax

• WebDAV

• FTP

• Secure FTP

• HTTP

• AS2

Delivering Documents by e-Mail

The following sample demonstrates delivery via E-mail:

// create delivery manager instance
     DeliveryManager dm = new DeliveryManager();
     // create a delivery request
     DeliveryRequest req = dm.createRequest(DeliveryManager.TYPE_SMTP_EMAIL);
 
     // set email subject
     req.addProperty(DeliveryPropertyDefinitions.SMTP_SUBJECT, "test mail");
     // set SMTP server host
     req.addProperty(
       DeliveryPropertyDefinitions.SMTP_HOST, "mysmtphost");
     // set the sender email address
     req.addProperty(DeliveryPropertyDefinitions.SMTP_FROM, "myname@mydomain.com");
     // set the destination email address
     req.addProperty(
       DeliveryPropertyDefinitions.SMTP_TO_RECIPIENTS, "user1@mydomain.com, user2@mydomain.com" );
     // set the content type of the email body
     req.addProperty(DeliveryPropertyDefinitions.SMTP_CONTENT_TYPE, "application/pdf");
     // set the document file name appeared in the email
     req.addProperty(DeliveryPropertyDefinitions.SMTP_CONTENT_FILENAME, "test.pdf");
     // set the document to deliver
     req.setDocument("/document/test.pdf");
 
     // submit the request
     req.submit();
     // close the request
     req.close();

The following table lists the supported properties:

Defining Multiple Recipients

The e-mail delivery server channel supports multiple documents and multiple destinations per request. The following example demonstrates multiple TO and CC addresses:

    // set the TO email addresses
     req.addProperty(
       DeliveryPropertyDefinitions.SMTP_TO_RECIPIENTS,
        "user1@mydomain.com, user2@mydomain.com, user3@mydomain.com");
 
     // set the CC email addresses
     req.addProperty(
       DeliveryPropertyDefinitions.SMTP_CC_RECIPIENTS, 
        "user4@mydomain.com, user5@mydomain.com, user6@mydomain.com");
 

Attaching Multiple Documents into One Request

Use the Attachment utility class (oracle.apps.xdo.delivery.smtp.Attachment) to attach multiple documents into one request. Sample usage is as follows:

     :
     :
   // create Attachment instance
   Attachment m = new Attachment();

   // add PDF attachment 
   m.addAttachment(
       "/pdf_doc/invoice.pdf",      // file to deliver
       "invoice.pdf",               // file name as appears in email
       "application/pdf");          // content type

   // add RTF attachment 
   m.addAttachment(
       "/rtf_doc/product.rtf",      // file to deliver
       "product.rtf",               // file name appears in the email
       "application/rtf");          // content type

   // add XML attachment
   m.addAttachment(
       "/xml_doc/data.xml",          // file to deliver
       "data.xml",                   // file name appears in the email
       "text/xml");                  // content type

   // If you want to attach HTML doucments, use addHtmlAttachment().
   // This method automatically resolves the image references 
   // in your HTML document and attaches those images. 
   m.addHtmlAttachment("/html_doc/invoice.html");
 
   // add the attachment to the request
   req.addProperty(DeliveryPropertyDefinitions.SMTP_ATTACHMENT, m);

     :
     :  

Attaching HTML Documents

You can attach HTML documents into one request. If you have references to image files located in the local file system in your HTML document, the Attachment utility automatically attaches those image files also. The sample usage is as follows:

   Attachment m = new Attachment();
   m.addHtmlAttachment("/path/to/my.html");
     :
     :
 
   req.addProperty(DeliveryPropertyDefinitions.SMTP_ATTACHMENT, m);

Displaying the Attachment at the top of the e-mail

If you want to show your attachment at the top of the e-mail, set the property SMTP_ATTACHMENT_FIRST to "true". Sample usage is as follows.

   Attachment m = new Attachment();
   m.addHtmlAttachment("/path/to/my.html");
     :
     :
   req.addProperty(DeliveryPropertyDefinitions.SMTP_ATTACHMENT_FIRST, "true");
     :

Using a String Object as the e-Mail Body

You can use a String object for the e-mail body. This may be useful if you want to include a message with your attached files. The following sample code will deliver the message "Please find the attached invoice." in the e-mail body and one PDF document "invoice.pdf" as an attachment.

   // create delivery manager instance
   DeliveryManager dm = new DeliveryManager();
   // create a delivery request
   DeliveryRequest req = dm.createRequest(DeliveryManager.TYPE_SMTP_EMAIL);
 
   // set email subject
   req.addProperty(DeliveryPropertyDefinitions.SMTP_SUBJECT, "Invoice");
   // set SMTP server host
   req.addProperty(
     DeliveryPropertyDefinitions.SMTP_HOST, "mysmtphost");
   // set the sender email address
   req.addProperty(DeliveryPropertyDefinitions.SMTP_FROM, "myname@mydomain.com");
   // set the destination email address
   req.addProperty(
     DeliveryPropertyDefinitions.SMTP_TO_RECIPIENTS, "user1@mydomain.com, user2@mydomain.com" );
   // set the document to deliver
   req.setDocument("Please find the attached invoice. ", "UTF-8");

   // create Attachment 
   Attachment m = new Attachment();
   // add attachments 
   m.addAttachment(
     "/pdf_doc/invoice.pdf",            // file to deliver
     "invoice.pdf",                     // file name appears in the email
     "application/pdf");                // content type
   // add the attachment to the request
   req.addProperty(DeliveryPropertyDefinitions.SMTP_ATTACHMENT, m);
 
   // submit the request
   req.submit();
   // close the request
   req.close();

     :
     :

Using an HTML Document as the e-Mail Body

You can also use an HTML document for the e-mail body. The utility automatically resolves the local image references in your HTML document and attaches those images also.

Sample usage is as follows:

   // create delivery manager instance
   DeliveryManager dm = new DeliveryManager();
   // create a delivery request
   DeliveryRequest req = dm.createRequest(DeliveryManager.TYPE_SMTP_EMAIL);
 
   // set email subject
   req.addProperty(DeliveryPropertyDefinitions.SMTP_SUBJECT, "Invoice");
   // set SMTP server host
   req.addProperty(
     DeliveryPropertyDefinitions.SMTP_HOST, "mysmtphost");
   // set the sender email address
   req.addProperty(DeliveryPropertyDefinitions.SMTP_FROM, "myname@mydomain.com");
   // set the destination email address
   req.addProperty(
     DeliveryPropertyDefinitions.SMTP_TO_RECIPIENTS, "user1@mydomain.com, user2@mydomain.com" );

   // set the content type of the email body
   req.addProperty(DeliveryPropertyDefinitions.SMTP_CONTENT_TYPE, "text/html");
   // set the document file name appeared in the email
   req.addProperty(DeliveryPropertyDefinitions.SMTP_CONTENT_FILENAME, "body.html");
   // set the document to deliver
   req.setDocument("/document/invoice.html");

   // submit the request
   req.submit();
   // close the request
   req.close();

     :
     :

Providing Username and Password for Authentication

If the SMTP server requires authentication, you can specify the username and password to the delivery request.

 :
   req.addProperty(DeliveryPropertyDefinitions.SMTP_USERNAME, "scott");
   req.addProperty(DeliveryPropertyDefinitions.SMTP_PASSWORD, "tiger");
     :

Delivering Your Document to a Printer

The Delivery Server supports Internet Printing Protocol (IPP) as defined in RFC 2910 and 2911 for the delivery of documents to IPP-supported printers or servers, such as CUPS.

Common Unix Printing System (CUPS) is a free, server-style, IPP-based software that can accept IPP requests and dispatch those requests to both IPP and non-IPP based devices, such as printers and fax machines. See http://www.cups.org/ for more information about CUPS. See Setting Up Cupsfor additional information about setting up CUPS in your system.

To print out your document with the IPP, you need to transform your document into the format that the target IPP printers or servers can understand before the delivery. For example, if the target printer is a Postscript printer, you must transform your document to Postscript format. Usually, printers do not natively understand PDF, RTF, Excel or Word document formats. The Delivery API itself does not provide the document format transformation functionality, but it does offer document filter support for this purpose. See Document Filter Support for more information.

Following is a code sample for delivery to a printer:

// create delivery manager instance
     DeliveryManager dm = new DeliveryManager();
     // create a delivery request
     DeliveryRequest req = dm.createRequest(DeliveryManager.TYPE_IPP_PRINTER);
 
     // set IPP printer host
     req.addProperty(DeliveryPropertyDefinitions.IPP_HOST, "myhost");
     // set IPP printer port
     req.addProperty(DeliveryPropertyDefinitions.IPP_PORT, "631");
     // set IPP printer name
     req.addProperty(DeliveryPropertyDefinitions.IPP_PRINTER_NAME, "/printers/myprinter");
     // set the document format
     req.addProperty(DeliveryPropertyDefinitions.IPP_DOCUMENT_FORMAT, 
       DeliveryPropertyDefinitions.IPP_DOCUMENT_FORMAT_POSTSCRIPT);
     // set the document
     req.setDocument("/document/invoice.ps");
 
     // submit the request
     req.submit();
     // close the request
     req.close();

The following properties are supported. A string value is required for each property, unless otherwise noted. Note that printer-specific properties such as IPP_SIDES, IPP_COPIES and IPP_ORIENTATION depend on the printer capabilities. For example, if the target printer does not support duplex printing, the IPP_SIDES setting will have no effect.

Printing over an HTTP Proxy Server

To deliver documents to IPP printers or fax machines over an HTTP proxy server, you may encounter delivery problems due to differences in the HTTP implementations between CUPS and the proxy servers. Setting the following two properties can resolve most of these problems:

• DeliveryPropertyDefinitions.IPP_USE_FULL_URL - set to "true"

• DeliveryPropertyDefinitions.IPP_USE_CHUNKED_BODY - set to "false"

If you use CUPS with the default setup, the typical property settings are as follows:

• IPP_HOST : <host-name>

• IPP_PORT : 631

• IPP_PRINTER_NAME : /printers/<printer-name>

If you use the Microsoft Internet Information Service (IIS) with the default setup, the typical property settings are as follows:

• IPP_HOST : <host-name>

• IPP_PORT : 80

• IPP_PRINTER_NAME : /printers/<printer-name>/.printer

Delivering Your Documents by a Fax Server

The delivery system supports the delivery of documents to fax modems configured on CUPS. You can configure fax modems on CUPS with efax (http://www.cce.com/efax/) and FAX4CUPS (http://www.gnu.org/directory/productivity/special/fax4CUPS.html).

Sample code for fax delivery is as follows:

// create delivery manager instance
     DeliveryManager dm = new DeliveryManager();
     // create a delivery request
     DeliveryRequest req = dm.createRequest(DeliveryManager.TYPE_IPP_FAX);
 
     // set IPP fax host
     req.addProperty(DeliveryPropertyDefinitions.IPP_HOST, "myhost");
     // set IPP fax port
     req.addProperty(DeliveryPropertyDefinitions.IPP_PORT, "631");
     // set IPP fax name
     req.addProperty(DeliveryPropertyDefinitions.IPP_PRINTER_NAME, "/printers/myfax");
     // set the document format
     req.addProperty(DeliveryPropertyDefinitions.IPP_DOCUMENT_FORMAT, "application/postscript");
     // set the phone number to send
     req.addProperty(DeliveryPropertyDefinitions.IPP_PHONE_NUMBER, "9999999");
     // set the document
     req.setDocument("/document/invoice.pdf");
 
     // submit the request
     req.submit();
     // close the request
     req.close();

The supported properties are the same as those supported for printer documents, plus the following:

Delivering Your Documents to a WebDAV Server

The following is sample code for delivery to a Web-based Distributed Authoring and Versioning (WebDAV) server:

// create delivery manager instance
     DeliveryManager dm = new DeliveryManager();
     // create a delivery request
     DeliveryRequest req = dm.createRequest(DeliveryManager.TYPE_WEBDAV);
 
     // set document content type
     req.addProperty(DeliveryPropertyDefinitions.WEBDAV_CONTENT_TYPE, "application/pdf");
     // set the WebDAV server hostname
     req.addProperty(DeliveryPropertyDefinitions.WEBDAV_HOST, "mywebdavhost");
     // set the WebDAV server port number
     req.addProperty(DeliveryPropertyDefinitions.WEBDAV_PORT, "80");
     // set the target remote directory
     req.addProperty(DeliveryPropertyDefinitions.WEBDAV_REMOTE_DIRECTORY, "/content/");
     // set the remote filename
     req.addProperty(DeliveryPropertyDefinitions.WEBDAV_REMOTE_FILENAME, "xdotest.pdf");
  
     // set username and password to access WebDAV server
     req.addProperty(DeliveryPropertyDefinitions.WEBDAV_USERNAME, "xdo");
     req.addProperty(DeliveryPropertyDefinitions.WEBDAV_PASSWORD, "xdo");
     // set the document
     req.setDocument("/document/test.pdf");
 
     // submit the request
     req.submit();
     // close the request
     req.close();

The following properties are supported. A String value is required for each, unless otherwise noted.

Delivering Your Document Using FTP

The following is sample code for delivery to a FTP server:

// create delivery manager instance
     DeliveryManager dm = new DeliveryManager();
     // create a delivery request
     DeliveryRequest req = dm.createRequest(DeliveryManager.TYPE_FTP);
 
     // set hostname of the FTP server
     req.addProperty(DeliveryPropertyDefinitions.FTP_HOST, "myftphost");
     // set port# of the FTP server
     req.addProperty(DeliveryPropertyDefinitions.FTP_PORT, "21");
     // set username and password to access WebDAV server
     req.addProperty(DeliveryPropertyDefinitions.FTP_USERNAME, "xdo");
     req.addProperty(DeliveryPropertyDefinitions.FTP_PASSWORD, "xdo");
     // set the remote directory that you want to send your document to
     req.addProperty(DeliveryPropertyDefinitions.FTP_REMOTE_DIRECTORY, "pub");
     // set the remote file name 
     req.addProperty(DeliveryPropertyDefinitions.FTP_REMOTE_FILENAME, "test.pdf");
     // set the document
     req.setDocument("/document/test.pdf");
 
     // submit the request
     req.submit();
     // close the request
     req.close();

The following properties are supported. A String value is required unless otherwise noted.

Delivering Your Documents over Secure FTP

Secure FTP is the protocol based on the Secure Shell technology (ssh) and it is widely used to transfer files in a secure manner. Both Secure Shell and Secure FTP are defined by the Internet Engineering Task Force (IETF) and the specifications are available on their Web site: http://www.ietf.org. The delivery system supports the delivery of documents to secure FTP servers.

The following tables lists the supported properties. A string value is required for each property unless otherwise noted.

// create delivery manager instance
     DeliveryManager dm = new DeliveryManager();
     // create a delivery request
     DeliveryRequest req = dm.createRequest(DeliveryManager.TYPE_SFTP);
     // set hostname of the SFTP server
     req.addProperty(DeliveryPropertyDefinitions.SFTP_HOST, "mysftphost");
     // set username and password to access server
     req.addProperty(DeliveryPropertyDefinitions.SFTP_USERNAME, "myname");
     req.addProperty(DeliveryPropertyDefinitions.SFTP_PASSWORD, "mypassword");
     // set the remote directory that you want to send your document to
     req.addProperty(DeliveryPropertyDefinitions.SFTP_REMOTE_DIRECTORY, "pub");
     // set the remote file name 
     req.addProperty(DeliveryPropertyDefinitions.SFTP_REMOTE_FILENAME, "test.pdf");
     // set the document
     req.setDocument("/document/test.pdf");
     
     // submit the request
     req.submit();
     // close the request
     req.close();

Authentication Modes

The secure FTP delivery supports two authentication modes: password authentication and public key authentication. Set the property SFTP_AUTH_TYPE to choose the mode. The default mode is password authentication.

         :
         :
      // set public key auth type
      req.addProperty(DeliveryPropertyDefinitions.SFTP_AUTH_TYPE, 
                      DeliveryPropertyDefinitions.SFTP_AUTH_TYPE_PUBLIC_KEY);
      // set username 
      req.addProperty(DeliveryPropertyDefinitions.SFTP_USERNAME, "myname");
      // set the client's private key file
      req.addProperty(DeliveryPropertyDefinitions.SFTP_PRIVATE_KEY_FILE,
             "/path/to/the/key");
      // set the client's private key password
      req.addProperty(DeliveryPropertyDefinitions.SFTP_PRIVATE_KEY_PASSWORD, "myPrivateKeyPass");         
         :
         :

The password authentication mode requires the username and password to log in to the secure FTP server. The following example shows sample code:

:
         :
     // set password auth type
      req.addProperty(DeliveryPropertyDefinitions.SFTP_AUTH_TYPE, 
                      DeliveryPropertyDefinitions.SFTP_AUTH_TYPE_PASSWORD);
      // set username and password to access server
      req.addProperty(DeliveryPropertyDefinitions.SFTP_USERNAME, "myname");
      req.addProperty(DeliveryPropertyDefinitions.SFTP_PASSWORD, "mypassword");
         :
         :

The public key authorization mode requires the username, your private key and password for the private key. This is a more secure method than the password authentication. Note that in order to use the public key authentication mode, you must set up the public key in the ssh/secure FTP server in advance. The following example shows sample code:

         :
         :
      // set public key auth type
      req.addProperty(DeliveryPropertyDefinitions.SFTP_AUTH_TYPE, 
                      DeliveryPropertyDefinitions.SFTP_AUTH_TYPE_PUBLIC_KEY);
      // set username 
      req.addProperty(DeliveryPropertyDefinitions.SFTP_USERNAME, "myname");
      // set the client's private key file
      req.addProperty(DeliveryPropertyDefinitions.SFTP_PRIVATE_KEY_FILE,
                      "/path/to/the/key");
      // set the client's private key password
      req.addProperty(DeliveryPropertyDefinitions.SFTP_PRIVATE_KEY_PASSWORD, "myPrivateKeyPass");         
         :
         :

Delivering Your Documents over HTTP

The Delivery Manager supports delivery of documents to HTTP servers. The following sample sends a document through the HTTP POST method. Note that the receiving HTTP server must be able to accept your custom HTTP request in advance (for example via a custom servlet or CGI program).

// create delivery manager instance
     DeliveryManager dm = new DeliveryManager();
     // create a delivery request
     DeliveryRequest req = dm.createRequest(DeliveryManager.TYPE_HTTP);
 
     // set request method 
     req.addProperty(DeliveryPropertyDefinitions.HTTP_METHOD, DeliveryPropertyDefinitions.HTTP_METHOD_POST);
     // set document content type
     req.addProperty(DeliveryPropertyDefinitions.HTTP_CONTENT_TYPE, "application/pdf");
     // set the HTTP server hostname
     req.addProperty(DeliveryPropertyDefinitions.HTTP_HOST, "myhost");
     // set the HTTP server port number
     req.addProperty(DeliveryPropertyDefinitions.HTTP_PORT, "80");
     // set the target remote directory
     req.addProperty(DeliveryPropertyDefinitions.HTTP_REMOTE_DIRECTORY, "/servlet/");
     // set the remote filename (servlet class)
     req.addProperty(DeliveryPropertyDefinitions.HTTP_REMOTE_FILENAME, "uploadDocument");
  
     // set the document
     req.setDocument("/document/test.pdf");
 
     // submit the request
     req.submit();
     // close the request
     req.close();

The following table lists the properties that are supported. A String value is required for each property unless otherwise noted.

Delivering Documents over AS2

AS2 is one of the standard protocols defined in the Electronic Data Interchange-Internet Integration (EDI-INT). AS2 is based on HTTP and other internet standard technologies and is designed to exchange data over the internet in a secure manner. The AS2 specification is defined in RFC4130 (available at http://www.ietf.org/). The delivery system supports the delivery of documents to AS2 servers. Sample code is as follows:

// create delivery manager instance
    DeliveryManager dm = new DeliveryManager();
    // create a delivery request
    DeliveryRequest req = dm.createRequest(DeliveryManager.TYPE_AS2);
 
    // set AS2 message properties 
    req.addProperty(DeliveryPropertyDefinitions.AS2_FROM, "Me");
    req.addProperty(DeliveryPropertyDefinitions.AS2_TO, "You");
    req.addProperty(DeliveryPropertyDefinitions.AS2_SUBJECT, "My EDI Message");
    req.addProperty(DeliveryPropertyDefinitions.AS2_CONTENT_TYPE, "applications/EDIFACT");
 
    // set HTTP properties
    req.addProperty(DeliveryPropertyDefinitions.AS2_HTTP_HOST, "as2hsot");
    req.addProperty(DeliveryPropertyDefinitions.AS2_HTTP_REMOTE_DIRECTORY, "/");
    req.addProperty(DeliveryPropertyDefinitions.AS2_HTTP_REMOTE_FILENAME, "as2");
 
    // set the document
    req.setDocument("/document/myEDIdoc");
    // submit the request
    DeliveryResponse res = req.submit();
    // close the request
    req.close();

The following table lists the supported properties. A string value is required for each property unless otherwise noted.

Delivery Receipt

The AS2 server always issues an AS2 delivery receipt for each AS2 request. Set the AS2_DELIVERY_RECEIPT_DIRECTORY property to specify the location to store the delivery receipts. If you do not specify this directory, delivery receipts will be ignored. Example code for setting the delivery receipt directory is as follows:

         :
         :
 // Set the delivery receipt directory
 req.addProperty(DeliveryPropertyDefinitions.AS2_DELIVERY_RECEIPT_DIRECTORY, "/my/receipt/dir");
         :
         :

Synchrony

You can send either synchronous or asynchronous delivery requests to the AS2 servers. By default, the request is synchronous so that you can see the Message Disposition Notification (MDN) immediately in the DeliveryResponse.

If you set the AS2_ASYNC_ADDRESS to your request, the request will be asynchronous. You can specify either an HTTP URL or an e-mail address where the delivery receipt will be delivered after processing. You must set up the HTTP server or e-mail address to receive the delivery receipts.

The Delivery API can track down the asynchronous request if you specify the e-mail address for the AS2_ASYNC_ADDRESS. If you provide the e-mail account information to the Delivery API, the Delivery API will periodically check the e-mail account to obtain the delivery receipt. Sample code for this is as follows:

         :
         :
 // Set the email address - async request
 req.addProperty(DeliveryPropertyDefinitions.AS2_ASYNC_ADDRESS, "async_target@acme.com");

 // Set the delivery receipt directory
 req.addProperty(DeliveryPropertyDefinitions.AS2_DELIVERY_RECEIPT_DIRECTORY, "/my/receipt/dir");
  
 // Set the email server information where the delivery receipt will be delivered to. 
 req.addProperty(
     DeliveryPropertyDefinitions.AS2_ASYNC_EMAIL_SERVER_HOST, "mail.acme.com");
 req.addProperty(
     DeliveryPropertyDefinitions.AS2_ASYNC_EMAIL_SERVER_USERNAME, "async_target");
 req.addProperty(
     DeliveryPropertyDefinitions.AS2_ASYNC_EMAIL_SERVER_PASSWORD, "mypassword");
 req.addProperty(
     DeliveryPropertyDefinitions.AS2_ASYNC_EMAIL_SERVER_FOLDER_NAME, "inbox");
  
 // set the document
 req.setDocument("/document/myEDIdoc");
    
 // submit the request with the DeliveryResponseListener 
 req.submit(myDeliveryListener);
        :
        :

Note that as shown in the preceding code, you must use the Delivery API's asynchronous delivery request mechanism to track down the asynchronous requests. See Asynchronous Delivery Requests for more information.

Document Signing

The Delivery API allows you to sign a document for the secure transaction. This is based on the public key architecture, so you must set up the following:

• Sender side: sender's public/private keys

  Sender must have sender's public/private keys in a PKCS12 standard file. The file extension is .p12. Place that file in your local system where you want to run the Delivery API.

• Receiver side (AS2 server side) : sender's public key certificate

  The receiver must have the sender's public key certificate. Installing certificates on the AS2 server can vary depending on your server. Generally, you must copy the .der or .cer certificates to a particular location. Consult your AS2 server manual for the procedure.

Once you have completed the setup, you can sign your document by setting properties in the delivery request. Sample code for this is as follows:

        :
        :
 // Signing the document
 req.addProperty(DeliveryPropertyDefinitions.AS2_MESSAGE_SIGNATURE, "true");
 req.addProperty(DeliveryPropertyDefinitions.AS2_SENDER_PKCS12_FILE, "/path/to/mykey.p12");
 req.addProperty(DeliveryPropertyDefinitions.AS2_SENDER_PKCS12_PASSWORD, "welcome");
        :
        :

Document Encryption

The Delivery API allows you to encrypt documents for the secure transaction. This is based on the public key architecture, so you need to set up the following:

• Sender's side: Receiver's public key certificate

  The sender side must have the receiver's public key certificate file. The file extension is .der or .cer. Place that file in your local system where you want to run the Delivery API. Please consult the manual of your AS2 server for the procedure to obtain the AS2 server's public key certificate.

• Receiver's side (AS2 server side): Receiver's public/private keys

  The receiver side (AS2 Server) must have the receiver's public/private keys. Please consult the manual of your AS2 server for the procedure to set up keys.

Once set up, you can encrypt your document by setting properties in the delivery request. The sample code is as follows:

        :
        :
 // Encrypting the document
 req.addProperty(DeliveryPropertyDefinitions.AS2_MESSAGE_ENCRYPTION, "true");
 req.addProperty(DeliveryPropertyDefinitions.AS2_RECEIVER_CERTIFICATES_FILE,  "/path/to/server-certificate.der");
        :
        :

Delivering Documents Using an External Command

The Delivery API supports the use of external, Operating System (OS) native commands to deliver documents.

Specify your OS native command with the {file} placeholder. At runtime, this placeholder will be replaced with the document file name.

The delivery status is determined by the exit value of the OS command. If the value is '0', the request is marked successful.

Sample code is as follows:

     // create delivery manager instance
     DeliveryManager dm = new DeliveryManager();
     // create a delivery request
     DeliveryRequest req = dm.createRequest(DeliveryManager.TYPE_EXTERNAL);
     // set the OS native command for delivery
     req.addProperty(ExternalDeliveryPropertyDefinitions.EXTERNAL_DELIVERY_COMMAND,
     "/usr/bin/lp -d myprinter {file}");
     // set the document
     req.setDocument("/document/test.pdf");
 
     // submit the request
     req.submit();
     // close the request
     req.close();

The following property is supported and defined in DeliveryPropertyDefinitions:

Delivering Documents to the Local File System

The Delivery API supports the delivery of documents to the local file system where the Delivery API runs. The command copies the file to the location you specify.

The following sample code copies the file /document/test.pdf to /destination/document.pdf.

     // create delivery manager instance
     DeliveryManager dm = new DeliveryManager();
     // create a delivery request
     DeliveryRequest req = dm.createRequest(DeliveryManager.TYPE_LOCAL);
     // set the document destination in the local filesystem.
     req.addProperty(ExternalDeliveryPropertyDefinitions.LOCAL_DESTINATION, "/destination/document.pdf");
     // set the document to deliver.
     req.setDocument("/document/test.pdf");
 
     // submit the request
     req.submit();
     // close the request
     req.close();

The following property is supported and defined in DeliveryPropertyDefinitons:

Direct and Buffering Modes

The delivery system supports two modes: Direct mode and Buffering mode. Buffering Mode is the default.

Direct Mode

Direct Mode offers full, streamlined delivery processing. Documents are delivered to the connection streams that are directly connected to the destinations. This mode is fast, and uses less memory and disk space. It is recommended for online interactive processing.

To set the direct mode, set the BUFFERING_MODE property to "false". Following is a code sample:

// create delivery manager instance
     DeliveryManager dm = new DeliveryManager();
 
     // create a delivery request
     DeliveryRequest req = dm.createRequest(DeliveryManager.TYPE_IPP_PRINTER);
 
     // set the direct mode  
     req.addProperty(DeliveryPropertyDefinitions.BUFFERING_MODE, "false");
           :
           :
           :

This mode does not offer document redelivery. For redelivery requirements, use the buffering mode.

Buffering Mode

The buffering mode allows you to redeliver documents as many times as you want. The delivery system uses temporary files to buffer documents, if you specify a temporary directory (ds-temp-dir) in the delivery server configuration file. If you do not specify a temporary directory, the delivery system uses the temporary memory buffer. It is recommended that you define a temporary directory. For more information about the configuration file, see Configuration File Support.

You can explicitly clear the temporary file or buffer by calling DeliveryRequest.close() after finishing your delivery request.

// create delivery manager instance
     DeliveryManager dm = new DeliveryManager();
 
     // create a delivery request
     DeliveryRequest req = dm.createRequest(DeliveryManager.TYPE_IPP_PRINTER);
 
     // set buffering mode 
     req.addProperty(DeliveryPropertyDefinitions.BUFFERING_MODE, "true");
     req.addProperty(DeliveryPropertyDefinitions.TEMP_DIR, "/tmp");
           :
           :
           :
     // submit request
     req.submit();
           :
           :
     // submit request again
     req.submit();
           :
           :
     // close the request
     req.close();

Asynchronous Delivery Requests

The Delivery API provides the ability to run the delivery requests asynchronously by registering the callback functions.

You can create your own callback logic by implementing the DeliveryResponseListener interface. You must implement the resposeReceived() method. You can implement your logic in this method so that it will be called when the delivery request is finished. Sample code is as follows:

  import oracle.apps.xdo.delivery.DeliveryResponseListener;

  class MyListener implements DeliveryResponseListener
  {

    public void responseReceived(DeliveryResponse pResponse)
    {
      // Show the status to the System.out
      System.out.println("Request done!");
      System.out.println("Request status id  : " + pResponse.getStatus());
      System.out.println("Request status msg : " + pResponse.getStatusMessage());
    }
    
  }

Once you implement the callback, you can pass your callback when you call the submit() method of your DeliveryRequest. If you call the submit() with the callback, the delivery process will start in the background and the submit() method will immediately return the control. Sample code follows:

    // create delivery manager instance
    DeliveryManager dm = new DeliveryManager();

    // create a delivery request
    DeliveryRequest req = dm.createRequest(DeliveryManager.TYPE_IPP_PRINTER);
          :
          :
    // submit request with the callback logic
    req.submit(new MyListener());
          :
          :

Document Filter Support

The Delivery API supports the document filter functionality for all the supported protocols. This functionality allows you to call the native OS command to transform the document before each delivery request. To specify the filter, pass the native OS command string with the two placeholders for the input and output filename: {infile} and {outfile}. You can set your filter in your delivery request as a delivery property. Following are two samples:

// The easiest filter, just copy the file :)
req.addProperty(DeliveryPropertyDefinitions.FILTER, "cp {infile} {outfile}"); 


// Call "pdftops" utility to transform the PDF document into Postscript format
 req.addProperty(DeliveryPropertyDefinitions.FILTER, "pdftops {infile} {outfile}"); 

Alternatively, you can also specify the filter for each server in the configuration file (see Configuration File Support). In this case, the server will always use this filter for the requests to this server:

         :
         :

<server name="printer1" type="ipp_printer" default="true">
<uri>ipp://myserver:80/printers/MyPrinter1/.printer</uri>
<filter>pdftops {infile} {outfile}</filter>
</server>
         :
         :

This is useful especially if you are trying to call IPP printers directly or IPP printers on Microsoft Internet Information Service (IIS) because those printers usually do not accept PDF documents, but only limited document formats. With this functionality, you can call any of the native OS commands to transform the document to the format that the target printer can understand. For example, if you need to call the HP LaserJet printer setup on the Microsoft IIS from Linux, you can set Ghostscript as a filter to transform the PDF document into the format that the HP LaserJet can understand.

     // specify filter
     req.addProperty(DeliveryPropertyDefinitions.FILTER, 
     "gs -q -dNOPAUSE -dBATCH -sDEVICE=laserjet -sOutputFile={outfile} 
      {infile}"); 
 

Note that to use this functionality you must set the buffering mode must be enabled and a temporary directory must be specified. See Configuration File Support for information on setting these properties.

Date Expression Support

Three properties support date expressions. Use the date expression if you want to name a file by the date, and have the date automatically set at runtime.

The properties that support date expressions are:

• SMTP_CONTENT_FILENAME

• FTP_REMOTE_FILENAME

• WEBDAV_REMOTE_FILENAME

The supported date expressions are:

• %y : 4 digit year (ex, 1972, 2005)

• %m : 2 digit month (00 - 12)

• %d : 2 digit date (00 - 31)

• %H : 24h based 2 digit hour (00 - 24)

• %M : 2 digit minute (00 - 59)

• %S : 2 digit sec (00 - 59)

• %l : 3 digit millisec (000 - 999)

For example, if you specify my_file_%y%m%d.txt for the filename, the actual filename will would be my_file_20051108.txt for November 8, 2005. All undefined expressions will be translated into 0 length string, for example, if you specify my_file_%a%b%c.txt, it would generate my_file_.txt. You can escape the '%' character by passing '%%'.

Internationalization Support

The Delivery Server API supports following internationalization features for the listed delivery channels:

SMTP

• Specify character encoding for the main document with SMTP_CONTENT_TYPE.

• Specify character encoding for the attachments by passing content type when you call addAttachment() method.

• Specify the character encoding for email To/From/CC/Subject with SMTP_CHARACTER_ENCODING property. The default value is "UTF-8".

IPP

• Specify character encoding for the IPP attributes by using IPP_ATTRIBUTE_CHARSET property. The default value is "UTF-8".

• Specify IPP_URL_CHARACTER_ENCODING property for encoding non-ASCII letters in a URL.

WebDAV

• Specify WEBDAV_URL_CHARACTER_ENCODING property for encoding non-ASCII letters in a URL.

FTP

• The FTP delivery channel automatically detects the internationalization support in the target FTP server. You can specify a non-ASCII directory name and file name only if the FTP server supports internationalization (see RFC 2640 for more detail). In that case, the UTF-8 encoding will be used automatically. If the server does not support internationalization and you specify a non-ASCII value, an exception will be thrown during the delivery process.

HTTP

• You can specify WEBDAV_URL_CHARACTER_ENCODING property for encoding non-ASCII letters in a URL.

Monitoring Delivery Status

The delivery system allows you to check the latest delivery status of your request by calling the getStatus() method. You can check the status of the request anytime, but currently you must retain the delivery request object. Status definitions are defined in the DeliveryRequest interface.

Monitoring delivery status is not available for the SMTP and HTTP delivery channels.

// create delivery manager instance
     DeliveryManager dm = new DeliveryManager();
 
     // create a delivery request
     DeliveryRequest req = dm.createRequest(DeliveryManager.TYPE_IPP_PRINTER);
           :
           :
     // submit request
     req.submit();
           :
           :
 
     // get request status 
     int status = req.getStatus();
     if (status == DeliveryRequest.STATUS_SUCCESSFUL)
     {
        System.out.println("Request has been delivered successfully.");
     }
           :
           :
     // get request status again...
     status = req.getStatus();
           :
           :

Setting Global Properties

You can define the global properties to the DeliveryManager so that all the delivery requests inherit the global properties automatically.

The following global properties are supported:

// create delivery manager instance
     DeliveryManager dm = new DeliveryManager();

     // set global properties 
     dm.addProperty(DeliveryPropertyDefinitions.TEMP_DIR, "/tmp");
     dm.addProperty(DeliveryPropertyDefinitions.BUFFERING_MODE, "true");
 
     // create delivery requests
     DeliveryRequest req1 = dm.createRequest(DeliveryManager.TYPE_IPP_PRINTER);
     DeliveryRequest req2 = dm.createRequest(DeliveryManager.TYPE_IPP_FAX);
     DeliveryRequest req3 = dm.createRequest(DeliveryManager.TYPE_SMTP_EMAIL);
           :
           :

Adding a Custom Delivery Channel

You can add custom delivery channels to the system by following the steps below:

1. Define the delivery properties

2. Implement the DeliveryRequest interface

3. Implement the DeliveryRequestHandler interface

4. Implement the DeliveryRequestFactory interface

5. Register your custom DeliveryRequestFactory to the DeliveryManager

The following sections detail how to create a custom delivery channel by creating a sample called "File delivery channel" that delivers documents to the local file system.

Define Delivery Properties

The first step to adding a custom delivery channel is to define the properties. These will vary depending on what you want your channel to do. You can define constants for your properties. Our example, a file delivery channel requires only one property, which is the destination.

Sample code is:

package oracle.apps.xdo.delivery.file;

public interface FilePropertyDefinitions
  {
     /** Destination property definition.  */
     public static final String FILE_DESTINATION = "FILE_DESTINATION:String";

   }

The value of each constant can be anything, as long as it is a String. It is recommend that you define the value in [property name]:[property value type]format so that the delivery system automatically validates the property value at runtime. In the example, the FILE_DESTINATION property is defined to have a String value.

Implement DeliveryRequest Interface

DeliveryRequest represents a delivery request that includes document information and delivery metadata, such as destination and other properties. To implement oracle.apps.xdo.delvery.DeliveryRequest you can extend the class oracle.apps.xdo.delivery.AbstractDeliveryRequest.

For example, to create a custom delivery channel to deliver documents to the local file system, the DeliveryRequest implementation will be as follows:

package oracle.apps.xdo.delivery.file;
import oracle.apps.xdo.delivery.AbstractDeliveryRequest;
  
public class FileDeliveryRequest extends AbstractDeliveryRequest
implements FilePropertyDefinitions
{
  private static final String[] MANDATORY_PROPS = {FILE_DESTINATION};
 
  /** 
   * Returns mandatory property names
   */
  public String[] getMandatoryProperties()
  {
    return MANDATORY_PROPS;
  }
  /** 
   * Returns optional property names
   */
  public String[] getOptionalProperties()
  {
    return null;
  }
}

Implement DeliveryRequestHandler Interface

DeliveryRequestHandler includes the logic for handling the delivery requests. A sample implementation of oracle.apps.xdo.delivery.DeliveryRequestHandler for the file delivery channel is as follows:

package oracle.apps.xdo.delivery.file;
import java.io.BufferedOutputStream;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.OutputStream;

import oracle.apps.xdo.delivery.DeliveryException;
import oracle.apps.xdo.delivery.DeliveryRequest;
import oracle.apps.xdo.delivery.DeliveryRequestHandler;
import oracle.apps.xdo.delivery.DeliveryStatusDefinitions;

public class FileDeliveryRequestHandler implements DeliveryRequestHandler
{

  private FileDeliveryRequest mRequest;
  private boolean mIsOpen = false;
  private OutputStream mOut;

  /**
   * default constructor.
   */ 
  public FileDeliveryRequestHandler()
  {
  }

  /** 
   * sets the request.
   */
  public void setRequest(DeliveryRequest pRequest)
  {
    mRequest = (FileDeliveryRequest) pRequest;
  }

  /** 
   * returns the request.
   */
  public DeliveryRequest getRequest()
  {
    return mRequest;
  }

  /** 
   * opens the output stream to the destination.
   */ 
  public OutputStream openRequest() throws DeliveryException
  {
    try
    {
      String filename =
        (String) mRequest.getProperty(FileDeliveryRequest.FILE_DESTINATION);
      mOut = new BufferedOutputStream(new FileOutputStream(filename));

      mIsOpen = true;
      // set request status to open
      mRequest.setStatus(DeliveryStatusDefinitions.STATUS_OPEN);
      return mOut;

    }
    catch (IOException e)
    {
      closeRequest();
      throw new DeliveryException(e);
    }

  }

  /**
   * flushes and closes the output stream to submit the request.
   */ 
  public void submitRequest() throws DeliveryException
  {
    try
    {
      // flush and close
      mOut.flush();
      mOut.close();
      // set request status
      mRequest.setStatus(DeliveryStatusDefinitions.STATUS_SUCCESSFUL);
      mIsOpen = false;
    }
    catch (IOException e)
    {
      closeRequest();
      throw new DeliveryException(e);
    }
  }

  /**
   * checks the delivery status.
   */
  public void updateRequestStatus() throws DeliveryException
  {

    // check if the file is successfully delivered
    String filename =
      (String) mRequest.getProperty(FileDeliveryRequest.FILE_DESTINATION);
    File f = new File(filename);

    // set request status
    if (f.exists())
      mRequest.setStatus(DeliveryStatusDefinitions.STATUS_SUCCESSFUL);
    else
      mRequest.setStatus(DeliveryStatusDefinitions.STATUS_FAILED_IO_ERROR);

  }
  /**
   * returns the request status.
   */ 
  public boolean isRequestOpen()
  {
    return mIsOpen;
  }

  /** 
   * closes the request, frees all resources.
   */
  public void closeRequest()
  {
    mIsOpen = false;
    try
    {
      if (mOut != null)
      {
        mOut.flush();
        mOut.close();
      }
    }
    catch (IOException e)
    {
    }
    finally
    {
      mOut = null;
    }
  }

}

Implement DeliveryRequestFactory Interface

Implement the DeliveryRequestFactory interface to register your custom delivery channel to the delivery system.

A sample implementation of oracle.apps.xdo.delivery.DeliveryRequestFactory is as follows:

package oracle.apps.xdo.delivery.file;

import oracle.apps.xdo.delivery.DeliveryRequest;
import oracle.apps.xdo.delivery.DeliveryRequestFactory;
import oracle.apps.xdo.delivery.DeliveryRequestHandler;

public class FileDeliveryRequestFactory
implements DeliveryRequestFactory
{
  /** 
   * default constructor.
   */
  public FileDeliveryRequestFactory()
  {
  }
  /** 
   * returns delivery request.
   */
  public DeliveryRequest createRequest()
  {
    return new FileDeliveryRequest();
  }
  /**
   * returns delivery request handler.
   */
  public DeliveryRequestHandler createRequestHandler()
  {
    return new FileDeliveryRequestHandler();
  }
  /**
   * returns this
   */  
  public DeliveryRequestFactory getFactory()
  {
    return this;
  }
} 

Register your custom DeliveryRequestFactory to DeliveryManager

The final step is to register your custom delivery channel to the delivery system. You can register your delivery channel in two ways:

• Static method

  Use this method to register your delivery channel to the whole delivery system by specifying it in the configuration file. See Configuration File Support for more information.

• Dynamic method

  Register the delivery channel to the Java VM instance by calling the Register API programmatically.

  Sample code to register the file delivery channel using the dynamic method and call the file delivery channel is as follows:

  package oracle.apps.xdo.delivery.file;
  
  import oracle.apps.xdo.delivery.DeliveryManager;
  import oracle.apps.xdo.delivery.DeliveryRequest;
  
  public class FileDeliverySample
  {
    public static void main(String[] args) throws Exception
    {
      // register the file delivery channel 
      DeliveryManager.addRequestFactory("file", "oracle.apps.xdo.delivery.file.FileDeliveryRequestFactory");
  
      // create delivery manager instance
      DeliveryManager dm = new DeliveryManager();
      // create a delivery request
      DeliveryRequest req = dm.createRequest("file");
  
      // set the destination
      req.addProperty(
        FileDeliveryRequest.FILE_DESTINATION,
        "d:/Temp/testDocument_delivered.pdf");
      // set the document to deliver
      req.setDocument("D:/Temp/testDocument.pdf");
  
      // submit the request
      req.submit();
      // close the request
      req.close();
    }
  }

Configuration File Support

The delivery systems supports a configuration file to set default servers, default properties, and custom delivery channels. The location of the configuration file is

{XDO_TOP}/resource/xdodelivery.cfg

where {XDO_TOP} is a Java system property that points to the physical directory.

This system property can be set in two ways:

• Pass -DXDO_TOP=/path/to/xdotop to the Java startup parameter

• Use a Java API in your code, such as java.lang.System.getProperties().put("XDO_TOP", "/path/to/xdotop")

The system property must be defined before constructing a DeliveryManager object.

Following is a sample configuration file:

<?xml version='1.0' encoding='UTF-8'?>
 <config xmlns="http://xmlns.oracle.com/oxp/delivery/config">
   <! -  ========================================================  - >
   <! -     servers section                                        - >
   <! -     List your pre-defined servers here.                    - >

   <! -  ========================================================  - >
   <servers>
     <server name="myprinter1" type="ipp_printer" default="true">
       <uri>ipp://myprinter1.oracle.com:631/printers/myprinter1</uri>

     </server>
     <server name="myprinter2" type="ipp_printer" >
       <host>myprinter2.oracle.com</host>
       <port>631</port>

       <uri>ipp://myprinter2.oracle.com:631/printers/myprinter2</uri>
       <authType>basic</authType>
       <username>xdo</username>
       <password>xdo</password>

     </server>
     <server name="myfax1" type="ipp_fax" default="true" >
       <host>myfax1.oracle.com</host>

       <port>631</port>
       <uri>ipp://myfax1.oracle.com:631/printers/myfax1</uri>
     </server>
     <server name="mysmtp1" type="smtp_email" default="true">

       <host>myprinter1.oracle.com</host>
       <port>25</port>
     </server>
     <server name="mysmtp2" type="smtp_email" >

       <host>mysmtp12.oracle.com</host>
       <port>25</port>
       <username>xdo</username>
       <password>xdo</password>

     </server>
   </servers>
   <! -  ========================================================  - >
   <! -     properties section                                     - >
   <! -     List the system properties here.                       - >
   <! -  ========================================================  - >
   <properties>

     <property name="ds-temp-dir">/tmp</property>
     <property name="ds-buffering">true</property>
   </properties>
   <! -  ========================================================  - >
   <! -      channels section                                      - >

   <! -      List the custom delivery channels here.               - >
   <! -  ========================================================  - >
   <channels>
     <channel name="file">oracle.apps.xdo.delivery.file.FileDeliveryRequestFactory</channel>
   </channels>

 </config>

Defining Multiple Servers for a Delivery Channel

You can define multiple server entries for each delivery channel. For example, the preceding sample configuration file has two server entries for the "ipp_printer" delivery channel ("myprinter1" and "myprinter2").

Load a server entry for a delivery request by calling DeliveryRequest.setServer() method. Following is an example:

// create delivery manager instance
     DeliveryManager dm = new DeliveryManager();
     // create a delivery request
     DeliveryRequest req = dm.createRequest(DeliveryManager.TYPE_IPP_PRINTER);
 
     // load myprinter1 setting
     req.setServer("myprinter1");

Specifying a Default Server for a Delivery Channel

To define a default server for a delivery channel, specify default="true". In the configuration file example above, "myprinter1" is defined as the default sever for the "ipp_printer" delivery channel. If a user does not specify the server properties for "ipp_printer" delivery, the server properties under the default server will be used.

Supported Configuration File Properties and Elements

The following properties are supported in the <properties> section:

• ds-temp-dir: temporary directory location.

• ds-buffering: specify true or false for buffering mode.

• ds-ca-cert-file: specify the SSL certification file location.

The following elements are supported for <server type="ipp_printer"> and <server type="ipp_fax">

• <host>

• <port>

• <printerName>

• <uri>

• <username>

• <password>

• <authType>

• <encType>

• <proxyHost>

• <proxyPort>

• <proxyUsername>

• <proxyPassword>

• <proxyAuthType>

• <filter>

The following elements are supported for <server type="smtp_email">

• <host>

• <port>

• <uri>

• <username>

• <password>

• <authType>

• <filter>

The following elements are supported for <server type="webdav">

• <host>

• <port>

• <uri>

• <username>

• <password>

• <authType>

• <encType>

• <proxyHost>

• <proxyPort>

• <proxyUsername>

• <proxyPassword>

• <proxyAuthType>

• <filter>

The following elements are supported for <server type="ftp"> and <server type="sftp">

• <host>

• <port>

• <uri>

• <username>

• <password>

• <filter>

The following elements are supported for <server type="external">

• <command>

• <filter>

Copyright © 2005, 2008, Oracle and/or its affiliates. All rights reserved.