Transfer- and Exchangelayer Contexts

Authors: J. Brauckmann (SRB)
@version [CVS] @(#) $Id: index.html,v 1.18 1998/07/14 09:06:49 semper Exp $

This package implements TXLayer contexts. We introduced them to support a connection oriented transfer and exchange service.

TXContexts are used to generate TXSubContexts. TXSubContexts are used in preparing the various Transaction types for sending, receiving, originating and responding. An example:

     TransferTransaction tta;
     TXContext txcontext;


When you call getSubContext(n), you specify an integer n, which must be the same for both peers. The integer defines some kind of "Subchannel" inside the TXContext, which allows for multiplexing over one TXContext. We recommend to take some long-term values, such as 1.

The subcontext values 99990 to 99999 are intended for internal use by the TXLayer.

In addition to the usage in preparing TransferTransactions, a TXContext has read and write methods that can be used to transfer arbitrary Serializable objects.

To create a TXContext, you can fix four things: A hostname of the peer to communicate with, a CLAddress, a SituationDescription for fixing your own name, the name of the peer and the name of the BA that called us thru the CL, and an AttributeSet.

A hostname is to be passed as an Object of type TXHostname. It must be a valid name of the internet host the peer you want to communicate with runs her SEMPER on.

A CLAddress is a String that must be the same for both peers. You might perhaps want to use some long term identifiers like "ORDER" or "OFFER" or sth. like that.

	CLAddress claddress = new CLAddress("ORDER");

For a description of what a SituationDescription is, please have a look at the certificate block where it is defined. You may pass a SituationDescription without any information in it, created by, e.g., SituationDescription sd = new SituationDescription(null,null,null);. If you specify real values, you must be sure that you or your peer have certificates with the specified names.

An AttributeSet specifies the security attributes to use, see Package txlayer/attribute. An empty AttributeSet will do fine for a first start. Note that you can specify additional security attributes when preparing a transaction. Currently valid attributes are Confidentiality and Authenticity

AttributeSet secattribs = new AttributeSet();

When you have these four things, you can create a fully specified TXContext:

        TXContext txc = new TXContext(peerHostname, claddress, situationDescription, secattribs);

However, there are various constructors with less parameters. The minimal constructor, usefull only for accepting TXContexts, is:

        TXContext txc = new TXContext(claddress);

The minimal constructor usefull for offering TXContexts is:

        TXContext txc = new TXContext(peerHostname, claddress);

Now you can accept an incoming context that matches your parameters.

Peer A:	txc_send.offerContext(userdata); 
Peer B:	userdata = txc_receive.acceptContext(); 

On connection establishment the user data object is transmitted from the party using offerContext() to the party using acceptContext() where it pops out as a return value. It is possible to omit it.

Thats it!

Both parties can learn the username of the peer by using

   String peerUsername = txcontext.getSituationDescription().getPeerName();

A context that has been offered or accepted must be closed before it can be used again.


It is possible to clone a TXContext. After it is cloned, it can be offered or accepted again.

     txc_send2 = (TXContext) txc_send.clone();

For a usage example, see the test programs and in ../test.


When dealing with TXContexts, the following exceptions might be thrown:

Configuration options

Normally, a call to TXContext.init() (which is automatically done in Library.init() at the beginning of every SEMPER session) results in a listener to be opened. This means that there cannot be two SEMPER programms on one host running, because both try to register a listener on the same port, which will fail.

To prevent the txlayer from opening a listener, you can include the following line into your _sempconfig file:

	#semper.txlayer.noListeners 1

Alternatively you can use:

        #semper.noListeners 1
which may affect other blocks too.

Beware: You will not be able to use any call to TXContext.acceptContext() with disabled listeners!

Classes and Interfaces

Addressing and nameing: Contexts: Exceptions: Misc.:

How it works internally

All the constructors for TXContexts just store their parameters. No further action is done in the constructor.

On calling acceptContext, first two responder channels are opened, one for reading and one for writing. Then a TXQueue is created with the two channels and started. Afterwards the transaction ID of the party accepting the context and the user data object is read.

On calling offerContext, first two initiator channels are opened, one for reading and one for writing. Then a TXQueue is created with the two channels and started. Afterwards the transaction ID and the user data object is written.

A TXSubContext contains all attributes of its parent TXContext or TXSubContext. It has a reference to the TXQueues object that is responsible for multiplexing/demultiplexing.