public interface Name {
// Public Instance Methods
public abstract String getLocalName( );
public abstract String getPrefix( );
public abstract String getQualifiedName( );
public abstract String getURI( );
}
Name is an interface that encapsulates the concept
of an XML element name that may be namespace-qualified. It is used
whenever such a name is required by the SAAJ API instead of the
javax.xml.namespace.QName class, which is used by
JAX-RPC. A Name has three attributes:
A local name, which all Name objects are required
to have
A namespace URI, which uniquely identifies the namespace within which
the local name is defined
The prefix that is used as a shorthand identifier for the namespace
and that appears along with the local name in XML tags
Name objects can be obtained by calling one of the
createName( ) methods of the
SOAPFactory class or the
SOAPEnvelope interface. These methods have two
variants:
public Name createName(String localName) throws SOAPException;
public Name createName(String localName, String prefix, String uri)
throws SOAPException;
The first method creates a Name that is not
explicitly associated with a namespace, as in the following example:
SOAPFactory factory = SOAPFactory.newInstance;
Name bookTitle = factory.createName("BookTitle");
SOAPElement bookTitleElement = factory.createElement(bookTitle);
If bookTitleElement is added to a
SOAPMessage and serialized, it appears as
BookTitle. The fact that the
Name object does not have an explicit namespace
does not, however, mean that an element created from it is not in a
namespace. In fact, the element is in the default namespace assigned
either by itself or by the nearest ancestor element that has an
xmlns with no namespace prefix, if there is one.
The second method returns a Name element that has
an explicit namespace defined by the uri argument.
Wherever the Name object is used to create a
SOAPElement and then serialized, both the local
name and the prefix appear. The following code creates an element
called BookTitle in a namespace defined by the URI
urn:BookService:
SOAPFactory factory = SOAPFactory.newInstance();
Name bookTitle = factory.createName("BookTitle", "book", "urn:BookService");
SOAPElement bookTitleElement = factory.createElement(bookTitle);
When the bookTitleElement is serialized, it
appears as book:BookTitle, and a namespace
declaration mapping the prefix book to the URI
urn:BookService is added:
<book:BookTitle xmlns:book="urn:BookService">
The getLocalPart( ), getPrefix,
and getURI( ) methods return the values of the
three independent attributes of the Name object.
The getQualifiedName( ) method returns a string
that shows how the element will appear within the serialized SOAP
message. For the two examples shown previously, this method returns
either BookTitle or
book:BookTitle.
It is important to note that two Name objects are
considered to be equal if they have the same local part and the same
namespace URI. In other words, the prefix is not a factor in the
comparison.
