Content

java.lang.Object
- uk.ac.sheffield.jast.xml.Content

All Implemented Interfaces:

java.lang.Cloneable, java.lang.Iterable<Content>

Direct Known Subclasses:

Document, Markup, Text
```
public abstract class Content
extends java.lang.Object
implements java.lang.Cloneable, java.lang.Iterable<Content>
```
Content is the abstract ancestor of different kinds of XML content. The different kinds of Content include the Document itself, and its contained Declaration, Instruction, Doctype, Comment, Element, Attribute, Text and Data nodes. Content nodes obey a standard interface for navigating up and down in the XML tree. This includes the ability to add, remove and access child Content nodes and navigate to the parent Content node, iterate over a Content node and all of its descendants, and navigate to the containing Document.
Content is the root of a Composite Design Pattern (Gamma et al., 1996). Content fulfils the component-role, and its subclass Element fulfils the composite-role, acting as a container for further Content nodes. Each Content subtype controls what kinds of Content may be added as children. The standard behaviour of addContent(Content) either adds the node, or ignores it, if it is not appropriate. Some leaf-nodes, such as Text, treat addContent(Text) as a request to append the textual content of the other node. It is possible to iterate over the Content subtree in document order (a pre-order traversal) using a XMLIterator, which is used implicitly when a foreach style of iteration is requested. Explicit iteration may also supply a Filter to restrict which kinds of Content node are visited.
Content nodes may be added to at most one parent Content node. This is to preserve the tree-structure of an XML document. If it is desired to move Content, this must first be detached from its parent. If it is desired to duplicate Content for attachment elsewhere, the Content must first be cloned to produce an unattached copy. The cloned Content is a deep copy of the Content subtree, in which all Content nodes are recursively cloned and re-attached to their cloned parents, but all raw data is shared.

Version:

2.5

Author:

Anthony J H Simons

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`ATTRIBUTE` A constant denoting the Attribute content-type.
`static int`	`COMMENT` A constant denoting the Comment content-type.
`static int`	`DATA` A constant denoting the Data content-type.
`static int`	`DECLARATION` A constant denoting the Declaration content-type.
`static int`	`DOCTYPE` A constant denoting the Doctype content-type.
`static int`	`DOCUMENT` A constant denoting the Document content-type.
`static int`	`ELEMENT` A constant denoting the Element content-type.
`static int`	`INSTRUCTION` A constant denoting the Instruction content-type.
`private Content`	`parent` The owner of this Content node.
`static int`	`TEXT` A constant denoting the Text content-type.
`static int`	`UNDEFINED` A constant denoting the undefined content-type.

Constructor Summary

Constructors
Modifier Constructor and Description

protected Content()
Creates this Content node.

