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;

     tta.prepareSender(txcontext.getSubContext(1));

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.

     txc_send.close();

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

     txc_send2 = (TXContext) txc_send.clone();
     txc_send2.offerContext();

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

Exceptions

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

```
TXContextNotAccepted
```
This exception is thrown when a method invocation to offerContext
- is timed out because there was no corresponding acceptContext call
- failed because the peer is not initialized or does not exist.

```
TXContextNotOffered
```
This exception is thrown when a method invocation to acceptContext is timed out because there was no corresponding offerContext call from a client.
```
TXContextCommException
```
This exception is thrown on all kinds of other communication errors. Another reason for this exception may be that you set semper.noListeners 1 or semper.txlayer.noListeners 1 in your _sempconfig-file and are trying to use the acceptContext() method. This must fail, because acceptContext() needs an listener.

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:

CLAddress Must be present when opening a TXContext.
TXHostname The internet name of the host to connect to or the name of the local machine.

Contexts:

TXBaseContext Base class for all contexts.
TXContext The class the user of the context package has to use.
TXSubContext An internal species of TXContexts.

Exceptions:

TXContextCommException Misc. Comm errors.
TXContextNotAccepted Failures when offering a TXContext. Peer did not do a correct acceptContext().
TXContextNotOffered Failures when accepting a TXContext. Peer did not do a correct offerContext().

Misc.:

TXContextMessage Internal message class, not for public use.
TXQueues Internal class, not for public use.

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.