PackageTop Level
Classpublic final class QName
InheritanceQName Inheritance Object

Language version: ActionScript 3.0
Runtime version: 

QName objects represent qualified names of XML elements and attributes. Each QName object has a local name and a namespace Uniform Resource Identifier (URI). When the value of the namespace URI is null, the QName object matches any namespace. Use the QName constructor to create a new QName object that is either a copy of another QName object or a new QName object with a uri from a Namespace object and a localName from a QName object.

Methods specific to E4X can use QName objects interchangeably with strings. E4X methods are in the QName, Namespace, XML, and XMLList classes. These E4X methods, which take a string, can also take a QName object. This interchangeability is how namespace support works with, for example, the XML.child() method.

The QName class (along with the XML, XMLList, and Namespace classes) implements powerful XML-handling standards defined in ECMAScript for XML (E4X) specification (ECMA-357 edition 2).

A qualified identifier evaluates to a QName object. If the QName object of an XML element is specified without identifying a namespace, the uri property of the associated QName object is set to the global default namespace. If the QName object of an XML attribute is specified without identifying a namespace, the uri property is set to an empty string.

View the examples.

See also

XML
XMLList
Namespace
ECMAScript for XML (E4X) specification (ECMA-357 edition 2)


Public Properties
 PropertyDefined by
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
  localName : String
[read-only] The local name of the QName object.
QName
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
  uri : String
[read-only] The Uniform Resource Identifier (URI) of the QName object.
QName
Public Methods
 MethodDefined by
  
QName(uri:Namespace, localName:QName)
Creates a QName object with a URI from a Namespace object and a localName from a QName object.
QName
  
QName(qname:QName)
Creates a QName object that is a copy of another QName object.
QName
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
  
Returns a string composed of the URI, and the local name for the QName object, separated by "::".
QName
  
Returns the QName object.
QName
Property detail
localNameproperty
localName:String  [read-only]

Language version: ActionScript 3.0
Runtime version: 

The local name of the QName object.

Implementation
    public function get localName():String
uriproperty 
uri:String  [read-only]

Language version: ActionScript 3.0
Runtime version: 

The Uniform Resource Identifier (URI) of the QName object.

Implementation
    public function get uri():String
Constructor detail
QName()constructor
public function QName(uri:Namespace, localName:QName)

Language version: ActionScript 3.0
Runtime version: 

Creates a QName object with a URI from a Namespace object and a localName from a QName object. If either parameter is not the expected data type, the parameter is converted to a string and assigned to the corresponding property of the new QName object. For example, if both parameters are strings, a new QName object is returned with a uri property set to the first parameter and a localName property set to the second parameter. In other words, the following permutations, along with many others, are valid forms of the constructor:


QName (uri:Namespace, localName:String);

QName (uri:String, localName: QName);

QName (uri:String, localName: String);

If you pass null for the uri parameter, the uri property of the new QName object is set to null.

Note: This class shows two constructor entries because each form accepts different parameters. The constructor behaves differently depending on the type and number of parameters passed, as detailed in each entry. ActionScript 3.0 does not support method or constructor overloading.

Parameters
uri:Namespace — A Namespace object from which to copy the uri value. A parameter of any other type is converted to a string.
 
localName:QName — A QName object from which to copy the localName value. A parameter of any other type is converted to a string.
QName()constructor 
public function QName(qname:QName)

Language version: ActionScript 3.0
Runtime version: 

Creates a QName object that is a copy of another QName object. If the parameter passed to the constructor is a QName object, a copy of the QName object is created. If the parameter is not a QName object, the parameter is converted to a string and assigned to the localName property of the new QName instance. If the parameter is undefined or unspecified, a new QName object is created with the localName property set to the empty string.

Note: This class shows two constructor entries because each form accepts different parameters. The constructor behaves differently depending on the type and number of parameters passed, as detailed in each entry. ActionScript 3.0 does not support method or constructor overloading.

Parameters
qname:QName — The QName object to be copied. Objects of any other type are converted to a string that is assigned to the localName property of the new QName object.
Method detail
toString()method
AS3 function toString():String