Constructors
Modifier	Constructor and Description
`protected`	`Content()` Creates this Content node.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Content`	`addAttribute(Attribute node)` Adds an Attribute to this Content node.
`Content`	`addContent(Content node)` Adds another Content node to this Content.
`Content`	`addContent(java.lang.String text)` Adds textual content to this Content.
`Content`	`clone()` Clones this Content node and its descendants.
`java.util.Iterator<Content>`	`descendants()` Returns an Iterator which visits the descendants of this Content node.
`java.util.Iterator<Content>`	`descendants(Filter filter)` Returns an Iterator which visits a filtered subset of the descendants of this Content node.
`Content`	`detach()` Detaches this Content node from its parent node.
`java.util.List<Attribute>`	`getAttributes()` Returns a list of this Content node's Attributes.
`Comment`	`getComment()` Returns the first Comment node associated with this Content.
`Content`	`getContent(Filter filter)` Returns the first child Content node satisfying the matching rule of a Filter.
`Content`	`getContent(Filter filter, int index)` Returns the child Content node satisfying a Filter and found at the given index.
`Content`	`getContent(int index)` Returns the Content node found under this node at the given index.
`java.util.List<Content>`	`getContents()` Returns a list of all the contents under this Content node.
`java.util.List<Content>`	`getContents(Filter filter)` Returns a list of contents under this Content node that satisfy the matching rule of a Filter.
`Document`	`getDocument()` Returns the Document associated with this Content node.
`java.lang.String`	`getIdentifier()` Returns the identifier for this Content.
`Content`	`getParent()` Returns the parent Content node of this Content node.
`java.lang.String`	`getText()` Returns the textual content of this Content node.
`int`	`getType()` Returns the type of this Content.
`boolean`	`hasContents()` Reports whether this Content node has any contents.
`java.util.Iterator<Content>`	`iterator()` Returns an Iterator which traverses this Content subtree in pre-order.
`java.util.Iterator<Content>`	`iterator(Filter filter)` Returns an Iterator which visits a filtered subset of this Content subtree.
`Content`	`removeContent(Content node)` Removes a Content node from this Content's immediate children.
`Content`	`removeContent(int index)` Removes the Content node at the given index from this Content's immediate children.
`java.util.List<Content>`	`removeContents(Filter filter)` Removes all Content nodes immediately under this node that satisfy the matching rule of a Filter.
`protected void`	`setParent(Content node)` Secret method used to install a parent Content node.
`java.lang.String`	`toString()` Returns a pretty representation of this Content.

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

Methods inherited from interface java.lang.Iterable
forEach, spliterator

- Field Detail
  - UNDEFINED
```
public static final int UNDEFINED
```
    A constant denoting the undefined content-type. Used as the type of null, the undefined node, this bit-mask is rejected by all Filters. Therefore, do not ever use this bit-mask as a Filter type!
    
    See Also:
    
    Constant Field Values
  - ATTRIBUTE
```
public static final int ATTRIBUTE
```
    A constant denoting the Attribute content-type. A Filter with this bit-mask will match only Attribute (XML attribute) nodes.
    
    See Also:
    
    Constant Field Values
  - ELEMENT
```
public static final int ELEMENT
```
    A constant denoting the Element content-type. A Filter with this bit-mask will match only Element (XML element) nodes.
    
    See Also:
    
    Constant Field Values
  - TEXT
```
public static final int TEXT
```
    A constant denoting the Text content-type. A Filter with this bit-mask will match only Text (XML PCDATA) nodes.
    
    See Also:
    
    Constant Field Values
  - DATA
```
public static final int DATA
```
    A constant denoting the Data content-type. A Filter with this bit-mask will match only Data (XML CDATA) nodes.
    
    See Also:
    
    Constant Field Values
  - DECLARATION
```
public static final int DECLARATION
```
    A constant denoting the Declaration content-type. A Filter with this bit-mask will match only Declaration (XML declaration) nodes.
    
    See Also:
    
    Constant Field Values
  - INSTRUCTION
```
public static final int INSTRUCTION
```
    A constant denoting the Instruction content-type. A Filter with this bit-mask will match only Instruction (XML processing-instruction) nodes.
    
    See Also:
    
    Constant Field Values
  - DOCTYPE
```
public static final int DOCTYPE
```
    A constant denoting the Doctype content-type. A Filter with this bit-mask will match only Doctype (XML DOCTYPE) nodes.
    
    See Also:
    
    Constant Field Values
  - COMMENT
```
public static final int COMMENT
```
    A constant denoting the Comment content-type. A Filter with this bit-mask will match only Comment nodes.
    
    See Also:
    
    Constant Field Values
  - DOCUMENT
```
public static final int DOCUMENT
```
    A constant denoting the Document content-type. A Filter with this bit-mask will match only the Document node. Also used as a sentinel, this bit-mask should always have the highest bit-value of all of the content-types.
    
    See Also:
    
    Constant Field Values
  - parent
```
private Content parent
```
    The owner of this Content node. This is initially null and is set to a single parent Content element, when this Content node is added as a child of another Content node. When this Content is removed from the children of another Content node, it is set to null.
- Constructor Detail
  - Content
```
protected Content()
```
    Creates this Content node.
- Method Detail
  - setParent
```
protected void setParent(Content node)
                  throws SemanticError
