MTree_ (BandM signal & music)

java.lang.Object
- eu.bandm.music.entities.MTree_<M>

All Implemented Interfaces:

MetrumIndication

Direct Known Subclasses:

MTree, MTreeSpec
```
public abstract class MTree_<M extends MTree_<M>>
extends Object
implements MetrumIndication
```
Abstract superclass for MTree and MTreeSpec. It realizes common methods for retrieval, inquiry, visualisation, etc.
Both subclasses are a representation of the internal metrical hierarchies of one single measure, used for interpretation of rhythms. This implementation has back-pointers to context and siblings, so sharing of nodes is not possible. Every node represents an interval of the time of the measure. The sequence of the intervals represented by the childs of a node cover the interval of this parent node, in the same order. As a consequence, every node has a duration, startpoint and endpoint. The children of each node can be of different length and/or structure.
Most algorithms work on an MTree. A user constructs an MTreeSpec, for representing a specifications, and then calls MTree.install(MTreeSpec,MTree.Parameters) to expand these.

Field Summary

Fields
Modifier and Type	Field and Description
`(package private) M`	`alternative` An alternative to this node.
`(package private) @Opt Rational`	`duration` The duration of the time interval (of a measure) represented by this node.
`(package private) @Opt Rational`	`end` The end time of the time interval (of a measure) represented by this node, relative to the start of the topmost node, which is fixed as "0/1".
`(package private) boolean`	`equidist` Whether all child nodes of this node have equal durations.
`(package private) boolean`	`explicitDuration` Whether the duration of this node has been given explicitly with its specification.
`(package private) boolean`	`implicit` Whether this node has been created automatically, by implict division into halfs.
`(package private) boolean`	`initialized` Whether all initialization has already been performed, by a call to `MTreeSpec.initialize(Modifiers.Reaction)`.
`(package private) M`	`parent` The parent node of this tree node.
`(package private) int`	`position` Position ot "this" in the parent's list, starting from zero(0).
`(package private) @Opt Rational`	`start` The start time of the time interval (of a measure) represented by this node, relative to the start of the topmost node, which is fixed as "0/1".
`(package private) List<M>`	`subs` List of child nodes.

Constructor Summary

Constructors
Constructor and Description

MTree_()

