com.levigo.jadice.document.outline

Class DefaultOutlineNode

java.lang.Object

com.levigo.jadice.document.outline.DefaultOutlineNode

All Implemented Interfaces:

MutableOutlineNode<DefaultOutlineNode>, OutlineNode<DefaultOutlineNode>, PropertiesProvider

Direct Known Subclasses:

Bookmark, DefaultOutline

public class DefaultOutlineNode
extends Object
implements MutableOutlineNode<DefaultOutlineNode>

A default implementation of MutableOutlineNode (and thus OutlineNode) suitable for most common use cases. Typically, DefaultOutlineNodes are part of an Outline Tree with an instance of DefaultOutline at its root. Refer to DefaultOutline's class documentation for further information on both classes.

Constructor Summary

Constructors

Constructor and Description
DefaultOutlineNode() Create a new instance with an empty description and no instructions.
DefaultOutlineNode(String description, Instruction... instructions) Create a new instance with the given description and instructions.
DefaultOutlineNode(String description, InstructionChain instructionChain)
DefaultOutlineNode(String description, List<Instruction> instructions) Create a new instance with the given description and list of instructions.

Method Summary

Modifier and Type	Method and Description
void	addPropertyChangeListener(PropertyChangeListener listener) Register a PropertyChangeListener which will be informed upon every property change of this node.
protected void	ensureWriteLocked()
List<DefaultOutlineNode>	getChildren() Returns this node's direct children in a list which allows for modifications.
String	getDescription() Get the human-readable description of this node.
InstructionChain	getInstructionChain() Get the Instructions to be executed for this node.
DefaultOutline	getOutline() Return the DefaultOutline to which this node belongs.
DefaultOutlineNode	getParent() Return the parent OutlineNode or null, if this node is the root of a subtree or the root of an Outline Tree (see Outline).
Map<String,Object>	getProperties() Return a map of user properties.
void	removePropertyChangeListener(PropertyChangeListener listener) Remove a PropertyChangeListener which was previously registered using addPropertyChangeListener(PropertyChangeListener).
void	setDescription(String description) Set the human-readable description for this node.
void	setInstructionChain(Instruction... instructions) Convenience method to replace the entire chain of instructionChain with an InstructionChain created from the given Instructions.
void	setInstructionChain(InstructionChain newChain) Replace the entire chain of instructionChain with the given one.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DefaultOutlineNode

public DefaultOutlineNode()

Create a new instance with an empty description and no instructions.

DefaultOutlineNode

public DefaultOutlineNode(String description,
                          Instruction... instructions)

Create a new instance with the given description and instructions.

Parameters:

description - a concise, human-readable description of this node. Passing null leads to an empty String being set.

instructions - zero or more Instruction instances to be assigned to this node

DefaultOutlineNode

public DefaultOutlineNode(String description,
                          List<Instruction> instructions)

Create a new instance with the given description and list of instructions.

Parameters:

description - a concise, human-readable description of this node. Passing null leads to an empty String being set.

instructions - a list of Instruction instances to be assigned to this node. They will be copied into an immutable list.

DefaultOutlineNode

public DefaultOutlineNode(String description,
                          InstructionChain instructionChain)

Method Detail

getProperties

public Map<String,Object> getProperties()

Return a map of user properties. It may be used to store additional information which can serve to enrich the OutlineNode's presentation or in other ways further augment its data.

A mutable, thread-safe map implementation is returned. It is not necessary to acquire the Outline's lock when calling this method or when accessing/modifying the map's contents.

Specified by:

getProperties in interface MutableOutlineNode<DefaultOutlineNode>

Specified by:

getProperties in interface OutlineNode<DefaultOutlineNode>

Specified by:

getProperties in interface PropertiesProvider

Returns:

the mutable, thread-safe map of user properties

getChildren

public List<DefaultOutlineNode> getChildren()

Returns this node's direct children in a list which allows for modifications. The list may be retrieved on any thread. For any access to the list, the outline's lock must be acquired via DefaultOutline.getLock(). For modifications, the write lock must be acquired, for read-only operations the read lock will suffice.

Specified by:

getChildren in interface MutableOutlineNode<DefaultOutlineNode>

Specified by:

getChildren in interface OutlineNode<DefaultOutlineNode>

Returns:

the mutable list of nodes which are direct children of this node.

getInstructionChain

public InstructionChain getInstructionChain()

Get the Instructions to be executed for this node. It is not necessary to acquire the outline's lock before calling this method.

Specified by:

getInstructionChain in interface OutlineNode<DefaultOutlineNode>

Returns:

this node's chain of instructions which will always be non-null.

setInstructionChain

public void setInstructionChain(Instruction... instructions)

Convenience method to replace the entire chain of instructionChain with an InstructionChain created from the given Instructions. It is necessary to acquire the outline's lock via DefaultOutline.getLock() before calling this method.

Parameters:

instructions - The Instructions to be used by this node in the future. If this parameter is null, the node will have no Instructions to be executed.

See Also:

setInstructionChain(InstructionChain)

setInstructionChain

public void setInstructionChain(InstructionChain newChain)

Replace the entire chain of instructionChain with the given one. It is necessary to acquire the outline's lock via DefaultOutline.getLock() before calling this method.

Specified by:

setInstructionChain in interface MutableOutlineNode<DefaultOutlineNode>

Parameters:

newChain - An InstructionChain holding the Instructions to be used by this node in the future. If this parameter is null, the node will have no Instructions to be executed.

getDescription

public String getDescription()

Get the human-readable description of this node. This is the main way of representing the information which the node stands for. A concise description is expected since one typical use-case of this description is to render it in a UI. It is not necessary to acquire the outline's lock before calling this method.

Specified by:

getDescription in interface OutlineNode<DefaultOutlineNode>

Returns:

a human-readable description. Never returns null.

setDescription

public void setDescription(String description)

Set the human-readable description for this node. It is necessary to acquire the outline's lock via DefaultOutline.getLock() before calling this method.

Specified by:

setDescription in interface MutableOutlineNode<DefaultOutlineNode>

Parameters:

description - the new description string. Passing null leads to an empty string being set.

ensureWriteLocked

protected void ensureWriteLocked()

getParent

public DefaultOutlineNode getParent()

Return the parent OutlineNode or null, if this node is the root of a subtree or the root of an Outline Tree (see Outline).

It is not necessary to acquire the outline's read lock via DefaultOutline.getLock() before calling this method.

Specified by:

getParent in interface OutlineNode<DefaultOutlineNode>

Returns:

the parent node or null if this node is the root node.

toString

public String toString()

Overrides:

toString in class Object

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)

Register a PropertyChangeListener which will be informed upon every property change of this node.

Parameters:

listener - the listener implementation to be registered. Passing null will have no effect.

See Also:

for a listener that will be informed upon every change in every node in an entire Outline Tree

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)

Remove a PropertyChangeListener which was previously registered using addPropertyChangeListener(PropertyChangeListener).

Parameters:

listener - the listener implementation to be removed. Passing null will hae no effect.

getOutline

public DefaultOutline getOutline()

Return the DefaultOutline to which this node belongs. It is not required to acquire the outline's lock to call this method.

Specified by:

getOutline in interface MutableOutlineNode<DefaultOutlineNode>

Specified by:

getOutline in interface OutlineNode<DefaultOutlineNode>

Returns:

this node's DefaultOutline, or null if this node is not part of an Outline Tree