Millstone

This package is the base of the Millstone library. The base package contains the Application class, the starting point of the Millstone Terminal Independent application. The sub-packages from this point contain application components and utilities.

Package Specification

The Millstone library base is composed of the following packages:

• org.millstone.base.data


A library of interfaces for transparently binding UI components to datasources.
• org.millstone.base.data.util
Basic implementations of data-intfaces and utilities for working with data-bound components.
• org.millstone.base.data.validator
Classes providing data-validation for Properties.
• org.millstone.base.event
Interfaces defining how to send and recieve events.
• org.millstone.base.service
Classes provding miscelaneous utility services.
• org.millstone.base.terminal
Classes and interfaces for implementing the terminal specific adapters.
• org.millstone.base.ui
The Millstone UI components.

Provides interfaces for the MillStone data layer which contains classes for typed data values, data collections, and handlers. A {@link org.millstone.base.data.Property Property} is a simple typed data value; an {@link org.millstone.base.data.Item Item} is a collection of Properties, each corresponding to a unique identifier; a {@link org.millstone.base.data.Container Container} is a collection of identified Items with special constraints; a {@link org.millstone.base.data.Buffered Buffered} class is able to track its changes and to commit or discard them later.

Package Specification

The package contains a three-tiered structure for typed data objects and collections of them:

• The simplest of these is the {@link org.millstone.base.data.Property Property} which represents a single typed data value. A Property may be read-only in which case attempts to modify its contents will throw an exception.
• The second level of the data layer is represented by the {@link org.millstone.base.data.Item Item} which embodies a set of Properties. Each Property in an Item corresponds to a locally unique(that is, inside the Item) identifier.
• The third level is called the {@link org.millstone.base.data.Container Container} which can be visualized as a set of Items, each corresponding to a locally unique identifier. Note that the Container imposes a few restrictions on the data stored in it, see further documentation in the class specification.

In addition to these interfaces the package contains the {@link org.millstone.base.data.Buffered Buffered} interface, which defines the methods to make an object buffered, that is, track the changes to an object and allow committing or discarding them at a later time.

Provides interfaces for the MillStone validation framework. The framework defines two interfaces; one for classes that need to support external validation, and another one for the validators themselves.

Validation

