Skip navigation links

Overview   Package  Class  Use  Tree  Deprecated  Index  Help 
Oracle Fusion Middleware Java API Reference for Oracle Business Intelligence Publisher
11g Release 1 (11.1.1)
E17789-02
 PREV PACKAGE   NEXT PACKAGE FRAMES    NO FRAMES    

Package oracle.xdo.delivery

BI Publisher Delivery API.

See:
          Description

Interface Summary
DeliveryPropertyDefinitions Delivery property definitions.
DeliveryRequest Delivery request internface.
DeliveryRequestFactory Delivery request factory interface.
DeliveryRequestHandler Delivery request handler interface.
DeliveryResponse Delivery response class.
DeliveryResponseListener Response callback interface mainly for asynchronus delivery requests.
DeliveryStatusDefinitions
DeliveryTypeDefinitions

 

Class Summary
AbstractDeliveryRequest Abstract implementation of the DeliveryRequest.
DeliveryComponent Sole class for delivery components.
DeliveryManager This class is the entry point to use the delivery system.
InvalidFactoryException
MissingRequiredPropertyException
UndefinedPropertyException
UndefinedRequestTypeException

 

Package oracle.xdo.delivery Description

BI Publisher Delivery API.

Deliver your documents

The Delivery API allows you to;

The basic flow to deliver the documents is following.

  1. Create DeliveryManager instance
  2. Create DeliveryRequest instance by createRequest() method
  3. Add request properties such as where to send to the DeliveryRequest. Most of properties require String value. See the supported properties of each delivery channel for more detail.
  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 is because it makes simple and easy to track down each delivery status and re-submit the request if it failed to deliver.

DeliveryRequest allows you to set the documents in 2 ways, these are;

The Delivery API supports a various kind of delivery channels. See following paragraphs how to send your documents through each delivery channel.

Deliver documents via Email

The sample code to deliver documents through Email is following.

   // 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, "myhost");
   // set the sender email address
   req.addProperty(DeliveryPropertyDefinitions.SMTP_FROM, "myname@example.org");
   // set the destination email address
   req.addProperty(
     DeliveryPropertyDefinitions.SMTP_TO_RECIPIENTS, "user1@example.org, user2@example.org" );
   // 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, "invoice.pdf");
   // set the document to deliver
   req.setDocument("/document/invoice.pdf");
 
   // submit the request
   req.submit();
   // close the request
   req.close();

Following properties are supported and defined in DeliveryPropertyDefinitons. Bold properties are mandatory. String value is required for each property unless there are no specific description.

Name Value
SMTP_TO_RECIPIENTS Recipients email address(es)
SMTP_CC_RECIPIENTS CC email address(es)
SMTP_BCC_RECIPIENTS BCC email address(es)
SMTP_FROM From email address
SMTP_REPLY_TO Reply-to email address
SMTP_SUBJECT Subject of the email.
SMTP_CHARACTER_ENCODING Email content encoding. Default is "UTF-8"
SMTP_ATTACHMENT Email attachment. Set Attachment object for the value.
SMTP_CONTENT_FILENAME Filename of the content, will be appeared on the email.
SMTP_CONTENT_TYPE Content type of the email.
SMTP_SMTP_HOST SMTP server host name.
SMTP_SMTP_PORT SMTP server port number. Default is 25
SMTP_SMTP_USERNAME SMTP server user name for SMTP authentication.
SMTP_SMTP_PASSWORD SMTP server password for SMTP authentication.
SMTP_ATTACHMENT_FIRST Set either "true" or "false"

Only this email delivery channel supports multiple documents and multiple destinations per request. You can set the multiple TO and CC address like following;

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

You can use oracle.apps.xdo.delivery.smtp.Attachment utility class to send multiple documents as attachments in one request. The sample usage is following.


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

   // add PDF attachment 
   m.addAttachment(
       "/pdf_doc/invoice.pdf",            // file to deliver
       "invoice.pdf",                     // file name appears in the 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);

     :
     :

You can use a String object for the email body. This may be useful if you want to describe the attachment files. The following sample code will deliver the email that has the message "Please find the attached invoice." in the email 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, "myhost");
   // set the sender email address
   req.addProperty(DeliveryPropertyDefinitions.SMTP_FROM, "myname@example.org");
   // set the destination email address
   req.addProperty(
     DeliveryPropertyDefinitions.SMTP_TO_RECIPIENTS, "user1@example.org, user2@example.org" );
   // 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();

     :
     :

