com.efaxdeveloper.util.outbound
Class StatusResponse

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

public class StatusResponse
extends java.lang.Object

StatusResponse application interface

Overview

The StatusResponse application interface is used by the client-side process to manage responses to status requests returned by eFax Developer™.

The following snippet provides a basic example of how the StatusResponse application interface might be used to process an XML-formatted response returned by eFax Developer™ for a status request:

   // Establish a PrintWriter for the response  
   PrintWriter out = response.getWriter();

   out.println("<html>");
   out.println("<head><title>StatusRequestServlet</title></head>");
   out.println("<body>");

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

   Set the StatusRequest state...

   try {

     // POST the status request to eFax Developer
     StatusResponse resp = req.getStatus();

     // When eFax Developer approved the status request
     if (resp.isApproved()) {
       out.println("<p>eFax Developer&trade; received your request and returned the following response:</p>");
       out.println("<blockquote>");
       out.println("<p>Status response for transmission ID: " + resp.getTransmissionID());
       out.println("</p>");
       out.println(resp.getMessage());
       out.println("<blockquote>");
       out.println("<br>DOC Identifier: "        + resp.getDocID());
       // When a client specified customer identifier is used
       if ((resp.getCustomerID() != null) && (resp.getCustomerID().trim().length() > 0)) {
         out.println("<br>Customer ID: "         + resp.getCustomerID());
       }
       out.println("<br>Fax Number: "            + resp.getRecipientFax());
       out.println("<br>Recipient: "             + resp.getRecipientName());
       out.println("<br>Company: "               + resp.getRecipientCompany());
       out.println("<br>Status Classification: " + resp.getClassification());
       out.println("<br>Status Outcome: "        + resp.getOutcome());
       out.println("<br>Last Attempt Date: "     + resp.getLastDate());
       out.println("<br>Last Attempt Time: "     + resp.getLastTime());
       out.println("<br>Next Attempt Date: "     + resp.getNextDate());
       out.println("<br>Next Attempt Time: "     + resp.getNextTime());
       out.println("<br>Pages Scheduled: "       + resp.getPagesScheduled());
       out.println("<br>Pages Sent: "            + resp.getPagesSent());
       out.println("<br>Baud Rate: "             + resp.getBaudRate());
       out.println("<br>Duration (in minutes): " + resp.getDuration());
       out.println("<br>Number of Retries: "     + resp.getRetries());
       out.println("<br>Remote CSID: "           + resp.getRemoteCSID());
       out.println("</blockquote>");
       out.println("</blockquote>");
     }  
     // Otherwise, eFax Developer rejected the status request
     else {
       out.println("<p>eFax Developer&trade; received your request but encountered an error</p>");
       out.println("<blockquote>");
       // When a client transmission identifier is provided
       if ((resp.getTransmissionID() != null) && (resp.getTransmissionID().length() > 0)) {
           out.println("Transmission ID: "       + resp.getTransmissionID());
           out.println("<br>");
       }
       out.println("<br>Error Level: "           + resp.getErrorLevel());
       out.println("<br>Error Message: "         + resp.getErrorMessage());
       out.println("</blockquote>");
     }

   }
   catch (Exception e) {
     e.printStackTrace();
     out.println("<p>Your post request failed due to an error.</p>");
   }
   catch (Error err) {
     err.printStackTrace();
     out.println("<p>Your post request failed due to an error.</p>");
   }
   finally {
     out.println("</body></html>");
     out.flush();
     out.close();
   }
   
 

Since:
2.0
Version:
2.0
See Also:
StatusRequest, StatusRequest.getStatus()

Constructor Summary
StatusResponse()
          Constructor method for StatusResponse
 