Constructors
Constructor and Description
`MTree_()`

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addAlternative(M alt)` Adds a node at the END of this's alternative chain. Used by MTreeSpec and MTree.
`protected void`	`calcStartEnd(Rational start)` Recursive function for calculating `start`, `end` and `equidist`.
`List<Integer>`	`compoundName()`
`Rational`	`constantRationalMeasureDuration()` Returns the length of a measure.
`protected void`	`copyTimeValues(MTree_<?> newthis)` Copies only time values and boolean flags, from this instance into the argument.
`void`	`dump()` Prints an indented visualization to System.err.
`void`	`dump(PrintStream p)` Prints an indented visualization.
`void`	`dump(PrintWriter p)` Prints an indented visualization.
`List<Integer>`	`durationName()`
`M`	`get_alternative()` Return the (first) alternative node.
`Rational`	`get_duration()` Get the duration value.
`Rational`	`get_end()` Get the end time point value.
`boolean`	`get_explicitDuration()` Return whether the duration has been set explicitly, when speficfying this node.
`boolean`	`get_implicit()` Whether this has been created explicitly, or by implicit division by two
`boolean`	`get_initialized()` Retrun whether this node is initialized.
`M`	`get_parent()` Return the parent node.
`int`	`get_position()` Position in the parents' list, starting from zero(0).
`int`	`get_size_binary()` Returns the number of children of this node.
`int`	`get_size()`
`Rational`	`get_start()` Get the start time point value.
`List<M>`	`get_subs()`
`M`	`getFollowing()` Returns the highest node which starts at the timepoint when this ends.
`M`	`getFollowingSibling()` Returns the node which is child of the same parent, and one position further, iff it exists, otherwise null.
`M`	`getPrecedingSibling()` Returns the node which is child of the same parent, and one position earlier, iff it exists, otherwise null.
`M`	`getTopNode()` Get the top most node to which this node is linked as a descendant.
`boolean`	`is_equi_binary()` Returns whether the cild level is divided equidistantly by two.
`boolean`	`isFollowingSiblingOf(MTree_<?> predec)` Returns whether this node is child of the same parent as the argument, and one position further.
`protected void`	`propagateDown_alt(Rational altdur, Modifiers.Reaction redundantDuration)` The duration of some alternative of the node is fixed (explicitly when constructing, or by upward propagation; in altdur != null).
`protected void`	`propagateDown(Modifiers.Reaction redundantDuration)` The duration of the node is fixed (by construction or by downward propagation or by some alternative.) Either all children do not have a duration, then the duration is distributed equally among them, or only one child does not have a duration and gets the rest.
`protected void`	`propagateUp(Modifiers.Reaction redundantDuration)` Visit depth-first and sum-up the durations of children, as long as possible and necessary.
`protected abstract M`	`self()` Necessary to avoid "unchecked cast" warning when returning "this" instance as a result of a methode declared of type "M".
`String`	`toString()` gives one-line rendering.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - position
```
int position
```
    Position ot "this" in the parent's list, starting from zero(0).
  - subs
```
List<M extends MTree_<M>> subs
```
    List of child nodes.
  - parent
```
@Opt
M extends MTree_<M> parent
```
    The parent node of this tree node. Can be ==null only for the topmost node.
  - alternative
```
@Opt
M extends MTree_<M> alternative
```
    An alternative to this node. Has same duration, start, end, but different internal structure by a different list of child nodes.
  - duration
```
@Opt
@Opt Rational duration
```
    The duration of the time interval (of a measure) represented by this node. Can be ==null in a specification and will be calculated by the constraints imposed by parents and siblings, etc. Must be !=null after installing and in every instance of MTree.
  - start
```
@Opt
@Opt Rational start
```
    The start time of the time interval (of a measure) represented by this node, relative to the start of the topmost node, which is fixed as "0/1". The topmost node is that for which eu.bandm.sig.music.entities.MTreeSpec#initialize(Reaction) and MTree.install(MTreeSpec,MTree.Parameters) have been called. Can be ==null in a specification and will be calculated by the constraints imposed by parents and siblings, etc. Must be !=null after installing and in every instance of MTree.
  - end
```
@Opt
@Opt Rational end
```
    The end time of the time interval (of a measure) represented by this node, relative to the start of the topmost node, which is fixed as "0/1". The topmost node is that for which eu.bandm.sig.music.entities.MTreeSpec#initialize(Reaction) and MTree.install(MTreeSpec,MTree.Parameters) have been called. Is always ==null in a specification and will be filled by the constraints imposed by parents and siblings, etc. Must be !=null after installing and in every instance of MTree.
  - explicitDuration
```
boolean explicitDuration
```
    Whether the duration of this node has been given explicitly with its specification.
  - initialized
```
boolean initialized
```
    Whether all initialization has already been performed, by a call to MTreeSpec.initialize(Modifiers.Reaction).
  - implicit
```
boolean implicit
```
    Whether this node has been created automatically, by implict division into halfs.
  - equidist
```
boolean equidist
```
    Whether all child nodes of this node have equal durations.
- Constructor Detail
  - MTree_
```
public MTree_()
```
- Method Detail
  - copyTimeValues
```
protected void copyTimeValues(MTree_<?> newthis)
```
    Copies only time values and boolean flags, from this instance into the argument. (All but "initialized", which is left, and normally is false). Context references (.parent, .alternative and .subs) are not affected and must be managed by caller. But .position is copied. FIXME CHECK IF SENSIBLE !?!? Called by MTreeSpec.deepCopy(), MTree.MTree(..), MTree.copyTreeValues(MTree).
  - addAlternative
```
public void addAlternative(M alt)
```
    Adds a node at the END of this's alternative chain.
    Used by MTreeSpec and MTree.
    
    Parameters:
    
    alt - the node to append to the list of alternatives of this node. Its start, end, duration, position and parent must be the same as with this, if specified.
    
    Throws:
    
    IllegalArgumentException - if durations of this and "alt" differ.
  - constantRationalMeasureDuration
```
public Rational constantRationalMeasureDuration()
```
    Returns the length of a measure. This is defined by the interface MetrumIndication, which MAY throw an UnsupportedOperationException in other implementations.
    
    Specified by:
    
    constantRationalMeasureDuration in interface MetrumIndication
  - get_position
```
public int get_position()
```
    Position in the parents' list, starting from zero(0).
  - get_size
```
public int get_size()
```
    Returns:
    
    number of child nodes.
  - get_implicit
```
public boolean get_implicit()
```
    Whether this has been created explicitly, or by implicit division by two
  - get_subs
```
public List<M> get_subs()
```
    Returns:
    
    unmodifiable list of child nodes.
  - get_parent
```
@Opt
public M get_parent()
```
    Return the parent node.
  - get_alternative
```
@Opt
public M get_alternative()
```
    Return the (first) alternative node.
  - get_initialized
```
public boolean get_initialized()
```
    Retrun whether this node is initialized.
  - get_start
```
public Rational get_start()
```
    Get the start time point value. For MTreeSpec this field is often initially ==null. But for MTree, the state initialized should be ==true and thus the result!=null.
  - get_end
```
public Rational get_end()
```
    Get the end time point value. For MTreeSpec this field is often initially ==null. But for MTree, The state initialized should be ==true and thus the result!=null.
  - get_duration
```
public Rational get_duration()
```
    Get the duration value. For MTreeSpec this field is often initially ==null. But for MTree, The state initialized should be ==true and thus the result!=null.
  - get_explicitDuration
```
public boolean get_explicitDuration()
```
    Return whether the duration has been set explicitly, when speficfying this node.
  - isFollowingSiblingOf
```
public boolean isFollowingSiblingOf(MTree_<?> predec)
```
    Returns whether this node is child of the same parent as the argument, and one position further.
  - getFollowingSibling
```
@Opt
public M getFollowingSibling()
```
    Returns the node which is child of the same parent, and one position further, iff it exists, otherwise null.
    ATTENTION: There may be alternative nodes, accessible by alternative, which have a different structure, but the same duration.
  - getPrecedingSibling
```
@Opt
public M getPrecedingSibling()
```
    Returns the node which is child of the same parent, and one position earlier, iff it exists, otherwise null.
    ATTENTION: There may be alternative nodes, accessible by alternative, which have a different structure, but the same duration.
  - getFollowing
```
@Opt
public M getFollowing()
```
    Returns the highest node which starts at the timepoint when this ends. It can be the following sibling, or the following sibling of the parent, if the first does not exist, etc.
    ATTENTION: There may be alternative nodes, accessible by alternative, which have a different structure, but the same duration.
    ATTENTION: only used locally, in doFC. AND IN makebeams .... FIXME
  - self
```
protected abstract M self()
```
    Necessary to avoid "unchecked cast" warning when returning "this" instance as a result of a methode declared of type "M". Must be implemented by the subclasses with their type as the return type.
  - getTopNode
```
public M getTopNode()
```
    Get the top most node to which this node is linked as a descendant.
  - get_size_binary
```
public int get_size_binary()
```
    Returns the number of children of this node. Returns two(2) iff no children currently exist. This mirrors the default division by two(2) implicitly allowed for every node in CWN.
  - is_equi_binary
```
public boolean is_equi_binary()
```
    Returns whether the cild level is divided equidistantly by two.
  - calcStartEnd
```
protected void calcStartEnd(Rational start)
```
    Recursive function for calculating start, end and equidist. Assume that all duration fields of all visited nodes are set.
    
    Parameters:
    
    start - the start time point of this node, relative to the start of the top-most node, which represents a complete measure.
  - propagateUp
```
protected void propagateUp(Modifiers.Reaction redundantDuration)
```
    Visit depth-first and sum-up the durations of children, as long as possible and necessary. Whenever an explicit duration is found, switch to propagateDown(Modifiers.Reaction) for the sub-tree.
  - propagateDown_alt
```
protected void propagateDown_alt(Rational altdur,
                                 Modifiers.Reaction redundantDuration)
