org.apache.axiom.om.OMContainer Maven / Gradle / Ivy
/*
* Copyright 2004,2005 The Apache Software Foundation.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.axiom.om;
import javax.xml.namespace.QName;
import java.util.Iterator;
/**
* Captures the operations related to containment shared by both a document and an element.
*
* Exposes the ability to add, find, and iterate over the children of a document or
* element.
*/
public interface OMContainer {
/**
* Adds the given node as the last child. One must preserve the order of children,
* in this operation.
* Tip : appending the new child is preferred.
*
* @param omNode
*/
public void addChild(OMNode omNode);
/**
* Returns an iterator for child nodes matching the criteria indicated by the given QName.
*
* This function searches in three ways:
*
* - Exact match - Both parts of the passed QName are non-null. Only children with the
* same namespace and local name will be returned.
*
* - Namespace match - The local name of the passed QName is null. All children matching the
* namespace will be returned by the iterator.
*
* - Local name match - The namespace of the passed QName is null. All children with the
* matching local name will be returned by the iterator.
*
*
*
*
* Example: header.getChildrenWithName( new QName(ADDRESSING_NAMESPACE, null));
* will return all of the "addressing" headers.
*
*
* @param elementQName The QName specifying namespace and local name to match.
* @return Returns an iterator of {@link OMElement} items that match the given QName appropriately.
*/
public Iterator getChildrenWithName(QName elementQName);
/**
* Returns the first child in document order that matches the given QName criteria.
*
* The QName filter is applied as in the function {@link #getChildrenWithName}.
*
* @param elementQName The QName to use for matching.
*
* @return Returns the first element in document order that matches the elementQName criteria.
*
* @see #getChildrenWithName
*
* @throws OMException Could indirectly trigger building of child nodes.
*/
public OMElement getFirstChildWithName(QName elementQName) throws OMException;
/**
* Returns an iterator for the children of the container.
*
* @return Returns a {@link Iterator} of children, all of which implement {@link OMNode}.
*
* @see #getFirstChildWithName
* @see #getChildrenWithName
*/
public Iterator getChildren();
/**
* Gets the first child.
*
* @return Returns the first child. May return null if the container has no children.
*/
public OMNode getFirstOMChild();
public boolean isComplete();
public void buildNext();
}