net.charlesames.music.ensemble
Class EnsembleChoir

java.lang.Object
  net.charlesames.utility.common.Disposable
      net.charlesames.utility.entity.Entity
          net.charlesames.utility.entity.WriteableEntity
              net.charlesames.music.ensemble.EnsembleEntity
                  net.charlesames.music.ensemble.ContainerOfChoirsAndContours
                      net.charlesames.music.ensemble.EnsembleChoir

All Implemented Interfaces:

EntityContainer

public class EnsembleChoir
extends ContainerOfChoirsAndContours

Instances of the EnsembleChoir class define hierarchical groupings for voice specifications, contour specifications, MIDI controls, and sub-choirs.

Author:

Charles Ames

Nested Class Summary

Nested classes/interfaces inherited from class net.charlesames.music.ensemble.EnsembleEntity

EnsembleEntity.AttributeTable

Constructor Summary

EnsembleChoir(EnsembleEntity container, int id, java.lang.String name)
Constructor for EnsembleChoir instances

Method Summary

MidiControl	addMidiControl(TypeOfMidiControl controlType) Add a new MidiControl to a choir.
boolean	check(HtmlBuilder builder) Check this component for errors and inconsistencies
void	checkNewContourID(int id) Check if the indicated ID is usable for a new EnsembleContour.
void	checkNewContourIndex(int index) Check if the indicated index is usable for a new EnsembleContour.
void	checkNewContourName(java.lang.String name) Check if the indicated name is usable for a new EnsembleContour.
EnsembleContour	createContour(java.lang.String name, int id, CalculationMode calculationMode) Add a new contour specification to a choir.
MusicXmlPart	createMusicXmlPart(java.lang.String name) Create a new MusicXmlPart instance using the next available id.
MusicXmlPart	createMusicXmlPart(java.lang.String name, int id) Create a new MusicXmlPart instance.
EnsembleContour	createVelocityContour() Add a standard Velocity EnsembleContour with a corresponding MIDI control.
EnsembleVoice	createVoice(java.lang.String voiceName) Adds an EnsembleVoice to the choir using the next available voice ID.
EnsembleVoice	createVoice(java.lang.String voiceName, int voiceID) Adds an EnsembleVoice to the choir.
static XmlSpec	createXmlSpec() Create an XML specification for the EnsembleChoir class.
boolean	equals(EnsembleEntity other) Check if this entity has the same class and content as another entity.
static EnsembleChoir	fromXmlNode(org.w3c.dom.Element element, ContainerOfChoirsAndContours container) Create a new Choir instance and fill it with loaded data.
static EnsembleChoir	fromXmlNode(org.w3c.dom.Element element, EnsembleInstrument instrument) Create a new {code EnsembleChoir} instance and fill it with loaded data.
EnsembleVoice	getAnyVoice() Searches for any voice specification defined under this Ensemble or Choir, or from any sub-choir.
EnsembleContour	getChildContour(int id) Search by id for a EnsembleContour which is defined in any sub-choir of this choir.
EnsembleContour	getChildContour(java.lang.String name) Search by name for a EnsembleContour which is defined in any sub-choir of this choir.
MidiControl	getChildControl(TypeOfMidiControl controlType) Search by name for a MidiControl which is defined in any sub-choir of this choir.
EnsembleContour	getContour(int id) Searches the EnsembleContours defined under this choir by id.
EnsembleContour	getContour(java.lang.String name) Searches the EnsembleContours defined under this choir by name.
java.util.SortedMap<java.lang.Integer,EnsembleContour>	getContoursByID()
java.util.SortedMap<java.lang.String,EnsembleContour>	getContoursByName()
int	getDefaultContourID() Generate a usable contour ID.
java.lang.String	getLongName() Generates a long name which a user interface can use in the name field of an entity-creation dialog.
MidiControl	getMidiControl(TypeOfMidiControl controlType) Search the MidiControls defined under this choir by control type.
java.util.SortedMap<java.lang.String,MidiControl>	getMidiControls()
int	getMusicXmlPartGroupNumber() Get the MusicXML part-group number.
GroupSymbol	getMusicXmlPartGroupSymbol() Get the MusicXML part-group display type.
java.util.SortedMap<java.lang.Integer,MusicXmlPart>	getMusicXmlPartsByID() Get the choir-specific collection of MusicXmlPart instances.
java.util.SortedMap<java.lang.String,MusicXmlPart>	getMusicXmlPartsByName() Get the choir-specific collection of MusicXmlPart instances.
EnsembleContour	getParentContour(int id) Search by id for a contour which is defined in this choir or one of its parents.
EnsembleContour	getParentContour(java.lang.String name) Search by name for a EnsembleContour which is defined in this choir or one of its parents.
MidiControl	getParentControl(TypeOfMidiControl controlType) Search by control type for a MidiControl which is defined in this choir or one of its parents.
java.lang.String	getPath() Return a description of this entity and its containers.
void	getSubchoirPaths(java.util.List<java.lang.String> result) Compile a list of sub-choir paths
EnsembleVoice	getVoice(java.lang.String name) Searches the EnsembleVoices defined under this choir by name.
java.util.SortedMap<java.lang.Integer,EnsembleVoice>	getVoicesByID() Get the collection of EnsembleVoice instances associated with this choir.
java.util.SortedMap<java.lang.String,EnsembleVoice>	getVoicesByName() Get the collection of EnsembleVoice instances associated with this choir.
boolean	hasExistingContour(int id) Check if this choir employs the indicated id.
boolean	hasExistingContour(java.lang.String name)
boolean	hasExistingControl(TypeOfMidiControl controlType) Tests if a MidiControl exists for a indicated controlType.
void	removeContour(java.lang.String name) Remove a contour specification.
void	removeMidiControl(TypeOfMidiControl controlType)
void	removeVoice(int id) Remove an existing EnsembleVoice from the choir.
void	removeVoice(java.lang.String name) Remove an existing EnsembleVoice from the choir.
void	resolve()
boolean	setID(int id) Setter for the ID property.
void	setMusicXmlPartGroupNumber(int musicXmlPartGroupNumber) Set the MusicXML part-group number.
void	setMusicXmlPartGroupSymbol(GroupSymbol musicXmlPartGroupSymbol) Set the MusicXML part-group display type.
boolean	setName(java.lang.String name) Setter for the Name property.
void	shiftContourDown(int id) Increments a contour's id by 1.
void	shiftContourUp(int id) Decrements a contour specification's id by 1.
void	wipe() Clear all data in this Entity instance.