You can use the HTML document for the email body. The sample usage is following.

It automatically resolves the local image references in your HTML document and attaches those images also.


   // 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, "myhost");
   // set the sender email address
   req.addProperty(DeliveryPropertyDefinitions.SMTP_FROM, "myname@example.org");
   // set the destination email address
   req.addProperty(
     DeliveryPropertyDefinitions.SMTP_TO_RECIPIENTS, "user1@example.org, user2@example.org" );

   // 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();

     :
     :

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

     :
   req.addProperty(DeliveryPropertyDefinitions.SMTP_USERNAME, "myname");
   req.addProperty(DeliveryPropertyDefinitions.SMTP_PASSWORD, "mypassword");
     :

Deliver your documents to printers

Internet Printing Protocol (IPP) is a standard printing protocol defined in RFC 2910 and 2911. The Delivery API supports IPP as a delivery channel so that you can deliver your documents to IPP supported printers or servers such as Common UNIX Printing System (CUPS) to print.

In order 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, the target printer is the Postscript printer, you need to have your document in the Postscript format. Usually, printers don't understand PDF, RTF, Excel or Word document format.

The Delivery API itself doesn't provide such document format transformation functionalities, but it offers the document filter support for this purpose. Please refer the "Document Filter Support" section for more detail.

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 faxes. CUPS is recommended to use because, unlike other IPP supported printers and servers, it can print out PDF documents. See http://www.cups.org/ for more detail.

The sample code is following.

  
     // 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();

Following properties are supported and defined in DeliveryPropertyDefinitons. Bold properties are mandatory. String value is required for each property unless there are no specific description. Note that printer specific properties such as IPP_SIDES, IPP_COPIES, IPP_ORIENTATIONS, IPP_MEDIA, IPP_PAGE_RANGES depend on printer's capability also. For example, if the target printer doesn't support two sided printing, IPP_SIDES setting won't work.

Name Value
IPP_HOST Server hostname
IPP_PORT Server port number. Default is 631
IPP_PRINTER_NAME IPP Printer name. Usually it is the same as the path part of the printer URL.
  • If you use the CUPS with the default setup, the printer name is /printers/<printer-name>
  • If you use the Microsoft Internet Information Service (IIS) with the default setup, the printer name is /printers/<printer-name>/.printer
IPP_AUTHTYPE HTTP authentication type. Set either of following Default is IPP_AUTHTYPE_NONE.
  • IPP_AUTHTYPE_NONE : No authentication
  • IPP_AUTHTYPE_BASIC : Using HTTP basic authentication
  • IPP_AUTHTYPE_DIGEST : Using HTTP digest authentication
IPP_USERNAME Username for HTTP authentication
IPP_PASSWORD Password for HTTP authentication
IPP_ENCTYPE Encryption type. Set either of following. Default is IPP_ENCTYPE_NONE.
  • IPP_ENCTYPE_NONE : No encryption
  • IPP_ENCTYPE_SSL : Use Secure Socket Layer (SSL)
IPP_USE_FULL_URL Use full URL for HTTP request header or not. Set either true or false. Default is false
IPP_USE_CHUNKED_BODY Use HTTP chunked message body or not. Set either true or false. Default is true
IPP_ATTRIBUTE_CHARSET Attribute character set of the IPP request. Default is 'UTF-8'.
IPP_NATURAL_LANGUAGE Natural language of the IPP request. Default is 'en'.
IPP_JOB_NAME Job name of the IPP request.
IPP_COPIES Number of copies. (ex: "1", "5", "10") Default is 1.
IPP_SIDES Two sided printing option. It will be ignored if the target printer doesn't support two sided printing. Set either of following. Default is 'IPP_SIDES_ONE_SIDED'
  • IPP_SIDES_ONE_SIDED : Print one side of papers.
  • IPP_SIDES_TWO_SIDED_LONG_EDGE : Print both side of papers for binding long edge.
  • IPP_SIDES_TWO_SIDED_SHORT_EDGE : Print both side of papers for binding short edge.
  • IPP_SIDES_DUPLEX : Same as IPP_SIDES_TWO_SIDED_LONG_EDGE.
  • IPP_SIDES_TUMBLE : Sane as IPP_SIDES_TWO_SIDED_SHORT_EDGE.
