Oracle Coherence for C++ API
Release 3.6.1.0
E18813-01

- Main Page
- Namespaces
- Classes
- Files

# 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.