Method Summary
 java.lang.String getBaudRate()
          Method to retrieve a transmission's BaudRate from the response XML.
 java.lang.String getClassification()
          Method to retrieve a transmission's status Classification from the response XML.
 java.lang.String getCustomerID()
          Method to retrieve a transmission's CustomerID from the response XML.
 java.lang.String getDocID()
          Method to retrieve a transmission's DOCID from the response XML.
 java.lang.String getDuration()
          Method to retrieve a transmission's Duration from the response XML.
 java.lang.String getErrorLevel()
          Method to retrieve a transmission's ErrorLevel from the response XML.
 java.lang.String getErrorMessage()
          Method to retrieve a transmission's ErrorMessage from the response XML.
 java.lang.String getLastDate()
          Method to retrieve a transmission's LastDate from the response XML.
 java.lang.String getLastTime()
          Method to retrieve a transmission's LastTime from the response XML.
 java.lang.String getMessage()
          Method to retrieve a transmission's status Message from the response XML.
 java.lang.String getNextDate()
          Method to retrieve a transmission's NextDate from the response XML.
 java.lang.String getNextTime()
          Method to retrieve a transmission's NextTime from the response XML.
 java.lang.String getOutcome()
          Method to retrieve a transmission's Outcome message from the response XML.
 java.lang.String getPagesScheduled()
          Method to retrieve a transmission's pages Scheduled from the response XML.
 java.lang.String getPagesSent()
          Method to retrieve a transmission's pages Sent from the response XML.
 java.lang.String getRawResponse()
          Method to retrieve the raw response returned by eFax Developer™.
 java.lang.String getRecipientCompany()
          Method to retrieve a transmission's recipient Company from the response XML.
 java.lang.String getRecipientFax()
          Method to retrieve a transmission's recipient Fax number from the response XML.
 java.lang.String getRecipientName()
          Method to retrieve a transmission's recipient Name from the response XML.
 java.lang.String getRemoteCSID()
          Method to retrieve a transmission's RemoteCSID from the response XML.
 java.lang.String getRetries()
          Method to retrieve a transmission's Retries from the response XML.
 java.lang.String getTransmissionID()
          Method to retrieve a transmission's TransmissionID from the response XML.
 boolean isApproved()
          Method to determine whether or not the status request was approved by eFax Developer™.
 boolean isHTMLResponse()
          Method to determine if an HTML response was requested.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

StatusResponse

public StatusResponse()
Constructor method for StatusResponse

Method Detail

getBaudRate

public java.lang.String getBaudRate()
Method to retrieve a transmission's BaudRate from the response XML.

The baud rate used to send the transmission which may or may not exist depending on the transmission's current status.

Returns:
a String value containing the baud rate which may or may not exist depending on the transmission's current status or empty when an HTML response is requested or isApproved() is false
See Also:
isApproved(), isHTMLResponse()

getClassification

public java.lang.String getClassification()
Method to retrieve a transmission's status Classification from the response XML.

The transmission's status classification may or may not exist depending on the transmission's current status.

Depending on the transmission's current status, one of the following status classifications will be assigned:

“Success”
“No answer”
“Busy”
“Call placement error”
“No dial tone”
“System error”
“Fax transmission failed”
“User defined”
“Remote hang-up”
“Unspecified failure”

Returns:
a String value containing the status classification which may or may not exist depending on the transmission's current status or empty when an HTML response is requested or isApproved() is false
See Also:
isApproved(), isHTMLResponse()

getCustomerID

public java.lang.String getCustomerID()
Method to retrieve a transmission's CustomerID from the response XML.

The client's customer identifier which may or may not exist depending on whether or not the client provided one.

Returns:
a String value containing the client's customer identifier which may or may not exist depending on the client's request or empty when an HTML response is requested or isApproved() is false
See Also:
isApproved(), isHTMLResponse()

getDocID

public java.lang.String getDocID()
Method to retrieve a transmission's DOCID from the response XML.

The eFax Developer transmission identifier for the specified transmission.

Returns:
a String value containing the eFax Developer transmission identifier or empty when an HTML response is requested or isApproved() is false
See Also:
isApproved(), isHTMLResponse()

getDuration

public java.lang.String getDuration()
Method to retrieve a transmission's Duration from the response XML.

The duration of the transmission in minutes which may or may not exist depending on the transmission's current status.

Returns:
a String value containing the actual duration in minutes which may or may not exist depending on the transmission's current status or empty when an HTML response is requested or isApproved() is false
See Also:
isApproved(), isHTMLResponse()

getErrorLevel

