com.efaxdeveloper.util.outbound
Class OutboundRequest

java.lang.Object
  extended by com.efaxdeveloper.util.outbound.OutboundRequest

public class OutboundRequest
extends java.lang.Object

OutboundRequest application interface

Overview

The OutboundRequest application interface is used to send outbound fax transmissions to eFax Developer™.

The following snippet provides a basic example of how the OutboundRequest application interface might be used to send an outbound transmission request in fine mode with disposition notifications sent to two separate recipients via email regardless of success or failure:

   // Instantiate a new OutboundRequest object
   OutboundRequest req = new OutboundRequest();

   // Set your eFax Developer outbound account identifier (required)
   req.setAccountID("1234567890");
   // Set your eFax Developer outbound user name (required)
   req.setUserName("joe");
   // Set your eFax Developer outbound password (required)
   req.setPassword("dog");

   // Set a unique transmission identifier (recommended)
   req.setTransmissionID("123456789");
   // Set the resolution to fine mode
   req.setFineResolution(true);

   // Set to receive disposition emails upon success or failure
   req.setDispositionLevel(OutboundRequest.DL_BOTH);

   // Instantiate an EmailBundler object
   EmailBundler dispositionEmails = new EmailBundler();

   // Add new recipient(s) to the EmailBundler object
   dispositionEmails.add("email1@a_domain.com");
   dispositionEmails.add("email2@a_domain.com");

   // Set your disposition emails to the OutboundRequest instance
   req.setDispositionsTo(dispositionEmails);

   // Set the recipient fax number for this transmission (required)
   req.setRecipientFax("1234567890");

   try {

     // Instantiate a DocumentBundler object
     DocumentBundler docs = new DocumentBundler();

     // Add document(s) to the DocumentBundler object by path (most common method)
     docs.add("C:\\your\\document\\path\\your.doc");

     // Set the documents to be faxed to the OutboundRequest instance
     req.setDocuments(docs);

     // POST the outbound transmission request to eFax Developer
     OutboundResponse resp = req.sendFax();

     Process the OutboundResponse...

   }
   catch (Exception e) {
     e.printStackTrace();
   }
   catch (Error err) {
     err.printStackTrace();
   }
   
 

Since:
2.0
Version:
2.0
See Also:
OutboundResponse, EmailBundler, DocumentBundler

Field Summary
static java.lang.String DL_BOTH
          Used to indicate a Disposition Level of "BOTH"
static java.lang.String DL_ERROR
          Used to indicate a Disposition Level of "ERROR"
static java.lang.String DL_NONE
          Used to indicate a Disposition Level of "NONE"
static java.lang.String DL_SUCCESS
          Used to indicate a Disposition Level of "SUCCESS"
static java.lang.String ISO_DUTCH
          Used to indicate a Disposition ISO 639-1 language code of "nl"
static java.lang.String ISO_ENGLISH
          Used to indicate a Disposition ISO 639-1 language code of "en"
static java.lang.String ISO_FRENCH
          Used to indicate a Disposition ISO 639-1 language code of "fr"
static java.lang.String ISO_GERMAN
          Used to indicate a Disposition ISO 639-1 language code of "de"
static java.lang.String ISO_ITALIAN
          Used to indicate a Disposition ISO 639-1 language code of "it"
static java.lang.String ISO_POLISH
          Used to indicate a Disposition ISO 639-1 language code of "pl"
static java.lang.String ISO_PORTUGUESE
          Used to indicate a Disposition ISO 639-1 language code of "pt"
static java.lang.String ISO_SPANISH
          Used to indicate a Disposition ISO 639-1 language code of "es"
 
Constructor Summary
OutboundRequest()
          Constructor method for the OutboundRequest
 
