dims 2002/06/14 11:37:34
Modified: java/src/javax/xml/rpc/encoding DeserializationContext.java
Deserializer.java DeserializerFactory.java
SerializationContext.java Serializer.java
SerializerFactory.java TypeMapping.java
TypeMappingRegistry.java XMLType.java
java/src/javax/xml/namespace QName.java
Log:
Updating javadocs for javax.xml.rpc.encoding and javax.xml.namespace
Revision Changes Path
1.7 +1 -1
xml-axis/java/src/javax/xml/rpc/encoding/DeserializationContext.java
Index: DeserializationContext.java
===================================================================
RCS file:
/home/cvs/xml-axis/java/src/javax/xml/rpc/encoding/DeserializationContext.java,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- DeserializationContext.java 15 Jan 2002 15:56:30 -0000 1.6
+++ DeserializationContext.java 14 Jun 2002 18:37:33 -0000 1.7
@@ -60,7 +60,7 @@
* processing mechanism specific manner. A deserializer uses this interface to
access and maintain context information
* during the deserialization..
*
- * @version 0.6
+ * @version 1.0
*/
public interface DeserializationContext {}
1.8 +13 -8 xml-axis/java/src/javax/xml/rpc/encoding/Deserializer.java
Index: Deserializer.java
===================================================================
RCS file: /home/cvs/xml-axis/java/src/javax/xml/rpc/encoding/Deserializer.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- Deserializer.java 13 May 2002 14:49:00 -0000 1.7
+++ Deserializer.java 14 Jun 2002 18:37:33 -0000 1.8
@@ -52,19 +52,24 @@
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*/
-
package javax.xml.rpc.encoding;
/**
- * The javax.xml.rpc.encoding.Deserializer interface defines a base interface for
deserializers.
- * A Deserializer converts an XML representation to a Java object
- * using a specific XML processing mechanism and based on the
- * specified type mapping and encoding style.
+ * The javax.xml.rpc.encoding.Deserializer interface defines a
+ * base interface for deserializers. A Deserializer converts
+ * an XML representation to a Java object using a specific XML
+ * processing mechanism and based on the specified type
+ * mapping and encoding style.
*
- * @version 0.6
+ * @version 1.0
*/
public interface Deserializer extends java.io.Serializable {
+
+ /**
+ * Gets the type of the XML processing mechanism and
+ * representation used by this Deserializer.
+ *
+ * @return XML processing mechanism type
+ */
public String getMechanismType();
}
-
-
1.8 +5 -5
xml-axis/java/src/javax/xml/rpc/encoding/DeserializerFactory.java
Index: DeserializerFactory.java
===================================================================
RCS file:
/home/cvs/xml-axis/java/src/javax/xml/rpc/encoding/DeserializerFactory.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- DeserializerFactory.java 13 May 2002 14:49:00 -0000 1.7
+++ DeserializerFactory.java 14 Jun 2002 18:37:33 -0000 1.8
@@ -58,10 +58,11 @@
import javax.xml.rpc.JAXRPCException;
/**
- * The javax.xml.rpc.encoding.DeserializerFactory is a factory of deserializers. A
DeserializerFactory is
- * registered with a TypeMapping instance as part of the TypeMappingRegistry.
+ * The javax.xml.rpc.encoding.DeserializerFactory is a factory of
+ * deserializers. A DeserializerFactory is registered with a
+ * TypeMapping instance as part of the TypeMappingRegistry.
*
- * @version 0.6
+ * @version 1.0
*/
public interface DeserializerFactory extends java.io.Serializable {
@@ -73,8 +74,7 @@
* @return Returns a Deserializer for the specified XML processing mechanism
type.
*
* @throws JAXRPCException If DeserializerFactory does not support
- * the specified XML processing mechanism
- * java.lang.IllegalArgumentException If an invalid mechanism type is specified.
+ * the specified XML processing mechanism
*/
public Deserializer getDeserializerAs(String mechanismType);
1.7 +7 -7
xml-axis/java/src/javax/xml/rpc/encoding/SerializationContext.java
Index: SerializationContext.java
===================================================================
RCS file:
/home/cvs/xml-axis/java/src/javax/xml/rpc/encoding/SerializationContext.java,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- SerializationContext.java 15 Jan 2002 15:56:30 -0000 1.6
+++ SerializationContext.java 14 Jun 2002 18:37:33 -0000 1.7
@@ -56,14 +56,14 @@
package javax.xml.rpc.encoding;
/**
- * The javax.xml.rpc.encoding.SerializationContext interface is
- * implemented by the JAX-RPC runtime system in an XML
- * processing mechanism specific manner. A serializer uses the
- * SerializationContext interface during the serialization
- * to get the context information related to the XML processing mechanism
- * and to manage information specific to serialization.
+ * The javax.xml.rpc.encoding.SerializationContext interface is
+ * implemented by the JAX-RPC runtime system in an XML processing
+ * mechanism specific manner. A serializer uses the
+ * SerializationContext interface during the serialization to get
+ * the context information related to the XML processing mechanism
+ * and to manage information specific to serialization.
*
- * @version 0.6
+ * @version 1.0
*/
public interface SerializationContext {}
1.7 +7 -7 xml-axis/java/src/javax/xml/rpc/encoding/Serializer.java
Index: Serializer.java
===================================================================
RCS file: /home/cvs/xml-axis/java/src/javax/xml/rpc/encoding/Serializer.java,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- Serializer.java 15 Jan 2002 15:56:30 -0000 1.6
+++ Serializer.java 14 Jun 2002 18:37:33 -0000 1.7
@@ -56,20 +56,20 @@
package javax.xml.rpc.encoding;
/**
- * The javax.xml.rpc.encoding.Serializer interface defines
- * a base interface for serializers. A Serializer serializes
- * a Java object to an XML representation using a specific
- * XML processing mechanism and based on the specified type
- * mapping and encoding style.
+ * The javax.xml.rpc.encoding.Serializer interface defines the
+ * base interface for serializers. A Serializer converts
+ * a Java object to an XML representation using a specific XML
+ * processing mechanism and based on the specified type
+ * mapping and encoding style.
*
- * @version 0.6
+ * @version 1.0
*/
public interface Serializer extends java.io.Serializable {
/**
* Gets the type of the XML processing mechanism and representation used by
this Serializer.
*
- * @return XML processing mechanism type supported by this Serializer
+ * @return XML processing mechanism type
*/
public String getMechanismType();
}
1.8 +4 -4 xml-axis/java/src/javax/xml/rpc/encoding/SerializerFactory.java
Index: SerializerFactory.java
===================================================================
RCS file: /home/cvs/xml-axis/java/src/javax/xml/rpc/encoding/SerializerFactory.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- SerializerFactory.java 13 May 2002 14:49:00 -0000 1.7
+++ SerializerFactory.java 14 Jun 2002 18:37:33 -0000 1.8
@@ -59,11 +59,11 @@
import java.util.Iterator;
/**
- * The javax.xml.rpc.encoding.SerializerFactory is a factory of the serializers.
- * A SerializerFactory is registered
- * with a TypeMapping object as part of the TypeMappingRegistry.
+ * The javax.xml.rpc.encoding.SerializerFactory is a factory of
+ * the serializers. A SerializerFactory is registered with a
+ * TypeMapping object as part of the TypeMappingRegistry.
*
- * @version 0.6
+ * @version 1.0
*/
public interface SerializerFactory extends java.io.Serializable {
1.12 +54 -42 xml-axis/java/src/javax/xml/rpc/encoding/TypeMapping.java
Index: TypeMapping.java
===================================================================
RCS file: /home/cvs/xml-axis/java/src/javax/xml/rpc/encoding/TypeMapping.java,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- TypeMapping.java 11 Jun 2002 14:53:50 -0000 1.11
+++ TypeMapping.java 14 Jun 2002 18:37:33 -0000 1.12
@@ -59,67 +59,78 @@
import javax.xml.rpc.JAXRPCException;
/**
- * The javax.xml.rpc.encoding.TypeMapping is the base interface for
- * representation of a type mapping. A TypeMapping implementation class
- * may support one or more encoding styles and XML schema namespaces.
- *
- * For its supported encoding styles and XML schema namespaces,
- * a TypeMapping instance maintains a set of tuples of
- * the type
- * {Java type, SerializerFactory, DeserializerFactory, XML data type}.
+ * The <code>javax.xml.rpc.encoding.TypeMapping</code> is the base
+ * interface for the representation of a type mapping. A TypeMapping
+ * implementation class may support one or more encoding styles.
+ * <p>
+ * For its supported encoding styles, a TypeMapping instance
+ * maintains a set of tuples of the type {Java type,
+ * <code>SerializerFactory</code>,
+ * <code>DeserializerFactory</code>, XML type}.
*
- * @version 0.6
+ * @version 1.0
*/
public interface TypeMapping {
/**
- * Gets the list of encoding styles supported by this TypeMapping.
+ * Returns the encodingStyle URIs (as String[]) supported by
+ * this TypeMapping instance. A TypeMapping that contains only
+ * encoding style independent serializers and deserializers
+ * returns <code>null</code> from this method.
*
- * @return String[] of namespace URIs for the supported encoding
- * styles and XML schema namespaces.
+ * @return Array of encodingStyle URIs for the supported
+ * encoding styles
*/
public String[] getSupportedEncodings();
/**
- * Sets the list of encoding styles supported by this
- * TypeMapping.
+ * Sets the encodingStyle URIs supported by this TypeMapping
+ * instance. A TypeMapping that contains only encoding
+ * independent serializers and deserializers requires
+ * <code>null</code> as the parameter for this method.
*
- * @param namespaceURIs String[] of namespace URI's
+ * @param encodingStyleURIs Array of encodingStyle URIs for the
+ supported encoding styles
*/
- public void setSupportedEncodings(String[] namespaceURIs);
+ public void setSupportedEncodings(String[] encodingStyleURIs);
/**
- * isRegistered returns true if the [javaType, xmlType]
- * pair is registered.
- * @param javaType - Class of the Java type
- * @param xmlType - Qualified name of the XML data type
- * @return: false if either javaType or xmlType is null
- * or if the pair is not specifically registered.
+ * Checks whether or not type mapping between specified XML
+ * type and Java type is registered.
+ *
+ * @param javaType Class of the Java type
+ * @param xmlType Qualified name of the XML data type
+ * @return boolean; <code>true</code> if type mapping between the
+ * specified XML type and Java type is registered;
+ * otherwise <code>false</code>
*/
public boolean isRegistered(Class javaType, QName xmlType);
/**
- * Registers SerializerFactory and DeserializerFactory for a
+ * Registers SerializerFactory and DeserializerFactory for a
* specific type mapping between an XML type and Java type.
+ * This method replaces any existing registered SerializerFactory
+ * DeserializerFactory instances.
*
- * @param javaType - Class of the Java type
- * @param xmlType - Qualified name of the XML data type
- * @param sf - SerializerFactory
- * @param dsf - DeserializerFactory
+ * @param javaType Class of the Java type
+ * @param xmlType Qualified name of the XML data type
+ * @param sf SerializerFactory
+ * @param dsf DeserializerFactory
*
- * @throws JAXRPCException - If any error during the registration
+ * @throws JAXRPCException If any error during the registration
*/
public void register(Class javaType, QName xmlType, SerializerFactory sf,
DeserializerFactory dsf);
/**
- * Gets the SerializerFactory registered for the specified pair
- * of Java type and XML data type.
+ * Gets the SerializerFactory registered for the specified
+ * pair of Java type and XML data type.
*
- * @param javaType - Class of the Java type
- * @param xmlType - Qualified name of the XML data type
+ * @param javaType Class of the Java type
+ * @param xmlType Qualified name of the XML data type
*
- * @return Registered SerializerFactory or null if there is no registered
factory.
+ * @return Registered SerializerFactory or <code>null</code>
+ * if there is no registered factory
*/
public SerializerFactory getSerializer(Class javaType, QName xmlType);
@@ -127,10 +138,11 @@
* Gets the DeserializerFactory registered for the specified pair
* of Java type and XML data type.
*
- * @param javaType - Class of the Java type
- * @param xmlType - Qualified name of the XML data type
+ * @param javaType Class of the Java type
+ * @param xmlType Qualified name of the XML data type
*
- * @return Registered DeserializerFactory or null if there is no registered
factory.
+ * @return Registered SerializerFactory or <code>null</code>
+ * if there is no registered factory
*/
public DeserializerFactory getDeserializer(Class javaType, QName xmlType);
@@ -138,10 +150,10 @@
* Removes the SerializerFactory registered for the specified
* pair of Java type and XML data type.
*
- * @param javaType - Class of the Java type
- * @param xmlType - Qualified name of the XML data type
+ * @param javaType Class of the Java type
+ * @param xmlType Qualified name of the XML data type
*
- * @throws JAXRPCException - If there is error
+ * @throws JAXRPCException If there is error
* in removing the registered SerializerFactory
*/
public void removeSerializer(Class javaType, QName xmlType);
@@ -150,10 +162,10 @@
* Removes the DeserializerFactory registered for the specified
* pair of Java type and XML data type.
*
- * @param javaType - Class of the Java type
- * @param xmlType - Qualified name of the XML data type
+ * @param javaType Class of the Java type
+ * @param xmlType Qualified name of the XML data type
*
- * @throws JAXRPCException - If there is error in removing
+ * @throws JAXRPCException If there is error in removing
* the registered DeserializerFactory
*/
public void removeDeserializer(Class javaType, QName xmlType);
1.13 +83 -70
xml-axis/java/src/javax/xml/rpc/encoding/TypeMappingRegistry.java
Index: TypeMappingRegistry.java
===================================================================
RCS file:
/home/cvs/xml-axis/java/src/javax/xml/rpc/encoding/TypeMappingRegistry.java,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- TypeMappingRegistry.java 13 May 2002 13:11:33 -0000 1.12
+++ TypeMappingRegistry.java 14 Jun 2002 18:37:33 -0000 1.13
@@ -33,7 +33,7 @@
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
- * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+ * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
@@ -55,113 +55,126 @@
package javax.xml.rpc.encoding;
-import javax.xml.rpc.JAXRPCException;
-import java.util.Iterator;
/**
- * The interface javax.xml.rpc.encoding.TypeMappingRegistry
- * defines a registry for TypeMapping instances for
- * the different encoding styles.
+ * The interface <code>javax.xml.rpc.encoding.TypeMappingRegistry</code>
+ * defines a registry of TypeMapping instances for various encoding
+ * styles.
*
- * @version 0.7
+ * @version 1.0
*/
public interface TypeMappingRegistry extends java.io.Serializable {
/**
- * Registers a TypeMapping instance with the TypeMappingRegistry. This
- * method replaces any existing registered TypeMapping instance for the
- * specified namespaceURI.
- *
- * @param namespaceURI - An encoding style or XML schema namespace specified
- * as an URI. An example is
- * "http://schemas.xmlsoap.org/soap/encoding/";
- * @param mapping - TypeMapping instance
- *
- * @return Previous TypeMapping associated with the specified namespaceURI,
- * or null if there was no TypeMapping associated with the specified
namespaceURI
- *
- * @throws JAXRPCException - If there is any error in the registration
- * of the TypeMapping for the specified namespace URI
- */
- public TypeMapping register(String namespace, TypeMapping mapping);
+ * Registers a <code>TypeMapping</code> instance with the
+ * <code>TypeMappingRegistry</code>. This method replaces any
+ * existing registered <code>TypeMapping</code> instance for
+ * the specified <code>encodingStyleURI</code>.
+ *
+ * @param encodingStyleURI An encoding style specified as an URI.
+ * An example is "http://schemas.xmlsoap.org/soap/encoding/";
+ * @param mapping TypeMapping instance
+ *
+ * @return Previous TypeMapping associated with the specified
+ * <code>encodingStyleURI</code>, or <code>null</code>
+ * if there was no TypeMapping associated with the specified
+ * <code>encodingStyleURI</code>
+ *
+ * @throws JAXRPCException If there is an error in the
+ * registration of the <code>TypeMapping</code> for
+ * the specified <code>encodingStyleURI</code>.
+ */
+ public TypeMapping register(String encodingStyleURI, TypeMapping mapping);
/**
- * Registers the TypeMapping instance that is default for all encoding
- * styles and XML schema namespaces supported by the TypeMappingRegistry. A
- * default TypeMapping should include serializers and deserializers that are
- * independent of and usable with any encoding style or XML namespaces. The
- * successive invocations of the registerDefault method replace any existing
- * default TypeMapping instance.
+ * Registers the <code>TypeMapping</code> instance that is default
+ * for all encoding styles supported by the
+ * <code>TypeMappingRegistry</code>. A default <code>TypeMapping</code>
+ * should include serializers and deserializers that are independent
+ * of and usable with any encoding style. Successive invocations
+ * of the <code>registerDefault</code> method replace any existing
+ * default <code>TypeMapping</code> instance.
* <p>
- * If the default TypeMapping is registered, any other TypeMapping instances
- * registered through the TypeMappingRegistry.register method (for a set of
- * namespace URIs) override the default TypeMapping.
+ * If the default <code>TypeMapping</code> is registered, any
+ * other TypeMapping instances registered through the
+ * <code>TypeMappingRegistry.register</code> method (for a set
+ * of encodingStyle URIs) override the default <code>TypeMapping</code>.
*
- * @param mapping - TypeMapping instance
+ * @param mapping TypeMapping instance
*
- * @throws JAXRPCException - If there is any error in the registration
- * of the TypeMapping for the specified namespace URI
+ * @throws JAXRPCException If there is an error in the
+ * registration of the default <code>TypeMapping</code>
*/
public void registerDefault(TypeMapping mapping);
/**
- * Return the registered default TypeMapping instance
- * @return TypeMapping or null
- **/
- public TypeMapping getDefaultTypeMapping();
-
- /**
- * Returns the registered TypeMapping for the specified namespace URI. If
- * there is no registered TypeMapping for the specified namespaceURI, this
- * method returns null.
- *
- * @param namespaceURI - Encoding style or XML schema namespace specified
- * as an URI
- * @return TypeMapping for the specified namespace URI or null
+ * Gets the registered default <code>TypeMapping</code> instance.
+ * This method returns <code>null</code> if there is no registered
+ * default TypeMapping in the registry.
+ *
+ * @return The registered default <code>TypeMapping</code> instance
+ * or <code>null</code>
*/
- public TypeMapping getTypeMapping(String namespaceURI);
+ public TypeMapping getDefaultTypeMapping();
/**
- * Unregisters a TypeMapping instance, if present, from the specified
- * namespaceURI.
+ * Returns a list of registered encodingStyle URIs in this
+ * <code>TypeMappingRegistry</code> instance.
*
- * @param namespaceURI - Encoding style or XML schema namespace specified
- * as an URI
- * @return The registered TypeMapping or null.
+ * @return Array of the registered encodingStyle URIs
*/
- public TypeMapping unregisterTypeMapping(String namespaceURI);
+ public String[] getRegisteredEncodingStyleURIs();
/**
- * Removes a TypeMapping from the TypeMappingRegistry. A TypeMapping is
- * associated with 1 or more namespaceURIs. This method unregisters the
- * specified TypeMapping instance from all associated namespaceURIs and then
- * removes this TypeMapping instance from the registry.
+ * Returns the registered <code>TypeMapping</code> for the specified
+ * encodingStyle URI. If there is no registered <code>TypeMapping</code>
+ * for the specified <code>encodingStyleURI</code>, this method
+ * returns <code>null</code>.
*
- * @param mapping - TypeMapping to remove
- * @return true if specified TypeMapping is removed from the
TypeMappingRegistry;
- * false if the specified TypeMapping was not in the TypeMappingRegistry
+ * @param encodingStyleURI Encoding style specified as an URI
+ * @return TypeMapping for the specified encodingStyleURI or
+ * <code>null</code>
*/
- public boolean removeTypeMapping(TypeMapping mapping);
-
+ public TypeMapping getTypeMapping(String encodingStyleURI);
/**
- * Creates a new empty TypeMapping object.
+ * Creates a new empty <code>TypeMapping</code> object.
*
* @return TypeMapping instance.
*/
public TypeMapping createTypeMapping();
/**
- * Gets a list of namespace URIs registered with this TypeMappingRegistry.
+ * Unregisters a TypeMapping instance, if present, from the specified
+ * encodingStyleURI.
*
- * @return String[] containing names of all registered namespace URIs
+ * @param encodingStyleURI Encoding style specified as an URI
+ * @return <code>TypeMapping</code> instance that has been unregistered
+ * or <code>null</code> if there was no TypeMapping
+ * registered for the specified <code>encodingStyleURI</code>
+ */
+ public TypeMapping unregisterTypeMapping(String encodingStyleURI);
+
+ /**
+ * Removes a <code>TypeMapping</code> from the TypeMappingRegistry. A
+ * <code>TypeMapping</code> is associated with 1 or more
+ * encodingStyleURIs. This method unregisters the specified
+ * <code>TypeMapping</code> instance from all associated
+ * <code>encodingStyleURIs</code> and then removes this
+ * TypeMapping instance from the registry.
+ *
+ * @param mapping TypeMapping to remove
+ * @return <code>true</code> if specified <code>TypeMapping</code>
+ * is removed from the TypeMappingRegistry; <code>false</code>
+ * if the specified <code>TypeMapping</code> was not in the
+ * <code>TypeMappingRegistry</code>
*/
- public String[] getRegisteredEncodingStyleURIs();
-
+ public boolean removeTypeMapping(TypeMapping mapping);
/**
- * Removes all TypeMappings and namespaceURIs from this TypeMappingRegistry.
+ * Removes all registered TypeMappings and encodingStyleURIs
+ * from this TypeMappingRegistry.
*/
public void clear();
1.9 +2 -0 xml-axis/java/src/javax/xml/rpc/encoding/XMLType.java
Index: XMLType.java
===================================================================
RCS file: /home/cvs/xml-axis/java/src/javax/xml/rpc/encoding/XMLType.java,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- XMLType.java 11 Jun 2002 14:53:50 -0000 1.8
+++ XMLType.java 14 Jun 2002 18:37:33 -0000 1.9
@@ -59,6 +59,8 @@
/**
* Class XMLType
+ *
+ * @version 1.0
*/
public class XMLType {
1.3 +47 -42 xml-axis/java/src/javax/xml/namespace/QName.java
Index: QName.java
===================================================================
RCS file: /home/cvs/xml-axis/java/src/javax/xml/namespace/QName.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- QName.java 11 Jun 2002 15:21:01 -0000 1.2
+++ QName.java 14 Jun 2002 18:37:34 -0000 1.3
@@ -58,23 +58,15 @@
import java.io.Serializable;
/**
- * QName class represents a qualified name based on "Namespaces in XML"
- * specification. A QName is represented as:
+ * <code>QName</code> class represents the value of a qualified name
+ * as specified in <a href="http://www.w3.org/TR/xmlschema-2/#QName";>XML
+ * Schema Part2: Datatypes specification</a>.
+ * <p>
+ * The value of a QName contains a <b>namespaceURI</b> and a <b>localPart</b>.
+ * The localPart provides the local part of the qualified name. The
+ * namespaceURI is a URI reference identifying the namespace.
*
- * QName ::= (Prefix ':') ? LocalPart
- *
- * Upgraded the implementation so that the namespaceURI and localPart are
- * always non-null. This simplifies the implementation, increases performance,
- * and cleans up NullPointerException problems.
- *
- * Upgraded the implemenation to make QName a final class, changed the
- * namespaceURI and localPart to final (and interned) Strings, changed equals()
- * to use == comparison on interned Strings.
- *
- * Updated to optimize use of empty string, and remove erroneous
- * (or at least (possibly?) optimizer-dependent) equivalence checks.
- *
- * @version 0.1
+ * @version 1.0
*/
public class QName implements Serializable {
/** comment/shared empty string */
@@ -89,7 +81,7 @@
/**
* Constructor for the QName.
*
- * @param localPart - Local part of the QName
+ * @param localPart Local part of the QName
*/
public QName(String localPart) {
this.namespaceURI = emptyString;
@@ -99,8 +91,8 @@
/**
* Constructor for the QName.
*
- * @param namespaceURI - Namespace URI for the QName
- * @param localPart - Local part of the QName.
+ * @param namespaceURI Namespace URI for the QName
+ * @param localPart Local part of the QName.
*/
public QName(String namespaceURI, String localPart) {
this.namespaceURI =
@@ -113,7 +105,7 @@
/**
* Gets the Namespace URI for this QName
*
- * @return namespaceURI
+ * @return Namespace URI
*/
public String getNamespaceURI() {
return namespaceURI;
@@ -122,7 +114,7 @@
/**
* Gets the Local part for this QName
*
- * @return the Local part for this QName.
+ * @return Local part
*/
public String getLocalPart() {
return localPart;
@@ -140,41 +132,51 @@
}
/**
- * Indicates whether some other object is "equal to" this QName object.
+ * Tests this QName for equality with another object.
+ * <p>
+ * If the given object is not a QName or is null then this method
+ * returns <tt>false</tt>.
+ * <p>
+ * For two QNames to be considered equal requires that both
+ * localPart and namespaceURI must be equal. This method uses
+ * <code>String.equals</code> to check equality of localPart
+ * and namespaceURI. Any class that extends QName is required
+ * to satisfy this equality contract.
+ * <p>
+ * This method satisfies the general contract of the <code>Object.equals</code>
method.
*
- * @param p1 - the reference object with which to compare
+ * @param obj the reference object with which to compare
*
- * @return true if this object is the same as the obj argument; false otherwise.
+ * @return <code>true</code> if the given object is identical to this
+ * QName: <code>false</code> otherwise.
*/
- public final boolean equals(Object p1) {
- if (p1 == this) {
+ public final boolean equals(Object obj) {
+ if (obj == this) {
return true;
}
- if (!(p1 instanceof QName)) {
+ if (!(obj instanceof QName)) {
return false;
}
- if (namespaceURI == ((QName)p1).namespaceURI &&
- localPart == ((QName) p1).localPart) {
+ if (namespaceURI == ((QName)obj).namespaceURI &&
+ localPart == ((QName)obj).localPart) {
return true;
}
-
- // Since the strings are interned, a direct == of the strings
- // is all that is needed. Here is the old code.
- // if (namespaceURI.equals(((QName)p1).namespaceURI) &&
- // localPart.equals(((QName)p1).localPart)) {
- // return true;
- // }
return false;
}
/**
- * Returns a QName holding the value of the specified String. The string must
be in the form returned by the
- * QName.toString() method, i.e. "{namespaceURI}localPart", with the
"{namespaceURI}" part being optional.
- * This method doesn't do a full validation of the resulting QName. In
particular, it doesn't check that the
- * resulting namespace URI is a legal URI (per RFC 2396 and RFC 2732), nor that
the resulting local part is a
- * legal NCName per the XML Namespaces specification.
+ * Returns a QName holding the value of the specified String.
+ * <p>
+ * The string must be in the form returned by the QName.toString()
+ * method, i.e. "{namespaceURI}localPart", with the "{namespaceURI}"
+ * part being optional.
+ * <p>
+ * This method doesn't do a full validation of the resulting QName.
+ * In particular, it doesn't check that the resulting namespace URI
+ * is a legal URI (per RFC 2396 and RFC 2732), nor that the resulting
+ * local part is a legal NCName per the XML Namespaces specification.
*
* @param s the string to be parsed
* @throws java.lang.IllegalArgumentException If the specified String cannot be
parsed as a QName
@@ -200,7 +202,10 @@
}
/**
- * Returns a hash code value for this QName object.
+ * Returns a hash code value for this QName object. The hash code
+ * is based on both the localPart and namespaceURI parts of the
+ * QName. This method satisfies the general contract of the
+ * <code>Object.hashCode</code> method.
*
* @return a hash code value for this Qname object
*/