IPP_ORIENTATIONS Orientation option. It will be ignored if the target printer doesn't support orientation option. Set either of following. Default is 'ORIENTATIONS_PORTRAIT'.
  • IPP_ORIENTATIONS_PORTRAIT : The content will be imaged across the short edge of the paper.
  • IPP_ORIENTATIONS_LANDSCAPE : The content will be imaged across the long edge of the paper.
IPP_MEDIA Media option. You can choose either the paper size or the tray number. If you don't specify this option, the default media of the target printer will be used. It will be ignored if the target printer doesn't support orientation option. Set either of following.
  • IPP_MEDIA_TRAY1 : Media on tray1.
  • IPP_MEDIA_TRAY2 : Media on tray2.
  • IPP_MEDIA_TRAY3 : Media on tray3.
  • 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_DOCUMENT_FORMAT Document format. Set either of following. It will be ignored if the target printer doesn't support specified document format. Default is 'IPP_DOCUMENT_FORMAT_OCTETSTREAM'.
  • IPP_DOCUMENT_FORMAT_POSTSCRIPT
  • IPP_DOCUMENT_FORMAT_PLAINTEXT
  • IPP_DOCUMENT_FORMAT_PDF
  • IPP_DOCUMENT_FORMAT_OCTETSTREAM
IPP_PAGE_RANGES Page ranges to print. Examples are following.
  • "3" : only print page 3.
  • "2-5" : print page 2-5.
  • "1,3-5" : print page 1 and 3-5.
If you don't specify, all pages will be printed out by default.

If you want to deliver documents to IPP printers or faxes over the HTTP proxy server, you may sometimes encounter the delivery problems that are coming from difference of the HTTP implementation between CUPS and proxy servers. Setting 2 following properties can solve most of those problems.

If you use the CUPS with the default setup, the typical property settings are following.

If you use the Microsoft Internet Information Service (IIS) with the default setup, the typical property settings are following.

Deliver your documents to fax

