Commerce layer transaction service interface reference
Document #: 321ST072
Authors: Stig Mjølsnes (STF) and Rolf Michelsen (STF)
Editor: Rolf Michelsen (STF)
Reviewer:
@version [CVS] @(#) $Id: index.html,v 1.7 1998/08/26 14:04:06 semper Exp $
Table of contents
Introduction
This document contains reference documentation for the classes constituting the new
transaction service of the SEMPER commerce layer. The transaction service is
implemented as a single Java package, semper.commerce.
The reference documentation is mostly provided as output from Javadoc.
Overview of semper.commerce
The classes in semper.commerce can be grouped according to the function they serve in
the commerce layer. In this section we give a brief description of each class to augment
the Javadoc documentation.
Deals
This group of classes are used for manipulating commerce deals. A deal consists of an
association between the involved parties and the transactions performed in the context of
the deal. The current implementation only supports deals between two explicit parties. Any
number of implicit parties may be involved in a deal, but these parties are not visible in
the commerce layer service.
Deals can be accessed in both an active and a suspended state. An
activated deal is associated with a communications session between the parties of
the deal. An active deal can be inspected and new transactions can be performed. All
involved parties must agree to activate the same deal at the same time.
When a deal is accessed in the suspended state, a communications session is not
established to the other parties. In this state the deal can only be locally inspected. A
deal browser will be a typical application for suspended deals.
An existing deal can be accessed both as an active and as a passive deal -- possibly
concurrently. This is equivalent to files that can be opened for reading or writing.
SEMPER is based on a client-server model. When a deal is accessed in the
active state, one of the parties act as the client and all other parties involved in the
deal act as servers. The client initiates the activation of the deal, and the
servers respond to the activation.
- InitiatorDeal
- This class is instantiated to access a deal in the active state. The party that requests
activation of the deal by instantiating this class is the client in the SEMPER
model. All other parties involved in the deal act as servers and instantiate the class
RespondentDeal
as discussed below.
- RespondentDeal
- When a client requests activation of a deal, an indication is received by all other
parties involved in the deal. These parties must then invoke a class of type
RespondentDeal
to activate the same deal and act as servers.
- ActiveDeal
- This is the base class for
InitiatorDeal
and RespondentDeal
.
It defines the common features of all active deals. This class cannot be instantiated
directly.
- SuspendedDeal
- This class is instantiated to access a deal in the suspended state.
- Deal
- This is the base class for
ActiveDeal
and SuspendedDeal
. It
defines the common features of all deals. This class cannot be instantiated directly.
Additionally the class DealState
is used internally by the semper.commerce
package. Objects of this class store all the information associated with a deal, e.g. the
transaction history. This information is maintained by a separate class to permit several
instances of subclasses of Deal
to access the same data.
Transactions
This group of classes are used for managing commerce transactions. Transactions can
only exist in the context of a deal. We have defined a set of very general transaction
classes. These generic transactions can then be subclassed and extended by applications or
in extensions of the commerce layer itself.
- GenericTransaction
- This transaction type is intended for generic information exchange between the client
and server applications in the deal. Transactions of this type will not bind or commit any
of the parties to specific actions in the future.
- PaymentTransaction
- This transaction type represents a payment transaction between two of the parties
involved in the deal. The commerce layer will only permit payment transactions after an
authorisation by the payer. An application will typically subclass this class to provide
more contextual information about the payment transaction.
- StatementTransaction
- This transaction type represents a statement signed by one party and then sent to some
other party. The commerce layer will only permit statement transactions after an
authorisation by the signer. An application will typically subclass this class to provide
more contextual information about the statement transaction.
- ExchangeTransaction
- This transaction type represents a fair exchange. An exchange consists of two
subtransactions: A requested transaction and an indicated transaction.
- Transaction
- This is the base class of all transaction classes. It defines the common functionality
of all transactions. This class cannot be instantiated directly.
Service quality
A number of classes for representing quality of service (QoS) requirements are
provided.
- DealQuality
- This class represents the QoS of a deal.
- ServiceQuality
- This is the base class for
DealQuality
, and it defines the common
functionality of classes for managing QoS settings. This class cannot be instantiated
directly.
Miscellaneous
The commerce layer defines a number of small helper classes that does not naturally fit
in the categories above. Some of these classes are very important to the commerce layer,
but the services offered by these classes are quite limited. A brief description of these
classes is given here for completeness.
- DealID
- This class encapsulates a deal identifier.
- TransactionID
- This class encapsulates a transaction identifier.
- Payment
- This class encapsulates information about a payment transaction, and it is used together
with the
PaymentTransaction
class.
- Statement
- This class encapsulates information about a statement transaction, and it is used
together with the
StatementTransaction
class.
- Description
- This class encapsulates a textual description of the context information for a
transaction.
- Commerce
- This is a static class that provides certain commerce services that are not naturally
associated with any of the objects defined by the commerce layer.
Exceptions
The commerce layer defines a number of exceptions. Information about the reason for an
exception is provided at several layers. First, exceptions are grouped in categories that
are represented by an exception class. Second, an exception code attribute can be
inspected to obtain further information about the reason for the exception.
- AccessException
- This exception is thrown if a service request cannot be completed because the caller has
not passed the required access control capabilities.
- AssociationException
- This exception is thrown if there is something wrong with the association between any of
the parties of the deal. Such problems are usually connected to the session established
when accessing an active deal.
- QualityException
- Thrown if conflicting service quality settings have been specified for a service. The
service quality for a transaction is determined by the QoS specified for the individual
transaction and the QoS for the deal containing the transaction. Additionally, both the
deal and transaction QoS are a result of a QoS negotiation between the parties of the
deal.
- DealException
- This exception is thrown if something is wrong with the deal exception for problems with
the association. These problems are reported by throwing an object of type
AssociationException
.
- TransactionException
- Thrown if there is something wrong with an individual transaction.
- CommerceException
- This is the common base class of all excepiton classes defined by the commerce layer. It
defines a common set of services for all types of exception. By catching exceptions of
this type it is also possible to catch all commerce related exceptions with a single
catch
clause.
Simplifications
A number of shortcuts have been made in this design round of the commerce layer
transaction service. The intention is that shortcuts and simplifications will only be made
in the implementation of the commerce layer services and not in the service interface. The
simplifications have been made to focus the attention on the implementation of services
that will be used by the SEMPER Bargainer application.
- Access control
- Access control is not yet implemented in the commerce layer as we don't expect that all
other modules will support it in the short term. The service interface support access
control, and some methods require the caller to pass an access control handle. Any
reference not
null
can be passed to these method. Passing a null
reference will result in an access control exception being thrown.
- Transaction authorisation
- Some transaction requests must be authorised by the user unless the requests are made by
trusted applications. The Bargainer application is assumed to be trusted so the
authorisation will not be implemented in the first version of the commerce layer.