Method Summary
 int getConnectionTimeout()
          Method used to retrieve the current connection timeout for the request.
 int getReadTimeout()
          Method used to retrieve the current read timeout for the response.
 boolean isHTMLResponse()
          Method to determine if an HTML response was requested.
 OutboundResponse sendFax()
          Method used to POST an outbound fax transmission to eFax Developer™.
 void setAccountID(java.lang.String accountID)
          Method used to set the client's account identifier.
 void setConnectionTimeout(int mills)
          Method used to control the connection timeout for the request.
 void setCustomerID(java.lang.String customerID)
          Method used to set the client generated customer identifier.
 void setDispositionLanguage(java.lang.String languageISOCode)
          Method used to set the disposition language.
 void setDispositionLevel(java.lang.String dispositionLevel)
          Method used to set the final disposition level.
 void setDispositionsTo(EmailBundler dispositionEmails)
          Method used to distribute final disposition notifications via email.
 void setDispositionsTo(java.lang.String dispositionURL)
          Method used to distribute final disposition notifications via HTTP POST.
 void setDocuments(DocumentBundler documents)
          Method used to set the documents to be faxed.
 void setFaxHeader(java.lang.String faxHeader)
          Method used to override the default fax header.
 void setFineResolution(boolean useFine)
          Method used to control the transmission resolution.
 void setHighPriority(boolean useHigh)
          Method used to control the transmission priority.
 void setHTMLResponse(boolean useHTML)
          Method used to request an HTML-formatted response.
 void setNoDuplicates(boolean noDuplicates)
          Method used to prevent duplicate transmission identifiers from being submitted.
 void setPassword(java.lang.String password)
          Method used to set the client's password.
 void setReadTimeout(int mills)
          Method used to control the read timeout for the response.
 void setRecipientCompany(java.lang.String recipientCompany)
          Method used to set the recipient company.
 void setRecipientFax(java.lang.String recipientFax)
          Method used to set the recipient fax number.
 void setRecipientName(java.lang.String recipientName)
          Method used to set the recipient name.
 void setSelfBusy(boolean useSelfBusy)
          Method used to control the "self-busy" option.
 void setTransmissionID(java.lang.String transmissionID)
          Method used to set the client generated transmission identifier.
 void setTSID(java.lang.String tsid)
          Method used to override the default TSID value.
 void setUserName(java.lang.String userName)
          Method used to set the client's user name.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DL_ERROR

public static final java.lang.String DL_ERROR
Used to indicate a Disposition Level of "ERROR"

See Also:
Constant Field Values

DL_SUCCESS

public static final java.lang.String DL_SUCCESS
Used to indicate a Disposition Level of "SUCCESS"

See Also:
Constant Field Values

DL_BOTH

public static final java.lang.String DL_BOTH
Used to indicate a Disposition Level of "BOTH"

See Also:
Constant Field Values

DL_NONE

public static final java.lang.String DL_NONE
Used to indicate a Disposition Level of "NONE"

See Also:
Constant Field Values

ISO_DUTCH

public static final java.lang.String ISO_DUTCH
Used to indicate a Disposition ISO 639-1 language code of "nl"

See Also:
Constant Field Values

ISO_ENGLISH

public static final java.lang.String ISO_ENGLISH
Used to indicate a Disposition ISO 639-1 language code of "en"

See Also:
Constant Field Values

ISO_FRENCH

public static final java.lang.String ISO_FRENCH
Used to indicate a Disposition ISO 639-1 language code of "fr"

See Also:
Constant Field Values

ISO_GERMAN

public static final java.lang.String ISO_GERMAN
Used to indicate a Disposition ISO 639-1 language code of "de"

See Also:
Constant Field Values

ISO_ITALIAN

public static final java.lang.String ISO_ITALIAN
Used to indicate a Disposition ISO 639-1 language code of "it"

See Also:
Constant Field Values

ISO_POLISH

public static final java.lang.String ISO_POLISH
Used to indicate a Disposition ISO 639-1 language code of "pl"

See Also:
Constant Field Values

ISO_PORTUGUESE

public static final java.lang.String ISO_PORTUGUESE
Used to indicate a Disposition ISO 639-1 language code of "pt"

See Also:
Constant Field Values

ISO_SPANISH

public static final java.lang.String ISO_SPANISH
Used to indicate a Disposition ISO 639-1 language code of "es"

See Also:
Constant Field Values
Constructor Detail

OutboundRequest

public OutboundRequest()
Constructor method for the OutboundRequest

Method Detail

isHTMLResponse

public boolean isHTMLResponse()
Method to determine if an HTML response was requested.

Selecting an HTML response limits the client-side application to formatted HTML returned via the getRawResponse() method.

Returns:
a boolean value indicating an HTML-formatted response
See Also:
setHTMLResponse(boolean), OutboundResponse.getRawResponse()

sendFax

public OutboundResponse sendFax()
                         throws java.lang.Exception
Method used to POST an outbound fax transmission to eFax Developer™.

Returns:
an OutboundResponse instance containing the response returned from eFax Developer™
Throws:
java.lang.Exception
See Also:
OutboundResponse, setReadTimeout(int), setConnectionTimeout(int)

setCustomerID

public void setCustomerID(java.lang.String customerID)
Method used to set the client generated customer identifier.