The most important method defined by the {@link org.millstone.base.data.Validatable Validatable} interface is {@link org.millstone.base.data.Validatable#isValid() isValid()}. It asks all registered validators to verify if the object's value is valid or not. Note that it depends on the validators registered for a object which values are valid and which are not. For example, a null value can be valid value for one validator but invalid for another.

In addition to isValid(), Validatable defines methods to add, remove and list validators of a validatable object.

{@link org.millstone.base.data.Validator Validator} defines the interface for an external validator. These validators may be added to any Validatable object, and their task is to check, when requested, that the object which they are attached to contains a valid value. The actual validation logic is hidden in the {@link org.millstone.base.data.Validator#validate(Object) validate(Object)} method.

In addition to check(Object), Validator defines the InvalidValueException which is used to signal that a checked value is invalid, and the {@link org.millstone.base.data.Validator.Suggestive Suggestive} subinterface which includes functionality to suggest a valid value for the validated object.

Provides various utility classes that implement the MillStone data layer functionality.

The first {@link org.millstone.base.data.Property Property} class, {@link org.millstone.base.data.util.ObjectProperty ObjectProperty}, provides a simple class containing a typed data value. The second, {@link org.millstone.base.data.util.MethodProperty MethodProperty}, provides a way to bind a field of an object to the Property interface using the accessor methods for the field.

The next level of the MillStone data layer, the {@link org.millstone.base.data.Item Item}, is implemented by {@link org.millstone.base.data.util.BeanItem BeanItem}, though it is only a simple wrapper to the former to provide the Item interface for any regular Java Bean.

The third level, the {@link org.millstone.base.data.Container Container}, has several implementations in the {@link org.millstone.base.data.util} package.

Provides validators for data contained in data-bound objects..

Provides classes and interfaces for the MillStone inheritable event model. The model supports inheritable events and a flexible way of registering and unregistering event listeners. It's a fundamental building block of the MillStone framework, and as it is included in {@link org.millstone.base.ui.AbstractComponent}, all UI components automatically support it.

Package Specification

The core of the MillStone event model is the inheritable event class hierarchy, and the {@link org.millstone.base.event.EventRouter EventRouter} which provide a simple, ubiquitous mechanism to transport events to all interested parties.

The power of the event inheritance arises from the possibility of receiving not only the events of the registered type, but also the ones which are inherited from it. For example, let's assume that there are the events GeneralEvent and SpecializedEvent so that the latter inherits the former. Furthermore we have an object A which registers to receive GeneralEvent type events from the object B. A would of course receive all GeneralEvents generated by B, but in addition to this, A would also receive all SpecializedEvents generated by B. However, if B generates some other events that do not have GeneralEvent as an ancestor, A would not receive them unless it registers to listen for them, too.

The interface to attaching and detaching listeners to and from an object works with methods. One specifies the event that should trigger the listener, the trigger method that should be called when a suitable event occurs and the object owning the method. From these a new listener is constructed and added to the event router of the specified component.

The interface is defined in {@link org.millstone.base.event.MethodEventSource MethodEventSource}, and a straightforward implementation of it is defined in {@link org.millstone.base.event.EventRouter EventRouter} which also includes a method to actually fire the events.

All fired events are passed to all registered listeners, which are of type {@link org.millstone.base.event.ListenerMethod ListenerMethod}. The listener then checks if the event type matches with the specified event type and calls the specified trigger method if it does.

Provides some general service classes used throughout a MillStone application.

Provides classes and interfaces that wrap the terminal-side functionalities for the server-side application. (FIXME: This could be a little more descriptive and wordy.)

Package Specification

Provides interfaces and classes in the the MillStone UI component library.

Package Specification

Interface hierarchy

The general interface hierarchy looks like this:

Note that the above picture includes only the main interfaces. This package includes several other lesser subinterfaces which are not significant in this scope. The interfaces not appearing here are documented with the classes that define them.

The {@link org.millstone.base.ui.Component} interface is the top-level interface which must be implemented by all UI components. It defines the common properties of the components and how the framework will handle them. Most simple components (like {@link org.millstone.base.ui.Button} for example} won't need to implement the lower level interfaces described below. Note that the classes and interfaces required by the component event framework are defined in {@link org.millstone.base.ui.Component}.

The next level in the component hierarchy are the classes implementing the {@link org.millstone.base.ui.ComponentContainer} interface. It adds the capacity to contain other components to {@link org.millstone.base.ui.Component} with a simple API.

The third and last level is the {@link org.millstone.base.ui.Layout}, which adds the concept of location to the components contained in a {@link org.millstone.base.ui.ComponentContainer}. It can be used to create containers whose contents can be positioned arbitrarily.

Component class hierarchy

The actual component classes form a hierarchy like this:

At the top level is {@link org.millstone.base.ui.AbstractComponent} which implements the {@link org.millstone.base.ui.Component} interface. As the name suggests it is abstract, but it does include a default implementation for all methods defined in Component so that a component is free to override only those functionalities it needs.

As seen in the picture, AbstractComponent serves as the superclass for several "real" components, but it also has a some abstract extensions. {@link org.millstone.base.ui.AbstractComponentContainer} serves as the root class for all components (for example, panels and windows) who can contain other components. {@link org.millstone.base.ui.AbstractField}, on the other hand, implements several interfaces to provide a base class for components that are used for data display and manipulation.

Provides the functionality of the MillStone Web Adapter, which adapts the MillStone applications to Web standards. (FIXME: We need a rather more extensive lithany here.)

Package Specification