Gumbo 030918

The Gumbo project is an open source project that provides an API (patterns) and library (services) for support of desktop applications with compelling 2D/3D user interfaces. Particular emphasis is placed on direct manipulation in desktop applications; however, passive visualization and immersive VR applications should also benefit.

See:
Description

Packages

gumbo.app
gumbo.graphic	Provides interfaces, services, and utilities that support application development independent of the implementing graphics technology, dimensionality, and precision.
gumbo.graphic.content
gumbo.graphic.impl.swing
gumbo.graphic.input
gumbo.graphic.input.impl.swing
gumbo.graphic.math
gumbo.graphic.probe
gumbo.graphic.space
gumbo.interact	Provides special purpose building blocks for user interaction, including user feedback.
gumbo.interact.button
gumbo.interact.select
gumbo.net	Provides special purpose application-level building blocks for networked application nodes, including clients, servers, and proxy servers.
gumbo.net.msg	Provides special purpose building blocks for building, writing and reading application-specific network messages.
gumbo.net.msg.ascii
gumbo.util	Provides general purpose low-level utilities, with particular emphasis on patterns and services for delegation of data relationships.
gumbo.util.relation
gumbo.util.route	Provides interfaces, services, and utilities that support the "routing" of events, with or without data, between objects.
gumbo.util.state
gumbo.visualize.data	Provides special purpose building blocks for 2D/3D visualization of generic data structures, such as graphs.
gumbo.visualize.data.client
gumbo.visualize.data.consistency
gumbo.visualize.data.impl.swing
gumbo.visualize.data.layout	Provides special purpose building blocks for 2D/3D layout in support of data visualization.

The Gumbo project is an open source project that provides an API (patterns) and library (services) for support of desktop applications with compelling 2D/3D user interfaces. Particular emphasis is placed on direct manipulation in desktop applications; however, passive visualization and immersive VR applications should also benefit. Rather than being an end unto itself this work serves as a means for combining and enhancing widgets, data models, and ingredients from other sources to form a rich user interface gumbo.

The attributes of this package are...

• Ranges from general purpose low-level utilities to special purpose building-block classes.
• Focus on 2D/3D patterns and services for desktop application GUIs.
• Implementation emphasizes dimensional and graphics technology independence.

Background

This work expands on the principles and code base described in the recent book "3D User Interfaces with Java 3D " published by Manning. Rather than focusing on GUI widgets and a particular graphics dimensionality or technology, the project instead offers architectural patterns and building blocks for MVC, delegation, event routing, in-scene manipulation, navigation, data visualization, interaction dynamics, etc.

Fundamental to this work is an abstraction of the graphics layer, allowing the API and library to work with most any graphics system (AWT, Swing, GL4, VRML, Java 3D, and what may come). The bridge pattern together with a set of generic math classes (tuple, point, etc.) allow independence from the implementing graphics technology, its dimensionality, and its data precision (int, float, etc.). (See gumbo.graphic)

Package Conventions

Each Java package in the Gumbo package hierarchy contains a package.html file describing that package. Collectively they provide an overview of the Gumbo API philosophy, organization, use, and design decisions. Further details are provided in the javadoc for the package classes and interfaces.

Top-level packages contain interfaces and classes closely related by pattern, function, or implementation. Emphasis is on having many narrowly defined packages rather than a few broad ones, which better reflects the multi-faceted nature of this project.

Utilities Conventions

Static constants and methods, collectively called utilities, can be associated with a package, a class, an interface, or a group of related classes and interfaces. Package utilities are provided in a class named for the package, such as the Graphic utility class in the gumbo.graphic package. For situations where this convention causes conflicts with common Java utility classes, the utility class name will include Gumbo, such as the GumboUtil and GumboCollections classes in the gumbo.util package.

Utilities associated with a class are simply included in the class. Utilities associated with an interface, or a group of classes and interfaces are provided in a class named for the plural of the interface, or a common class or interface. For example, in the gumbo.util package, utilities related to the TreeNode interface and its sub-interfaces are found in the TreeNodes class.

All utility classes use a private constructor to prevent instantiation (and, as a result, subclassing).

Interface Conventions

Most interfaces are accompanied by some form of implementation class, which are provided as a convenience, an example, and/or as a usable service. Partial implementations, which are abstract classes, and implementations of "abstract" interfaces, which are not considered a complete service, are named Abstract???. Full implementations that can stand on their own as a service are named Concrete??? or ???Service.

For many interfaces it is not necessary to support all of the methods. Unsupported methods can perform some null function or throw an unsupported operation exception. Also, some methods may impose restrictions, via runtime exceptions, on parameters, such as requiring a more restrictive data type, disallowing nulls and duplicates, or requiring parameter objects to be in a certain state.

