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