An exchange is a special transaction, in which two send each other party a collection of goods under consideration of a former agreement on these goods. The agreement states the good that each of both parties promises to to send, and it also states the expectation to the other party's goods. If the two tupels fit together the transaction of the goods can start. After the actual receiving of goods each party has to check that the promise of the other party was fulfilled.
Example:
Agreement part 1: Alice: " If you send me an B, i'll send you an A."
Agreement part 2: Bob: "O.k. If you really send me an A, I will send a B:"
Alice gives Bob an A', and Bob gives Alice the desired B'. To this point it is not sure that the A' is really the A they had been formerly speaking about. The same holds for B'.
Alice checks: B=B'?
Bob checks: A=A'?
If both checks are positive then both Alice and Bob are satisfied. Otherwise there has to a dispute for clearing this, invoked by one party.
Problems in the example:
An exchange as seen here is somehow abstract form the type of items to be exchanged. The only requirement is that they are describeable in some way. But there are dependencies on the items. The classification questions are here: Is an item revocable by a party? Is an item generatable by a third party? Is an item observable by a third (=external) party? Can an item be redirected via a third party? But all these questions are not further considered at the moment, so one should not take the existence of interfaces concerning these points too serious :-)
Logically in an exchange there is no one to start the exchange transaction, both parties have equal rights. But technically, the transactions cannot start at the same point of time, and therefore one has to start its transaction. But all this is done under the blanket and the parties themselves should not be bothered with negotiations about who starts.
The concepts involved are exchange transaction, describability and exchangeability, description.
The class ExchangeTransaction is derived from the class Transaction. It is a transaction composed of several TransferTransactions. Despite the asymmetry of TransferTransactions this type of transaction is almost symmetric. Asymmetric preparation is just needed for not conflicting TransactionIDs. Another difference to TransferTransactions is that there is (up to now) no need to customize an ExchangeTransaction to particular types of goods. Since ExchangeTransactions are expressed in terms of transfers, this is not necessary. The steps to do an exchange are given in the following list:
1. Create a container with some goods inside.
2. Create a Description of what you want to receive.
3. Create a new object of class ExchangeTransaction and pass the container
to its constructor.
4. Have a TXContext that is connected with the other side handy. (see
txcontext index.html)
5. Prepare the ExchangeTransaction, either being an Originator or a Responder.
Here the TXContext is needed, and also a Description of the expected
container is to be input.
6. Begin the transaction.
Here comes a program example:
Side 1 (Originator):
//--- Create some example items, and a container containing them:
ItemA item1 = new ItemA("GoodOriginator #1");
ItemA item2 = new ItemA("GoodOriginator #2");
Container c1 = new Container(item1, item2);
//--- Create some example descriptions, and a container description containing them:
ItemADescription item1d = new ItemADescription("GoodResponder #3");
ContainerDescription expectation = new ContainerDescription(item1d);
//--- Create a new exchange transaction on the container c1.
ExchangeTransaction et1 = new ExchangeTransaction(c1);
//--- Prepare as an Originator: although an exchange is symmetric, this is
//--- necessary for determining some internal things having a sequence.
//---
//--- txcontext is the one of the responder. The id specified in the call to
getSubContext is an integer that must be the same on the responder and originator side.
//---
//--- secAttributes describe the security attributes to apply to
this particular exchange.
//---
//--- The Expectation is of type Description (interface).
//---
et1.prepareOriginator(txcontext.getSubContext(id), offeredAttributes, requestedAttributes, expectation);
//--- Start the transaction, and block until it has finished. Also possible is
//--- begin(), which doesn't block and lets the transaction run asychronously
//--- compared to this caller's code.
et1.beginAndBlock();
//--- Now retrieve the received container:
Container received_container = (Container)et1.getObject();
Side 2 (responder): It is very similar to the originator's code, since exchange is symmetric.
//--- Create some example items, and a container containing them:
ItemA item3 = new ItemA("GoodResponder #3");
Container c2 = new Container(item3);
//--- Create some example descriptions, and a container description containing them:
ItemADescription item1d = new ItemADescription("GoodOriginator #1");
ItemADescription item2d = new ItemADescription("GoodOriginator #2");
ContainerDescription expectation = new ContainerDescription(item1d, item2d);
//--- Create a new exchange transaction on the container c2.
ExchangeTransaction et2 = new ExchangeTransaction(c2);
//--- Prepare as an Responder:
//---
//--- >txccontext is the one of the originator.
et2.prepareResponder(txcontext.getSubContext(id), offeredAttributes, requestedAttributes, expectation);
//--- Start the transaction.
et2.beginAndBlock();
//--- retrieve the received container:
Container received_container = (Container)et2.getObject();