00001 /* 00002 * Copyright (c) 2000, 2020, Oracle and/or its affiliates. 00003 * 00004 * Licensed under the Universal Permissive License v 1.0 as shown at 00005 * http://oss.oracle.com/licenses/upl. 00006 */ 00007 #ifndef COH_XML_ELEMENT_HPP 00008 #define COH_XML_ELEMENT_HPP 00009 00010 #include "coherence/lang.ns" 00011 00012 #include "coherence/run/xml/XmlValue.hpp" 00013 #include "coherence/util/HashMap.hpp" 00014 #include "coherence/util/Iterator.hpp" 00015 #include "coherence/util/List.hpp" 00016 00017 #include <ostream> 00018 00019 COH_OPEN_NAMESPACE3(coherence,run,xml) 00020 00021 using coherence::util::HashMap; 00022 using coherence::util::Iterator; 00023 using coherence::util::List; 00024 00025 00026 /** 00027 * An interface for XML element access. The XmlElement interface represents 00028 * both the element and its content (through the underlying XmlValue 00029 * interface). 00030 * 00031 * @author js 2007.12.14 00032 */ 00033 class COH_EXPORT XmlElement 00034 : public interface_spec<XmlElement, 00035 implements<XmlValue> > 00036 { 00037 // ----- XmlElement interface ------------------------------------------- 00038 00039 public: 00040 /** 00041 * Get the name of the element. 00042 * 00043 * @return the element name 00044 */ 00045 virtual String::View getName() const = 0; 00046 00047 /** 00048 * Set the name of the element. This method is intended primarily 00049 * to be utilized to configure a newly instantiated element 00050 * before adding it as a child element to another element. 00051 * 00052 * @param vsName the new element name 00053 */ 00054 virtual void setName(String::View vsName) = 0; 00055 00056 /** 00057 * Get the root element. 00058 * 00059 * @return the root element for this element 00060 */ 00061 virtual Handle getRoot() = 0; 00062 00063 /** 00064 * Get the root element. 00065 * 00066 * @return the root element for this element 00067 */ 00068 virtual View getRoot() const = 0; 00069 00070 /** 00071 * Get the '/'-delimited path of the element starting from the root 00072 * element. 00073 * 00074 * @return the element path 00075 */ 00076 virtual String::View getAbsolutePath() const = 0; 00077 00078 /** 00079 * Get an array of all child elements. The contents of the array 00080 * implement the XmlValue interface. 00081 * 00082 * @return an array containing all child elements 00083 */ 00084 virtual ObjectArray::Handle getAllElements() const = 0; 00085 00086 /** 00087 * Get the list of all child elements. The contents of the list 00088 * implement the XmlValue interface. If this XmlElement is mutable, 00089 * then the list returned from this method is expected to be mutable 00090 * as well. 00091 * 00092 * @return a List containing all elements of this XmlElement 00093 */ 00094 virtual List::Handle getElementList() = 0; 00095 00096 /** 00097 * Get the list of all child elements. The contents of the list 00098 * implement the XmlValue interface. If this XmlElement is mutable, 00099 * then the list returned from this method is expected to be mutable 00100 * as well. 00101 * 00102 * @return a List containing all elements of this XmlElement 00103 */ 00104 virtual List::View getElementList() const = 0; 00105 00106 /** 00107 * Get a child element. If multiple child elements exist that 00108 * have the specified name, then any matching element may be 00109 * returned. 00110 * 00111 * @param vsName the name of the element to get 00112 * 00113 * @return an element with the specified name or NULL if no 00114 * matches are found 00115 */ 00116 virtual Handle getElement(String::View vsName) = 0; 00117 00118 /** 00119 * Get a View to a child element. If multiple child elements 00120 * exist that have the specified name, then any matching element 00121 * may be returned. 00122 * 00123 * @param vsName the name of the element to get 00124 * 00125 * @return an element with the specified name or NULL if no 00126 * matches are found 00127 */ 00128 virtual View getElement(String::View vsName) const = 0; 00129 00130 /** 00131 * Return the specified child element using the same path notation as 00132 * supported by findElement, but return a read-only element if the 00133 * specified element does not exist. 00134 * 00135 * <b>This method never returns NULL.</b> 00136 * 00137 * This is a convenience method. Elements are accessed and manipulated 00138 * via the list returned from getElementList(). 00139 * 00140 * If multiple child elements exist that have the specified name, then 00141 * the behavior of this method is undefined, and it is permitted to return 00142 * any one of the matching elements, to return null, or to throw an 00143 * arbitrary runtime exception. 00144 * 00145 * @param vsPath element path 00146 * 00147 * @return the specified element (never NULL) as an object implementing 00148 * XmlElement for read-only use 00149 */ 00150 virtual View getSafeElement(String::View vsPath) const = 0; 00151 00152 /** 00153 * Get an iterator of child elements that have a specific name. 00154 * 00155 * @param vsName the name of the element to get 00156 * 00157 * @return an iterator containing all child elements of the specified 00158 * name 00159 */ 00160 virtual Iterator::Handle getElements(String::View vsName) = 0; 00161 00162 /** 00163 * Get an iterator of child elements that have a specific name. 00164 * Note: This method returns only read-only Views of the elements. 00165 * 00166 * @param vsName the name of the element to get 00167 * 00168 * @return an iterator containing all child elements of the specified 00169 * name 00170 */ 00171 virtual Iterator::Handle getElements(String::View vsName) const = 0; 00172 00173 /** 00174 * Ensure that a child element exists. 00175 * 00176 * This method combines the functionality of findElement() and 00177 * addElement(). If any part of the path does not exist create new 00178 * child elements to match the path. 00179 * 00180 * @param vsPath element path 00181 * 00182 * @return the existing or new XmlElement object 00183 * 00184 * @throws IllegalArgumentException if the name is NULL or if any 00185 * part of the path is not a legal XML tag name 00186 * @throws UnsupportedOperationException if unable to add a child 00187 * element 00188 */ 00189 virtual XmlElement::Handle ensureElement(String::View vsPath) = 0; 00190 00191 /** 00192 * Create a new element and add it as a child element to this element. 00193 * 00194 * @param vsName the name for the new element 00195 * 00196 * @return a handle to the new XmlElement object 00197 */ 00198 virtual Handle addElement(String::View vsName) = 0; 00199 00200 /** 00201 * Find a child element with the specified '/'-delimited path. This is 00202 * based on a subset of the XPath specification, supporting: 00203 * 00204 * <ul> 00205 * <li>Leading '/' to specify root</li> 00206 * <li>Use of '/' as a path delimiter</li> 00207 * <li>Use of '..' to specify parent</li> 00208 * </ul> 00209 * </p> 00210 * If multiple child elements exist that have the specified path, 00211 * then the behavior of this method is undefined, and it is 00212 * permitted to return any one of the matching elements. 00213 * 00214 * @param vsPath the element path to search for 00215 * 00216 * @return the specified element or NULL if the specified child 00217 * element does not exist 00218 */ 00219 virtual Handle findElement(String::View vsPath) = 0; 00220 00221 /** 00222 * Find a child element with the specified '/'-delimited path. This is 00223 * based on a subset of the XPath specification, supporting: 00224 * 00225 * <ul> 00226 * <li>Leading '/' to specify root</li> 00227 * <li>Use of '/' as a path delimiter</li> 00228 * <li>Use of '..' to specify parent</li> 00229 * </ul> 00230 * </p> 00231 * If multiple child elements exist that have the specified path, 00232 * then the behavior of this method is undefined, and it is 00233 * permitted to return any one of the matching elements. 00234 * 00235 * @param vsPath the element path to search for 00236 * 00237 * @return the specified element or NULL if the specified child 00238 * element does not exist 00239 */ 00240 virtual View findElement(String::View vsPath) const = 0; 00241 00242 /** 00243 * Get an attribute value. 00244 * 00245 * @param vsName the name of the attribute 00246 * 00247 * @return the attribute corresponding to the specified name or NULL 00248 * if the attribute does not exist 00249 */ 00250 virtual XmlValue::Handle getAttribute(String::View vsName) const = 0; 00251 00252 /** 00253 * Get the map of all attributes. The map is keyed by attribute names. 00254 * The corresponding values are non-NULL objects that implement the 00255 * XmlValue interface. 00256 * 00257 * @return a Map containing all attributes of this XmlElement; the 00258 * return value will never be NULL, although it may be an 00259 * empty map 00260 */ 00261 virtual HashMap::Handle getAttributeMap() = 0; 00262 00263 /** 00264 * Get the map of all attributes. The map is keyed by attribute names. 00265 * The corresponding values are non-NULL objects that implement the 00266 * XmlValue interface. 00267 * 00268 * @return a Map containing all attributes of this XmlElement; the 00269 * return value will never be NULL, although it may be an 00270 * empty map 00271 */ 00272 virtual HashMap::View getAttributeMap() const = 0; 00273 00274 /** 00275 * Set an attribute value. If the attribute does not already exist, 00276 * and the new value is non-NULL, then the attribute is added and its 00277 * value is set to the passed value. If the attribute does exist, and 00278 * the new value is non-NULL, then the attribute's value is updated to 00279 * the passed value. If the attribute does exist, but the new value is 00280 * NULL, then the attribute and its corresponding value are removed. 00281 * 00282 * @param vsName name of the attribute 00283 * @param hValue the new value for the attribute; NULL indicates that 00284 * the attribute should be removed 00285 */ 00286 virtual void setAttribute(String::View vsName, 00287 XmlValue::Handle hValue) = 0; 00288 00289 /** 00290 * Provides a means to add a new attribute value. If the attribute of 00291 * the same name already exists, it is returned, otherwise a new value 00292 * is created and added as an attribute. 00293 * 00294 * @param vsName the name of the attribute 00295 * 00296 * @return the value of the existing attribute if the attribute 00297 * of the same name exist; otherwise the value of a newly 00298 * created attribute 00299 */ 00300 virtual XmlValue::Handle addAttribute(String::View vsName) = 0; 00301 00302 /** 00303 * Get an attribute value, and return a temporary value if the attribute 00304 * does not exist. 00305 * 00306 * This is a convenience method. Attributes are accessed and manipulated 00307 * via the map returned from getAttributeMap. 00308 * 00309 * @param vsName the name of the attribute 00310 * 00311 * @return the value of the specified attribute, or a temporary value if 00312 * the attribute does not exist 00313 * 00314 * @since Coherence 12.1.2 00315 */ 00316 virtual XmlValue::Handle getSafeAttribute(String::View vsName) const = 0; 00317 00318 /** 00319 * Get the text of any comments that are in the XML element. An 00320 * element can contain many comments interspersed randomly with 00321 * textual values and child elements. In reality, comments are rarely 00322 * used. The purpose of this method and the corresponding mutator are 00323 * to ensure that if comments do exist, that their text will be 00324 * accessible through this interface and not lost through a transfer 00325 * from one instance of this interface to another. 00326 * 00327 * @return the comment text from this element (not including the 00328 * "<!--" and "-->") or NULL if there was no comment 00329 */ 00330 virtual String::View getComment() const = 0; 00331 00332 /** 00333 * Set the text of this element's comment. This interface allows 00334 * a single comment to be associated with the element. The XML 00335 * specification does not allow a comment to contain the string "--". 00336 * 00337 * @param vsComment the comment text 00338 * 00339 * @throws coherence::lang::IllegalArgumentException 00340 * if the comment contains "--" 00341 */ 00342 virtual void setComment(String::View vsComment) = 0; 00343 00344 /** 00345 * Format the element as it will appear in XML. 00346 * 00347 * @param fPretty true to specify that the output is intended to 00348 * be as human readable as possible 00349 * @param cIndent the number of spaces to indent each line 00350 * 00351 * @return the XML formatted string. 00352 */ 00353 virtual String::View formatXml(bool fPretty = false, size32_t cIndent = 0) const = 0; 00354 00355 /** 00356 * Write the element as it will appear in XML. 00357 * 00358 * @param out an std::ostream object to use to write to 00359 * @param fPretty true to specify that the output is intended to 00360 * be as human readable as possible 00361 * @param cIndent the number of spaces to indent each line 00362 */ 00363 COH_INLINE void writeXml(std::ostream& out, bool fPretty = false, size32_t cIndent = 0) const 00364 { 00365 out << formatXml(fPretty, cIndent); 00366 } 00367 }; 00368 00369 COH_CLOSE_NAMESPACE3 00370 00371 #endif // COH_XML_ELEMENT_HPP