Skip Headers

Oracle Business Intelligence Publisher Administrator's and Developer's Guide
Release 10.1.3.4
Part Number E12188-01
Go to Table of Contents
Contents
Go to previous page
Previous
Go to next page
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:

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:

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:

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:

Property Description
SMTP_TO_RECIPIENTS Required
Enter multiple recipients separated by a comma (example: "user1@mydomain.com, user2@mydomain.com")
SMTP_CC_RECIPIENTS Optional
Enter multiple recipients separated by a comma.
SMTP_BCC_RECIPIENTS Optional
Enter multiple recipients separated by a comma.
SMTP_FROM Required
Enter the e-mail address of the sending party.
SMTP_REPLY_TO Optional
Enter the reply-to e-mail address.
SMTP_SUBJECT Required
Enter the subject of the e-mail.
SMTP_CHARACTER_ENCODING Optional
Default is "UTF-8".
SMTP_ATTACHMENT Optional
If you are including an attachment, enter the attachment object name.
SMTP_CONTENT_FILENAME Required
Enter the file name of the document (example: invoice.pdf)
SMTP_CONTENT_TYPE Required
Enter the MIME type.
SMTP_SMTP_HOST Required
Enter the SMTP host name.
SMTP_SMTP_PORT Optional
Enter the SMTP port. Default is 25.
SMTP_SMTP_USERNAME Optional
If the SMTP server requires authentication, enter your username for the server.
SMTP_SMTP_PASSWORD Optional
If the SMTP server requires authentication, enter the password for the username you entered.
SMTP_ATTACHMENT_FIRST Optional
If your e-mail contains an attachment and you want the attachment to appear first, enter "true". If you do not want the attachment to appear first, enter "false".

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.

Property Description
IPP_HOST Required
Enter the host name.
IPP_PORT Optional
Default is 631.
IPP_PRINTER_NAME Required
Enter the name of the printer that is to receive the output.
  • If you use CUPS with the default setup, enter the printer name as /printers/<printer-name>

  • If you use the Microsoft Internet Information Service (IIS) with the default setup, enter the printer name as /printers/<printer-name>/.printer

IPP_AUTHTYPE Optional
Valid values for authentication type are:
IPP_AUTHTYPE_NONE - no authentication (default)
IPP_AUTHTYPE_BASIC - use HTTP basic authentication
IPP_AUTHTYPE_DIGEST - use HTTP digest authentication
IPP_USERNAME Optional
Enter the username for HTTP authentication.
IPP_PASSWORD Optional
Enter the password for HTTP authentication.
IPP_ENCTYPE Optional
The encryption type can be set to either of the following:
IPP_ENCTYPE_NONE - no encryption (default)
IPP_ENCTYPE_SSL - use Secure Socket Layer
IPP_USE_FULL_URL Optional
Set to "true" to send the full URL for the HTTP request header. Valid values are "true" or "false" (default).
IPP_USE_CHUNKED_BODY Optional
Valid values are "true" (default) to use HTTP chunked transfer coding for the message body, or "false".
IPP_ATTRIBUTE_CHARSET Optional
Attribute character set of the IPP request. Default is "UTF-8".
IPP_NATURAL_LANGUAGE Optional
The natural language of the IPP request. Default is "en".
IPP_JOB_NAME Optional
Job name of the IPP request.
IPP_COPIES Optional
Define the number of copies to print (example: "1" , "5", "10"). Default is 1.
IPP_SIDES Optional
Enable two-sided printing. This setting will be ignored if the target printer does not support two-sided printing. Valid values are:
  • IPP_SIDES_ONE_SIDED - default

  • IPP_SIDES_TWO_SIDED_LONG_EDGE - prints both sides of paper for binding long edge.

  • IPP_SIDES_TWO_SIDED_SHORT_EDGE - prints both sides of paper for binding short edge.

  • IPP_SIDES_DUPLEX : Same as IPP_SIDES_TWO_SIDED_LONG_EDGE.

  • IPP_SIDES_TUMBLE : Same as IPP_SIDES_TWO_SIDED_SHORT_EDGE.