The Delivery API supports to deliver documents to the fax modems configured on CUPS. You can configure the fax modems on CUPS with efax (http://www.cce.com/efax/) and FAX4CUPS (http://gongolo.usr.dsi.unimi.it/fax4CUPS/). By the default setting, CUPS can fax the document in Postscript and PDF document.

The sample code is following.

  
     // 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, "5550100");
     // set the document
     req.setDocument("/document/invoice.pdf");
 
     // submit the request
     req.submit();
     // close the request
     req.close();

Supported properties are the same as printer supports, plus following.

Name Value
IPP_PHONE_NUMBER Phone number of the fax destination

Deliver your documents to WebDAV servers

The Delivery API supports to deliver documents to the WebDAV servers. The sample code is following.

  
     // 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, "myhost");
     // 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, "test.pdf");
  
     // set username and password to access WebDAV server
     req.addProperty(DeliveryPropertyDefinitions.WEBDAV_USERNAME, "myname");
     req.addProperty(DeliveryPropertyDefinitions.WEBDAV_PASSWORD, "mypassword");
     // set the document
     req.setDocument("/document/test.pdf");
 
     // submit the request
     req.submit();
     // close the request
     req.close();

Following properties are supported and defined in DeliveryPropertyDefinitons. Bold properties are mandatory. String value is required for each property unless there are no specific description.

Name Value
WEBDAV_CONTENT_TYPE Document content type.
WEBDAV_HOST Server hostname
WEBDAV_PORT Server port number. Default is 80
WEBDAV_REMOTE_DIRECTORY Remote directory name. (ex. /home/)
WEBDAV_REMOTE_FILENAME Document file name on remote.
WEBDAV_AUTHTYPE HTTP authentication type. Set either of following Default is WEBDAV_AUTHTYPE_NONE.
  • WEBDAV_AUTHTYPE_NONE : No authentication
  • WEBDAV_AUTHTYPE_BASIC : Using HTTP basic authentication
  • WEBDAV_AUTHTYPE_DIGEST : Using HTTP digest authentication
WEBDAV_USERNAME Username for HTTP authentication
WEBDAV_PASSWORD Password for HTTP authentication
WEBDAV_ENCTYPE Encryption type. Set either of following. Default is WEBDAV_ENCTYPE_NONE.
  • WEBDAV_ENCTYPE_NONE : No encryption
  • WEBDAV_ENCTYPE_SSL : Use Secure Socket Layer (SSL)
WEBDAV_USE_FULL_URL Use full URL for HTTP request header or not. Set either true or false. Default is false
WEBDAV_USE_CHUNKED_BODY Use HTTP chunked message body or not. Set either true or false. Default is true
WEBDAV_URL_CHARACTER_ENCODING Encoding of the URL. It will be used if you use non-ASCII characters for URL. Set the Java supported encoding string for value.

Deliver your documents to FTP servers

The Delivery API supports to deliver documents to the FTP servers. The sample code is following.

  
     // 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, "myhost");
     // 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, "myname");
     req.addProperty(DeliveryPropertyDefinitions.FTP_PASSWORD, "mypassword");
     // 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();

Following properties are supported and defined in DeliveryPropertyDefinitons. Bold properties are mandatory. String value is required for each property unless there are no specific description.

Name Value
FTP_HOST Server hostname.
FTP_PORT Server port number. Default is 21.
FTP_USERNAME Login user name to the FTP server
FTP_PASSWORD Login passsword to the FTP server
FTP_REMOTE_DIRECTORY Remote directory name. (ex. /pub/)
FTP_REMOTE_FILENAME Document file name on remote.
FTP_BINARY_MODE Transfer binary mode. Set either 'true' or 'false'. Default is 'true'.

Deliver your documents through HTTP

The Delivery API supports to deliver documents to the HTTP servers. The following sample is sending a document through HTTP POST method. Technically, you can send not only documents, but also anything you want. But the servers should be capable to accept your custom HTTP requests in advance, such as your 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();

Following properties are supported and defined in DeliveryPropertyDefinitons. Bold properties are mandatory. String value is required for each property unless there are no specific description.

Name Value
HTTP_METHOD HTTP request method. Set one of following. Default is POST.
  • HTTP_METHOD_POST
  • HTTP_METHOD_PUT
HTTP_CONTENT_TYPE Document content type
HTTP_HOST Server host name.
HTTP_PORT Server port number. Default is 80.
HTTP_REMOTE_DIRECTORY Remote directory name. (ex. /home/)
HTTP_REMOTE_FILENAME Remote file name.
HTTP_AUTHTYPE HTTP authentication type. Set either of following Default is HTTP_AUTHTYPE_NONE.
  • HTTP_AUTHTYPE_NONE : No authentication
  • HTTP_AUTHTYPE_BASIC : Using HTTP basic authentication
  • HTTP_AUTHTYPE_DIGEST : Using HTTP digest authentication
HTTP_USERNAME Username for HTTP authentication
HTTP_PASSWORD Password for HTTP authentication
HTTP_ENCTYPE Encryption type. Set either of following. Default is IPP_ENCTYPE_NONE.
  • HTTP_ENCTYPE_NONE : No encryption
  • HTTP_ENCTYPE_SSL : Use Secure Socket Layer (SSL)
HTTP_USE_FULL_URL Use full URL for HTTP request header or not. Set either true or false. Default is false.
HTTP_USE_CHUNKED_BODY Use HTTP chunked message body or not. Set either true or false. Default is false.
HTTP_TIMEOUT Time out in millisecond. Default is 60000. (1min)
HTTP_URL_CHARACTER_ENCODING Encoding of the URL. It will be used if you use non-ASCII characters for URL. Set the Java supported encoding string for value.

Deliver your documents to Secure FTP servers

Secure FTP (SFTP) is the protocol based on the Secure Shell technology (ssh) and it is widely used to transfer the 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 website (http://www.ietf.org). The delivery system supports to deliver documents to the secure FTP servers. The sample code is following.

  
     // 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, "myhost");
     // 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();

Following properties are supported and defined in DeliveryPropertyDefinitons. Bold properties are mandatory. String value is required for each property unless there are no specific description.

Name Description Default value
SFTP_HOST Target server host name (None)
SFTP_PORT Target server SSH port number 22
SFTP_USERNAME Login username (None)
SFTP_PASSWORD Login passsword (Mandatory if you choose SFTP_AUTH_TYPE_PASSWORD auth type.) (None)
SFTP_REMOTE_DIRECTORY Remote directory name where the document will be delivered to (ex. /pub/) / (login directory)
SFTP_REMOTE_FILENAME Remote filename of the document. (None)
SFTP_AUTH_TYPE Authentication type. Set either of following.
  • SFTP_AUTH_TYPE_PASSWORD : Password auth type
  • SFTP_AUTH_TYPE_PUBILC_KEY : Public key auth type
 SFTP_AUTH_TYPE_PASSWORD
SFTP_PRIVATE_KEY_FILE Client private key file (Mandatory if you choose SFTP_AUTH_TYPE_PUBLIC_KEY auth type.) (None)
SFTP_PRIVATE_KEY_PASSWORD Client private key password (Mandatory if you choose SFTP_AUTH_TYPE_PUBLIC_KEY auth type.) (None)
SFTP_FILE_PERMISSION Permissions for the file being created 0755

Authentication mode

This secure FTP delivery supports 2 authentication modes, password authentication and public key authentication. You can set the property SFTP_AUTH_TYPE to choose the mode. The default is password authentiaction.

The password authentication mode requires the username and password to login the secure FTP server. Sample code is following.

         :
         :
     // 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 authentication mode requires the username, your private key and password for the private key. This is more secure to connect to the server than the password authentication. Note that in order to use the public key authentication mode, you need to setup your public key in the ssh/secure FTP server in advance. Sample code is following.

         :
         :
      // 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");         
         :
         :

Deliver your documents with 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 designed to exchange the data over the internet in a secure manner. AS2 specification is defined in RFC4130. The delivery system supports to deliver documents to AS2 servers. The sample code is following.

  

    // 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_REQUIRE_RECEIPT, "true");
 
    // set HTTP properties
    req.addProperty(DeliveryPropertyDefinitions.AS2_CONTENT_TYPE, "applications/EDIFACT");
    req.addProperty(DeliveryPropertyDefinitions.AS2_HTTP_HOST, "myhost");
    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();

    // show the delivery receipt returned by AS2 server to the system out.
    System.out.println(new String(res.getBody());

Following properties are supported and defined in DeliveryPropertyDefinitons. Bold properties are mandatory. String value is required for each property unless there are no specific description.

Name Description Default value
AS2_FROM AS2 message sender (None)
AS2_TO AS2 message recipient (None)
AS2_SUBJECT AS2 message subject (None)
AS2_CONTENT_TYPE Content type of the document. Usually, it will be either "application/EDIFACT" or "application/xml". (None)
AS2_MESSAGE_COMPRESSION Compress the message or not. false
AS2_MESSAGE_SIGNATURE Sign the message or not. false
AS2_MESSAGE_ENCRYPTION Encrypt the message or not. false
AS2_ASYNC_ADDRESS Asynchronous address to which delivery receipt should be send (None)
AS2_SENDER_PKCS12_FILE Location of the sender's PKCS12 (public/private key) file (None)
AS2_SENDER_PKCS12_PASSWORD Password for the sender's PKCS12 (public/private key) (None)
AS2_RECEIVER_CERTIFICATES_FILE Location of the receiver's certificates file (None)
AS2_HTTP_HOST Server host name. (None)
AS2_HTTP_PORT Server HTTP port number. 80
AS2_HTTP_REMOTE_DIRECTORY Remote directory name. (ex. /home/) (None)
AS2_HTTP_REMOTE_FILENAME Remote file name. (None)
AS2_HTTP_AUTHTYPE HTTP authentication type. Set either of following.
  • AS2_HTTP_AUTHTYPE_NONE : No authentication
  • AS2_HTTP_AUTHTYPE_BASIC : Using HTTP basic authentication
  • AS2_HTTP_AUTHTYPE_DIGEST : Using HTTP digest authentication
 AS2_HTTP_AUTHTYPE_NONE
AS2_HTTP_USERNAME Username for HTTP authentication (None)
AS2_HTTP_PASSWORD Password for HTTP authentication (None)
AS2_HTTP_ENCTYPE Encryption type. Set either of following.
  • AS2_HTTP_ENCTYPE_NONE : No encryption
  • AS2_HTTP_ENCTYPE_SSL : Use Secure Socket Layer (SSL)
 AS2_HTTP_ENCTYPE_NONE
AS2_HTTP_TIMEOUT Time out in millisecond 60000 (1 min)
AS2_HTTP_PROXY_HOST Proxy server host name. (None)
AS2_HTTP_PROXY_PORT Proxy server port number. 80
AS2_HTTP_PROXY_AUTHTYPE Proxy server HTTP authentication type. Set either of following.
  • AS2_HTTP_AUTHTYPE_NONE : No authentication
  • AS2_HTTP_AUTHTYPE_BASIC : Using HTTP basic authentication
  • AS2_HTTP_AUTHTYPE_DIGEST : Using HTTP digest authentication
 AS2_HTTP_AUTHTYPE_NONE
AS2_HTTP_PROXY_USERNAME Username for HTTP proxy authentication (None)
AS2_HTTP_PROXY_PASSWORD Password for HTTP proxy authentication (None)
AS2_REQUIRE_RECEIPT Require receipt(MDN) or not false

Delivery Receipt

If you need the delivery receipt (MDN) for your request, you can set the AS2_REQUIRE_RECEIPT property to "true". The sample code is following.

         :
         :
 // Require delivery receipt.
 req.addProperty(DeliveryPropertyDefinitions.AS2_REQUIRE_RECEIPT, "true");
         :
         :

You can retrieve the receipt from the delivery response. The sample code is following.

         :
         :
 // submit the request
 DeliveryResponse res = req.submit();

 // show the delivery receipt returned by AS2 server to the system out.
 System.out.println(new String(res.getBody());
         :
         :

Asynchronus Request

The AS2 protocol allows both synchronus and asynchronus requests, and the Delivery API supports both type of requests. If you don't specify explicitly, the request will be the synchronus request.

If you set the AS2_ASYNC_ADDRESS to your request, the request will be asynchronus. You can specify either HTTP URL or email address where the delivery receipt will be delivered to after the processing. You are responsible for setting up the HTTP server or email address to receive those delivery receipts.

Document signing

The Delivery API allows you to sign the documents for the secure transaction. This is based on the public key architecture, so you need to setup followings in both sernder side(your side) and receiver side(AS2 server side).

The sender side (your side) must have sender's public/private keys in a PKCS12 standard file. The file extension is .p12. You can locate that file in your local system where you want to run the Delivery API.

The receiver side(AS2 Server) must have sender's public key certificate. The way how to install certificates in the AS2 server differs from server to server. Generally, it involves copying the .der or .cer certificates in a particular location. Please consult the manual of your AS2 server for the exact procedure.

Once you have done the setup, you can sign your document by setting properties to the delivery request. The sample code is following.

        :
        :
 // 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, "mypassword");
        :
        :

Document encryption

The Delivery API allows you to encrypt the documents for the secure transaction. This is based on the public key architecture, so you need to setup followings in both sernder side(your side) and receiver side(AS2 server side).

The sender side (your side) must have receiver's public key certificate file. The file extension is .der or .cer. You can locate 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 how to obtain the AS2 server's public key certificate.

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

Once you have done the setup, you can encrypt your document by setting properties to the delivery request. The sample code is following.

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

Deliver your documents with the external command

The Delivery API supports to deliver documents with any of the external, Operating system(OS) native command you want to use.

You can specify any of OS native command with the {file} placeholder At runtime, this place holder will be replaced with the document filename.

The delivery status is judged by the exit value of the OS command. If the value is '0', the request will be marked as successful.

The sample code is following.

  
     // 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(DeliveryPropertyDefinitions.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();

Following properties are supported and defined in DeliveryPropertyDefinitons. Bold properties are mandatory.

Name Value
EXTERNAL_DELIVERY_COMMAND OS native command for delivery.

Deliver your documents to the local filesystem

The Delivery API supports to deliver documents to the local filesystem where the Delivery API runs. It is like copying a file. The sample code following 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(DeliveryPropertyDefinitions.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();

Following properties are supported and defined in DeliveryPropertyDefinitons. Bold properties are mandatory.

Name Value
LOCAL_DESTINATION Full path to the destination filename in the local filesystem.

Direct/Buffering mode

The Delivery API supports 2 document sending modes, direct mode and buffering mode.

The direct mode offers you the 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 so it is good for online, interactive processing. This mode doesn't offer the document re-delivery since it's fully streamlined, so you need to provide documents again if you need to re-deliver documents. If you need the document re-delivery, use the buffering mode. You can specify the direct mode by setting the buffering mode to off. The sample code is following.

  
     // 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");
           :
           :
           :

The buffering mode offers you to re-deliver documents as many times as you want. The Delivery API internally uses temporary files to buffer documents if you specify TEMP_DIR, or uses temporary memory buffer if you don't specify it. We encourage you to set the TEMP_DIR property because the temporary memory buffer consumes a lot of memory speces. You can explicitly clear the temporary file/buffer by calling DeliveryRequest.close() after finishing your delivery request. The sample code is following.

  
     // 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();

The default mode is the buffering mode.

Asynchronous Delivery Requests

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

You can create your own callback logic by implementing the DeliveryResponseListener interface. There is only 1 method called resposeReceived() to implement. You can implement your logic in this method so that it will be called when the delivery request is finished. The sample code is following. It just shows some text to standard output when the request is done.

  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. The sample code is following.

  
    // 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 the each delivery request. To specify the filter, you can just pass the native OS command string with the 2 placeholders for the input and output filename, {infile} and {outfile}. You can set your filter to your delivery request as a delivery property. Samples are following.

     // 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. 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, unlike CUPS, those printers usually do not accept PDF documents, but only accept only limited document formats. With this functionality, you can call any of the native OS command 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 the Linux, you can set the 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 this functionality works only if the buffering mode is on and the valid temporary directory is specified.

Date expression support

You can use the date expressions for a couple of properties. Those expressions will be translated with the actual values just before the delivery. Available expression are following.

For example, if you specify my_file_%y%m%d.txt for the filename, the actual filename will be like my_file_20051108.txt. All undefined expressions will show up as is, for example, if you specify my_file_%a%b%c.txt, it will be my_file_%a%b%c.txt.

The properties that support the date expressions are following.

Internationalization

The Delivery Server API supports internationalization. Following internationalization features are supported in each delivery channel.

SMTP

IPP

WebDAV

FTP

HTTP

Global properties

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

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

     // set global properties 
     dm.addProperty(DeliveryPropertyDefinitions.SYSTEM_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);
           :
           :

Following global properties are supported. Bold properties are mandatory. String value is required for each property unless there are no specific description.

Adding your custom delivery channel

Additional to the delivery channels provided by default, you can add your own delivery channels to the system. The steps to add the custom delivery channels are following.

  1. Define delivery properties
  2. Implement DeliveryRequest interface
  3. Implement DeliveryRequestHandler interface
  4. Implement DeliveryRequestFactory interface
  5. Register your custom DeliveryRequestFactory to DeliveryManager

See following paragraphs for details how to create custom delivery channels with the sample delivery channel called "File delivery channel" that delivers documents to the local filesystem. It is just like copying files.

Define delivery properties

The first step to add custom delivery channel is to define the properties. You can define constants for those properties. File delivery channel requires only one property that tells "where to go". The sample code is following.

package oracle.apps.xdo.delivery.file;

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

}

Technically, the value of each constant can be anything as long as it is String. But we recommend you to define the value in [property name]:[property value type] format so that the Delivery API automatically validate the property value at runtime. In this sample, we define FILE_DESTINATION property that will have the String value.

Implement DeliveryRequest interface

DeliveryRequest represents a delivery request that includes documents information to deliver, and delivery meta data such as destinations and other properties for delivery. You need to implement oracle.apps.xdo.delivery.DeliveryRequest, but, fortunately, oracle.apps.xdo.delivery.AbstractDeliveryRequest covers most of generic things you need so you can just extend the class and define the your delivery channel specific features.

Sample implementation of DeliveryRequest for the File delivery channel is following.

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 is responsible for handling delivery requests. It actually includes the logic to deliver. You need to implement oracle.apps.xdo.delivery.DeliveryRequestHandler interface.

Sample implementation of DeliveryRequestHandler for the File delivery channel is following.

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.InputStream;
import java.io.OutputStream;

import oracle.apps.fnd.common.VersionInfo;
import oracle.apps.xdo.delivery.DeliveryException;
import oracle.apps.xdo.delivery.DeliveryPropertyDefinitions;
import oracle.apps.xdo.delivery.DeliveryRequest;
import oracle.apps.xdo.delivery.DeliveryRequestHandler;
import oracle.apps.xdo.delivery.DeliveryStatusDefinitions;
/**
 * Implementation of the file delivery channel. 
 * It delivers a certain file to the other place in the local file system.
 * 
 */
public class FileDeliveryRequestHandler implements DeliveryRequestHandler
{
  /**
   * default constructor.
   */ 
  public FileDeliveryRequestHandler()
  {
  }

  /**
   * Submits the request.
   */
  public void submitRequest(DeliveryRequest pRequest) throws DeliveryException
  {

    FileDeliveryRequest request = (FileDeliveryRequest)pRequest;
    OutputStream out = null;
    InputStream in = null;
    try
    {
      // Open the destination file.
      String filename =
        request.getStringProperty(FileDeliveryRequest.FILE_DESTINATION);
      out = new BufferedOutputStream(new FileOutputStream(filename));

      // Obtain the document content to deliver. 
      // You can obtain the InputStream of the document content to deliver 
      // by getting DeliveryPropertyDefinitions.CONTENT property. 
      in = (InputStream)request.getProperty(DeliveryPropertyDefinitions.CONTENT);
      
      // Write (deliver) the document content to the destination file.
      byte[] buf = new byte[8192];
      int len = 0;
      while((len = in.read(buf))!= -1)
      {
        out.write(buf, 0, len);
      }
      
      // Closing the destination file.
      out.flush();
      out.close();
      // Set request status
      request.setStatus(DeliveryStatusDefinitions.STATUS_SUCCESSFUL);

    }
    catch (IOException e)
    {
      request.setStatus(DeliveryStatusDefinitions.STATUS_FAILED_CLIENT_ERROR);
      throw new DeliveryException(e);
    }
    finally
    {
      try
      {
        out.close();
      }
      catch(Exception e)
      {
        
      }
      finally
      {
        out = null;
        in = null;
      }
    }
  }
  /**
   * Updates the request status.
   */
  public void updateRequestStatus(DeliveryRequest pRequest)
      throws DeliveryException
  {
    FileDeliveryRequest request = (FileDeliveryRequest)pRequest;

    // check if the file is successfully delivered or not
    // by checking whether the file exists or not.
    String filename =
      (String) request.getProperty(FileDeliveryRequest.FILE_DESTINATION);
    File f = new File(filename);
    if (f.exists())
      request.setStatus(DeliveryStatusDefinitions.STATUS_SUCCESSFUL);
    else
      request.setStatus(DeliveryStatusDefinitions.STATUS_FAILED_IO_ERROR);

  }

}

Implement DeliveryRequestFactory interface

DeliveryRequestFactory is required to register your custom delivery channel to the Delivery API. You need to implement oracle.apps.xdo.delivery.DeliveryRequestFactory interface.

Sample implementation of DeliveryRequestFactory for the File delivery channel is following.

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 API. You can register your delivery channel in 2 ways, in a static way and a dynamic way. The static way offers you to register your delivery channel to the whole Delivery API by specifying it in the configuration file. Please refer the configuration file section for more detail. The dynamic way offers you to register your delivery channel to the Java VM instance by calling the register API programatically. Sample code to register the File delivery channel in a dynamic way and call the File delivery channel is following.

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 API supports configuration file for setting the default servers, default properties and custom delivery channels. The location of the configuration file is {XDO_TOP}/resource/xdodelivery.cfg. The {XDO_TOP} is a Java system property that points to the actual physical directory You need to set this system property by either passing -DXDO_TOP=/path/to/xdotop to the java startup parameter or setting through the Java API in your code like java.lang.System.getProperties().put("XDO_TOP", "/path/to/xdotop"). This system property should be defined before constructing DeliveryManager object. The sample configuration file is following.

  
 <?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.example.org:631/printers/myprinter1</uri>

     </server>
     <server name="myprinter2" type="ipp_printer" >
       <host>myprinter2.example.org</host>
       <port>631</port>

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

     </server>
     <server name="myfax1" type="ipp_fax" default="true" >
       <host>myfax1.example.org</host>

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

       <host>myprinter1.example.org</host>
       <port>25</port>
     </server>
     <server name="mysmtp2" type="smtp_email" >

       <host>mysmtp12.example.org</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>

You can define multiple server entries for each delivery channel. For example, the sample configuration file above has 2 server entries ("myprinter1" and "myprinter2") for "ipp_printer" delivery channel. You can load the one of server entries for each delivery request by calling DeliveryReqeust.setServer() method. The sample code is following.

  
     // 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");

You can also define a default server entry for each delivery channel by specifying default="true". In this case, "myprinter1" is marked as a default server for "ipp_printer" delivery channel. If users don't specify the server properties for "ipp_printer" delivery, server properties under the default server will be used.

List of available elements are following.

Skip navigation links

Overview   Package  Class  Use  Tree  Deprecated  Index  Help 
Oracle Fusion Middleware Java API Reference for Oracle Business Intelligence Publisher
11g Release 1 (11.1.1)
E17789-02
 PREV PACKAGE   NEXT PACKAGE FRAMES    NO FRAMES    

Copyright © 2010, 2011, Oracle. All rights reserved.