Methods inherited from class net.charlesames.music.ensemble.ContainerOfChoirsAndContours

checkNewChoirID, checkNewChoirName, clear, createChoir, getChoir, getChoirsByID, getChoirsByName, getContainer, getDefaultChoirID, getDefaultVoiceName, getEnsemble, hasChoirName, removeChoir, resequenceChoirs, shiftChoirDown, shiftChoirsDown, shiftChoirUp

Methods inherited from class net.charlesames.music.ensemble.EnsembleEntity

buildDescription, copyToClipboard, createIndentCell, createXmlSpec, describeFeature, logError, predecessor, toString

Methods inherited from class net.charlesames.utility.entity.WriteableEntity

clearXmlSpecs, createXmlSpec, getTagName, getXmlData, getXmlSpec, getXmlSpec, initializeXsd, isPersistent, logError, logError, makeDirty, putXmlData, save, setPersistent, setStatus, toXmlNode

Methods inherited from class net.charlesames.utility.entity.Entity

decrementReferenceCount, dereferenceHandle, dispose, equals, getHandle, getID, getName, getReferenceCount, getStatus, getText, hasContainer, incrementReferenceCount, isModifiable, methodHasOverride, predecessor, resequenceEntities, setContainer, setModifiable, shiftEntitiesDown, shiftEntityDown, shiftEntityUp, successor

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

EnsembleChoir

public EnsembleChoir(EnsembleEntity container,
                     int id,
                     java.lang.String name)

Constructor for EnsembleChoir instances

Parameters:

container - Can be either an Ensemble or a EnsembleChoir

id - Must be unique under the container.

name - Must be unique under the container.

Method Detail

getLongName

public java.lang.String getLongName()

Generates a long name which a user interface can use in the name field of an entity-creation dialog. This is done by starting with the choir name, prefixing the parent choir name, and so forth.

Returns:

A top-down chain of choir names.

setID

public boolean setID(int id)

