com.ibm.etill.framework.cassette
Class APIResponse

java.lang.Object
  |
  +--com.ibm.etill.framework.cassette.CassetteResponse
        |
        +--com.ibm.etill.framework.cassette.APIResponse

public final class APIResponse
extends CassetteResponse

APIResponse is a concrete class that cassettes use to specify return codes and (optionally) other data in response to an associated APIRequest object. Once the cassette completes its processing of the request, the Framework will send any response codes or other data contained in this object back to the the merchant application program to acknowledge completion of the command.

The Framework instantiates a new APIResponse object for every inbound APIRequest and passes both objects to the appropriate Cassette object's service method for processing. Unlike APIRequest, APIResponse is a final class and as such cannot be subclassed.

See Also:
APIRequest, Cassette.service(com.ibm.etill.framework.cassette.CassetteRequest, com.ibm.etill.framework.cassette.CassetteResponse)

Constructor Summary
APIResponse(ETillConnection connection)
          Constructs an APIResponse containing the specified ETillConnection object.
 
Method Summary
 short getPrimaryRC()
          Returns the primary return code contained within this object (if any).
 ReturnCodeStructure getReturnCodeStructure()
          Deprecated. Use getPrimaryRC and getSecondaryRC instead.
 byte[] getReturnMessage()
          Returns the contents of the auxillary response message contained in this object (if any).
 short getSecondaryRC()
          Returns the secondary return code contained within this object (if any).
 void setReturnCodes(short pRC, short sRC)
          Sets the primary and secondary return code for the associated command.
 void setReturnMessage(byte[] message)
          Specifies a byte array that contains auxillary protocol-specific response data that must be returned to the merchant application as part of the command response message.
 
Methods inherited from class com.ibm.etill.framework.cassette.CassetteResponse
getConnection, setConnection
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

APIResponse

public APIResponse(ETillConnection connection)
Constructs an APIResponse containing the specified ETillConnection object. This constructor is typically invoked by the Framework as the last link in a chain of constructors.
Parameters:
connection - an ETillConnection object through which the command response message will eventually be sent. Since the Framework sends all command response messages to the requesting merchant applications, cassettes should never write any data over this connection. Rather, return codes and other response data should simply be stored in this object through the setter methods that are provided.
Method Detail

setReturnCodes

public void setReturnCodes(short pRC,
                           short sRC)
Sets the primary and secondary return code for the associated command. These return codes will eventually be sent back to the merchant application software once the cassette completes its processing of the associated APIRequest.

A note about Commerce Payments return codes:
Cassette writers are strongly encouraged to use the primary and secondary return code values that are provided in com.ibm.etill.framework.payapi.PaymentAPIConstants in order to provide a consistent programming interface to merchant software that's written to Commerce Payments' framework payment API. Furthermore, under no circumstances should a cassette define its own primary return codes.

If you cannot find a suitable primary/secondary return code pair in the existing set of codes in PaymentAPIConstants:

  1. First, check with the IBM Commerce Payments Cassette Developer's support group to ensure an appropriate return code has not been recently added. Since new cassettes are constantly being developed, new return codes are also being defined to meet the needs of the cassette development as well as the merchant development communities. If a suitable code has been added, then use it. Otherwise request that a new code be defined in com.ibm.etill.framework.payapi.PaymentAPIConstants. Unless the error case you want to report through this return code is completely unique to your payment protocol, then IBM will most likely be willing to make the addition.
  2. If the error case is truly unique to your payment protocol, then use a primary return code of PRC_CASSETTE_ERROR and your own secondary return code. In order to minimize the confusion over ambiguous secondary return codes, the range between 50000 and 65534 has been reserved for highly protocol-dependent codes whose meanings will vary between payment protocols. In order to minimize the confusion over ambiguous secondary return codes, define your codes with a value above 10000. The range 0-9999 is reserved for IBM-defined return codes,including those codes added through the process described above.
Please remember that ambiguous return codes make it very difficult to write merchant software that is protocol-independent. Since such independence is a goal of Commerce Payments' payment framework, the addition of such codes is in direct conflict with the product's direction and will therefore make cassettes that use such methods less attractive to merchants.
Parameters:
pRC - a short containing the primary return code as defined in com.ibm.etill.framework.payapi.PaymentAPIConstants. Note that cassettes should not define their own primary return codes, as described above.
sRC - a short containing the secondary return code as defined in either com.ibm.etill.framework.payapi.PaymentAPIConstants or by the cassette itself, as described above. Note that all secondary return codes that may be set through this method must be documented in the appropriate programming guide for reference by merchant software writers.
See Also:
PaymentAPIConstants

getPrimaryRC

public short getPrimaryRC()
Returns the primary return code contained within this object (if any).
Returns:
short - the primary return code value. If no such value has been set, then this method returns a value of -1.
See Also:
PaymentAPIConstants

getSecondaryRC

public short getSecondaryRC()
Returns the secondary return code contained within this object (if any).
Returns:
short - the secondary return code value. If no such value has been set, then this method returns a value of -1.

setReturnMessage

public void setReturnMessage(byte[] message)
Specifies a byte array that contains auxillary protocol-specific response data that must be returned to the merchant application as part of the command response message. Currently, the only command that expects such protocol-specific data is RECEIVEPAYMENT.
Parameters:
message - a byte array created by the cassette which contains the auxillary data that must be returned to the merchant application program as part of the command response.

getReturnMessage

public byte[] getReturnMessage()
Returns the contents of the auxillary response message contained in this object (if any).
Returns:
byte[] - the contents of the auxillary response message. If no such message exists, null is returned.

getReturnCodeStructure

public ReturnCodeStructure getReturnCodeStructure()
Deprecated. Use getPrimaryRC and getSecondaryRC instead.

Cassette writers should not use this method. Rather, use the primary and secondary return code access methods directly. This method is maintained for historical reasons only and may be removed in the future.