ACCORD Tangible Toolbox Developers Guide

Introduction

This document is meant as a guide for developers who intend to modify or extend some parts of the Tangible Toolbox. Start with making sure you are familiar with the structure and functionality of the Toolbox. The User Guide Appendix gives more information on the system structure but also look at the User Guide to make sure you understand fundamental concepts of the Toolbox and how they are used.

This guide is divided into the following sections:

The Source Code Access section describes how to get hold of the publice source code
The Equip section describes Equip briefly, how to obtain it, and how it's used for the ACCORD toolbox.
In ACCORD Source Structure the layout of the directory structure is explained.
The following four sections, Toolbox, Editors, Transformers and Services describe how to modify and extend the existing parts.
The last section lists Known Issues with the current release.

Source Code Access

The source code will be made available at the ACCORD website at http://www.sics.se/accord.

Equip

Equip is a data distribution infrastructure based on tuple spaces. It utilizes the notion of a dataspace in which data objects reside. The dataspace is populated by cross-platform data objects. Patterns are used to match and retrieve the current states of these objects in the dataspace. Subscribing to data patterns, such as via a template object sharing a subset of the same field values as the interested object in the dataspace.
Accord makes use EQUIP to mediate the network communications between its components. JavaBeans is the model used for defining interchangeable data between ACCORD components. The bean instance specification (omiting internal states) is converted into an equip object. Each internal accessible bean property generates an equip object. This model is to ensure that only changes in a single property value is relayed in the dataspace, and not the entire bean state.
For more spcifics on equip, read documentation and papers available mostly through Chris Greenhalgh at Nottingham University and the Equator project.

ACCORD Source Structure

The main parts of the ACCORD toolbox source hierarchy have the following structure:


apps/
 lib/ - separate support packages, local and external
 services/ - support service software, for example for hardware dependent services like SMS server, webserver log watcher, etc.

 transformers/ - transformer beans, each contained in sub-directory

docs/ - this documentation

toolbox/
src/

  accord/

   toolbox/

    access/ - Classes for handling user and access rights in equip.  Supposedly generic for any kind of bean and not toolbox-specific.
    beans/ - BeanManager and local event model for bean, property and link events.
    editors/ - jigsaw, graph, PDA, paper editor code.
    equipbeans/ - Utilities for launching beans into equip space
    equiptools/ - Contains the EquipConnector, which handles primary access to EQUIP services.
    gui/ - Generic graphical classes for designing guis and handling media.
    util/ - Miscelaneous utilities for file input/output, storing config properties, etc.

The Toolbox Core Components

The ACCORD toolbox can be regarded as bestowed of four parts:

The core components for managing the communication of data, utilities, access management, user profile management, and so on.
The EQUIP utilities for using EQUIP as the infrastructure of data sharing.
The dataspace editors, including graphics middleware, for composing and editing services deviced through the toolkit.
The transformer and services libraries, comprising of components, tools, and ready-to-run software for envisioned scenarios.

The main ACCORD toolbox libraries comprises all but the last of these, and are as follows ...

accord.toolbox.gui
Generic graphical classes for designing guis and handling media.

accord.toolbox.beans
BeanManager and local event model for bean, property and link events.

accord.toolbox.access
Classes for handling User and access rights in equip. Supposedly generic for any kind of bean and not toolbox specific.

accord.toolbox.equipbeans
Utilities for launching beans into equip space.

accord.toolbox.equiptools
Contains the EquipConnector, which handles primary access to EQUIP services.

accord.toolbox.editors.puzzleeditor
Jigsaw editor, uses the accord.toolbox.gui files.

accord.toolbox.editors.PDAEditor
Java 1.1 targeted code, for PDAs running ex Jeode.

accord.toolbox.editors.papereditor
ACREO's editor for RFID paper editor.

accord.toolbox.editors.grapheditor
Original nottingham diagram editor.

accord.toolbox.util
Miscelaneous utilities for file input/output, storing config properties, etc.

Creating, Modifying or Extending the Editors

The accord.toolbox.gui package provides a set of middle-ware components to quickly develop graphical editors. It describes a drawing canvas in which to manipulate canvas items in a number of ways. it provides functionality for adding, removing, moving, connecting items, and devices for self-maintenance of the canvas surface. It provides components for rendering backdrops and timed paint calls. It provides utilities for handling and managing image and audio media to be used with the editors. It provides drag and drop functionality for items in the canvas.

Any editing canvas should extend the InteractiveCanvas class, and any items within the InteractiveCanvasItem. The Canvas is itself a JDesktop pane, which can render lightweight internal frames as well as any lightweight Swing component.

Attractors are components which can be embedded in InteractiveCanvasItems or anywhere else to specify points of connection. They can act as gravitational points, translating itself and any parent item automatically to the origo of any other attractor within its range.

See the java documentation for specifics on all the toolbox classes.

Modifying or Extending the Transformers

Each component in the system can be thought of as a digital/physical transformer that provides a conduit between the real and the digital. Each transformer has a set of properties that it uses to make information digitally available. The values of these properties are shared through a distributed data space. The dataspace is dynamic and reacts to changes in the values of properties; propagating these changes to all the components that share these properties. For more background info, see the Understanding and Using the Tangible Toolbox deliverable.

The easiest way to get started writing your own transformer, take a look at one of the other transformers in their subdirectories under accord/transformers/. There is also a minimal example transformer implemented called ExampleBean, see the ExampleBean.java with its ExampleBeanBeanInfo.java, or ExampleBean javadoc which publishes a text string which it updates once on startup.

The important points about a transformer:

Published properties should be declared private.
There needs to be a get... and a set... method for each published property, which should be declared along the properties in the BeanInfo file.
Extending the SimpleBean class lets you skip some of the property propagating code, as well as icon handling code.

A set of guidelines are available to help develop new bean transformers.

Modifying or Extending the Services

Some of the transformers require some kind of supporting software due to dependency on external hardware or web services. We've called these support packages services, and they are located under accord/apps/services/ in the source tree. Brief descriptions of the services supplied with this release and how to use them can be found in the User Guide Appendix : services. Since this support software is very specialized depending on what it's supporting, there cannot really be any general advice on how to modify or build new ones. They generally involve fairly little code, mostly written in java or tcl. Some of the may use external support packages, found under accord/apps/lib/java/. Also, some of the hardware-dependent services make use of the

Known Issues

The GSM SMS Gnokii software have had problems at times, moreso during heavier loads.