Description copied from class: Entity

Setter for the ID property.

Overrides:

setID in class WriteableEntity

Parameters:

id - The intended ID value.

Returns:

True if an ID change actually happened; false otherwise.

setName

public boolean setName(java.lang.String name)

Description copied from class: Entity

Setter for the Name property.

Overrides:

setName in class WriteableEntity

Parameters:

name - The intended Name value.

Returns:

True if a Name change actually happened; false otherwise.

getMusicXmlPartGroupNumber

public int getMusicXmlPartGroupNumber()

Get the MusicXML part-group number. This value is assigned on-the-fly during MusicXML export and does not persist in the native ensemble file.

Returns:

The assigned MusicXML part-group number.

setMusicXmlPartGroupNumber

public void setMusicXmlPartGroupNumber(int musicXmlPartGroupNumber)

Set the MusicXML part-group number. This value is assigned on-the-fly during MusicXML export and does not persist in the native ensemble file.

Parameters:

musicXmlPartGroupNumber - The intended MusicXML part-group number.

getMusicXmlPartGroupSymbol

public GroupSymbol getMusicXmlPartGroupSymbol()

Get the MusicXML part-group display type.

Returns:

The assigned MusicXML part-group display type; none suppresses group creation.

setMusicXmlPartGroupSymbol

public void setMusicXmlPartGroupSymbol(GroupSymbol musicXmlPartGroupSymbol)

Set the MusicXML part-group display type.

Parameters:

musicXmlPartGroupSymbol - The assigned MusicXML part-group display type; none suppresses group creation.

getPath

public java.lang.String getPath()

Description copied from class: Entity

Return a description of this entity and its containers.

Specified by:

getPath in interface EntityContainer

Overrides:

getPath in class Entity

Returns:

A description of this entity and its containers.

getVoicesByID

public java.util.SortedMap<java.lang.Integer,EnsembleVoice> getVoicesByID()

Get the collection of EnsembleVoice instances associated with this choir.

Returns:

A collection of EnsembleVoice instances, sorted by ID.

getVoicesByName

public java.util.SortedMap<java.lang.String,EnsembleVoice> getVoicesByName()

Get the collection of EnsembleVoice instances associated with this choir.

Returns:

A collection of EnsembleVoice instances, sorted by name.

getContoursByName

public java.util.SortedMap<java.lang.String,EnsembleContour> getContoursByName()

Returns:

The collection of contour specifications defined by this choir, indexed by name.

getContoursByID

public java.util.SortedMap<java.lang.Integer,EnsembleContour> getContoursByID()

Returns:

The collection of EnsembleContour instances (contour specifications) defined by this choir, indexed by id.

getParentContour

public EnsembleContour getParentContour(java.lang.String name)

Search by name for a EnsembleContour which is defined in this choir or one of its parents.

Parameters:

name - The indicated name.

Returns:

The contour specification with the indicated name (null if not found).

getChildContour

public EnsembleContour getChildContour(java.lang.String name)

Search by name for a EnsembleContour which is defined in any sub-choir of this choir.

Parameters:

name - The indicated name.

Returns:

The first contour specification found with the indicated name (null if not found).

hasExistingContour

public boolean hasExistingContour(java.lang.String name)

Parameters:

name - The indicated name.

Returns:

True if there is either a parent EnsembleContour or child EnsembleContour with the indicated name; false otherwise.

checkNewContourName

public void checkNewContourName(java.lang.String name)

Description copied from class: ContainerOfChoirsAndContours

Check if the indicated name is usable for a new EnsembleContour.

Specified by:

checkNewContourName in class ContainerOfChoirsAndContours

Parameters:

name - The indicated name.

getParentContour

public EnsembleContour getParentContour(int id)

Search by id for a contour which is defined in this choir or one of its parents.

Parameters:

id - The indicated id.

Returns:

The contour with the indicated id (null if not found).

getChildContour

public EnsembleContour getChildContour(int id)

Search by id for a EnsembleContour which is defined in any sub-choir of this choir.

Parameters:

id - The indicated id.

Returns:

The first contour specification found with the indicated id (null if not found).

hasExistingContour

public boolean hasExistingContour(int id)

Check if this choir employs the indicated id.

Parameters:

id - The indicated id.