public java.lang.String getErrorLevel()
Method to retrieve a transmission's ErrorLevel from the response XML.

When isApproved() is false, this method will return one of the following values:

“User”
“System”

A “User” level error will be handled by the client while “System” level errors will require eFax Developer™ team intervention.

Additional information regarding “User” level errors can be found in the eFax Developer™ Java User Guide for Outbound Processing included with the SDK.

Returns:
a String value containing the response error level or empty when an HTML response is requested or isApproved() is true
See Also:
isApproved(), isHTMLResponse(), getErrorMessage()

getErrorMessage

public java.lang.String getErrorMessage()
Method to retrieve a transmission's ErrorMessage from the response XML.

The error message will explain why a status request failed or was rejected.

When isApproved() is false, this method will return the actual error message.

The value returned depends on the getErrorLevel(). A “System” level error message will return a generic message of “System error encountered.” A “User” level error message will return a message that indicates the exact reason for the failure.

Additional information regarding “User” level errors can be found in the eFax Developer™ Java User Guide for Outbound Processing included with the SDK.

Returns:
a String value containing the generated error message or empty when an HTML response is requested or isApproved() is true
See Also:
isApproved(), isHTMLResponse(), getErrorLevel()

getLastDate

public java.lang.String getLastDate()
Method to retrieve a transmission's LastDate from the response XML.

The last attempt date will be formatted as MM/dd/yyyy and may or may not exist depending on the transmission's current status.

Returns:
a String value containing the last attempt date or empty when an HTML response is requested or isApproved() is false
See Also:
isApproved(), isHTMLResponse()

getLastTime

public java.lang.String getLastTime()
Method to retrieve a transmission's LastTime from the response XML.

The last attempt time will be returned as HH:mm:ss (24 hour) in Pacific Time and may or may not exist depending on the transmission's current status.

Returns:
a String value containing the last attempt time or empty when an HTML response is requested or isApproved() is false
See Also:
isApproved(), isHTMLResponse()

getMessage

public java.lang.String getMessage()
Method to retrieve a transmission's status Message from the response XML.

The current status of the transmission as it progresses to completion.

Depending on the transmission's current status, one of the following status messages could be returned:

“Unable to retrieve statistics for transmission.”
“Your transmission is in the conversion process.”
“Your transmission is waiting to be sent.”
“Your high priority transmission is waiting to be sent.”
“Your transmission is waiting to be retried.”
“Your transmission has completed.”
“Your transmission has completed - sending disposition notifications.”

Returns:
a String value containing the status message or empty when an HTML response is requested or isApproved() is false
See Also:
isApproved(), isHTMLResponse()

getNextDate

public java.lang.String getNextDate()
Method to retrieve a transmission's NextDate from the response XML.

The next attempt date will be formatted as MM/dd/yyyy and may or may not exist depending on the transmission's current status.

Returns:
a String value containing the next attempt date or empty when an HTML response is requested or isApproved() is false
See Also:
isApproved(), isHTMLResponse()

getNextTime

public java.lang.String getNextTime()
Method to retrieve a transmission's NextTime from the response XML.

The next attempt time will be returned as HH:mm:ss (24 hour) in Pacific Time and may or may not exist depending on the transmission's current status.

Returns:
a String value containing the next attempt time or empty when an HTML response is requested or isApproved() is false
See Also:
isApproved(), isHTMLResponse()

getOutcome

public java.lang.String getOutcome()
Method to retrieve a transmission's Outcome message from the response XML.

The transmission's last outcome may or may not exist depending on the transmission's current status.

Returns:
a String value containing the last outcome which may or may not exist depending on the transmission's current status or empty when an HTML response is requested or isApproved() is false
See Also:
isApproved(), isHTMLResponse()

getPagesScheduled

public java.lang.String getPagesScheduled()
Method to retrieve a transmission's pages Scheduled from the response XML.

The number of pages scheduled which may or may not exist depending on the transmission's current status.

Returns:
a String value containing the pages scheduled or empty when an HTML response is requested or isApproved() is false
See Also:
isApproved(), isHTMLResponse()

getPagesSent

