Contents
----------------------------------

1. About Panckoucke
   
2. The two parts of Panckoucke
   


3. The API in more detail

   The panckoucke-flow
   

   Event-Notification
   

   Abstraction model
   

   The Abstractor
   

   The AbstractionContext
   

   The AbstractionContributor
   

   Rendering the model
   

   
   
4. Developing with the implementation
   

The panckoucke-flow
----------------------------------

The fundamental idea behind panckoucke is: The abstraction process should be the last location where topicmap-specific business logic is required. After leaving the panckoucke-abstraction-process, towards the user interface, the hosting application deals with the "Abstraction Model", which is completly defined in panckoucke and does not point over itself back to Topicmap specific ideas, constraints, ways of expressing meanings etc..

The panckoucke defined flow includes the following steps:

1. Selecting a TopicMap-Element
2. Generating an abstract model for that element
3. Rendering the model
4. User selects an Element
5. and so on...

Event-Notification
----------------------------------

Panckoucke defines a very basic set of Events which may occur in a TopicMap-Application. The most important one is the TMO_Selected-Event (TMO stands for topic map object). Other Eventtypes include events which should be send on opening and closing a topicmap.

Despite of the Eventtypes, the core defines a Listener-Interface which must be implemented by custom classes, in order to receive Panckoucke-Events. The Panckoucke - Implementation contains an EventDispatcher which is able to send the panckoucke-Events to the registered Listeners. Furthermore the EventDispatcher defines Util-Methods to send Events with a single method call.

The Abstraction Model
----------------------------------

The AbstractionModel is the basic data structure of panckoucke. A model is always centered around one distinct node. It is generated by an org.tm4j.tmnav.panckoucke.core.abstraction.Abstractor for a distinct TopicMapObject in focus. Later on, it is passed to a renderer, which will present the model to the user.

The shape of the model describes a generic graph, suitable for very different displaying purposes. The graph has the following properties:

• Nodes are connected via directed arcs
• One Node is labeled as the "centerNode"
• An arc starts at exactly one node and connects it to 1 or many other nodes.
• Nodes and Arcs may be labeled
• Nodes and Arcs may represent one ore more topic map objects
• An upcoming alpha-version will introduce the ability to add type-information to arcs, nodes and represented objects

Panckoucke defines five Interfaces for dealing with the AbstractionModel. Theese Interfaces are located in org.tm4j.tmnav.panckoucke.core.abstraction.model.

AModelFactory

a factory for creating models

AModel

the model-API is used by abstractors to generate models. Afterwards the generated model is passed to the renderer

AMMember

the base-interface for arcs and nodes. This interface defines the common properties of the two structures

AMNode

contains API to retrieve properties of a node

AMArc

contains API to retrieve properties of an arc

Please pay attention to the fact, that neither AMNode nor AMArc contains API to manipulate the underlying graph. All manipulation of the graph is done through the AModel implementing class. AMNode and AMArc are used only to traverse the graph, not to manipulate it.

The Abstractor
----------------------------------

The Abstractor is the place where topicmap-specific business logic is used to create an generic, abstract model for a given TopicMap-Object.

This is the location where you control what information your app displays to the user.

The Abstractor-Interface defines two methods. The method "supportsAbstraction" is intended to allow applicatons to determine if a concrete abstractor is able to provide an abstraction model for a concrete TopicMapObject.

The second method, "generateModel" is used to generate the model. Please have a look at Writing a custom abstractor for a more in depth discussion of the Abstractor - interface

The AbstractionContext
----------------------------------

The AbstractionContext was created with the idea to provide a strategy to make the abstraction process configurable. By now, the panckoucke-implementation does not use the abstractionContext at all, and it is predictable that the AbstractionContext will massively change, since the idea behind it's design seems to be wrong.

The AbstractionContributor
----------------------------------

This Interface is intended to allow developpers to modularize the abstractionProcess and therefore make code more reusable. It defines one method (public void contribute (AModel model, TopicMapObject tmo, AbstractionContext ac)) which may be called by Abstractors while building the model. The contributor may or may not contribute some nodes and arcs to the model

Rendering the model
----------------------------------

This is the last step in the panckoucke-flow and the one which is most dependant of a concrete application. The Renderer-Interface contains just one method "renderModel" which is used to render panckoucke models.