IPP_ORIENTATIONS Optional
Sets the paper orientation. This setting will be ignored if the target printer does not support orientation settings. Valid values are:
IPP_ORIENTATIONS_PORTRAIT (default)
IPP_ORIENTATIONS_LANDSCAPE
IPP_DOCUMENT_FORMAT Optional
The target printer must support the specified format. Valid values are:
IPP_DOCUMENT_FORMAT_POSTSCRIPT
IPP_DOCUMENT_FORMAT_PLAINTEXT
IPP_DOCUMENT_FORMAT_PDF
IPP_DOCUMENT_FORMAT_OCTETSTREAM (default)
IPP_MEDIA You can choose either the paper size or the tray number. If you do not specify this option, the default media of the target printer will be used. It will be ignored if the target printer doesn't support the media option. Valid values are:
  • IPP_MEDIA_TRAY1 : Media on tray 1

  • IPP_MEDIA_TRAY2 : Media on tray 2

  • IPP_MEDIA_TRAY3 : Media on tray 3

  • IPP_MEDIA_A3 : A3 Media

  • IPP_MEDIA_A4 : A4 Media

  • IPP_MEDIA_A5 : A5 Media

  • IPP_MEDIA_B4 : B4 Media

  • IPP_MEDIA_B5 : B5 Media

