org.apache.axiom.om.OMNamedInformationItem Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you 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;
/**
* Represents an information item that has a name, more precisely a namespace URI, a local name and
* a prefix. This applies to elements and attributes.
*/
public interface OMNamedInformationItem extends OMInformationItem {
/**
* Get the local name of the information item.
*
* @return the local name of the information item
*/
String getLocalName();
/**
* Set the local name of this information item.
*
* @param localName
* the new local name of the information item
*/
void setLocalName(String localName);
/**
* Get the namespace this information item is part of.
*
* @return The namespace of this information item, or null if the information item
* has no namespace. Note that this implies that the method never returns an
* {@link OMNamespace} object with both prefix and namespace URI set to the empty
* string. In addition, the prefix of the returned {@link OMNamespace} object (if any)
* is never null: if a null prefix was specified when creating
* this information item, then a prefix has been automatically assigned and the assigned
* prefix is returned.
*/
OMNamespace getNamespace();
/**
* Set the namespace for this information item. This will change the namespace URI and the
* prefix of the information item. In addition, if declare is true
* this method ensures that a corresponding namespace declaration exists: if no corresponding
* namespace declaration is already in scope, then a new one will be added to the nearest
* element (i.e. the element itself if this information item is an element or the owner element
* if this information item is an attribute).
*
* @param namespace
* The new namespace for this information item, or null to remove the
* namespace from this information item. If an {@link OMNamespace} instance with a
* null prefix is given, then a prefix will be generated automatically.
* In this case, the generated prefix can be determined using {@link #getNamespace()}
* method.
* @param declare
* Indicates whether a namespace declaration should be generated if necessary;
* ignored if the information item is an attribute without owner element.
* @throws IllegalArgumentException
* if an attempt is made to change the namespace of the information item in such a
* way that it would make the document ill-formed with respect to namespaces (e.g.
* binding a prefix to the empty namespace name)
*/
void setNamespace(OMNamespace namespace, boolean declare);
/**
* Get the QName of this information item.
*
* Note that if you simply need to check if the information item has a given QName, then you
* should use {@link #hasName(QName)} instead of this method.
*
* @return the {@link QName} for the information item
*/
QName getQName();
/**
* Get the prefix of this information item. Note that the contract of this method is identical
* to DOM's {@link org.w3c.dom.Node#getPrefix()} (when called on an {@link org.w3c.dom.Element}
* or {@link org.w3c.dom.Attr}).
*
* @return the prefix of the information item or null if the information item has
* no prefix
*/
String getPrefix();
/**
* Get the namespace URI of this information item. Note that the contract of this method is
* identical to DOM's {@link org.w3c.dom.Node#getNamespaceURI()} (when called on an
* {@link org.w3c.dom.Element} or {@link org.w3c.dom.Attr}).
*
* @return the namespace URI of the information item or null if the information
* item has no namespace
*/
String getNamespaceURI();
/**
* Determine if this information item has the given name. Note that only the namespace URI and
* local part will be compared, the prefix is ignored.
*
* The result of the expression node.hasName(name) is the same as
* node.getQName().equals(name). However, the former expression is generally more
* efficient than the latter because it avoids the creation of the {@link QName} object. In
* addition, for an {@link OMSourcedElement} it avoids the expansion of the element if the
* prefix is unknown.
*
* @param name
* the QName to compare with the QName of this information item
* @return true if the information item has the given name, false
* otherwise
*/
boolean hasName(QName name);
}