```
    Secret method used to install a parent Content node. This method is called inside the addContent(Content) method, and checks that this Content node has at most one parent node. This method is also called with a null argument by the removeContent(Content) method to detach this Content node from its parent.
    
    Parameters:
    
    node - the desired parent node, possibly null.
    
    Throws:
    
    SemanticError
  - clone
```
public Content clone()
```
    Clones this Content node and its descendants. Creates a true copy of each Content node in this Content node's subtree, but shares other data and object references. Returns an unattached deep copy of this Content node, connected to its cloned subtree. By default, this method returns a shallow copy of this Content node. It is overridden in each subclass to return an instance of the most specific type, and to perform recursive cloning and node re-attachment where required.
    
    Overrides:
    
    clone in class java.lang.Object
  - detach
```
public Content detach()
```
    Detaches this Content node from its parent node. If this Content node is attached to a parent, removes this node from the parent's content list and sets this node's parent to null. Otherwise, does nothing.
    
    Returns:
    
    this Content node.
  - getType
```
public int getType()
```
    Returns the type of this Content. Returns an integer value denoting the type of this Content. This is one of the public constants defined in Content. By default, this method returns UNDEFINED, denoting some unspecified Content type. It is overridden in each subclass.
    
    Returns:
    
    the integer constant UNDEFINED.
  - getParent
```
public Content getParent()
```
    Returns the parent Content node of this Content node. This is useful when navigating up the XML tree.
    
    Returns:
    
    the parent of this Content node.
  - getIdentifier
```
public java.lang.String getIdentifier()
```
    Returns the identifier for this Content. If this Content is a kind of Markup with a long identifier, returns this label. Otherwise, returns this Content's class name. This method is useful to visualise the kinds of Content under a node.
    
    Returns:
    
    the name of this Content.
  - getComment
```
public Comment getComment()
```
    Returns the first Comment node associated with this Content. This is a convenience method to allow access to a single Comment child under those Content nodes that contain children nodes.
    
    Returns:
    
    the first Comment, or null.
  - addContent
```
public Content addContent(Content node)
```
    Adds another Content node to this Content. If this Content node is an Element, adds the Content node to the end of this Element's immediate contents. If this Content node is a leaf-node and the other Content node contains compatible textual content, appends the text to the end of this Content's textual content. Otherwise, ignores the request.
    
    Parameters:
    
    node - another Content node.
    
    Returns:
    
    this Content node.
  - addContent
```
public Content addContent(java.lang.String text)
```
    Adds textual content to this Content. If this Content node is an Element, adds a new Text node to the end of this Element's immediate contents. If this Content node is a leaf-node, attempts to validate the textual content and appends the text to the end of this Content's textual content. The default implementation does nothing.
    
    Parameters:
    
    text - the textual content.
    
    Returns:
    
    this Content node.
  - getContent
```
public Content getContent(int index)
```
    Returns the Content node found under this node at the given index. If this Content node has a content list, seeks to return the node at the given index. If no such node exists because the index is out of range, returns null. This is to be consistent with other kinds of searching operation.
    
    Parameters:
    
    index - the index of the Content.
    
    Returns:
    
    the child Content node at the index, or null.
  - getContent
```
public Content getContent(Filter filter)
```
    Returns the first child Content node satisfying the matching rule of a Filter. If this Content node has a content list, and one of the child Content nodes satisfies the matching rule of the Filter, returns this node; otherwise returns null. This is to be consistent with other kinds of searching operation.
    
    Parameters:
    
    filter - the Filter used to select an acceptable node.
    
    Returns:
    
    the found child Content node, or null.
  - getContent
```
public Content getContent(Filter filter,
                          int index)