Returns:

True if there is either a parent EnsembleContour or child EnsembleContour with the indicated id; false otherwise.

checkNewContourID

public void checkNewContourID(int id)

Check if the indicated ID is usable for a new EnsembleContour.

Specified by:

checkNewContourID in class ContainerOfChoirsAndContours

Parameters:

id - The indicated ID.

checkNewContourIndex

public void checkNewContourIndex(int index)

Description copied from class: ContainerOfChoirsAndContours

Check if the indicated index is usable for a new EnsembleContour.

Specified by:

checkNewContourIndex in class ContainerOfChoirsAndContours

Parameters:

index - The indicated index.

getDefaultContourID

public int getDefaultContourID()

Generate a usable contour ID.

Returns:

A usable contour ID.

createContour

public EnsembleContour createContour(java.lang.String name,
                                     int id,
                                     CalculationMode calculationMode)

Add a new contour specification to a choir.

Parameters:

name - The new contour name. May not already be used by any parent or child choir.

id - The new contour id. May not already be used by any parent or child choir.

calculationMode -

Returns:

The newly created EnsembleContour instance.

createVelocityContour

public EnsembleContour createVelocityContour()

Add a standard Velocity EnsembleContour with a corresponding MIDI control.

Returns:

The newly created EnsembleContour instance.

removeContour

public void removeContour(java.lang.String name)

Remove a contour specification.

Parameters:

name - The contour name.

getContour

public EnsembleContour getContour(java.lang.String name)

Searches the EnsembleContours defined under this choir by name.

Parameters:

name - The indicated name.

Returns:

The contour specification with the indicated name.

getContour

public EnsembleContour getContour(int id)

Searches the EnsembleContours defined under this choir by id.

Parameters:

id - The indicated id.

Returns:

The contour specification with the indicated id.

shiftContourUp

public void shiftContourUp(int id)

Decrements a contour specification's id by 1.

Parameters:

id - The contour id.

shiftContourDown

public void shiftContourDown(int id)

Increments a contour's id by 1.

Parameters:

id - The contour id.

createVoice

public EnsembleVoice createVoice(java.lang.String voiceName,
                                 int voiceID)

Adds an EnsembleVoice to the choir.

Parameters:

voiceName - The new voice name. May not already be used by any parent or child choir.

voiceID - The new voice id. May not already be used by any parent or child choir.

Returns:

The newly created EnsembleVoice instance.

createVoice

public EnsembleVoice createVoice(java.lang.String voiceName)

Adds an EnsembleVoice to the choir using the next available voice ID.

Parameters:

voiceName - The new voice name. May not already be used by any parent or child choir.

Returns:

The newly created EnsembleVoice instance.

removeVoice

public void removeVoice(java.lang.String name)

Remove an existing EnsembleVoice from the choir.

Parameters:

name - The voice name.

removeVoice

public void removeVoice(int id)

Remove an existing EnsembleVoice from the choir.

Parameters:

id - The voice id.

getVoice

public EnsembleVoice getVoice(java.lang.String name)

Searches the EnsembleVoices defined under this choir by name.

Parameters:

name - The indicated name.

Returns:

The voice specification with the indicated name.

getAnyVoice

public EnsembleVoice getAnyVoice()

Description copied from class: ContainerOfChoirsAndContours

Searches for any voice specification defined under this Ensemble or Choir, or from any sub-choir.

Specified by:

getAnyVoice in class ContainerOfChoirsAndContours

Returns:

The first voice specification found.

getMusicXmlPartsByName

public java.util.SortedMap<java.lang.String,MusicXmlPart> getMusicXmlPartsByName()

Get the choir-specific collection of MusicXmlPart instances.

Returns:

A collection of MusicXmlPart instances indexed by name.

getMusicXmlPartsByID

public java.util.SortedMap<java.lang.Integer,MusicXmlPart> getMusicXmlPartsByID()

Get the choir-specific collection of MusicXmlPart instances.

Returns:

A collection of MusicXmlPart instances indexed by id.

resolve

public void resolve()

Overrides:

resolve in class ContainerOfChoirsAndContours

check

public boolean check(HtmlBuilder builder)

Description copied from class: WriteableEntity

Check this component for errors and inconsistencies

Overrides:

