com.efaxdeveloper.util.outbound
Class OutboundResponse

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

public class OutboundResponse
extends java.lang.Object

OutboundResponse application interface

Overview

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

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

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

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

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

   Set the OutboundRequest state...

   try {

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

     // When eFax Developer approved the outbound request
     if (resp.isApproved()) {
       out.println("<p>eFax Developer&trade; successfully received your request</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>DOC Identifier: "       + resp.getDocID());
       out.println("</blockquote>");
     }
     // Otherwise, eFax Developer rejected the outbound 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:
OutboundRequest, OutboundRequest.sendFax()

Constructor Summary
OutboundResponse()
          Constructor method for OutboundResponse
 
Method Summary
 java.lang.String getDocID()
          Method to retrieve a transmission's DOCID 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 getRawResponse()
          Method to retrieve the raw response returned by eFax Developer™.
 java.lang.String getTransmissionID()
          Method to retrieve a transmission's TransmissionID from the response XML.
 boolean isApproved()
          Method to determine whether or not the outbound 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

OutboundResponse

public OutboundResponse()
Constructor method for OutboundResponse

Method Detail

getDocID

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

The eFax Developer transmission identifier assigned to this request.

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

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 an outbound 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()

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 response response
See Also:
isHTMLResponse(), OutboundRequest.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
See Also:
isHTMLResponse(), isApproved()

isApproved

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

When true, the outbound request was approved for transmission. The response to an approved outbound request will contain the client specified transmission identifier and associated DOC identifier generated by eFax Developer™.

When false, the outbound request was successfully received, but rejected for some reason. The response to a rejected outbound request will contain getErrorLevel() and getErrorMessage() behavior that can be parsed to determine why the outbound 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 outbound request was approved, otherwise false
See Also:
getTransmissionID(), getDocID(), 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:
OutboundRequest.setHTMLResponse(boolean), getRawResponse()