Multivalent API

multivalent
Class Layer

java.lang.Object
  extended by multivalent.VObject
      extended by multivalent.Behavior
          extended by multivalent.Layer
Direct Known Subclasses:
PerPage

public class Layer
extends Behavior

Special behavior type that groups (1) behaviors (which can be nested Layer's) and (2) data trees of ESISNodes, and dispatches (round robin) protocol events over its collection. Every Document has at least one Layer to implement genre and document-specific functionality, and the Root's Layer holds all-document/pan-genre system functionality. Some behaviors store data in the trees; for instance, multipage documents store pagewise behaviors, and Note stores its content.

Layers are loaded from and saved to hubs, in which the case a constituant behavior's logical name is the tag or generic identifier (GI) and its attributes the tag's attributes; trees are stored as is. Because of this, behavior logical names are normalized to all lowercase. Behaviors are distinguished from data by a BEHAVIOR attribute.

Dispatches round robin (non-tree) protocols (restore, build, save, semantic events, ...) by recursing over the component behaviors. Tree-based protocols (format, paint, low-level events, ...) are handled elsewhere, by the document tree.

Works with Multipage as follows. Stores hub encompassing all pages in data tree keyed by page number. On buildBefore, if PAGE attribute on document, clears behaviors and instantiates relevant portion. Likewise, on "closedDocumentPage", saves current behaviors to data tree. Still loads full on Document.MSG_OPENED and saves everything to disk on "closedDocument".

Version:
$Revision: 1.18 $ $Date: 2005/01/01 04:02:15 $
See Also:
Multipage

Field Summary
static java.lang.String ATTR_ACTIVE
           
static java.lang.String BASE
          Standard name for layer that holds media adaptor for primary document.
static java.lang.String MSG_LOAD
          Load a layer as specified in a hub document, such as genre-specific behaviors or a set of annotations.
static java.lang.String PERSONAL
          Layer names are given by String's and usually known by convention, but some are defined, such as PERSONAL for personal annotations.
static java.lang.String PREFIX
           
static java.lang.String SCRATCH
          Standard name for layer that holds behaviors that have no semantic standing in the document.
static java.lang.String SHARED
          Standard name for layer that holds behaviors shared among other behaviors, although any layer can be shared by asking for the right name.
static java.lang.String SYSTEM
          Layer name for core behaviors, usually created by a document's media adaptor.
 
Fields inherited from class multivalent.Behavior
ATTR_BEHAVIOR, name_
 
Fields inherited from class multivalent.VObject
attr_
 
Constructor Summary
Layer()
           
 
Method Summary
protected  void addAux(ESISNode e)
          Add ESISNode tree to aux trees, if not already there (not a multilist).
 void addBehavior(Behavior be)
          A Behavior can only be in one layer at a time, so if it's already in a layer, it's removed from that layer first.
 int auxSize()
          Number of auxiliary trees (often 0).
 void buildAfter(Document doc)
          Iterates over component Behaviors (Layer is a subclass of Behavior), lowest priority to highest.
 void buildBefore(Document doc)
          Iterates over component Behaviors (Layer is a subclass of Behavior), highest priority to lowest, if layer is active.
 void buildBeforeAfter(Document doc)
           
 boolean checkRep()
          Checks "representation invariant" (see MIT SE), and returns true iff object is valid, which should be always
 void clear()
          Clears everything, behaviors and aux.
 void clearBehaviors()
          Removes all active behaviors from Layer, destroy()'ing in the process.
 void destroy()
          Iterates over component Behaviors (including nested Layer's), highest priority to lowest.
 void dump()
           
 void dump(int level)
           
 Behavior findBehavior(java.lang.String path)
          Given a layer pathname, finds nested layer.
 java.awt.Color getAnnoColor()
           
 NFont getAnnoFont()
           
 ESISNode getAux(java.lang.String tag)
          Returns tree of aux tree data with passed tag.
 ESISNode getAux(java.lang.String attrname, java.lang.String attrval)
          Returns tree of aux tree data with attribute name = val.
 Behavior getBehavior(int index)
           
 Behavior getBehavior(java.lang.String logicalname)
          Get behavior of given logical name, null if doesn't exist.
 Behavior getBehavior(java.lang.String logicalname, java.lang.String classname)
          Get (first) behavior of given logical name.
 Browser getBrowser()
          End of Layer chain.
 Document getDocument()
          Often end of Layer chain.
 Layer getInstance(java.lang.String logicalname)
          Constructs empty layer with given name, unless one by that name already exists, in which case that existing Layer is returned.
static Layer getInstance(java.lang.String logicalname, Document doc)
          Constructs top-most Layer of Layers in a Document.
 boolean isActive()
           
 boolean isEditable()
          For now, a layer is editable if its name is "personal".
protected  void removeAux(ESISNode e)
           
protected  void removeAux(java.lang.String attrname, java.lang.String attrval)
           
 void removeBehavior(Behavior be)
          Removes behavior from Layer as soon as pending semanticEvent roundrobins completed; if none, then remove immediately.
 void restore(ESISNode n, java.util.Map<java.lang.String,java.lang.Object> attr, Layer layer)
          Takes the place of a constructor's initialization functions; that is, it is invoked exactly once immediately after object instantiation.
 void restoreChildren(ESISNode n, Layer layer)
          Override definition in Behavior to keep immediate subtrees that aren't behaviors.
 ESISNode save()
          Iterate over auxiliary non-behavior trees, then component Behaviors highest priority to lowest.
 boolean semanticEventAfter(SemanticEvent se, java.lang.String msg)
          Iterates over component Behaviors, lowest priority to highest.
 boolean semanticEventBefore(SemanticEvent se, java.lang.String msg)
          Iterates over component Behaviors (including nested Layer's), highest priority to lowest.
 void setActive(boolean active)
          If a Layer is not active, all its component behaviors are still instantiated but not invoked during protocols.
 int size()
          Returns the numbers behaviors in the layer.
 
Methods inherited from class multivalent.Behavior
clipboardAfter, clipboardBefore, createUI, eventAfter, eventBefore, formatAfter, formatBefore, getInstance, getInstance, getLayer, getLogger, getName, getPreference, getRoot, paintAfter, paintBefore, putPreference, redo, setName, toString, undo
 
Methods inherited from class multivalent.VObject
attrEntrySetIterator, attrKeysIterator, clearAttributes, getAttr, getAttr, getAttributes, getGlobal, getValue, hasAttributes, putAttr, removeAttr, setAttributes
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

MSG_LOAD

public static final java.lang.String MSG_LOAD
Load a layer as specified in a hub document, such as genre-specific behaviors or a set of annotations.

"loadLayer": arg= URI location of hub

See Also:
Constant Field Values

SYSTEM

public static final java.lang.String SYSTEM
Layer name for core behaviors, usually created by a document's media adaptor.

See Also:
Constant Field Values

PERSONAL

public static final java.lang.String PERSONAL
Layer names are given by String's and usually known by convention, but some are defined, such as PERSONAL for personal annotations.

See Also:
Constant Field Values

SCRATCH

public static final java.lang.String SCRATCH
Standard name for layer that holds behaviors that have no semantic standing in the document.

See Also:
Constant Field Values

BASE

public static final java.lang.String BASE
Standard name for layer that holds media adaptor for primary document.

See Also:
Constant Field Values

SHARED

public static final java.lang.String SHARED
Standard name for layer that holds behaviors shared among other behaviors, although any layer can be shared by asking for the right name.

See Also:
Constant Field Values

ATTR_ACTIVE

public static final java.lang.String ATTR_ACTIVE
See Also:
Constant Field Values

PREFIX

public static final java.lang.String PREFIX
See Also:
Constant Field Values
Constructor Detail

Layer

public Layer()
Method Detail

getInstance

public static Layer getInstance(java.lang.String logicalname,
                                Document doc)
Constructs top-most Layer of Layers in a Document.


getInstance

public Layer getInstance(java.lang.String logicalname)
Constructs empty layer with given name, unless one by that name already exists, in which case that existing Layer is returned. Construction of a new layer nests within this layer. New layer is populated from all hubs by that name in all JARs and the uer's home directory; if there are no hubs, the result is an empty layer.

See Also:
getBehavior(String)

getAnnoColor

public java.awt.Color getAnnoColor()

getAnnoFont

public NFont getAnnoFont()

getBrowser

public Browser getBrowser()
End of Layer chain.

Overrides:
getBrowser in class Behavior

getDocument

public Document getDocument()
Often end of Layer chain.

Overrides:
getDocument in class Behavior

isEditable

public boolean isEditable()
For now, a layer is editable if its name is "personal".

Overrides:
isEditable in class Behavior

setActive

public void setActive(boolean active)
If a Layer is not active, all its component behaviors are still instantiated but not invoked during protocols. Layer directly controls build and semanticEvent, and without build there should be no attachments to the document tree for format, paint, .... Useful to disable Debugging layer, various annotation layers.


isActive

public boolean isActive()

addBehavior

public void addBehavior(Behavior be)
A Behavior can only be in one layer at a time, so if it's already in a layer, it's removed from that layer first. Behaviors added to layer during a protocol are ignored until the protocol (both before and after phases) cpmpletes in this Layer.


removeBehavior

public void removeBehavior(Behavior be)
Removes behavior from Layer as soon as pending semanticEvent roundrobins completed; if none, then remove immediately.


clearBehaviors

public void clearBehaviors()
Removes all active behaviors from Layer, destroy()'ing in the process. Also used in Anno/Wipe.


size

public int size()
Returns the numbers behaviors in the layer.


findBehavior

public Behavior findBehavior(java.lang.String path)
Given a layer pathname, finds nested layer.


getBehavior

public Behavior getBehavior(int index)

getBehavior

public Behavior getBehavior(java.lang.String logicalname)
Get behavior of given logical name, null if doesn't exist.


getBehavior

public Behavior getBehavior(java.lang.String logicalname,
                            java.lang.String classname)
Get (first) behavior of given logical name. If one doesn't exist, create with passed class name. To create a behavior regardless if one by that name already existes, use Behavior.getInstance(String, String, java.util.Map, Layer). To get all behaviors of given logical name, iterate over the list yourself from 0 .. size()-1 with getBehavior(int).


getAux

public ESISNode getAux(java.lang.String tag)
Returns tree of aux tree data with passed tag.


getAux

public ESISNode getAux(java.lang.String attrname,
                       java.lang.String attrval)
Returns tree of aux tree data with attribute name = val. If attrval == null, anything matches.


addAux

protected void addAux(ESISNode e)
Add ESISNode tree to aux trees, if not already there (not a multilist).


removeAux

protected void removeAux(ESISNode e)

removeAux

protected void removeAux(java.lang.String attrname,
                         java.lang.String attrval)

auxSize

public int auxSize()
Number of auxiliary trees (often 0).


clear

public void clear()
Clears everything, behaviors and aux.


save

public ESISNode save()
Iterate over auxiliary non-behavior trees, then component Behaviors highest priority to lowest. Trees go first as they may have information needed by behaviors to follow. If document is multipage, as indicated by a MediaAdapator.PAGE attribute in Document, then stuff aux.

Overrides:
save in class Behavior

restore

public void restore(ESISNode n,
                    java.util.Map<java.lang.String,java.lang.Object> attr,
                    Layer layer)
Description copied from class: Behavior
Takes the place of a constructor's initialization functions; that is, it is invoked exactly once immediately after object instantiation. When restored from hub, passed XML content subtree if any as first parameter and attributes from XML tag's attributes. This protocol cannot be short-circuited.

Overrides:
restore in class Behavior

restoreChildren

public void restoreChildren(ESISNode n,
                            Layer layer)
Override definition in Behavior to keep immediate subtrees that aren't behaviors.

Overrides:
restoreChildren in class Behavior

buildBeforeAfter

public void buildBeforeAfter(Document doc)

buildBefore

public void buildBefore(Document doc)
Iterates over component Behaviors (Layer is a subclass of Behavior), highest priority to lowest, if layer is active. If in multipage document, first clear current behaviors and instantiate those for new page, if any, regardless of active state.

Overrides:
buildBefore in class Behavior
See Also:
Mark

buildAfter

public void buildAfter(Document doc)
Iterates over component Behaviors (Layer is a subclass of Behavior), lowest priority to highest.

Overrides:
buildAfter in class Behavior

semanticEventBefore

public boolean semanticEventBefore(SemanticEvent se,
                                   java.lang.String msg)
Iterates over component Behaviors (including nested Layer's), highest priority to lowest. On Multipage.MSG_CLOSEPAGE for isEditable() documents, first saves active behaviors for that page to aux in memory (behaviors are moved from aux to active in buildBefore). (Low-level eventBefore/After is a tree-based protocol, so it's not seen by Layer.)

Overrides:
semanticEventBefore in class Behavior

semanticEventAfter

public boolean semanticEventAfter(SemanticEvent se,
                                  java.lang.String msg)
Iterates over component Behaviors, lowest priority to highest.

Overrides:
semanticEventAfter in class Behavior

destroy

public void destroy()
Iterates over component Behaviors (including nested Layer's), highest priority to lowest.

Overrides:
destroy in class Behavior

checkRep

public boolean checkRep()
Description copied from class: VObject
Checks "representation invariant" (see MIT SE), and returns true iff object is valid, which should be always.

Overrides:
checkRep in class Behavior

dump

public void dump()

dump

public void dump(int level)

Multivalent API