net.sourceforge.nite.nom.nomwrite
Interface NOMElement

All Known Subinterfaces:
NOMAnnotation, NOMObject, NOMResourceElement, NOMTypeElement
All Known Implementing Classes:
NOMReadAnnotation, NOMReadElement, NOMReadObject, NOMReadResourceElement, NOMReadTypeElement, NOMWriteAnnotation, NOMWriteElement, NOMWriteObject, NOMWriteResourceElement, NOMWriteTypeElement

public interface NOMElement

Extends the nomread version with methods for adding & deleting elements & attributes

Author:
jonathan

Nested Class Summary
static interface NOMElement.SharedEl
          This inner interface provides some utility functions for shared NOM users
 
Field Summary
static int FEATURAL_LAYER
           
static int IMPLICIT_ORDER
           
static int STRUCTURAL_LAYER
           
static int TEMPORAL_ORDER
           
static int TIME_ALIGNED_LAYER
           
static int UNORDERED
           
static double UNTIMED
           
 
Method Summary
 void addAfterSibling(NOMElement sibling)
          add the element as a sibling of the given element.
 void addAttribute(NOMAttribute attribute)
          add an attribute to the element or if it exists already, just set it
 void addBeforeSibling(NOMElement sibling)
          add the element as a sibling of the given element.
 void addChild(NOMElement child)
          adds a child to this element.
 void addChildAboveChildren(NOMElement newchild, java.util.List old_children)
          Adds the NOMElement newchild in place of the given child list, making the current children children of the newly added node.
 void addChildAfter(NOMElement oldchild, NOMElement newchild)
          adds the NOMElement newchild immediately after the given existing child, or reports an exception if the child cannot be found
 void addChildBefore(NOMElement oldchild, NOMElement newchild)
          adds the NOMElement newchild immediately before the given existing child, or reports an exception if the child cannot be found
 void addExternalPointer(java.lang.String role, java.lang.String value)
          Set the href value of the external pointer from this element.
 void addFirstChild(NOMElement child)
          adds the NOMElement as the first child
 void addLastChild(NOMElement child)
          adds the NOMElement as the last child
 void addPointer(NOMPointer pointer)
          add a pointer to the element
 void addToCorpus()
          add an element to the corpus with no information about location.
 void appendText(java.lang.String chars)
          appends to the textual content of an element.
 void deleteChild(NOMElement child)
          Delete an element.
 NOMElement findAncestorInLayer(NLayer layer)
           
 NOMElement findAncestorNamed(java.lang.String name)
           
 java.util.List findAncestorsInFile()
           
 java.util.Set findAncestorsInLayer(NLayer layer)
           
 java.util.Set findAncestorsNamed(java.lang.String name)
           
 NOMElement findCommonAncestorInFile(NOMElement other)
           
 java.util.List findDescendantsInLayer(NLayer layer)
           
 java.util.List findDescendantsNamed(java.lang.String name)
           
 NAgent getAgent()
          Returns the agent responsible for the element (or null if it's not in an agent coding).
 java.lang.String getAgentName()
          returns the name of the agent responsible for the element (or null if there is none)
 NOMAttribute getAttribute(java.lang.String attribute_name)
          return the NOMAttribute on this element that has the given name (or null if no such attribute exists).
 java.lang.Comparable getAttributeComparableValue(java.lang.String name)
          Returns the value of an attribute specified by his name as Comparable.
 java.util.List getAttributes()
          returns a List of NOMAttributes of this element
 int getChildOrder()
          specifies whether the children are temporally ordered, implicitly ordered or unordered by returning one of UNORDERED, IMPLICIT_ORDER or TEMPORAL_ORDER
 java.util.List getChildren()
          returns a List of NOMElements which are immediate descendents of this element (excluding comment elements)
 java.util.List getChildrenWithInterleavedComments()
          This version of getChildren includes any comments that are present in the correct order within the child stream.
 java.lang.String getColour()
          returns the "colour" of the element (this essentially determines the serialization of elements)
 java.lang.String getComment()
          returns the contents of the reserved comment String (or null if not set)
 NOMCorpus getCorpus()
          Simply return the Corpus that this element is a part of
 double getEndTime()
          returns the end time of the element
 java.lang.String getExternalPointerValue()
          returns the value of any external pointer from this element.
 java.lang.String getGVM()
          returns the Graphical Visual Markup string for the element: this is used by the GRAM tool only for encoding information about on-video overlays
 java.lang.String getID()
          returns the ID of the element
 java.lang.String getKeyStroke()
          returns the keystroke associated with this element (as a string)
 NLayer getLayer()
          Returns the metadata layer to which this element belongs.
 java.lang.String getLink()
          return a string representing an XLink to this element
 NElement getMetadataElement()
          Returns the metadata element for this element.
 java.lang.String getName()
          returns the name of the element (not namespace qualified)
 NOMElement getNextElement()
          returns the element following this one in the corpus if it were to be serialized
 NOMElement getNextSibling()
          returns this element's following sibling of the same colour
 java.lang.String getObservation()
          returns the name of the observation to which the element belongs
 NOMElement getParentInFile()
          returns the NOMElement belonging to the same colour
 java.util.List getParents()
          returns a List of NOMElements which directly dominate this element
 java.util.List getPointers()
          returns a List of NOMPointers pointing from this element
 java.util.List getPointersTo()
          returns a List of NOMPointers that point to this element
 NOMPointer getPointerWithRole(java.lang.String rolename)
          returns the first NOMPointer which has a matching role
 NOMElement getPreviousSibling()
          returns this element's previous sibling of the same colour
 int getRecursiveDepth()
          get the actual recursive depth of this element in its recursive layer where 0 means no parents in this layer; 1 means one etc.
 int getRecursiveHeight()
          get the actual recursive height of this element in its recursive layer where 0 means no children in this layer; 1 means kids to a depth of 1 etc.
 NOMElement.SharedEl getShared()
          return a shared view of this element which simply provides utility functions for editing the element without thinking about locking and unlocking the corpus.
 double getStartTime()
          returns the start time of the element
 java.lang.String getText()
          returns the textual content of the element
 int getTimeType()
          returns the integer TIME_ALIGNED_LAYER, STRUCTURAL_LAYER or FEATURAL_LAYER: the type of the element as far as timing is concerned.
 java.lang.String getXLink()
          Returns the xlink:href to the element this element is stored.
 boolean hasNextElement()
          returns true if there is an element following this one in the corpus if it were to be serialized
 void insertParent(NOMElement newparent, NOMElement oldparent)
          Insert n new parent node, making me and my siblings children of the new parent and making our current parent the parent of the new parent
 boolean isComment()
          returns true if this element is a comment
 boolean isStreamElement()
          A Boolean which is true if this element is a 'stream' type element
 void removeAttribute(java.lang.String name)
          Remove an attribute completely from an element
 void removeChild(NOMElement child)
          Remove a nite:child from an element without actually deleting the element referred to.
 void removeParentAndAdjust(NOMElement par)
          Remove the parent node, making me and my siblings children of our grandparent.
 void removePointer(NOMPointer pointer)
          remove a pointer from the element
 void setComment(java.lang.String comment)
          set the contents of the reserved comment attribute
 void setDoubleAttribute(java.lang.String name, java.lang.Double value)
          Set the value of a named Double attribute
 void setEndTime(double time)
          Set the end time of this element.
 void setGVM(java.lang.String name)
          sets the Graphical Visual Markup string for this element
 void setKeyStroke(java.lang.String name)
          sets the keystroke string associated with this element
 void setName(java.lang.String name)
          sets the name of the element - not commonly used!
 void setStartTime(double time)
          Set the start time of this element.
 void setStreamElement(boolean stream)
          Set the "stream"ness of the element - a stream element is one which is purely there as a container for other elements for the purposes of serialization.
 void setStringAttribute(java.lang.String name, java.lang.String value)
          Set the value of a named string attribute
 void setText(java.lang.String chars)
          sets the textual content of an element.
 

Field Detail

UNTIMED

static final double UNTIMED
See Also:
Constant Field Values

FEATURAL_LAYER

static final int FEATURAL_LAYER
See Also:
Constant Field Values

STRUCTURAL_LAYER

static final int STRUCTURAL_LAYER
See Also:
Constant Field Values

TIME_ALIGNED_LAYER

static final int TIME_ALIGNED_LAYER
See Also:
Constant Field Values

UNORDERED

static final int UNORDERED
See Also:
Constant Field Values

IMPLICIT_ORDER

static final int IMPLICIT_ORDER
See Also:
Constant Field Values

TEMPORAL_ORDER

static final int TEMPORAL_ORDER
See Also:
Constant Field Values
Method Detail

getName

java.lang.String getName()
returns the name of the element (not namespace qualified)


getColour

java.lang.String getColour()
returns the "colour" of the element (this essentially determines the serialization of elements)


getText

java.lang.String getText()
returns the textual content of the element


getID

java.lang.String getID()
returns the ID of the element


getObservation

java.lang.String getObservation()
returns the name of the observation to which the element belongs


getGVM

java.lang.String getGVM()
returns the Graphical Visual Markup string for the element: this is used by the GRAM tool only for encoding information about on-video overlays


getKeyStroke

java.lang.String getKeyStroke()
returns the keystroke associated with this element (as a string)


getChildren

java.util.List getChildren()
returns a List of NOMElements which are immediate descendents of this element (excluding comment elements)


getChildrenWithInterleavedComments

java.util.List getChildrenWithInterleavedComments()
This version of getChildren includes any comments that are present in the correct order within the child stream.


getParents

java.util.List getParents()
returns a List of NOMElements which directly dominate this element


getPointers

java.util.List getPointers()
returns a List of NOMPointers pointing from this element


getPointersTo

java.util.List getPointersTo()
returns a List of NOMPointers that point to this element


getAttributes

java.util.List getAttributes()
returns a List of NOMAttributes of this element


getStartTime

double getStartTime()
returns the start time of the element


getEndTime

double getEndTime()
returns the end time of the element


getTimeType

int getTimeType()
returns the integer TIME_ALIGNED_LAYER, STRUCTURAL_LAYER or FEATURAL_LAYER: the type of the element as far as timing is concerned.


getChildOrder

int getChildOrder()
specifies whether the children are temporally ordered, implicitly ordered or unordered by returning one of UNORDERED, IMPLICIT_ORDER or TEMPORAL_ORDER


isStreamElement

boolean isStreamElement()
A Boolean which is true if this element is a 'stream' type element


getAttributeComparableValue

java.lang.Comparable getAttributeComparableValue(java.lang.String name)
Returns the value of an attribute specified by his name as Comparable. The interface Comparable is useful for comparing values. Because both, String and Double, implement Comparable, this is a useful shorthand, and may speed up reading for example in the search engine.

Parameters:
name - the name of the attribute
Returns:
the value of an attribute as Comparable

getXLink

java.lang.String getXLink()
Returns the xlink:href to the element this element is stored. The xlink:href could be something like "file.xml#id".

Returns:
the xlink:href to the element this element is stored

getComment

java.lang.String getComment()
returns the contents of the reserved comment String (or null if not set)


isComment

boolean isComment()
returns true if this element is a comment


getRecursiveDepth

int getRecursiveDepth()
get the actual recursive depth of this element in its recursive layer where 0 means no parents in this layer; 1 means one etc.


getRecursiveHeight

int getRecursiveHeight()
get the actual recursive height of this element in its recursive layer where 0 means no children in this layer; 1 means kids to a depth of 1 etc.


getMetadataElement

NElement getMetadataElement()
                            throws NOMException
Returns the metadata element for this element.

Throws:
NOMException

getLayer

NLayer getLayer()
                throws NOMException
Returns the metadata layer to which this element belongs. Used when adding elements and in serialization

Throws:
NOMException

getAgent

NAgent getAgent()
Returns the agent responsible for the element (or null if it's not in an agent coding).


getAgentName

java.lang.String getAgentName()
returns the name of the agent responsible for the element (or null if there is none)


getAttribute

NOMAttribute getAttribute(java.lang.String attribute_name)
return the NOMAttribute on this element that has the given name (or null if no such attribute exists).


getCorpus

NOMCorpus getCorpus()
Simply return the Corpus that this element is a part of


getLink

java.lang.String getLink()
return a string representing an XLink to this element


getParentInFile

NOMElement getParentInFile()
returns the NOMElement belonging to the same colour


findAncestorNamed

NOMElement findAncestorNamed(java.lang.String name)

findAncestorInLayer

NOMElement findAncestorInLayer(NLayer layer)

findAncestorsInFile

java.util.List findAncestorsInFile()

findAncestorsNamed

java.util.Set findAncestorsNamed(java.lang.String name)

findAncestorsInLayer

java.util.Set findAncestorsInLayer(NLayer layer)

findCommonAncestorInFile

NOMElement findCommonAncestorInFile(NOMElement other)

findDescendantsInLayer

java.util.List findDescendantsInLayer(NLayer layer)

findDescendantsNamed

java.util.List findDescendantsNamed(java.lang.String name)

hasNextElement

boolean hasNextElement()
returns true if there is an element following this one in the corpus if it were to be serialized


getNextElement

NOMElement getNextElement()
returns the element following this one in the corpus if it were to be serialized


getNextSibling

NOMElement getNextSibling()
returns this element's following sibling of the same colour


getPreviousSibling

NOMElement getPreviousSibling()
returns this element's previous sibling of the same colour


setStringAttribute

void setStringAttribute(java.lang.String name,
                        java.lang.String value)
                        throws NOMException
Set the value of a named string attribute

Throws:
NOMException

setDoubleAttribute

void setDoubleAttribute(java.lang.String name,
                        java.lang.Double value)
                        throws NOMException
Set the value of a named Double attribute

Throws:
NOMException

addAttribute

void addAttribute(NOMAttribute attribute)
                  throws NOMException
add an attribute to the element or if it exists already, just set it

Throws:
NOMException

removeAttribute

void removeAttribute(java.lang.String name)
                     throws NOMException
Remove an attribute completely from an element

Throws:
NOMException

addPointer

void addPointer(NOMPointer pointer)
                throws NOMException
add a pointer to the element

Throws:
NOMException

removePointer

void removePointer(NOMPointer pointer)
                   throws NOMException
remove a pointer from the element

Throws:
NOMException

getPointerWithRole

NOMPointer getPointerWithRole(java.lang.String rolename)
returns the first NOMPointer which has a matching role


getExternalPointerValue

java.lang.String getExternalPointerValue()
returns the value of any external pointer from this element.


setStartTime

void setStartTime(double time)
                  throws NOMException
Set the start time of this element. Only elements in a timed layer can have their start and end times set directly; all structural times are strictly inherited.

Throws:
NOMException

setEndTime

void setEndTime(double time)
                throws NOMException
Set the end time of this element. Only elements in a timed layer can have their start and end times set directly; all structural times are strictly inherited.

Throws:
NOMException

setStreamElement

void setStreamElement(boolean stream)
Set the "stream"ness of the element - a stream element is one which is purely there as a container for other elements for the purposes of serialization.


addFirstChild

void addFirstChild(NOMElement child)
                   throws NOMException
adds the NOMElement as the first child

Throws:
NOMException

addLastChild

void addLastChild(NOMElement child)
                  throws NOMException
adds the NOMElement as the last child

Throws:
NOMException

addChildBefore

void addChildBefore(NOMElement oldchild,
                    NOMElement newchild)
                    throws NOMException
adds the NOMElement newchild immediately before the given existing child, or reports an exception if the child cannot be found

Throws:
NOMException

addChildAfter

void addChildAfter(NOMElement oldchild,
                   NOMElement newchild)
                   throws NOMException
adds the NOMElement newchild immediately after the given existing child, or reports an exception if the child cannot be found

Throws:
NOMException

removeChild

void removeChild(NOMElement child)
                 throws NOMException
Remove a nite:child from an element without actually deleting the element referred to. Throw an error if we're trying to remove the child from its serialized parent.

Throws:
NOMException

deleteChild

void deleteChild(NOMElement child)
                 throws NOMException
Delete an element. Remove the child from all its parents. Ranges need to be handled separately (in a different thread?)

Throws:
NOMException

setText

void setText(java.lang.String chars)
             throws NOMException
sets the textual content of an element.

Throws:
NOMException

appendText

void appendText(java.lang.String chars)
                throws NOMException
appends to the textual content of an element.

Throws:
NOMException

setName

void setName(java.lang.String name)
sets the name of the element - not commonly used!


setGVM

void setGVM(java.lang.String name)
sets the Graphical Visual Markup string for this element


setKeyStroke

void setKeyStroke(java.lang.String name)
sets the keystroke string associated with this element


addToCorpus

void addToCorpus()
                 throws NOMException
add an element to the corpus with no information about location. This should only be used with elements that are in the top level of a coding. If the element is in a timed layer and has start and end times, the placement of the addition in the "stream" is derived from those. Otherwise the element is added at the end of the stream.

Throws:
NOMException

addBeforeSibling

void addBeforeSibling(NOMElement sibling)
                      throws NOMException
add the element as a sibling of the given element. Of course the siblings must be in the same layer and the ordering must not violate any of the precedence constraints

Throws:
NOMException

addAfterSibling

void addAfterSibling(NOMElement sibling)
                     throws NOMException
add the element as a sibling of the given element. Of course the siblings must be in the same layer and the ordering must not violate any of the precedence constraints

Throws:
NOMException

addChild

void addChild(NOMElement child)
              throws NOMException
adds a child to this element. Since no order is specified, add the child to the end of the list of children.

Throws:
NOMException

addChildAboveChildren

void addChildAboveChildren(NOMElement newchild,
                           java.util.List old_children)
                           throws NOMException
Adds the NOMElement newchild in place of the given child list, making the current children children of the newly added node.

Throws:
NOMException

removeParentAndAdjust

void removeParentAndAdjust(NOMElement par)
                           throws NOMException
Remove the parent node, making me and my siblings children of our grandparent. Possibly need to check validity...

Throws:
NOMException

insertParent

void insertParent(NOMElement newparent,
                  NOMElement oldparent)
                  throws NOMException
Insert n new parent node, making me and my siblings children of the new parent and making our current parent the parent of the new parent

Throws:
NOMException

getShared

NOMElement.SharedEl getShared()
return a shared view of this element which simply provides utility functions for editing the element without thinking about locking and unlocking the corpus.


setComment

void setComment(java.lang.String comment)
set the contents of the reserved comment attribute


addExternalPointer

void addExternalPointer(java.lang.String role,
                        java.lang.String value)
                        throws NOMException
Set the href value of the external pointer from this element. Only allowed in elements oin layers of type EXTERNAL_POINTER_LAYER

Throws:
NOMException