Cross-Platform C++

ot::sax
class NamespaceSupport

#include "ot/sax/NamespaceSupport.h"

ot::ManagedObject Tracks Namespace declarations currently in effect.

This class encapsulates the logic of Namespace processing: it tracks the declarations currently in force for each context and automatically processes qualified XML 1.0 names into their Namespace parts; it can also be used in reverse for generating XML 1.0 from Namespaces.

Namespace support objects are reusable, but the reset method must be invoked between each session.

Here is a simple session:

    String uri, localName;
    RefPtr<NamespaceSupport> rpSupport = new NamespaceSupport;
    
    rpSupport->pushContext();
    rpSupport->declarePrefix("", "http://www.w3.org/1999/xhtml");
    rpSupport->declarePrefix("dc", "http://www.purl.org/dc#");
    
    rpSupport->processName("p", false, uri, localName);
    Console::cout() << OT_T("Namespace URI: ") << uri << endl;
    Console::cout() << OT_T("Local name: ") << localName << endl;

    rpSupport->processName("dc:title", false, uri, localName);
    Console::cout() << OT_T("Namespace URI: ") << uri << endl;
    Console::cout() << OT_T("Local name: ") << localName << endl;

    rpSupport->popContext();




Constructor/Destructor Summary
NamespaceSupport()
         Default constructor.

Method Summary
 bool declarePrefix(const String& prefix, const String& uri)
         Declare a Namespace prefix.
 PrefixList getDeclaredPrefixes() const
         Return a list of all prefixes declared in this context.
 String getPrefix(const String& uri) const
         Return one of the prefixes mapped to a Namespace URI.
 PrefixList getPrefixes() const
         Return a list of all prefixes currently declared.
 PrefixList getPrefixes(const String& uri) const
         Return a list of all prefixes currently declared for a URI.
 String getURI(const String& prefix) const
         Look up the URI associated with a prefix in this context.
 void popContext()
         Revert to the previous Namespace context.
 bool processName(const String& qName, bool bAttribute, String& retUri, String& retLocal) const
         Process a raw XML 1.0 name.
 void pushContext()
         Start a new Namespace context.
 void reset()
         Reset this Namespace support object for reuse.

Methods inherited from class ot::ManagedObject
addRef, getRefCount, onFinalRelease, operator=, release

Public Static Data Members

XMLNS

const String XMLNS

The XML Namespace as a constant.

This is the Namespace URI that is automatically mapped to the xml prefix.


Typedefs

PrefixList

typedef std::list< String > PrefixList

Constructor/Destructor Detail

NamespaceSupport

 NamespaceSupport()
Default constructor.


Method Detail

declarePrefix

bool declarePrefix(const String& prefix,
                   const String& uri)
Declare a Namespace prefix.

This method declares a prefix in the current Namespace context; the prefix will remain in force until this context is popped, unless it is shadowed in a descendant context.

To declare a default Namespace, use the empty string. The prefix must not be xml or xmlns.

Note that there is an asymmetry in this class: while getPrefix will not return the empty (default) prefix, even if you have declared one; to check for a default prefix, you have to look it up explicitly using getURI. This asymmetry exists to make it easier to look up prefixes for attribute names, where the default prefix is not allowed.

Parameters:
prefix - The prefix to declare, or the empty string.
uri - The Namespace URI to associate with the prefix.
Returns:
true if the prefix was legal, false otherwise
See also:
processName() , getURI() , getPrefix()

getDeclaredPrefixes

PrefixList getDeclaredPrefixes() const
Return a list of all prefixes declared in this context.

The empty (default) prefix will be included in this list; note that this behaviour differs from that of getPrefix() and getPrefixes().

Returns:
A list of all prefixes declared in this context.
See also:
getPrefixes() , getURI()

getPrefix

String getPrefix(const String& uri) const
Return one of the prefixes mapped to a Namespace URI.

If more than one prefix is currently mapped to the same URI, this method will make an arbitrary selection; if you want all of the prefixes, use the getPrefixes() method instead.

Note: this will never return the empty (default) prefix; to check for a default prefix, use the getURI() method with an argument of the empty string.

Parameters:
uri - The Namespace URI.
Returns:
One of the prefixes currently mapped to the URI supplied, or the empty string if none is mapped or if the URI is assigned to the default Namespace.
See also:
getPrefixes(const String& uri) , getURI()

getPrefixes

PrefixList getPrefixes() const
Return a list of all prefixes currently declared.

Note: if there is a default prefix, it will not be returned in this list; check for the default prefix using the getURI() method with an argument of the empty string.

Returns:
A list of all prefixes currently declared except for the empty (default) prefix.
See also:
getDeclaredPrefixes() , getURI()

getPrefixes

PrefixList getPrefixes(const String& uri) const
Return a list of all prefixes currently declared for a URI.

This method returns prefixes mapped to a specific Namespace URI. The xml prefix will be included. If you want only one prefix that's mapped to the Namespace URI, and you don't care which one you get, use the getPrefix() method instead.

Note: the empty (default) prefix is never included in this list; to check for the presence of a default Namespace, use the getURI() method with an argument of the empty string.

Parameters:
uri - The Namespace URI.
Returns:
A list of all prefixes currently declared for the passed uri
See also:
getPrefix() , getDeclaredPrefixes() , getURI()

getURI

String getURI(const String& prefix) const
Look up the URI associated with a prefix in this context.

Parameters:
prefix - The prefix to look up.
Returns:
The associated Namespace URI, or the empty string if none is declared.

popContext

void popContext()
Revert to the previous Namespace context.

Normally, you should pop the context at the end of each XML element. After popping the context, all Namespace prefix mappings that were previously in force are restored.

You must not attempt to declare additional Namespace prefixes after popping a context, unless you push another context first.

See also:
pushContext()

processName

bool processName(const String& qName,
                 bool bAttribute,
                 String& retUri,
                 String& retLocal) const
Process a raw XML 1.0 name.

This method processes a raw XML 1.0 name in the current context by removing the prefix and looking it up among the prefixes currently declared.

The two return parameters: retUri and retLocal are filled in with the associated Namespace URI and local part respectively. A return value of false is returned if the qName contains a Namespace prefix which has not been declared.

Note that attribute names are processed differently to element names: an unprefixed element name will receive the default Namespace (if any), while an unprefixed element name will not.

Parameters:
qName - The raw XML 1.0 name to be processed.
bAttribute - A flag indicating whether this is an attribute name (true) or an element name (false).
retUri - A return parameter that will contain the Namespace URI associated with qName.
retLocal - A return parameter that will contain the local part of the Namespace-qualified qName.
Returns:
true if the supplied raw XML name contained either a valid prefix or no prefix at all; false otherwise.
See also:
declarePrefix()

pushContext

void pushContext()
Start a new Namespace context.

Normally, you should push a new context at the beginning of each XML element: the new context will automatically inherit the declarations of its parent context, but it will also keep track of which declarations were made within this context.

The Namespace support object always starts with a base context already in force: in this context, only the xml prefix is declared.

See also:
popContext()

reset

void reset()
Reset this Namespace support object for reuse.

It is necessary to invoke this method before reusing the Namespace support object for a new session.



Cross-Platform C++

Found a bug or missing feature? Please email us at support@elcel.com

Copyright © 2000-2003 ElCel Technology   Trademark Acknowledgements