```
    The duration of some alternative of the node is fixed (explicitly when constructing, or by upward propagation; in altdur != null). Check for identiy iff there is an explicit duration, and call propagateDown(Modifiers.Reaction).
  - propagateDown
```
protected void propagateDown(Modifiers.Reaction redundantDuration)
```
    The duration of the node is fixed (by construction or by downward propagation or by some alternative.) Either all children do not have a duration, then the duration is distributed equally among them, or only one child does not have a duration and gets the rest.
  - durationName
```
public List<Integer> durationName()
```
    Returns:
    
    a single broken number (NOT a rational) as meter name, reflecting only the duration. If there are child nodes, than the LCM of their denominators is used as denominator. This makes 1/8+1/4+1/8 = 4/8 Otherwise, if numerator of the duration ==1, then the fraction is enhanced by "2", reflecting the default bi-section.
  - compoundName
```
public List<Integer> compoundName()
```
    Returns:
    
    a list of broken numbers as a name for the meter. [a, b, c, d] is an encoding for "a/b+c/d". The algorithm steps through the children of this MTree_. As long as the length values are identical, their numerators are summed up.
  - toString
```
public String toString()
```
    gives one-line rendering. See also dump(PrintStream), which gives a multi-line indented view.
    
    Overrides:
    
    toString in class Object
  - dump
```
public void dump()
```
    Prints an indented visualization to System.err.
  - dump
```
public void dump(PrintStream p)
```
    Prints an indented visualization.
  - dump
```
public void dump(PrintWriter p)
```
    Prints an indented visualization.

Class MTree_<M extends MTree_<M>>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

position

subs

parent

alternative

duration

start

end

explicitDuration

initialized

implicit

equidist

Constructor Detail

MTree_

Method Detail

copyTimeValues

addAlternative

constantRationalMeasureDuration

get_position

get_size

get_implicit

get_subs

get_parent

get_alternative

get_initialized

get_start

get_end

get_duration

get_explicitDuration

isFollowingSiblingOf

getFollowingSibling

getPrecedingSibling

getFollowing

self

getTopNode

get_size_binary

is_equi_binary

calcStartEnd

propagateUp

propagateDown_alt

propagateDown

durationName

compoundName

toString

dump

dump

dump