Some interfaces require special methods used exclusively for implementation. By convention, such methods are named impl???(). Implementation methods are intended for internal use by the interface implentor, and typically perform some cooperative low-level portion of a high-level user function. As such, implementation methods generally assume a safe environment, performing little if any parameter validation or error checking. Their use by the external interface user may produce an inconsistent or corrupt internal state in the interface implementation.

Coding Conventions

Mutability

In general, the javadoc for a method that serves as a master mutator states so. A master mutator is one that all other mutators in a class or subclass should use. Adherence to this contract and the exclusive use of private fields facilitates creation of immutable versions of a class.

Accessibility

In general, the javadoc for a method that serves as a master accessor states so. A master accessor is one that all other accessors in a class or subclass should use. Adherence to this contract and the exclusive use of private fields facilitates observation of the class state.

Null Parameters

In general, the javadoc for a parameter or return that can be null states so. If a parameter can be null, the conditions under which it can be null and the result of it being null are noted.

Return Value

There are several ways for a method to return a value. In general, creation and return of new objects is avoided, except by factory methods. The most common ones used in Gumbo are to return a reference object, to return an immutable view, or to copy the value into a return value object, which the client provides. In general, Gumbo uses the following guidelines.

• Reference object: A reference object provides the client with a dynamic and mutable view of the object. A reference object is returned if the object's state is not part of the host object's state. Thus, mutating the object will not have a negative impact on the host object.
• Immutable view: An immutable view comes in two forms. An immutable reference provides the client with a dynamic view of the host object's state. An immutable snapshot must be used or saved by the client immediately. In either case, clients must consider concurrency since the object is owned by the host object. An immutable view is often used by accessors returning an element in the object's state. The presumption is that the host object already has the state object and returning an immutable form is more convenient for the client to use.
• Return value object: A return value object is used by accessors and utility methods when returning a value derived from the host object's state, or where concurrency may be an issue. The presumption is that the object does not actually exist in the host (or the host doesn't want to own it) and therefore it makes more sense for the client to provide it.

Comments

Javadoc is used throughout for all public and protected members, and for many package and private members as well. Comments within a code block may be nested, which is indicated by the number of slashes used for the comment. Typically, only two levels of nesting are needed (otherwise the code should be broken up into separate methods for clarity).

public void myMethod {
// do something
...
/// do the first part of something
...
while(...) {
// do something in the loop
}

//// do a part of a part of something
...
/// do the second part of something
...
// do something else
}

Framework Conventions

The framework proper consists of functional building blocks that the client connects using event routes. Event routing is an event model where the wiring of directional events between objects is made explicit. Its purpose is to allow clients to easily build higher level function blocks from lower level ones provided with this framework. Provisions are included to block event loops and to aggregate routes.

Functional building blocks typically end with a name describing the general nature or form of the block. The block types are as follows. Note that these designations are unavoidably subjective in nature and somewhat ambiguous.

Sensor

A sensor is a fundamental source of data, such as that provided by a mouse or keyboard. As such a sensor has no significant input events, only output events. The term is also loosely applied to higher level blocks that are commonly treated as fundamental data sources, and in some native graphic systems may be implemented as such. For example, a pick sensor produces a pick as a pseudo-source data type.

Trigger

A trigger monitors input events and fires an event of a different type when trigger conditions are satisfied.

Filter

A filter has the same basic input and output event type, with the block modifying the data in some significant and continuous manner. The modification can be qualitative, quantitative, or temporal, such as a change in sampling interval.

Mapper

A mapper transforms or maps data from an input space to an output space, which may be different event types. The mapping process can be continuous (like a filter) or discrete (like a trigger).

Gesture

A gesture interprets low level user inputs as a combined higher level user output. Interpretation may incorporate temporal factors, such as a jerk versus a drag. A gesture can have qualities of a trigger, filter and mapper, but has a more specific purpose.

Engine

An engine provides a general interface for specific implementations of a strategy (as in the Strategy software pattern). An engine, unlike other block types that involve strategy implementation, is rather low-level, narrowly defined, and kernel-like in nature. For example, a pick engine serves as the core for a pick sensor.

Adapter

An adapter converts an input event type into a different output event type that is more or less equivalent in nature or purpose (as in the Adapter software pattern). An adapter, unlike other block types, is rather low-level and simplistic in nature.

Facade

A facade provides a simplified interface for a common but complex set of building blocks (as in the Facade software pattern). For example, a selection facade incorporates picking, mapping, and feedback adapters.