IPP_PAGE_RANGES Specify page ranges to print. By default, all pages are printed. Example valid values are:
  • "3" : prints only page 3.

  • "2-5" : prints pages 2-5.

  • "1,3-5" : print page 1 and 3-5.

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:

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

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

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 (ftp://ftp.metalab.unc.edu/pub/Linux/apps/serialcomm/fax/efax-0.9.tar.gz) and FAX4CUPS (http://vigna.dsi.unimi.it/fax4CUPS/).

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:

Property Description
IPP_PHONE_NUMBER Required
Enter the fax number.

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.

Property Description
WEBDAV_CONTENT_TYPE Required
Enter the document content type (example: "application/pdf").
WEBDAV_HOST Required
Enter the server host name.
WEBDAV_PORT Optional
Enter the server port number.
Default is 80.
WEBDAV_REMOTE_DIRECTORY Required.
Enter the remote directory name (example: "/myreports/").
WEBDAV_REMOTE_FILENAME Required.
Enter the remote file name.
WEBDAV_AUTHTYPE Optional
Valid values for authentication type are:
WEBDAV_AUTHTYPE_NONE - no authentication (default)
WEBDAV_AUTHTYPE_BASIC - use HTTP basic authentication
WEBDAV_AUTHTYPE_DIGEST - use HTTP digest authentication
WEBDAV_USERNAME Optional
Enter the username for HTTP authentication.
WEBDAV_PASSWORD Optional
Enter the password for HTTP authentication.
WEBDAV_ENCTYPE Optional
Valid values for encryption type are:
WEBDAV_ENCTYPE_NONE - no encryption (default)
WEBDAV_ENCTYPE_SSL - use Secure Socket Layer
WEBDAV_USE_FULL_URL Optional
Set to "true" to send the full URL for the HTTP request header. Valid values are "true" or "false" (default).
WEBDAV_USE_CHUNKED_BODY Optional
Valid values are "true" (default) to use HTTP chunked transfer coding for the message body, or "false".
WEBDAV_URL_CHARACTER_ENCODING Encoding of the URL. It will be used if you use non-ASCII characters in the URL. Set the Java-supported encoding string for the value.

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.

Property Description
FTP_HOST Required
Enter the server host name.
FTP_PORT Optional
Enter the server port number. Default is 21.
FTP_USERNAME Required
Enter the login user name to the FTP server.
FTP_PASSWORD Required
Enter the login password to the FTP server.
FTP_REMOTE_DIRECTORY Required
Enter the directory to which to deliver the document (example: /pub/)
FTP_REMOTE_FILENAME Required
Enter the document file name for the remote server.
FTP_BINARY_MODE Optional
Valid values are "true" (default) or "false".

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();
Property Description
SFTP_HOST Required
Enter the target server host name.
SFTP_PORT Optional
Enter the target server SSH port number. Default is 22.
SFTP_USERNAME Required
Enter the login user name.
SFTP_PASSWORD Required if you choose the SFTP_AUTH_TYPE_PASSWORD authentication type.
Enter the login password.
SFTP_REMOTE_DIRECTORY Enter the directory to which to deliver the document (example: /pub/). If no value is entered, the document will be delivered to the login directory.
SFTP_REMOTE_FILENAME Required
Enter the document file name on the remote server.
SFTP_AUTH_TYPE Set either of the following:
SFTP_AUTH_TYPE_PASSWORD (Default) Requires providing password at login.
SFTP_AUTH_TYPE_PUBLIC_KEY - public key authorization type.
SFTP_PRIVATE_KEY_FILE Enter the client private key file. Required if you choose SFTP_AUTH_TYPE_PUBLIC_KEY.
SFTP_PRIVATE_KEY_PASSWORD Enter the client private key password. Required if you choose SFTP_AUTH_TYPE_PUBLIC_KEY.
SFTP_FILE_PERMISSION Enter the permissions to set for the file being created. Default is 0755.

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.

Property Description
HTTP_METHOD Optional
Sets the HTTP request method. Valid values are:
HTTP_METHOD_POST (Default)
HTTP_METHOD_PUT
HTTP_CONTENT_TYPE Optional
The document content type (example: "application/pdf").
HTTP_HOST Required
Enter the server host name.
HTTP_PORT Optional
Enter the server port number. The default is 80.
HTTP_REMOTE_DIRECTORY Required
Enter the remote directory name (example: "/home/").
HTTP_REMOTE_FILENAME Required
Enter the file name to save the document as in the remote directory.
HTTP_AUTHTYPE Optional
Valid values for authentication type are:
HTTP_AUTHTYPE_NONE - no authentication (default)
HTTP_AUTHTYPE_BASIC - use basic HTTP authentication
HTTP_AUTHTYPE_DIGEST - use digest HTTP authentication
HTTP_USERNAME Optional
If the server requires authentication, enter the username.
HTTP_PASSWORD Optional
If the server requires authentication, enter the password for the username.
HTTP_ENCTYPE Optional
Enter the encryption type:
HTTP_ENCTYPE_NONE - no encryption (default)
HTTP_ENCTYPE_SSL - use Secure Socket Layer
HTTP_USE_FULL_URL Optional
Set to "true" to send the full URL for the HTTP request header. Valid values are "true" or "false" (default).
HTTP_USE_CHUNKED_BODY Optional
Valid values are "true" (default) to use HTTP chunked transfer coding for the message body, or "false".
HTTP_TIMEOUT Optional
Enter a length of time in milliseconds after which to terminate the request if a connection is not made to the HTTP server. The default is 60000 (1 minute).
HTTP_URL_CHARACTER_ENCODING Encoding of the URL. It will be used if you use non-ASCII characters in the URL. Set the Java-supported encoding string for the value.

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.

Property Description
AS2_FROM Required.
Enter the AS2 message sender.
AS2_TO Required.
Enter the AS2 message recipient.
AS2_SUBJECT Required.
Enter the message subject.
AS2_MESSAGE_COMPRESSION Default value is False. Enter True to compress the message.
AS2_MESSAGE_SIGNATURE Default value is False. Enter True to sign the message.
AS2_MESSAGE_ENCRYPTION Default value is False. Enter True to encrypt the message.
AS2_CONTENT_TYPE Required.
Enter the content type of the document. Valid values are:
  • application/EDIFACT

  • application/xml

AS2_ENC_ALGO The AS2 encryption algorithm. Set one of the following:
  • AS2_ENC_ALGO_RC2_40

  • AS2_ENC_ALGO_RC2_64

  • AS2_ENC_ALGO_RC2_128

  • AS2_ENC_ALGO_DES

  • AS2_ENC_ALGO_DES_EDE3 (Defau

  • AS2_ENC_ALGO_AES_128

  • AS2_ENC_ALGO_AES_192

  • AS2_ENC_ALGO_AES_256

AS2_DIGEST_ALGO Enter the AS2 digest algorithm for signing the messages. Set either of the following:
  • AS2_DIGEST_ALGO_MD5 (Default)

  • AS2_DIGEST_ALGO_SHA1

AS2_ASYNC_ADDRESS Enter the asynchronous address to which MDN notifications should be set.
AS2_ASYNC_EMAIL_SERVER_HOST Enter the email server host for asynchronous email MDN.
AS2_ASYNC_EMAIL_SERVER_PORT Enter the email server port for asynchronous email MDN.
AS2_ASYNC_EMAIL_SERVER_USERNAME Enter the email server USERNAME for asynchronous email MDN.
AS2_ASYNC_EMAIL_SERVER_PASSWORD Enter the email server PASSWORD for asynchronous email MDN.
AS2_ASYNC_EMAIL_SERVER_FOLDER_NAME Enter the IMAP folder name for aynchronous email MDN.
AS2_SENDER_PKCS12_FILE Location of the sender's PKCS12 (public/private key) file.
AS2_SENDER_PKCS12_PASSWORD Password for the sender's PKCS12 (public/private key).
AS2_RECEIVER_CERTIFICATES_FILE Location of the receiver's certificates file.
AS2_DELIVERY_RECEIPT_DIRECTORY Directory to store the delivery receipts. This directory must be specified if you wish to receive delivery receipts.
AS2_HTTP_HOST Required.
Enter the server host name.
AS2_HTTP_PORT Enter the server HTTP port number. The default is 80.
AS2_HTTP_REMOTE_DIRECTORY Required.
Enter the remote directory name. (Example: /home/)
AS2_HTTP_REMOTE_FILENAME Required.
Enter the remote file name.
AS2_HTTP_AUTHTYPE Enter the HTTP authentication type. Valid values are:
  • AS2_HTTP_AUTHTYPE_NONE - no authentication (Default)

  • AS2_HTTP_AUTHTYPE_BASIC - Use HTTP basic authentication.

  • AS2_HTTP_AUTHTYPE_DIGEST - user HTTP digest authentication.

AS2_HTTP_USERNAME Enter the username for HTTP authentication.
AS2_HTTP_PASSWORD Enter the password for HTTP authentication.
AS2_HTTP_ENCTYPE Set the encryption type. Valid values are:
  • AS2_HTTP_ENCTYPE_NONE - no encryption (default)

  • AS2_HTTP_ENCTYPE_SSL - use secure socket layer (SSL)

AS2_HTTP_TIMEOUT Enter the time out allowance in milliseconds. Default is 60,000 (1 minute)
AS2_HTTP_PROXY_HOST Required.
Enter the proxy server host name.
AS2_HTTP_PROXY_PORT Enter the proxy server port number. Default is 80.
AS2_HTTP_PROXY_AUTHTYPE
  • AS2_HTTP_AUTHTYPE_NONE - no authentication (Default)

  • AS2_HTTP_AUTHTYPE_BASIC - Use HTTP basic authentication.

  • AS2_HTTP_AUTHTYPE_DIGEST - user HTTP digest authentication.

AS2_HTTP_PROXY_USERNAME Enter the username for proxy authentication.
AS2_HTTP_PROXY_PASSWORD Enter the password for HTTP proxy authentication.

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:

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:

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:

Property Description
EXTERNAL_DELIVERY_COMMAND Required.
Enter the OS native command for delivery.

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:

Property Description
LOCAL_DESTINATION Required.
Full path to the destination file name in the local file system.

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:

The supported date expressions are:

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

IPP

WebDAV

FTP

HTTP

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:

Property Description
BUFFERING_MODE Valid values are "true" (default) and "false". See Direct and Buffering Modes for more information.
TEMP_DIR Define the location of the temporary directory.
CA_CERT_FILE Define the location of the CA Certificate file generated by Oracle Wallet Manager. This is used for SSL connection with the Oracle SSL library. If not specified, the default CA Certificates are used.
// 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:

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:

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:

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

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

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

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

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