Oracle Coherence for C++ API
Release 3.6.0.0

E15728-01

coherence/run/xml/XmlElement.hpp

00001 /*
00002 * XmlElement.hpp
00003 *
00004 * Copyright (c) 2000, 2010, 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 the text of any comments that are in the XML element. An
00313         * element can contain many comments interspersed randomly with
00314         * textual values and child elements. In reality, comments are rarely
00315         * used. The purpose of this method and the corresponding mutator are
00316         * to ensure that if comments do exist, that their text will be
00317         * accessible through this interface and not lost through a transfer
00318         * from one instance of this interface to another.
00319         *
00320         * @return the comment text from this element (not including the
00321         *         "<!--" and "-->") or NULL if there was no comment
00322         */
00323         virtual String::View getComment() const = 0;
00324 
00325         /**
00326         * Set the text of this element's comment. This interface allows
00327         * a single comment to be associated with the element. The XML
00328         * specification does not allow a comment to contain the string "--".
00329         *
00330         * @param vsComment  the comment text
00331         *
00332         * @throws coherence::lang::IllegalArgumentException
00333         *         if the comment contains "--"
00334         */
00335         virtual void setComment(String::View vsComment) = 0;
00336 
00337         /**
00338         * Write the element as it will appear in XML.
00339         *
00340         * @param out      an std::ostream object to use to write to
00341         * @param fPretty  true to specify that the output is intended to
00342         *                 be as human readable as possible
00343         * @param cIndent  the number of spaces to indent each line
00344         */
00345         virtual void writeXml(std::ostream& out, bool fPretty = false,
00346                 size32_t cIndent = 0) const = 0;
00347     };
00348 
00349 COH_CLOSE_NAMESPACE3
00350 
00351 #endif // COH_XML_ELEMENT_HPP
Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.