The customerID is a client specified value used to identify a customer. The customerID is "pass-through" data that is not required or validated by eFax Developer™. The field is provided for client-side customer identification purposes only.

Parameters:
customerID - the client's customer identifier

setDispositionLanguage

public void setDispositionLanguage(java.lang.String languageISOCode)
Method used to set the disposition language.

The dispositionLanguage contains the desired ISO 639-1 language code for final dispositions. Clients can choose one of the following supported languages:
"nl" - Dutch
"en" - English (default)
"fr" - French
"de" - German
"it" - Italian
"pl" - Polish
"pt" - Portuguese
"es" - Spanish

Parameters:
languageISOCode - the chosen ISO 639-1 language code

setDispositionLevel

public void setDispositionLevel(java.lang.String dispositionLevel)
Method used to set the final disposition level.

The dispositionLevel contains the desired disposition level at which final disposition notifications will be generated. Clients can suppress the notification completely, or generate the notification upon success, failure or both. Valid values are:
"SUCCESS"
"ERROR"
"BOTH"
"NONE" (default)

Parameters:
dispositionLevel - the desired disposition level
See Also:
setDispositionsTo(String), setDispositionsTo(EmailBundler)

setDispositionsTo

public void setDispositionsTo(EmailBundler dispositionEmails)
Method used to distribute final disposition notifications via email.

Clients can choose to have final disposition notifications sent via email or to a designated endpoint as desired. This method will accept an EmailBundler instance indicating that final disposition notifications should be sent via email.

Disposition notifications will be sent based on the setDispositionLevel(String) setting.

Parameters:
dispositionEmails - an EmailBundler object containing all email addresses to receive final disposition notifications
See Also:
setDispositionLevel(String), setDispositionsTo(String)

setDispositionsTo

public void setDispositionsTo(java.lang.String dispositionURL)
Method used to distribute final disposition notifications via HTTP POST.

Clients can choose to have final disposition notifications sent via email or to a designated endpoint as desired. This method will accept a URL string indicating that final disposition notifications should be sent via HTTP POST.

Disposition notifications will be sent based on the setDispositionLevel(String) setting.

Client's may consider using a DispositionCatcher instance to process disposition notification received at the designated endpoint.

Parameters:
dispositionURL - a client-defined URL that will accept the final disposition HTTP POST
See Also:
setDispositionLevel(String), setDispositionsTo(EmailBundler)

setDocuments

public void setDocuments(DocumentBundler documents)
Method used to set the documents to be faxed.

The DocumentBundler object contains all documents chosen for this transmission.

Parameters:
documents - DocumentBundler object that contains the chosen documents to be faxes
See Also:
DocumentBundler

setFaxHeader

public void setFaxHeader(java.lang.String faxHeader)
Method used to override the default fax header.

A client generated fax header may be set to override the system default.

Additional information regarding "Dynamic Fax Headers" can be obtained by reviewing the eFax Developer™ Outbound User Guide received with this package.

Parameters:
faxHeader - the client specified "Dynamic Fax Header"

setFineResolution

public void setFineResolution(boolean useFine)
Method used to control the transmission resolution.

Passing true to this method will override the default resolution ("standard") and cause eFax Developer™ to set the transmission resolution to "fine" instead of "standard."

Transmissions requested with "fine" resolution will incur a price premium.

Parameters:
useFine - a boolean value indicating that the desired resolution should be set to "fine"

setHighPriority

public void setHighPriority(boolean useHigh)
Method used to control the transmission priority.

Passing true to this method will override the default priority ("normal") and cause eFax Developer™ to set the transmission priority to "high" instead of "normal."

Transmissions requested with "high" priority will incur a price premium.

Parameters:
useHigh - a boolean value indicating that the desired priority should be set to "high"

setHTMLResponse

public void setHTMLResponse(boolean useHTML)
Method used to request an HTML-formatted response.

Passing true to this method will cause eFax Developer™ to respond with standard HMTL instead of formatted XML.

Selecting an HTML response limits the client-side application to formatted HTML only. Clients who wish to store metadata returned by eFax Developer™ should not request an HTML response.

Parameters:
useHTML - a boolean value indicating that a standard HTML response is desired
See Also:
OutboundResponse.isHTMLResponse(), isHTMLResponse()

setNoDuplicates

public void setNoDuplicates(boolean noDuplicates)
Method used to prevent duplicate transmission identifiers from being submitted.

By default, the system will allow duplicate transmission identifiers to be submitted.

Enabling this option causes eFax Developer™ to verify that the transmission identifier has not already been used by a previous transmission.