public java.lang.String getPagesSent()
Method to retrieve a transmission's pages Sent from the response XML.

The number of pages successfully transmitted which may or may not exist depending on the transmission's current status.

Returns:
a String value containing the pages sent which may or may not exist depending on the transmission's current status or empty when an HTML response is requested or isApproved() is false
See Also:
isApproved(), isHTMLResponse()

getRawResponse

public java.lang.String getRawResponse()
Method to retrieve the raw response returned by eFax Developer™.

The raw response will contain formatted XML (default) or an HTML-formatted response when an HTML response is requested.

Returns:
a String value containing the raw response returned by eFax Developer™
See Also:
isHTMLResponse(), StatusRequest.isHTMLResponse()

getRecipientCompany

public java.lang.String getRecipientCompany()
Method to retrieve a transmission's recipient Company from the response XML.

The recipient company name which may or may not exist depending on whether or not the client provided one.

Returns:
a String value containing the recipient company name which may or may not exist depending on the client's request or empty when an HTML response is requested or isApproved() is false
See Also:
isApproved(), isHTMLResponse()

getRecipientFax

public java.lang.String getRecipientFax()
Method to retrieve a transmission's recipient Fax number from the response XML.

The recipient fax number for the transmission.

Returns:
a String value containing the recipient fax number or empty when an HTML response is requested or isApproved() is false
See Also:
isApproved(), isHTMLResponse()

getRecipientName

public java.lang.String getRecipientName()
Method to retrieve a transmission's recipient Name from the response XML.

The recipient name which may or may not exist depending on whether or not the client provided one.

Returns:
a String value containing the recipient name which may or may not exist depending on the client's request or empty when an HTML response is requested or isApproved() is false
See Also:
isApproved(), isHTMLResponse()

getRemoteCSID

public java.lang.String getRemoteCSID()
Method to retrieve a transmission's RemoteCSID from the response XML.

The receiving CSID which may or may not exist depending on the transmission's current status and whether or not the receiving machine is set to return one.

Returns:
a String value containing the CSID transmitted to which may or may not exist depending on the transmission's current status or empty when an HTML response is requested or isApproved() is false
See Also:
isApproved(), isHTMLResponse()

getRetries

public java.lang.String getRetries()
Method to retrieve a transmission's Retries from the response XML.

The current number of retries which may or may not exist depending on the transmission's current status.

Returns:
a String value containing the actual number of retry attempts which may or may not exist depending on the transmission's current status or empty when an HTML response is requested or isApproved() is false
See Also:
isApproved(), isHTMLResponse()

getTransmissionID

public java.lang.String getTransmissionID()
Method to retrieve a transmission's TransmissionID from the response XML.

The client's transmission identifier which may or may not exist depending on whether or not the client provided one.

Returns:
a String value containing the client's transmission identifier which may or may not exist depending on the client's request or empty when an HTML response is requested or isApproved() is false is requested
See Also:
isApproved(), isHTMLResponse()

isApproved

public boolean isApproved()
Method to determine whether or not the status request was approved by eFax Developer™.

When true, the status request was approved. The response to an approved status request will contain statistics for the requested transmission identifier or DOC identifier.

When false, the status request was successfully received, but rejected for some reason. The response to a rejected status request will contain getErrorLevel() and getErrorMessage() behavior that can be parsed to determine why the status request rejected.

Client processing should check the getErrorLevel() behavior and correct any “User” level errors before resubmitting.

Accounts that continuously hit eFax Developer™ with bad requests or submit malformed requests in an effort to "ping" our servers will be deactivated without notice.

Returns:
true if the status request was successfully approved, otherwise false
See Also:
getErrorLevel(), getErrorMessage(), isHTMLResponse()

isHTMLResponse

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

When an HTML-formatted response is requested, client processing will be limited to the HTML response returned by the getRawResponse() method. With the exception of Boolean accessors isHTMLResponse() or isApproved(), attempting to retrieve response data via an accessor method will result in an empty string being returned when an HTML response is indicated.

Returns:
true if an HTML-formatted response was returned, otherwise false
See Also:
StatusRequest.setHTMLResponse(boolean), getRawResponse()