ACE/ACEXML/common/NamespaceSupport.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    NamespaceSupport.h
   6  *
   7  *  @author Nanbor Wang <nanbor@cs.wustl.edu>
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACEXML_NAMESPACESUPPORT_H
  12 #define ACEXML_NAMESPACESUPPORT_H
  13
  14 #include /**/ "ace/pre.h"
  15 #include "ACEXML/common/ACEXML_Export.h"
  16
  17 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  18 #pragma once
  19 #endif /* ACE_LACKS_PRAGMA_ONCE */
  20
  21 #include "ACEXML/common/XML_Types.h"
  22 #include "ace/Functor.h"
  23 #include "ace/Hash_Map_Manager.h"
  24 #include "ace/Containers_T.h"
  25 #include "ace/Null_Mutex.h"
  26
  27
  28 typedef ACE_Hash_Map_Entry<ACEXML_String,
  29                            ACEXML_String> ACEXML_NS_CONTEXT_ENTRY;
  30
  31 typedef ACE_Hash_Map_Manager_Ex<ACEXML_String,
  32                                 ACEXML_String,
  33                                 ACE_Hash<ACEXML_String>,
  34                                 ACE_Equal_To<ACEXML_String>,
  35                                 ACE_Null_Mutex> ACEXML_NS_CONTEXT;
  36
  37 typedef ACE_Hash_Map_Iterator_Ex<ACEXML_String,
  38                                  ACEXML_String,
  39                                  ACE_Hash<ACEXML_String>,
  40                                  ACE_Equal_To<ACEXML_String>,
  41                                  ACE_Null_Mutex> ACEXML_NS_CONTEXT_ITER;
  42
  43 typedef ACE_Hash_Map_Reverse_Iterator_Ex<ACEXML_String,
  44                                          ACEXML_String,
  45                                          ACE_Hash<ACEXML_String>,
  46                                          ACE_Equal_To<ACEXML_String>,
  47                                          ACE_Null_Mutex> ACEXML_NS_CONTEXT_REVERSE_ITER;
  48
  49 typedef ACE_Unbounded_Queue<const ACEXML_Char *> ACEXML_STR_LIST;
  50
  51 /**
  52  * @class ACEXML_Namespace_Context_Stack
  53  *
  54  * @brief ACEXML_Namespace_Context_Stack implements a simple stack
  55  * that ACEXML_NamespaceSupport uses to keep track of namespace scopes.
  56  *
  57  * @sa ACEXML_NamespaceSupport
  58  */
  59 class ACEXML_Export ACEXML_Namespace_Context_Stack
  60 {
  61 public:
  62   /// Default constructor.
  63   ACEXML_Namespace_Context_Stack ();
  64
  65   /// Destructor.
  66   ~ACEXML_Namespace_Context_Stack ();
  67
  68   /// Push the old namespace before entering into a new namespace scope.
  69   int push (ACEXML_NS_CONTEXT * old);
  70
  71   /// Pop the old namespace when exiting a namespace scope.
  72   ACEXML_NS_CONTEXT *pop ();
  73
  74 private:
  75   /// Internal stack structure to hold namespace context.
  76   ACE_Unbounded_Stack<ACEXML_NS_CONTEXT*> stack_;
  77 };
  78
  79 /**
  80  * @class ACEXML_NamespaceSupport NamespaceSupport.h "ACEXML/common/NamespaceSupport.h"
  81  *
  82  * @brief ACEXML_NamespaceSupport provides namespace management
  83  * operation for an XML parser.
  84  *
  85  * This class encapsulates the logic of Namespace processing: it
  86  * tracks the declarations currently in force for each context and
  87  * automatically processes qualified XML 1.0 names into their
  88  * Namespace parts; it can also be used in reverse for generating XML
  89  * 1.0 from Namespaces.
  90  *
  91  * Namespace support objects are reusable, but the reset method must
  92  * be invoked between each session.
  93  *
  94  * Here is a simple session (in Java :-p):
  95  * @code
  96  *  String parts[] = new String[3];
  97  *  NamespaceSupport support = new NamespaceSupport();
  98  *
  99  *  support.pushContext();
 100  *  support.declarePrefix("", "http://www.w3.org/1999/xhtml");
 101  *  support.declarePrefix("dc", "http://www.purl.org/dc#");
 102  *
 103  *  String parts[] = support.processName("p", parts, false);
 104  *  System.out.println("Namespace URI: " + parts[0]);
 105  *  System.out.println("Local name: " + parts[1]);
 106  *  System.out.println("Raw name: " + parts[2]);
 107  *
 108  *  String parts[] = support.processName("dc:title", parts, false);
 109  *  System.out.println("Namespace URI: " + parts[0]);
 110  *  System.out.println("Local name: " + parts[1]);
 111  *  System.out.println("Raw name: " + parts[2]);
 112  *
 113  *  support.popContext();
 114  * @endcode
 115  *
 116  * Note that this class is optimized for the use case where most
 117  * elements do not contain Namespace declarations: if the same
 118  * prefix/URI mapping is repeated for each context (for example), this
 119  * class will be somewhat less efficient.
 120  *
 121  * @sa ACEXML_Exception
 122  */
 123 class ACEXML_Export ACEXML_NamespaceSupport
 124 {
 125 public:
 126   /**
 127    * Default constructor.
 128    */
 129   ACEXML_NamespaceSupport ();
 130
 131   /**
 132    * Default destructor.
 133    */
 134   ~ACEXML_NamespaceSupport ();
 135
 136   /**
 137    *  Initialize the namespace support object
 138    */
 139   int init();
 140
 141   /**
 142    * XMLNS default prefix and URI strings.
 143    */
 144   static const ACEXML_Char *XMLNS_PREFIX;
 145   static const ACEXML_Char *XMLNS;
 146
 147   /**
 148    * Declare a Namespace prefix.  Return -1 if the prefix was illegal
 149    * or an internal error occurred.  Return 0 if the prefix gets declared
 150    * successfully, 1 if the prefix replaces an existing prefix definition.
 151    */
 152   int declarePrefix (const ACEXML_Char *prefix,
 153                      const ACEXML_Char *uri);
 154
 155   /**
 156    * Return all prefixes declared in current context in
 157    * the user-supplied list @a prefixes.  It is user's reponsibility
 158    * to ensure the list was empty originally.
 159    */
 160   int getDeclaredPrefixes (ACEXML_STR_LIST &prefixes) const;
 161
 162   /**
 163    * Return one of the prefixes mapped to a Namespace URI.
 164    */
 165   const ACEXML_Char *getPrefix (const ACEXML_Char *uri) const;
 166
 167   /**
 168    * Return all prefixes currently declared in the user-supplied list.
 169    * @@ Known bug: This function should only return user-defined prefixes.
 170    */
 171   int getPrefixes (ACEXML_STR_LIST &prefixes) const;
 172
 173   /**
 174    * Return all prefixes currently declared for a URI in the
 175    * user-supplied list.
 176    */
 177   int getPrefixes (const ACEXML_Char *uri,
 178                    ACEXML_STR_LIST &prefixes) const;
 179
 180   /**
 181    * Look up a prefix and get the currently-mapped Namespace URI.
 182    */
 183   const ACEXML_Char *getURI (const ACEXML_Char *prefix) const;
 184
 185   /**
 186    * Revert to the previous namespace context.
 187    */
 188   int popContext ();
 189
 190   /**
 191    * Process a raw XML 1.0 name.
 192    * @a qName is the raw XML name we want to parse,
 193    * @a uri contains the URI string of the raw name.  It points to a null
 194    *    string if the namespace is not valid or there's no namespace defined.
 195    * @a name contains the original name without the prefix.
 196    * @a is_attribute specifies whether the name is an attribute or not.
 197    *    Attributes have different scoping rules from elements.
 198    */
 199   int processName (const ACEXML_Char *qName,
 200                    const ACEXML_Char *&uri,
 201                    const ACEXML_Char *&name,
 202                    int is_attribute) const;
 203
 204   /**
 205    * Start a new Namespace context.  Prefixes defined in previous
 206    * context are copied over to the new context.
 207    */
 208   int pushContext ();
 209
 210   /**
 211    * Reset this Namespace support object for reuse.
 212    *
 213    */
 214   int reset ();
 215
 216 private:
 217   /**
 218    * Namespace Context stack.  When we entering a new namespace
 219    * context, the old context is duplicated and pushed into
 220    * this stack.
 221    */
 222   ACEXML_Namespace_Context_Stack ns_stack_;
 223
 224   /**
 225    * The effective namespace context.
 226    */
 227   ACEXML_NS_CONTEXT *effective_context_;
 228 };
 229
 230 #include /**/ "ace/post.h"
 231
 232 #endif /* ACEXML_NAMESPACESUPPORT_H */