When enabled, eFax Developer™ will fail the transmission if a duplicate transmission identifier exists.

Parameters:
noDuplicates - a boolean value indicating the desired "no duplicates" option setting
See Also:
setTransmissionID(String)

setRecipientCompany

public void setRecipientCompany(java.lang.String recipientCompany)
Method used to set the recipient company.

The recipientCompany contains the name of the company who will be receiving the fax. This optional value will be merged into the fax header line.

Parameters:
recipientCompany - the name of the company that will receive the fax

setRecipientFax

public void setRecipientFax(java.lang.String recipientFax)
Method used to set the recipient fax number.

The recipientFax contains the destination fax number for this transmission.

Parameters:
recipientFax - the destination fax number to receive the fax

setRecipientName

public void setRecipientName(java.lang.String recipientName)
Method used to set the recipient name.

The recipientName contains the name of the person who will be receiving the fax. This optional value will be merged into the fax header line.

Parameters:
recipientName - the name of the person who will receive the fax

setSelfBusy

public void setSelfBusy(boolean useSelfBusy)
Method used to control the "self-busy" option.

Passing false to this method will override the default "self-busy" option and cause eFax Developer™ to set the transmission "self-busy" option to "disable" instead of "enable."

By default, the eFax Developer™ prevents multiple fax channels from simultaneously dialing the same fax number. Disabling this option will allow a single fax number to be dialed simultaneously by multiple fax channels.

Parameters:
useSelfBusy - a boolean value indicating the desired "self-busy" option setting

setTransmissionID

public void setTransmissionID(java.lang.String transmissionID)
Method used to set the client generated transmission identifier.

The transmissionID is a unique client specified number used to identify a transmission. This optional value can be searched for during status request processing. The transmissionID should be a unique number when used.

Parameters:
transmissionID - the client generated transmission identifier
See Also:
setNoDuplicates(boolean)

setTSID

public void setTSID(java.lang.String tsid)
Method used to override the default TSID value.

A TSID or Transmitting Subscriber Identification is transmitted to the receiving fax machine to identify the fax sender. As default, eFax Developer™ transmits the account's fax number as the TSID.

This method provides clients the ability to override the default TSID on a request-by-request basis when needed.

Parameters:
tsid - the TSID or Transmitting Subscriber Identification

getConnectionTimeout

public int getConnectionTimeout()
Method used to retrieve the current connection timeout for the request.

Returns:
the current connection timeout value. 0 return implies that the option is disabled (i.e., timeout of infinity).
See Also:
setConnectionTimeout(int)

getReadTimeout

public int getReadTimeout()
Method used to retrieve the current read timeout for the response.

Returns:
the current read timeout value. 0 return implies that the option is disabled (i.e., timeout of infinity).
See Also:
setReadTimeout(int)

setAccountID

public void setAccountID(java.lang.String accountID)
Method used to set the client's account identifier.

The accountID value is required by eFax Developer™ for user authentication. The account identifier is provided by eFax Developer at setup time.

Parameters:
accountID - the client's account identifier used for authentication

setConnectionTimeout

public void setConnectionTimeout(int mills)
Method used to control the connection timeout for the request.

Sets the connection timeout to a specified value, in milliseconds, to be used when opening the connection to eFax Developer™. If the timeout expires before the connection can be established, a java.net.SocketTimeoutException will be thrown.

A timeout of zero is interpreted as an infinite timeout.

Parameters:
mills - an int value that specifies the connect timeout in milliseconds
See Also:
getConnectionTimeout(), sendFax(), getStatus()

setPassword

public void setPassword(java.lang.String password)
Method used to set the client's password.

The password is required by eFax Developer™ for user authentication.

The password value passed here must match the password specified in the Outbound Settings tab of the online user interface.

Parameters:
password - the client's outbound password used for authentication

setReadTimeout

public void setReadTimeout(int mills)
Method used to control the read timeout for the response.

Sets the read timeout to a specified value, in milliseconds, to be used when reading the response returned by eFax Developer™. If the timeout expires before there is data available for read, a java.net.SocketTimeoutException will be thrown.

A timeout of zero is interpreted as an infinite timeout.

Parameters:
mills - an int value that specifies the read timeout in milliseconds
See Also:
getReadTimeout(), sendFax(), getStatus()

setUserName

public void setUserName(java.lang.String userName)
Method used to set the client's user name.

The userName value is required by eFax Developer™ for user authentication.

The user name value passed here must match the user name specified in the Outbound Settings tab of the online user interface.

Parameters:
userName - the client's outbound user name used for authentication