check in class ContainerOfChoirsAndContours

Parameters:

builder - Accumulates an HTML formatted record of each error or inconsistency found.

Returns:

False if any errors or inconsistencies are found; true otherwise.

getMidiControls

public java.util.SortedMap<java.lang.String,MidiControl> getMidiControls()

Returns:

The collection of MidiControls defined under this choir, indexed by control name.

getParentControl

public MidiControl getParentControl(TypeOfMidiControl controlType)

Search by control type for a MidiControl which is defined in this choir or one of its parents.

Parameters:

controlType - The indicated control type.

Returns:

The MidiControl with the indicated control type (null if not found).

getChildControl

public MidiControl getChildControl(TypeOfMidiControl controlType)

Search by name for a MidiControl which is defined in any sub-choir of this choir.

Parameters:

controlType - The indicated control type.

Returns:

The first MidiControl found with the indicated name (null if not found).

hasExistingControl

public boolean hasExistingControl(TypeOfMidiControl controlType)

Tests if a MidiControl exists for a indicated controlType.

Parameters:

controlType - The indicated controlType.

Returns:

True if there is either a parent control or child control with the indicated name; false otherwise.

addMidiControl

public MidiControl addMidiControl(TypeOfMidiControl controlType)

Add a new MidiControl to a choir.

Parameters:

controlType - The new control's type. May not already be used by any parent or child choir.

Returns:

The newly created MidiControl.

removeMidiControl

public void removeMidiControl(TypeOfMidiControl controlType)

Parameters:

controlType -

getMidiControl

public MidiControl getMidiControl(TypeOfMidiControl controlType)

Search the MidiControls defined under this choir by control type.

Parameters:

controlType - The indicated control type.

Returns:

The MidiControl with the indicated control type (null if not found).

createMusicXmlPart

public MusicXmlPart createMusicXmlPart(java.lang.String name,
                                       int id)

Create a new MusicXmlPart instance.

Parameters:

name - The new MusicXML part name. Must not be used by any existing MusicXmlPart.

id - The new MusicXML part id. Must not be used by any existing MusicXmlPart.

Returns:

The newly created MusicXmlPart instance.

Throws:

java.lang.IllegalArgumentException - If the ensemble already has a MusicXmlPart with the indicated id or name.

createMusicXmlPart

public MusicXmlPart createMusicXmlPart(java.lang.String name)

Create a new MusicXmlPart instance using the next available id.

Parameters:

name - The new MusicXML part name. Must not be used by any existing MusicXmlPart.

Returns:

The newly created MusicXmlPart instance.

fromXmlNode

public static EnsembleChoir fromXmlNode(org.w3c.dom.Element element,
                                        ContainerOfChoirsAndContours container)

Create a new Choir instance and fill it with loaded data.

Parameters:

element - The XML element that provides the Choir data

container - The Choir or Ensemble which will contain the new Choir.

Returns:

The newly created Choir instance.

wipe

public void wipe()

Description copied from class: Entity

Clear all data in this Entity instance.

Overrides:

wipe in class ContainerOfChoirsAndContours

getSubchoirPaths

public void getSubchoirPaths(java.util.List<java.lang.String> result)

Compile a list of sub-choir paths

Parameters:

result - The list which is to receive each path string.

fromXmlNode

public static EnsembleChoir fromXmlNode(org.w3c.dom.Element element,
                                        EnsembleInstrument instrument)

Create a new {code EnsembleChoir} instance and fill it with loaded data.

Parameters:

element - The XML element that provides the {code EnsembleChoir} data

instrument - The {link EnsembleInstrument} which will contain the new {code EnsembleChoir}.

Returns:

The newly created {code EnsembleChoir} instance.

createXmlSpec

public static XmlSpec createXmlSpec()

Create an XML specification for the EnsembleChoir class.

Returns:

The newly created XmlSpec instance.

Throws:

java.lang.RuntimeException - when an XmlSpec instance already exists for the EnsembleChoir class.

equals

public boolean equals(EnsembleEntity other)

Description copied from class: EnsembleEntity

Check if this entity has the same class and content as another entity.

Overrides:

equals in class ContainerOfChoirsAndContours

Parameters:

other - The other entity.

Returns:

True if the two entities have the same class and content; false otherwise.