| Oracle® Fusion Middleware Developer's Guide for Oracle Business Intelligence Publisher (Oracle Fusion Applications Edition) 11g Release 1 (11.1.1) Part Number E20838-01 |
|
|
View PDF |
| Oracle® Fusion Middleware Developer's Guide for Oracle Business Intelligence Publisher (Oracle Fusion Applications Edition) 11g Release 1 (11.1.1) Part Number E20838-01 |
|
|
View PDF |
This chapter contains the following sections for the Delivery Manager Java APIs:
Section 8.6, "Delivering Your Documents to a RightFax Server"
Section 8.8, "Delivering Your Document over the File Transfer Protocol (FTP)"
Section 8.10, "Delivering Your Documents over Hypertext Transfer Protocol (HTTP)"
Section 8.12, "Delivering Documents Using an External Command"
Section 8.13, "Delivering Documents to the Local File System"
The Delivery Manager is a set of Java APIs that enables you to control the delivery of your BI Publisher documents. Use the Delivery Manager to:
Deliver documents through established or custom delivery channels
Redeliver documents
To use the Delivery Manager follow these steps:
Create a DeliveryManager instance.
Create a DeliveryRequest instance using the createRequest() method.
Add the request properties (such as DeliveryRequest destination). Most properties require a String value. For more information, see the supported properties for each delivery channel.
Set your document to the DeliveryRequest.
Call submit() to submit the delivery request.
One delivery request can handle one document and one destination. This facilitates monitoring and resubmitting, if necessary.
DeliveryRequest enables you to set documents in the following two ways:
Set InputStream of the document to DeliveryRequest. The DeliveryRequest will read the InputStream when you call submit()for the first time. The DeliveryRequest does not close the InputStream so you must ensure to close it.
Set the file name of the document to DeliveryRequest.
The Delivery Manager supports streamlined delivery when you set the direct mode. See Section 8.14, "Direct and Buffering Modes."
The follow delivery channels are described in this document:
Printer
Local Printer
Fax
RightFax
WebDAV
FTP
Secure FTP
HTTP
AS2
The following sample demonstrates delivery through e-mail:
Example 8-1 Sample Code for Delivering Documents through 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:
Table 8-1 Properties for E-Mail Delivery
| 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 |
Optional Enter the file name of the attachment (example: invoice.pdf) |
|
SMTP_CONTENT_DISPOSITION |
Content disposition of the attachment. Value should be either "inline" or "attachment". Default is "attachment". |
|
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_SECURE_CONNECTION |
This property controls secure connection method to use. Valid values are:
|
|
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". |
The e-mail delivery server channel supports multiple documents and multiple destinations per request. The following example demonstrates multiple TO and CC addresses:
Example 8-2 Sample Code for Defining Multiple Recipients
// 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");
Use the Attachment utility class (oracle.apps.xdo.delivery.smtp.Attachment) to attach multiple documents into one request. Sample usage is as follows:
Example 8-3 Sample Code for Attaching Multiple Documents to One Request
:
:
// 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);
:
:
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:
If you want to show your attachment at the top of an e-mail, set the property SMTP_ATTACHMENT_FIRST to "true". Sample usage is as follows.
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.
Example 8-6 Sample Code for Using a String Object as the E-Mail Body
// 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();
:
:
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.
Sample usage is as follows:
Example 8-7 Sample Code for Using an HTML Document as the E-Mail Body
// 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();
:
:
The Delivery Manager 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.
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 Section 8.16, "Document Filter Support."
Following is a code sample for delivery to a printer:
Example 8-9 Sample Code for Delivering Documents 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.
Table 8-2 Properties for Delivering Documents to Printers
| 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.
|
|
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_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_PAGE_RANGES |
Specify page ranges to print. By default, all pages are printed. Example valid values are:
|
To deliver documents to IPP printers or fax machines over an HTTP proxy server, you may encounter delivery problems due to differences in the HTTP implementations between CUPS and the proxy servers. Setting the following two properties can resolve most of these problems:
DeliveryPropertyDefinitions.IPP_USE_FULL_URL - set to "true"
DeliveryPropertyDefinitions.IPP_USE_CHUNKED_BODY - set to "false"
If you use CUPS with the default setup, the typical property settings are as follows:
IPP_HOST : <host-name>
IPP_PORT : 631
IPP_PRINTER_NAME : /printers/<printer-name>
If you use the Microsoft Internet Information Service (IIS) with the default setup, the typical property settings are as follows:
IPP_HOST : <host-name>
IPP_PORT : 80
IPP_PRINTER_NAME : /printers/<printer-name>/.printer
The Delivery Manager supports delivery of documents to "local" printers attached to the system where the Delivery Manager runs.
Following is a code sample for delivery to a local printer.
Example 8-10 Sample Code for Delivering Documents to a Local Printer
// create delivery manager instance
DeliveryManager dm = new DeliveryManager();
// create a delivery request
DeliveryRequest req = dm.createRequest(DeliveryManager.TYPE_PRINTER);
// set target printer name as HOST - if no HOST is set default printer is used
//req.addProperty(PRINTER_HOST, "PrinterName");
// set cotnent type – the content type must be supported by the printer
req.addProperty(CONTENT_TYPE, CONTENT_TYPE_POSTSCRIPT);
// set the document
req.setDocument("/document/invoice.ps");
// submit the request
req.submit();
// close the request
req.close();
The following table lists the supported properties. Note that support of printer-specific properties such as PRINTER_SIDES, PRINTER_COPIES, PRINTER_MEDIA, PRINTER_ORIENTATION, PRINTER_PAGE_RANGES and PRINTER_SIDES depends on the printer and local printing system's capabilities. For example, on Windows, these properties are ignored unless a you also use a filter that supports adding these properties to your document.
Table 8-3 Properties for Delivering Documents to Local Printers
| Property | Description |
|---|---|
|
PRINTER_CONTENT_TYPE |
Optional The document content type (example: "application/pdf"). |
|
PRINTER_COPIES |
Optional Specify the number of copies to print (example: "1", "5", "10"). Default is 1. |
|
PRINTER_HOST |
Optional Printer name (name of the printer on the operating system or local printing system) to send the documents to. If HOST is not specified, the default local printer is used. |
|
PRINTER_MEDIA |
Optional 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:
|
|
PRINTER_ORIENTATIONS |
Optional Sets the paper orientation. This setting will be ignored if the target printer does not support orientation settings. Valid values are: PRINTER_ORIENTATIONS_PORTRAIT (default) PRINTER_ORIENTATIONS_LANDSCAPE |
|
PRINTER_PAGE_RANGES |
Specify page ranges to print. By default, all pages are printed. Example valid values are:
|
|
PRINTER_SIDES |
Optional Enable two-sided printing. This setting will be ignored if the target printer does not support two-sided printing. Valid values are:
|
The delivery manager supports the delivery of documents to fax modems configured on CUPS. You can configure fax modems on CUPS with efax (http://www.cce.com/efax/) and FAX4CUPS (http://www.gnu.org/directory/productivity/special/fax4CUPS.html).
Sample code for fax delivery is as follows:
Example 8-11 Sample Code for Delivering Documents to a Fax Server
// 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:
The Delivery Manager supports the delivery of documents to OpenText Fax Server, RightFax Edition (formerly Captaris RightFax) 9.3 or above. The XML interface on HTTP port must be enabled on RightFax server to enable this integration.
Following is a code sample for delivery to RightFax server:
Example 8-12 Sample Code for Delivering Documents to a RightFax Server
// create delivery manager instance
DeliveryManager dm = new DeliveryManager();
// create a delivery request
DeliveryRequest req = dm.createRequest(DeliveryManager.TYPE_RIGHTFAX);
// set RightFax host
req.addProperty(DeliveryPropertyDefinitions.RIGHTFAX_HTTP_HOST, "myhost");
// set RightFax server port
req.addProperty(DeliveryPropertyDefinitions.RIGHTFAX_HTTP_PORT, "80");
// set the target remote directory
req.addProperty(DeliveryPropertyDefinitions.RIGHTFAX_HTTP_REMOTE_DIRECTORY, "/RFWebCon.dll");
// sender information
req.addProperty(DeliveryPropertyDefinitions.RIGHTFAX_SENDER_NAME, "Lex De Hann");
req.addProperty(DeliveryPropertyDefinitions.RIGHTFAX_SENDER_COMPANY, "Company, Ltd.");
req.addproperty(DeliveryPropertyDefinitions.RIGHTFAX_SENDER_PHONE", "555-9976");
// destionation
req.addProperty(DeliveryPropertyDefinitions.RIGHTFAX_TO_FAXNUM, "555-1111");
req.addProperty(DeliveryPropertyDefinitions.RIGHTFAX_TO_NAME, "Jane Bennett");
req.addProperty(DeliveryPropertyDefinitions.RIGHTFAX_TO_COMPANY, "Acme, Inc.");
// set the document
req.setDocument("/document/invoice.pdf");
// submit the request
req.submit();
// close the request
req.close();
The following table lists the supported properties:
Table 8-5 Properties for Delivering Documents to RightFax Servers
| Property | Description |
|---|---|
|
RIGHTFAX_HTTP_HOST |
Required HTTP host of the RightFax server |
|
RIGHTFAX_HTTP_PORT |
Optional HTTP port of the RightFax server. Default=80. |
|
RIGHTFAX_HTTP_REMOTE_DIRECTORY |
Optional Enter the remote directory name (example: /RFWebCon.dll) of the RightFax XML interface. |
|
RIGHTFAX_HTTP_AUTHTYPE |
Optional HTTP authentication type of the RightFax server URL. Valid values are RIGHTFAX_HTTP_AUTHTYPE_NONE, RIGHTFAX_HTTP_AUTHTYPE_BASIC, RIGHTFAX_HTTP_AUTHTYPE_DIGEST. Default value is RIGHTFAX_AUTHTYPE_NONE. |
|
RIGHTFAX_HTTP_USERNAME |
Optional HTTP username for the RightFax server url. Required when RIGHTFAX_HTTP_AUTH_TYPE is set to values other than RIGHTFAX_HTTP_AUTHTYPE_NONE. |
|
RIGHTFAX_HTTP_PASSWORD |
Optional HTTP password for the RightFax server url. Required when RIGHTFAX_HTTP_AUTH_TYPE is set to values other than RIGHTFAX_HTTP_AUTHTYPE_NONE. |
|
RIGHTFAX_HTTP_ENCTYPE |
Optional The encryption type can be set to either of the following: RIGHTFAX_HTTP_ENCTYPE_NONE – no encryption (default) RIGHTFAX_HTTP_ENCTYPE_SSL – use Secure Socket Layer |
|
RIGHTFAX_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). |
|
RIGHTFAX_HTTP_USE_CHUNKED_BODY |
Optional Valid values are "true" (default) to use HTTP chunked transfer coding for the message body, or "false". |
|
RIGHTFAX_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). |
|
RIGHTFAX_HTTP_PROXY_HOST |
Optional Enter the proxy server host name. |
|
RIGHTFAX_HTTP_PROXY_PORT |
Optional Enter the proxy server port number. Default=80. |
|
RIGHTFAX_HTTP_PROXY_AUTHTYPE |
Optional Valid value is either of the following. RIGHTFAX_HTTP_PROXY_AUTHTYPE_NONE – no authentication RIGHTFAX_HTTP_PROXY_AUTHTYPE_BASIC – Use HTTP basic authentication RIGHTFAX_HTTP_PROXY_AUTHTYPE_DIGEST – Use HTTP digest authentication. |
|
RIGHTFAX_HTTP_PROXY_USERNAME |
Optional Enter the username for proxy authentication. |
|
RIGHTFAX_HTTP_PROXY_PASSWORD |
Optional Enter the password for HTTP proxy authentication. |
|
RIGHTFAX_SENDER_FROM_NAME |
Optional Enter the name of the sender. |
|
RIGHTFAX_SENDER_EMP_ID |
Optional Enter the employee id of the sender. |
|
RIGHTFAX_SENDER_FROM_COMPANY |
Optional Enter the name of the sender's company. |
|
RIGHTFAX_SENDER_FROM_DEPARTMENT |
Optional Enter the name of the sender's department. |
|
RIGHTFAX_SENDER_FROMO_PHONE |
Optional Enter sender's phone number. |
|
RIGHTFAX_SENDER_RETURN_EMAIL |
Optional Enter sender's return email address. |
|
RIGHTFAX_SENDER_BILLINFO1 |
Optional Enter the billing code of the fax owner. |
|
RIGHTFAX_SENDER_BILLINFO2 |
Optional Enter the secondary billing code of the fax owner. |
|
RIGHTFAX_SENDER_RF_USER |
Required Enter the name of the sender's RightFax user name. |
|
RIGHTFAX_FAX_TO_NUMBER |
Required Enter the fax number where the document will be sent. |
|
RIGHTFAX_FAX_TO_NAME |
Optional Enter the recipient's name. |
|
RIGHTFAX_FAX_TO_COMPANY |
Optional Enter the recipient's company name. |
|
RIGHTFAX_FAX_ALT_FAX_NUM |
Optional Enter the alternative fax number. |
|
RIGHTFAX_FAX_TO_CONTACTNUM |
Optional Enter the contact phone number of the recipient. |
|
RIGHTFAX_FAX_COVERSHEET |
Optional Enter the cover sheet template for the current document. The file name can be either a full path on the RightFax server computer or a path relative to RightFax\Production\Covers. |
|
RIGHTFAX_COVERTEXT |
Optional Enter the text that should appear on the cover sheet. |
|
RIGHTFAX_COVERTEXT_TYPE |
Optional Enter the type of the cover sheet text. Valid values are:
|
|
RIGHTFAX_COVERTEXT_ENCODING |
Optional Enter the encoding of the cover sheet text. Valid values are:
|
|
RIGHTFAX_DOCUMENT_FORMAT |
Optional Valid values are:
|
The following is sample code for delivery to a Web-based Distributed Authoring and Versioning (WebDAV) server:
Example 8-13 Sample Code for Delivering Documents to a 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.
Table 8-6 Properties for Delivering Documents to WebDAV Servers
| 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. |
The following is sample code for delivery to an FTP server:
Example 8-14 Sample Code for Delivering Documents over FTP
// 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.
Table 8-7 Properties for Delivering Documents over FTP
| 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". |
|
FTP_PASSIVE_MODE |
Optional Valid values are "true" or "false" (default). |
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.
Example 8-15 Sample Code for Delivering Documents over SFTP
// 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();
Table 8-8 Properties for Delivering Documents over SFTP
| 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 |
Required 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. |
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.
The password authentication mode requires the username and password to log in to the secure FTP server. The following example shows sample code:
Example 8-16 Sample Code for Password Authentication
:
:
// 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 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:
Example 8-17 Sample Code for Public Key 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 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 through a custom servlet or CGI program).
Example 8-18 Sample Code for Delivering Documents over HTTP
// 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.
Table 8-9 Properties for Delivering Documents over HTTP
| 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. |
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:
Example 8-19 Sample Code for Delivering Documents over AS2
// 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.
Table 8-10 Properties for Delivering Documents over AS2
| 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:
|
|
AS2_ENC_ALGO |
The AS2 encryption algorithm. Set one of the following:
|
|
AS2_DIGEST_ALGO |
Enter the AS2 digest algorithm for signing the messages. Set either of the following:
|
|
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 asynchronous 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 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_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_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_PROXY_USERNAME |
Enter the username for proxy authentication. |
|
AS2_HTTP_PROXY_PASSWORD |
Enter the password for HTTP proxy authentication. |
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. Sample code for setting the delivery receipt directory is as follows:
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:
Example 8-21 Sample Code for Sending Asychronous Delivery Requests
:
:
// 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 APIs asynchronous delivery request mechanism to track down the asynchronous requests. See Section 8.15, "Asynchronous Delivery Requests."
The Delivery API enables you to sign a document for the secure transaction. This is based on the public key architecture, so you must set up the following:
Sender side: sender's public/private keys
Sender must have sender's public/private keys in a PKCS12 standard file. The file extension is .p12. Place that file in your local system where you want to run the Delivery API.
Receiver side (AS2 server side): sender's public key certificate
The receiver must have the sender's public key certificate. Installing certificates on the AS2 server can vary depending on your server. Generally, you must copy the .der or .cer certificates to a particular location. Consult your AS2 server manual for the procedure.
Once you have completed the setup, you can sign your document by setting properties in the delivery request. Sample code for this is as follows:
Example 8-22 Sample Code for Signing Documents
:
:
// 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");
:
:
The Delivery API enables you to encrypt documents for the secure transaction. This is based on the public key architecture, so you need to set up the following:
Sender's side: Receiver's public key certificate
The sender side must have the receiver's public key certificate file. The file extension is .der or .cer. Place that file in your local system where you want to run the Delivery API. Please consult the manual of your AS2 server for the procedure to obtain the AS2 server's public key certificate.
Receiver's side (AS2 server side): Receiver's public/private keys
The receiver side (AS2 Server) must have the receiver's public/private keys. Please consult the manual of your AS2 server for the procedure to set up keys.
Once set up, you can encrypt your document by setting properties in the delivery request. The sample code is as follows:
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 run time, 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:
Example 8-24 Sample Code for Delivering Documents Using External Commands
// 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();
The following property is supported and defined in DeliveryPropertyDefinitions:
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:
Example 8-25 Sample Code for Delivering Documents to Local File Systems
// 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();
The following property is supported and defined in DeliveryPropertyDefinitons:
The delivery system supports two modes: direct mode and buffering mode. Buffering mode is the default 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:
Example 8-26 Sample Code for Setting Direct Mode
// 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.
The buffering mode enables 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 Section 8.21, "Configuration File Support."
You can explicitly clear the temporary file or buffer by calling DeliveryRequest.close() after finishing your delivery request.
Example 8-27 Sample Code for Setting Buffering Mode
// 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 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:
Example 8-28 Sample Code for Implementing Callback Logic
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:
Example 8-29 Sample Code for Submitting Callback Logic
// 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());
:
:
The Delivery API supports the document filter functionality for all the supported protocols. This functionality enables you to call the native operating system (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:
Example 8-30 Sample Code for Setting Document Filter as Delivery Property
// 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 Section 8.21, "Configuration File Support"). In this case, the server will always use this filter for the requests to this server:
Example 8-31 Sample Code for Setting Document Filter in Configuration File
:
:
<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 operating system (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.
Example 8-32 Sample Code for Setting Document Filter through OS Commands
// 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 Section 8.21, "Configuration File Support."
In addition, BI Publisher provides a PDF-to-Postscript Level 2 conversion filter. You do not need to set {infile} and {outfile} place holders to use this internal filter, instead, directly specify the filter class as shown below:
Example 8-33 Sample for Setting the PDF-to-Postscript Level 2 Conversion Filter
req.addProperty(DeliveryPropertyDefinitions.FILTER, "oracle.xdo.delivery.filter.PDF2PSFilterImpl"); <server name="printer1" type="ipp_printer" default="true"> ipp://myserver:80/printers/MyPrinter1/.printer <filter>oracle.xdo.delivery.filter.PDF2PSFilterImpl</filter> </server>
BI Publisher provides properties that support date expressions. Use date expressions if you want to name a file by the date, and have the date automatically set at run time.
The following properties support date expressions:
SMTP_CONTENT_FILENAME
FTP_REMOTE_FILENAME
WEBDAV_REMOTE_FILENAME
The supported date expressions are:
%y : 4 digit year (ex, 1972, 2005)
%m : 2 digit month (00 - 12)
%d : 2 digit date (00 - 31)
%H : 24h based 2 digit hour (00 - 24)
%M : 2 digit minute (00 - 59)
%S : 2 digit sec (00 - 59)
%l : 3 digit millisec (000 - 999)
For example, if you specify my_file_%y%m%d.txt for the filename, the actual filename will would be my_file_20051108.txt for November 8, 2005. All undefined expressions will be translated into 0 length string, for example, if you specify my_file_%a%b%c.txt, it would generate my_file_.txt. You can escape the '%' character by passing '%%'.
The Delivery Server API supports following internationalization features for the listed delivery channels:
Specify character encoding for the main document with SMTP_CONTENT_TYPE.
Specify character encoding for the attachments by passing content type when you call addAttachment() method.
Specify the character encoding for email To/From/CC/Subject with SMTP_CHARACTER_ENCODING property. The default value is "UTF-8".
Specify character encoding for the IPP attributes by using IPP_ATTRIBUTE_CHARSET property. The default value is "UTF-8".
Specify IPP_URL_CHARACTER_ENCODING property for encoding non-ASCII letters in a URL.
Specify WEBDAV_URL_CHARACTER_ENCODING property for encoding non-ASCII letters in a URL.
The FTP delivery channel automatically detects the internationalization support in the target FTP server. You can specify a non-ASCII directory name and file name only if the FTP server supports internationalization (see RFC 2640 for more detail). In that case, the UTF-8 encoding will be used automatically. If the server does not support internationalization and you specify a non-ASCII value, an exception will be thrown during the delivery process.
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:
Table 8-13 Global Properties Supported by the DeliveryManager API
| Property | Description |
|---|---|
|
BUFFERING_MODE |
Valid values are "true" (default) and "false". See Section 8.14, "Direct and Buffering Modes." |
|
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. |
Example 8-34 Sample Code for Setting Global Properties
// 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);
:
:
You can add custom delivery channels to the system by following the steps below:
Define the delivery properties
Implement the DeliveryRequest interface
Implement the DeliveryRequestHandler interface
Implement the DeliveryRequestFactory interface
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.
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:
Example 8-35 Sample Code for Defining Delivery Channel Properties
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, if 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 run time. In the example, the FILE_DESTINATION property is defined to have a String value.
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:
Example 8-36 Sample Code for Delivering Documents to a Local File System through a Custom Delivery Channel
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;
}
}
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:
Example 8-37 Sample Code for Implementing the DeliveryRequestHandler Interface
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 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:
Example 8-38 Sample Code for Implementing the DeliveryRequestFactory Interface
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;
}
}
The final step is to register your custom delivery channel to the delivery system. You can register your delivery channel in two ways:
Static method
Use this method to register your delivery channel to the whole delivery system by specifying it in the configuration file. See Section 8.21, "Configuration File Support."
Dynamic method
Register the delivery channel to the Java VM instance by calling the Register API programmatically.
Sample code to register the file delivery channel using the dynamic method and call the file delivery channel is as follows:
Example 8-39 Sample Code for Registering and Calling File Delivery Channel Using the Dynamic Method
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();
}
}
The delivery systems supports a configuration file to set default servers, default properties, and custom delivery channels. The location of the configuration file is
{XDO_TOP}/resource/xdodelivery.cfg
where {XDO_TOP} is a Java system property that points to the physical directory.
This system property can be set in two ways:
Pass -DXDO_TOP=/path/to/xdotop to the Java startup parameter
Use a Java API in your code, such as java.lang.System.getProperties().put("XDO_TOP", "/path/to/xdotop")
The system property must be defined before constructing a DeliveryManager object.
Following is a sample configuration file:
Example 8-40 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>
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:
Example 8-41 Sample Code for Defining Multiple Servers for a Delivery Channel
// 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");
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.
The following properties are supported in the <properties> section:
ds-temp-dir: temporary directory location.
ds-buffering: specify true or false for buffering mode.
ds-ca-cert-file: specify the SSL certification file location.
The following elements are supported for <server type="ipp_printer"> and <server type="ipp_fax">
<host>
<port>
<printerName>
<uri>
<username>
<password>
<authType>
<encType>
<proxyHost>
<proxyPort>
<proxyUsername>
<proxyPassword>
<proxyAuthType>
<filter>
<filterOutputContentType>
The following elements are supported for <server type="smtp_email">
<secureConnection>
<host>
<port>
<username>
<password>
<authType>
<filter>
The following elements are supported for <server type="rightfax">
<host>
<port>
<uri>
<username>
<password>
<authType>
<encType>
<proxyHost>
<proxyPort>
<proxyUsername>
<proxyPassword>
<proxyAuthType>
<filter>
<filterOutputContentType>
The following elements are supported for <server type="printer">
<host>
<filter>
<filterOutputContentType>
The following elements are supported for <server type="webdav">
<host>
<port>
<uri>
<username>
<password>
<authType>
<encType>
<proxyHost>
<proxyPort>
<proxyUsername>
<proxyPassword>
<proxyAuthType>
<filter>
The following elements are supported for <server type="ftp">
<host>
<port>
<username>
<password>
<filter>
<passiveMode>
The following elements are supported for <server type="sftp">
<host>
<port>
<username>
<password>
<filter>
<authType>
The following elements are supported for <server type="http">
<host>
<port>
<uri>
<username>
<password>
<authType>
<encType>
<proxyHost>
<proxyPort>
<proxyUsername>
<proxyPassword>
<proxyAuthType>
The following elements are supported for <server type="as2">
<host>
<port>
<uri>
<username>
<password>
<authType>
<encType>
<proxyHost>
<proxyPort>
<proxyUsername>
<proxyPassword>
<proxyAuthType>
The following elements are supported for <server type="external">
<command>
<filter>
|
 Copyright © 2010, 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|