```
    Returns the child Content node satisfying a Filter and found at the given index. If this Content node has a content list, applies the the matching rule of the Filter to each node in turn, counting each accepted node, and returning the node whose rank matches the index. If no such node exists, returns null.
    
    Parameters:
    
    filter - the Filter used to select acceptable nodes.
    
    index - the index of the sought node.
    
    Returns:
    
    the found child Content node, or null.
  - removeContent
```
public Content removeContent(Content node)
```
    Removes a Content node from this Content's immediate children. If this Content node has a content list, seeks to remove the node from the content list. If the node is removed successfully, returns the node; otherwise returns null. By default, returns null, but is overridden in subclasses.
    
    Parameters:
    
    node - another Content node.
    
    Returns:
    
    the removed node, or null.
  - removeContent
```
public Content removeContent(int index)
```
    Removes the Content node at the given index from this Content's immediate children. If this Content node has a content list, seeks to remove the node at the given index. If the node is removed successfully, returns the node; otherwise returns null.
    
    Parameters:
    
    index - the index of the Content.
    
    Returns:
    
    the removed node, or null.
  - hasContents
```
public boolean hasContents()
```
    Reports whether this Content node has any contents. By default, returns false, but is overridden in subclasses.
    
    Returns:
    
    true if this Content node has contents.
  - getContents
```
public java.util.List<Content> getContents()
```
    Returns a list of all the contents under this Content node. If this is a leaf-node, returns the empty list. The default implementation returns an empty list.
    
    Returns:
    
    a list of Content nodes under this node.
  - getContents
```
public java.util.List<Content> getContents(Filter filter)
```
    Returns a list of contents under this Content node that satisfy the matching rule of a Filter. If this Content node has a content list, returns a new sublist containing only those contents that match the Filter's rule.
    
    Parameters:
    
    filter - a Filter to select acceptable nodes.
    
    Returns:
    
    a list of nodes accepted by the Filter, possibly empty.
  - removeContents
```
public java.util.List<Content> removeContents(Filter filter)
```
    Removes all Content nodes immediately under this node that satisfy the matching rule of a Filter. If this Content node has a content list, seeks to remove all immediate children that match the Filter's rule. Returns a list of the removed Content nodes, possibly empty.
    
    Parameters:
    
    filter - a content Filter.
    
    Returns:
    
    the list of removed Content, possibly empty.
  - addAttribute
```
public Content addAttribute(Attribute node)
```
    Adds an Attribute to this Content node. If this Content node is an Element, or some subclass of Descriptor having Attributes, adds the given Attribute to this node's set. If this node already has an Attribute with the same name, replaces the old Attribute's value. By default, does nothing.
    
    Parameters:
    
    node - the Attribute to add.
    
    Returns:
    
    this Content node.
  - getAttributes
```
public java.util.List<Attribute> getAttributes()
```
    Returns a list of this Content node's Attributes. If this Content node is an Element, or some subclass of Descriptor having Attributes, returns list of Attributes. Otherwise, returns an empty list.
    
    Returns:
    
    a list of this Content node's Attributes.
  - getDocument
```
public Document getDocument()
```
    Returns the Document associated with this Content node. If this Content node is attached to an XML tree that is part of a Document, navigates up the tree and returns the Document. Otherwise, returns null if this Content node is part of an unattached XML tree.
    
    Returns:
    
    this Content node's Document, or null if unattached.
  - getText
```
public java.lang.String getText()
```
    Returns the textual content of this Content node. If this node is an Element node, returns all the text added as its contents, as a single string, by appending the text stored in each child Text or Data node. If this node is an Attribute node, returns the value of the Attribute. If this node is a Text or Data node, returns the encapsulated text. If this node is a Comment, returns the comment string. If this node is a Doctype, returns the grammar as a single string. The default implementation returns an empty string.
    
    Returns:
    
    the textual content of this Content node.
  - iterator
```
public java.util.Iterator<Content> iterator()
```
    Returns an Iterator which traverses this Content subtree in pre-order. This is the default strategy used by foreach-style iteration. Returns an instance of XMLIterator, which will visit each branch-node and leaf-node in document order. If this Content node is a branch-node (a Document or Element), visits this node first, then recursively visits each child subtree, in the order that the subtrees were added. If this Content node is a leaf-node (Text, Data, Doctype, or Comment), visits the node only.
    
    Specified by:
    
    iterator in interface java.lang.Iterable<Content>
    
    Returns:
    
    a XMLIterator, implementing Iterator<Content>.
    
    See Also:
    
    XMLIterator
  - iterator
```
public java.util.Iterator<Content> iterator(Filter filter)
```
    Returns an Iterator which visits a filtered subset of this Content subtree. Returns an instance of XMLIterator having the given Filter, which will traverse each branch-node and leaf-node in document order, but will only visit those nodes satisfying the Filter. The traversal behaviour is identical to unfiltered iteration, but only a subset of nodes are actually visited.
    
    Parameters:
    
    filter - the Filter to apply.
    
    Returns:
    
    a XMLIterator, filtering according to the Filter.
    
    See Also:
    
    XMLIterator
  - descendants
```
public java.util.Iterator<Content> descendants()
```
    Returns an Iterator which visits the descendants of this Content node. Returns an instance of XMLIterator, which will visit all descendants of the starting node, excluding the node itself. The descendants will be visited in document order, according to the same traversal behaviour described for the iterator() method.
    
    Returns:
    
    a XMLIterator, starting with this node's successors.
    
    See Also:
    
    XMLIterator
  - descendants
```
public java.util.Iterator<Content> descendants(Filter filter)
```
    Returns an Iterator which visits a filtered subset of the descendants of this Content node. Returns an instance of XMLIterator having the given Filter, which will traverse all the descendants of the starting node, excluding the node itself, but will only visit those nodes that satisfy the Filter. The traversal behaviour is identical to the unfiltered descendants() method, but only a subset of nodes are actually visited.
    
    Parameters:
    
    filter - the Filter to apply.
    
    Returns:
    
    a XMLIterator, filtering according to the Filter and starting with this node's successors.
    
    See Also:
    
    XMLIterator
  - toString
```
public java.lang.String toString()
```
    Returns a pretty representation of this Content. Returns the same as the identifier of this Content, which may be the given name of a named Element or Attribute, or the type-name of some other kind of content.
    
    Overrides:
    
    toString in class java.lang.Object

Class Content

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Field Detail

UNDEFINED

ATTRIBUTE

ELEMENT

TEXT

DATA

DECLARATION

INSTRUCTION

DOCTYPE

COMMENT

DOCUMENT

parent

Constructor Detail

Content

Method Detail

setParent

clone

detach

getType

getParent

getIdentifier

getComment

addContent

addContent

getContent

getContent

getContent

removeContent

removeContent

hasContents

getContents

getContents

removeContents

addAttribute

getAttributes

getDocument

getText

iterator

iterator

descendants

descendants

toString