The Container Package

of the Transfer And Exchange Layer (txlayer.container)

Editor: T. Beiler (SRB)
@version [CVS] @(#) $Id: index.html,v 1.1 1997/07/28 16:34:27 semper Exp $

Introduction

Container are a means to bundle a number of items in order to apply a service to all of them. In SEMPER containers are used to bundle items in order to perform a transfer with them or to exchange the container as a whole with another container of another player. The items inside are also called goods since SEMPER mainly deals with trading over the internet. Items which can be put into a container have the ability to be contained. This is explained in more detail later. In comparison to a set, the contained items can occur more than once, and they have a sequence not affected by the container itself. The container can simply be seen as a list (in java a vector). Like lists, containers can be nested, and form therefore a tree.

A container groups items together, and so the contained items can use it to communicate with each other. For example, this might be neccessary, if an item can only be contained together with other items and therefore has to check if these are already contained.

An item's property of being containable is expressed in an java-interface, Containable. This includes mainly, that a containable item is notified when it is adopted by a container. The item may reject its insertion in that container.

Since the goods which are expected to be contained are already existing and therefore can be categorized considering some properties, there are so called container adapters, which form a connection between those categorized items and a container. Adapters then map the expected functionality of a containable item to the actual item. From the view of container this makes no difference. For to unite the properties of several adapters, they may be eventually chained (an idea of M. Steiner). But this is still to be investigated, and the outlook is that this needs additional adapters. The one who wants to put an item into a container, has the task either to choose an appropriate existing adapter, or to build a new one, or to extend that special item with the required functionality. This points becomes more important, if a specialisation of containers, like a transfer container, is used: The one who wants to insert that item has to determine what the meaning of 'transfer' to this item exactly is, and then she can choose an adequate adapter.

A container offers the following families of methods:

  • construction insert, delete, append, isElement, elementAt, size checkInsertion
  • checkDeletion, checkAppend (are coming later, when the neccessity is more clear)

    • Classes and Interfaces

    Interface Containable

    This interface intended to implement a mutual callback (or as  I suppose: in other words an instance connection). It is to enable communication via messages (method calls) between a container and its contained items, and between the items themselves. But not at the moment, there is no sophisticted communication implemented.

    Class Container

    The class container is similar to a list or a java vector, but it meets some additional constraints. Therefore some of the methods are leaned from the java.util.Vector class, but some are renamed, like append and delete, since I felt these names describe the method a bit more abstract than 'removeElement()'. But I did this not too consequent, the name 'elementAt' remained.

    A Container can only contain items that implement the interface Containable.

    There is set of constructors which make the construction of a container flexible. See below.

    Class ContainerAdapter

    This class may serve as a base class for derived ContainerAdapters, like the tranferable ones in the transfer package.

    Class ContainerDescription

    This class is very similar to Container. The only difference is that it does not container Containables, but instead it works with Describables (see description index.html).

    Usage of Containers

    How to fill a Container with Items

    Suppose, there are 2 items to put into a container, one of type ItemA and one of type ItemB; Somewhere in the code something like ... ItemA a; ItemB b; ... has been written.

    Suppose further that

  • for ItemA there exists a ContainerAdapter satisfying the desired properties, and this one may be called ContainerAdapterA,
  • for ItemB there exists a ContainerAdapter satisfying the desired properties, and this one may be called ContainerAdapterB.

    • Then the composition of a container goes like this:

    1. Container c = new Container();
2. c.append(new ContainerAdapter(a));
3. c.append(new ContainerAdapter(b));

    To make it easier to put a small and fixed number of items into a container like in the case before, a constructor takes up to 4 Containables as arguments:

    1. Container c = new Container(new ContainerAdapter(a), new ContainerAdapter(b));

    This is to work around that the compiler does not accept the form 

    1. Container c = new Container({a, b}); // would have been nice.

    and the accepted form

    1. Containable[] tmp = {a, b};        // Two lines is too much for this!!
2. Container c = new Container(tmp);

    is a bit complicated.

    It is also possible to construct a container with an array of Containables, or with a Vector of Containables. In the latter case an exception is thrown if one of the elements is not containable.

    When constructing a container it can be given at first a set of attributes. In all constructors this is the first argument. It is applied to the container before the first containable is inserted. This sequence is the reason why it the first in the parameter list.

    If an AttributeSet is omitted, a default AttributeSet is taken; this is normally the empty set.

    Way of plugging an Item into a Container, or how to be 'Containable'

    There are several ways how an item can be made contained by a container. One way, using adapters, was already shown in the above example. Here comes a list of some possibilities (covering also adapters):

  • If an item knows absolutely nothing about containers and containability, the best method is to use an adapter. This is the case if the class of this item was already existing before considering to apply a SEMPER service to it. The programmer who brings together that item and a container via such an adapter takes the responsibility that the adapter fulfills the interfaces in an appropriate way. The container sees the adapter and is convinced that the requirements are met, the adapter maps the requirements down to the item, and the item itself does not note anything of this.
  • If the programmers of the item have been known of the requirements of the tx-layer, and an adequate adapter exists, and the programmers want to have the possibility to be involved in the choice of exactly this adapter (maybe they know their item better than any other person), then they may provide a method like for example 'getAdapter()' which returns an instance of that adapter class. This can then be used to put it into a container.
  • If none of the existing adapters is appropriate for that type of item then there is no way other than creating a new adapter (or without adapter: to code directly in an extension of that class itself). Hopefully, the number of elements in the set of existing adapters is monotonly increasing and the need to write a new one will therefore decrease.