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

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.

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.

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.

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.

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.

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.

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.

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.