com.ibm.etill.framework.payapi
Class ETillAbortOperation

java.lang.Object
  |
  +--java.lang.Throwable
        |
        +--java.lang.Exception
              |
              +--com.ibm.etill.framework.payapi.ETillAbortOperation
All Implemented Interfaces:
Serializable

public final class ETillAbortOperation
extends Exception

The ETillAbortOperation exception should be thrown by cassettes to terminate the processing of the current operation. If that operation is an API command, then the Framework will send the return codes contained in the exception object back to the merchant application in the command response message.

Note that this exception only affects the current operation. Once thrown, the current Commerce Payments thread as well as the cassette continue servicing new requests. To terminate the cassette due to a very serious error, cassettes should throw an ETillCassetteException.

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' generic 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, 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' generic 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.

See Also:
ETillCassetteException, Serialized Form

Field Summary
 ReturnCodeStructure returnStructure
          Deprecated. Cassettes should not access this instance variable.
 
Constructor Summary
ETillAbortOperation()
          Default constructor.
ETillAbortOperation(ReturnCodeStructure rc)
          Constructs an ETillAbortOperation exception that contains the specified return code.
ETillAbortOperation(short pRC, short sRC)
          Constructs an ETillAbortOperation exception that contains the specified primary and secondary return codes.
ETillAbortOperation(short pRC, short sRC, String s)
          Constructs an ETillAbortOperation exception that contains the specified return codes and error text.
 
Method Summary
 short getPrimaryRC()
          Returns the primary return code contained within this exception object.
 ReturnCodeStructure getReturnCodeStructure()
           
 short getSecondaryRC()
          Returns the secondary return code contained within this exception object.
 String toString()
          Returns a string representation of this object for tracing purposes.
 
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, printStackTrace, printStackTrace, printStackTrace
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

returnStructure

public ReturnCodeStructure returnStructure
Deprecated. Cassettes should not access this instance variable.

Constructor Detail

ETillAbortOperation

public ETillAbortOperation(short pRC,
                           short sRC)
Constructs an ETillAbortOperation exception that contains the specified primary and secondary return codes.
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

ETillAbortOperation

public ETillAbortOperation(short pRC,
                           short sRC,
                           String s)
Constructs an ETillAbortOperation exception that contains the specified return codes and error text.
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.
s - a String containing text to log in case the exception is written to the trace log.
See Also:
PaymentAPIConstants

ETillAbortOperation

public ETillAbortOperation(ReturnCodeStructure rc)
Constructs an ETillAbortOperation exception that contains the specified return code.
Parameters:
rc - a ReturnCodeStructure that contains primary and secondary return codes. A cassette should not define their own primary, and must have secondary return codes documented in the appropriate programming guide for reference by merchant software writers.

ETillAbortOperation

public ETillAbortOperation()
Default constructor. Sets primary and secondary return codes to PaymentAPIConstants.PRC_INTERNAL_ETILL_ERROR and PaymentAPIConstants.RC_UNEXPECTED, respectively.
See Also:
PaymentAPIConstants
Method Detail

getReturnCodeStructure

public ReturnCodeStructure getReturnCodeStructure()

getPrimaryRC

public short getPrimaryRC()
Returns the primary return code contained within this exception object.
Returns:
short - the primary return code value.

getSecondaryRC

public short getSecondaryRC()
Returns the secondary return code contained within this exception object.
Returns:
short - the secondary return code value.

toString

public String toString()
Returns a string representation of this object for tracing purposes.
Overrides:
toString in class Throwable
Returns:
String - a string representation of the key elements of this exception object.