/* IXMLElement.java NanoXML/Java
*
* $Revision: 1.4 $
* $Date: 2002/01/04 21:03:28 $
* $Name: RELEASE_2_2_1 $
*
* This file is part of NanoXML 2 for Java.
* Copyright (C) 2000-2002 Marc De Scheemaecker, All Rights Reserved.
*
* This software is provided 'as-is', without any express or implied warranty.
* In no event will the authors be held liable for any damages arising from the
* use of this software.
*
* Permission is granted to anyone to use this software for any purpose,
* including commercial applications, and to alter it and redistribute it
* freely, subject to the following restrictions:
*
* 1. The origin of this software must not be misrepresented; you must not
* claim that you wrote the original software. If you use this software in
* a product, an acknowledgment in the product documentation would be
* appreciated but is not required.
*
* 2. Altered source versions must be plainly marked as such, and must not be
* misrepresented as being the original software.
*
* 3. This notice may not be removed or altered from any source distribution.
*/
package edu.isi.karma.modeling.research.graphmatching.net.n3.nanoxml;
import java.io.Serializable;
import java.util.Enumeration;
import java.util.Hashtable;
import java.util.Properties;
import java.util.Vector;
/**
* @author kriesen
*/
public interface IXMLElement
{
/**
* No line number defined.
*/
public static final int NO_LINE = -1;
/**
* Creates an element to be used for #PCDATA content.
*/
public IXMLElement createPCDataElement();
/**
* Creates an empty element.
*
* @param fullName the name of the element.
*/
public IXMLElement createElement(String fullName);
/**
* Creates an empty element.
*
* @param fullName the name of the element.
* @param systemID the system ID of the XML data where the element starts.
* @param lineNr the line in the XML data where the element starts.
*/
public IXMLElement createElement(String fullName,
String systemID,
int lineNr);
/**
* Creates an empty element.
*
* @param fullName the full name of the element
* @param namespace the namespace URI.
*/
public IXMLElement createElement(String fullName,
String namespace);
/**
* Creates an empty element.
*
* @param fullName the full name of the element
* @param namespace the namespace URI.
* @param systemID the system ID of the XML data where the element starts.
* @param lineNr the line in the XML data where the element starts.
*/
public IXMLElement createElement(String fullName,
String namespace,
String systemID,
int lineNr);
/**
* Returns the parent element. This method returns null for the root
* element.
*/
public IXMLElement getParent();
/**
* Returns the full name (i.e. the name including an eventual namespace
* prefix) of the element.
*
* @return the name, or null if the element only contains #PCDATA.
*/
public String getFullName();
/**
* Returns the name of the element.
* @return the name, or null if the element only contains #PCDATA.
* @uml.property name="name"
*/
public String getName();
/**
* Returns the namespace of the element.
*
* @return the namespace, or null if no namespace is associated with the
* element.
*/
public String getNamespace();
/**
* Sets the full name. This method also sets the short name and clears the namespace URI.
* @param name the non-null name.
* @uml.property name="name"
*/
public void setName(String name);
/**
* Sets the name.
*
* @param fullName the non-null full name.
* @param namespace the namespace URI, which may be null.
*/
public void setName(String fullName,
String namespace);
/**
* Adds a child element.
*
* @param child the non-null child to add.
*/
public void addChild(IXMLElement child);
/**
* Removes a child element.
*
* @param child the non-null child to remove.
*/
public void removeChild(IXMLElement child);
/**
* Removes the child located at a certain index.
*
* @param index the index of the child, where the first child has index 0.
*/
public void removeChildAtIndex(int index);
/**
* Returns an enumeration of all child elements.
*
* @return the non-null enumeration
*/
public Enumeration enumerateChildren();
/**
* Returns whether the element is a leaf element.
*
* @return true if the element has no children.
*/
public boolean isLeaf();
/**
* Returns whether the element has children.
*
* @return true if the element has children.
*/
public boolean hasChildren();
/**
* Returns the number of children.
*
* @return the count.
*/
public int getChildrenCount();
/**
* Returns a vector containing all the child elements.
*
* @return the vector.
*/
public Vector getChildren();
/**
* Returns the child at a specific index.
*
* @param index the index of the child
*
* @return the non-null child
*
* @throws java.lang.ArrayIndexOutOfBoundsException
* if the index is out of bounds.
*/
public IXMLElement getChildAtIndex(int index)
throws ArrayIndexOutOfBoundsException;
/**
* Searches a child element.
*
* @param name the full name of the child to search for.
*
* @return the child element, or null if no such child was found.
*/
public IXMLElement getFirstChildNamed(String name);
/**
* Searches a child element.
*
* @param name the name of the child to search for.
* @param namespace the namespace, which may be null.
*
* @return the child element, or null if no such child was found.
*/
public IXMLElement getFirstChildNamed(String name,
String namespace);
/**
* Returns a vector of all child elements named <I>name</I>.
*
* @param name the full name of the children to search for.
*
* @return the non-null vector of child elements.
*/
public Vector getChildrenNamed(String name);
/**
* Returns a vector of all child elements named <I>name</I>.
*
* @param name the name of the children to search for.
* @param namespace the namespace, which may be null.
*
* @return the non-null vector of child elements.
*/
public Vector getChildrenNamed(String name,
String namespace);
/**
* Returns the number of attributes.
*/
public int getAttributeCount();
/**
* @deprecated As of NanoXML/Java 2.0.1, replaced by
* {@link #getAttribute(java.lang.String,java.lang.String)}
* Returns the value of an attribute.
*
* @param name the non-null name of the attribute.
*
* @return the value, or null if the attribute does not exist.
*/
public String getAttribute(String name);
/**
* Returns the value of an attribute.
*
* @param name the non-null full name of the attribute.
* @param defaultValue the default value of the attribute.
*
* @return the value, or defaultValue if the attribute does not exist.
*/
public String getAttribute(String name,
String defaultValue);
/**
* Returns the value of an attribute.
*
* @param name the non-null name of the attribute.
* @param namespace the namespace URI, which may be null.
* @param defaultValue the default value of the attribute.
*
* @return the value, or defaultValue if the attribute does not exist.
*/
public String getAttribute(String name,
String namespace,
String defaultValue);
/**
* Returns the value of an attribute.
*
* @param name the non-null full name of the attribute.
* @param defaultValue the default value of the attribute.
*
* @return the value, or defaultValue if the attribute does not exist.
*/
public int getAttribute(String name,
int defaultValue);
/**
* Returns the value of an attribute.
*
* @param name the non-null name of the attribute.
* @param namespace the namespace URI, which may be null.
* @param defaultValue the default value of the attribute.
*
* @return the value, or defaultValue if the attribute does not exist.
*/
public int getAttribute(String name,
String namespace,
int defaultValue);
/**
* Returns the type of an attribute.
*
* @param name the non-null full name of the attribute.
*
* @return the type, or null if the attribute does not exist.
*/
public String getAttributeType(String name);
/**
* Returns the namespace of an attribute.
*
* @param name the non-null full name of the attribute.
*
* @return the namespace, or null if there is none associated.
*/
public String getAttributeNamespace(String name);
/**
* Returns the type of an attribute.
*
* @param name the non-null name of the attribute.
* @param namespace the namespace URI, which may be null.
*
* @return the type, or null if the attribute does not exist.
*/
public String getAttributeType(String name,
String namespace);
/**
* Sets an attribute.
*
* @param name the non-null full name of the attribute.
* @param value the non-null value of the attribute.
*/
public void setAttribute(String name,
String value);
/**
* Sets an attribute.
*
* @param fullName the non-null full name of the attribute.
* @param namespace the namespace URI of the attribute, which may be null.
* @param value the non-null value of the attribute.
*/
public void setAttribute(String fullName,
String namespace,
String value);
/**
* Removes an attribute.
*
* @param name the non-null name of the attribute.
*/
public void removeAttribute(String name);
/**
* Removes an attribute.
*
* @param name the non-null name of the attribute.
* @param namespace the namespace URI of the attribute, which may be null.
*/
public void removeAttribute(String name,
String namespace);
/**
* Returns an enumeration of all attribute names.
*
* @return the non-null enumeration.
*/
public Enumeration enumerateAttributeNames();
/**
* Returns whether an attribute exists.
*
* @param name the non-null name of the attribute.
*
* @return true if the attribute exists.
*/
public boolean hasAttribute(String name);
/**
* Returns whether an attribute exists.
*
* @param name the non-null name of the attribute.
* @param namespace the namespace URI of the attribute, which may be null.
*
* @return true if the attribute exists.
*/
public boolean hasAttribute(String name,
String namespace);
/**
* Returns all attributes as a Properties object.
*
* @return the non-null set.
*/
public Properties getAttributes();
/**
* Returns all attributes in a specific namespace as a Properties object.
*
* @param namespace the namespace URI of the attributes, which may be null.
*
* @return the non-null set.
*/
public Properties getAttributesInNamespace(String namespace);
/**
* Returns the system ID of the data where the element started.
*
* @return the system ID, or null if unknown.
*
* @see #getLineNr
*/
public String getSystemID();
/**
* Returns the line number in the data where the element started.
*
* @return the line number, or NO_LINE if unknown.
*
* @see #NO_LINE
* @see #getSystemID
*/
public int getLineNr();
/**
* Return the #PCDATA content of the element. If the element has a combination of #PCDATA content and child elements, the #PCDATA sections can be retrieved as unnamed child objects. In this case, this method returns null.
* @return the content.
* @uml.property name="content"
*/
public String getContent();
/**
* Sets the #PCDATA content. It is an error to call this method with a non-null value if there are child objects.
* @param content the (possibly null) content.
* @uml.property name="content"
*/
public void setContent(String content);
/**
* Returns true if the element equals another element.
*
* @param rawElement the element to compare to
*/
public boolean equals(Object rawElement);
/**
* Returns true if the element equals another element.
*
* @param rawElement the element to compare to
*/
public boolean equalsXMLElement(IXMLElement elt);
}