Language version: ActionScript 3.0
Runtime version: 

Returns a string composed of the URI, and the local name for the QName object, separated by "::".

The format depends on the uri property of the QName object:

If uri == "" 

		toString returns localName

	else if uri == null

		toString returns *::localName 

	else

		toString returns uri::localName

Returns
String — The qualified name, as a string.
valueOf()method 
AS3 function valueOf():QName

Language version: ActionScript 3.0
Runtime version: 

Returns the QName object.

Returns
QName — The primitive value of a QName instance.
Examples
examples\QNameExample
The following example shows how to create a QName instance and use it to select XML elements. Two ways of creating a QName are shown:
  1. Creating a Namespace instance and then using it as input to the QName constructor. This approach is best if you want to use the Namespace.prefix property for other purposes later.
  2. Creating a QName instance using a simple string value for the uri parameter in the QName constructor.

This code does the following things:

  1. Defines an XML variable named rssXML.
  2. Creates a new Namespace object with the prefix dc.
  3. Creates a new QName object using the Namespace object and the local name creator.
  4. Calls the showDescendants() method, which uses the XML.descendants() method to get an XMLList instance containing all the descendant elements whose qualified name matches the given QName instance.
  5. Displays the qualified name and the text value of each element in the list using a for each loop.
  6. Creates another QName object using a string value for the uri parameter and the local name date.
  7. Calls the showDescendants() method again to display the name and text value of the descendant elements.
package
{
	import flash.display.Sprite;
	
	public class QNameExample extends Sprite
	{
		public function QNameExample()
		{
            var rssXML:XML =  <rdf:RDF
              xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
              xmlns="http://purl.org/rss/1.0/"
              xmlns:dc="http://purl.org/dc/elements/1.1/">
              <channel rdf:about="http://www.xml.com/cs/xml/query/q/19">
                <title>Test RSS</title>
                <link>http://www.adobe.com/</link>
                <description>This is a test RSS document.</description>
                <language>en-us</language>
                <items>
                  <rdf:Seq>
                <rdf:li rdf:resource="http://www.adobe.com/devnet/flash/"/>
                <rdf:li rdf:resource="http://www.adobe.com/devnet/flex/"/>
                  </rdf:Seq>
                </items>
              </channel>
              <item rdf:about="http://www.adobe.com/devnet/flash/">
                <title>Flash Developer Center</title>
                <link>http://www.adobe.com/devnet/flash/</link>
                <description>Welcome to the Flash Developer Center</description>
                <dc:creator>Adobe</dc:creator>
                <dc:date>2005-08-08</dc:date>    
              </item>
              <item rdf:about="http://www.adobe.com/devnet/flex/">
                <title>Flex Developer Center</title>
                <link>http://www.adobe.com/devnet/flex/</link>
                <description>Welcome to the Flex Developer Center</description>
                <dc:creator>Adobe</dc:creator>
                <dc:date>2005-10-16</dc:date>    
              </item>
            </rdf:RDF>;
            
            var dcNamespace:Namespace = new Namespace("dc", "http://purl.org/dc/elements/1.1/");
            var creatorQName:QName = new QName(dcNamespace, "creator");
            trace(creatorQName.uri); // http://purl.org/dc/elements/1.1/
            trace(creatorQName.localName); // creator
            
            showDescendants(rssXML, creatorQName);
            
            var dateQName:QName = new QName("http://purl.org/dc/elements/1.1/", "date");
            trace(dateQName.uri); // http://purl.org/dc/elements/1.1/
            trace(dateQName.localName); // date
            
            showDescendants(rssXML, dateQName);
		}
		
        public function showDescendants(xmlData:XML, qualifiedName:QName):void
        {
            var decendantList:XMLList = xmlData.descendants(qualifiedName);
            
            for each (var element:XML in decendantList)
            {
            	trace(element.name()); // the fully qualified name, 
            	                       // like "http://purl.org/dc/elements/1.1/::creator"
            	trace(element); // the simple text value of each element, like "Adobe"
	        }            	
        }
	}
}