public class DefaultOutline extends DefaultOutlineNode implements MutableOutline<DefaultOutlineNode>
MutableOutline
(and thus Outline
) suitable for most
common use cases. It is designed to be used with child nodes of the type
DefaultOutlineNode
.
For general information on the outline concept, refer to Outline
's class documentation.
The following sections describe various aspects of this implementation.
This implementation follows a strict tree hierarchy where each node knows its child nodes as well
as its parent. Every node can have at most one parent. For this reason, each node is always part
of exactly one hierarchy. A node that doesn't have a parent starts its own hierarchy. Attempts to
add a DefaultOutlineNode
to more than one hierarchy, or more than once to the same
hierarchy, will result in IllegalArgumentException
s. However, removing single nodes or
subtrees from one hierarchy and then adding them to another hierarchy is allowed.
Typically, the tree hierarchy's root node is represented by an instance of DefaultOutline
(which is also an instance of DefaultOutlineNode
). In this case, the hierarchy is called
an Outline Tree. The DefaultOutline
represents the whole structure and each node has a
reference to it. Note that a DefaultOutline
will always refer to itself as its root node.
Every DefaultOutlineNode
carries a description string which can be replaced.
Every DefaultOutlineNode
holds a map of user properties which may be used to store
additional information. Keys and values can be chosen freely according to the desired use-case.
Some components might expect values under well-known identifiers such as the constants defined by
OutlineNode
.
Every DefaultOutlineNode
carries a list of Instruction
s (wrapped in an
InstructionChain
) which may also be supplied at construction time. The method
DefaultOutlineNode.getInstructionChain()
offers access to the chain, which is always
immutable. It can, however, be replaced as a whole.
Via OutlineListener
, the DefaultOutline
offers a listener mechanism which informs
registered instances about structural changes in the Outline Tree as a whole, as well as about
changes to every single node in the hierarchy. In addition, every node offers the option to
register a PropertyChangeListener
which informs about changes to that specific node.
This class is ready for use with multiple threads. It employs locking to achieve this. The lock
can be obtained from the DefaultOutline
which an instance of DefaultOutlineNode
is assigned to. (If an instance is not assigned to any Outline, thread-safety must be ensured in
other ways.) The lock returned by getLock()
distinguishes between read and
write operations. In both cases, it is necessary to acquire the correct lock. For writing
operations, the modification methods offered by this class throw
ConcurrentModificationException
if the lock is not held by the current thread.
Category | Method/Operation | Usage |
---|---|---|
Tree Structure | DefaultOutlineNode.getChildren() |
No locking required. Read-lock recommended. |
Setting list of children | Not possible. Operation not available. | |
Iterating over list of children | Read-lock required. | |
Modifying list of children | Write-lock required | |
DefaultOutlineNode.getParent() |
No locking required. Read-lock recommended. | |
DefaultOutlineNode.getOutline() |
No locking required. Read-lock optional. | |
Description | DefaultOutlineNode.getDescription() |
No locking required. Read-lock recommended. |
DefaultOutlineNode.setDescription(String) |
Write-lock required | |
Properties | DefaultOutlineNode.getProperties() |
No locking required. Read-lock optional. |
Setting map of properties | Not possible. Operation not available. | |
Iterating over map of properties | No locking required. Read-lock optional. | |
Modifying map of properties | No locking required. Write-lock optional. | |
Instructions | DefaultOutlineNode.getInstructionChain() |
No locking required. Read-lock recommended. |
MutableOutlineNode.setInstructionChain(InstructionChain)
|
Write-lock required | |
Iterating over list of instructions | No locking required. Read-lock recommended. | |
Modifying list of instructions | Operation not possible – List is immutable. | |
Listeners | DefaultOutlineNode.addPropertyChangeListener(PropertyChangeListener) |
No locking required. Write-lock optional. |
DefaultOutlineNode.removePropertyChangeListener(PropertyChangeListener) |
No locking required. Write-lock optional. | |
addOutlineListener(MutableOutline.OutlineListener) |
No locking required. Write-lock optional. | |
removeOutlineListener(MutableOutline.OutlineListener) |
No locking required. Write-lock optional. |
MutableOutline.OutlineListener<N extends MutableOutlineNode<?>>
PROPERTY_DESCRIPTION, PROPERTY_INSTRUCTIONS, PROPERTY_PREFIX_USER_PROPERTY
Constructor and Description |
---|
DefaultOutline()
Construct a new instance with a type of
Outlines.TYPE_CUSTOM_OUTLINE . |
DefaultOutline(String type)
Construct a new instance with the given type.
|
DefaultOutline(String type,
String description,
Instruction... instructions)
Construct a new Outline with the given type, root node description and root node instructions.
|
Modifier and Type | Method and Description |
---|---|
void |
addOutlineListener(MutableOutline.OutlineListener<DefaultOutlineNode> outlineListener)
Add an
OutlineListener to be notified of changes to this Outline Tree. |
ReadWriteLock |
getLock()
Return the
ReadWriteLock which must be acquired during all modifications and read
actions on any node within this Outline Tree. |
String |
getType()
Returns the type identifier which is an indicator of this
Outline 's purpose. |
void |
removeOutlineListener(MutableOutline.OutlineListener<DefaultOutlineNode> outlineListener)
Remove an
OutlineListener from this Outline Tree. |
addPropertyChangeListener, ensureWriteLocked, getChildren, getDescription, getInstructionChain, getOutline, getParent, getProperties, removePropertyChangeListener, setDescription, setInstructionChain, setInstructionChain, toString
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
getChildren, getOutline, getProperties, setDescription, setInstructionChain
getDescription, getInstructionChain, getParent
public DefaultOutline()
Outlines.TYPE_CUSTOM_OUTLINE
. The root node
will have an empty description and no instructions.public DefaultOutline(String type)
public DefaultOutline(String type, String description, Instruction... instructions)
type
- identifies the kind of Outline
. Usually one of the constants in
Outline
. Must not be null
.instructions
- zero or more Instruction
instances to be assigned to this node (the
root node)public String getType()
Outline
Outline
's purpose. It can be
helpful to distinguish multiple Outline Trees from each other, or to present a suitable
heading/name to users.
Outlines may have arbitrary type identifiers. However, some components may also rely on well-known type identifiers. The constants defined in this class serve as well-known type identifiers which should usually be supported.
getType
in interface Outline<DefaultOutlineNode>
Outline
's purpose. Must not return
null
.public void addOutlineListener(MutableOutline.OutlineListener<DefaultOutlineNode> outlineListener)
OutlineListener
to be notified of changes to this Outline Tree. This method may
be called from any Thread. It is not necessary to acquire the Outline's lock via
getLock()
in order to call this method. However, in some circumstances it can be
helpful in order to ensure that the listener is properly registered before certain events
happen.addOutlineListener
in interface MutableOutline<DefaultOutlineNode>
outlineListener
- the listener to be added. Must not be null
.public void removeOutlineListener(MutableOutline.OutlineListener<DefaultOutlineNode> outlineListener)
OutlineListener
from this Outline Tree. This method does nothing if the
listener has not previously been registered using MutableOutline.addOutlineListener(OutlineListener)
.removeOutlineListener
in interface MutableOutline<DefaultOutlineNode>
outlineListener
- the listener to be removed. If this parameter is null
,
nothing will happen.public ReadWriteLock getLock()
ReadWriteLock
which must be acquired during all modifications and read
actions on any node within this Outline Tree. Failing to acquired a lock during modifications
may cause those modifications to conflict with others or lead to them being improperly
reflected in the UI.
The following operations are exempt from this rule:
OutlineListener
sgetLock
in interface MutableOutline<DefaultOutlineNode>
Copyright © 2024 levigo holding gmbh. All rights reserved.