001/*
002 * Copyright (c) 2000 World Wide Web Consortium,
003 * (Massachusetts Institute of Technology, Institut National de
004 * Recherche en Informatique et en Automatique, Keio University). All
005 * Rights Reserved. This program is distributed under the W3C's Software
006 * Intellectual Property License. This program is distributed in the
007 * hope that it will be useful, but WITHOUT ANY WARRANTY; without even
008 * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
009 * PURPOSE.
010 * See W3C License http://www.w3.org/Consortium/Legal/ for more details.
011 */
012
013package org.w3c.dom;
014
015/**
016 * The <code>CharacterData</code> interface extends Node with a set of 
017 * attributes and methods for accessing character data in the DOM. For 
018 * clarity this set is defined here rather than on each object that uses 
019 * these attributes and methods. No DOM objects correspond directly to 
020 * <code>CharacterData</code>, though <code>Text</code> and others do 
021 * inherit the interface from it. All <code>offsets</code> in this interface 
022 * start from <code>0</code>.
023 * <p>As explained in the <code>DOMString</code> interface, text strings in 
024 * the DOM are represented in UTF-16, i.e. as a sequence of 16-bit units. In 
025 * the following, the term 16-bit units is used whenever necessary to 
026 * indicate that indexing on CharacterData is done in 16-bit units.
027 * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>Document Object Model (DOM) Level 2 Core Specification</a>.
028 */
029public interface CharacterData extends Node {
030    /**
031     * The character data of the node that implements this interface. The DOM 
032     * implementation may not put arbitrary limits on the amount of data 
033     * that may be stored in a <code>CharacterData</code> node. However, 
034     * implementation limits may mean that the entirety of a node's data may 
035     * not fit into a single <code>DOMString</code>. In such cases, the user 
036     * may call <code>substringData</code> to retrieve the data in 
037     * appropriately sized pieces.
038     * @exception DOMException
039     *   NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
040     * @exception DOMException
041     *   DOMSTRING_SIZE_ERR: Raised when it would return more characters than 
042     *   fit in a <code>DOMString</code> variable on the implementation 
043     *   platform.
044     */
045    public String getData()
046                            throws DOMException;
047    public void setData(String data)
048                            throws DOMException;
049
050    /**
051     * The number of 16-bit units that are available through <code>data</code> 
052     * and the <code>substringData</code> method below. This may have the 
053     * value zero, i.e., <code>CharacterData</code> nodes may be empty.
054     */
055    public int getLength();
056
057    /**
058     * Extracts a range of data from the node.
059     * @param offsetStart offset of substring to extract.
060     * @param countThe number of 16-bit units to extract.
061     * @return The specified substring. If the sum of <code>offset</code> and 
062     *   <code>count</code> exceeds the <code>length</code>, then all 16-bit 
063     *   units to the end of the data are returned.
064     * @exception DOMException
065     *   INDEX_SIZE_ERR: Raised if the specified <code>offset</code> is 
066     *   negative or greater than the number of 16-bit units in 
067     *   <code>data</code>, or if the specified <code>count</code> is 
068     *   negative.
069     *   <br>DOMSTRING_SIZE_ERR: Raised if the specified range of text does 
070     *   not fit into a <code>DOMString</code>.
071     */
072    public String substringData(int offset, 
073                                int count)
074                                throws DOMException;
075
076    /**
077     * Append the string to the end of the character data of the node. Upon 
078     * success, <code>data</code> provides access to the concatenation of 
079     * <code>data</code> and the <code>DOMString</code> specified.
080     * @param argThe <code>DOMString</code> to append.
081     * @exception DOMException
082     *   NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
083     */
084    public void appendData(String arg)
085                           throws DOMException;
086
087    /**
088     * Insert a string at the specified 16-bit unit offset.
089     * @param offsetThe character offset at which to insert.
090     * @param argThe <code>DOMString</code> to insert.
091     * @exception DOMException
092     *   INDEX_SIZE_ERR: Raised if the specified <code>offset</code> is 
093     *   negative or greater than the number of 16-bit units in 
094     *   <code>data</code>.
095     *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
096     */
097    public void insertData(int offset, 
098                           String arg)
099                           throws DOMException;
100
101    /**
102     * Remove a range of 16-bit units from the node. Upon success, 
103     * <code>data</code> and <code>length</code> reflect the change.
104     * @param offsetThe offset from which to start removing.
105     * @param countThe number of 16-bit units to delete. If the sum of 
106     *   <code>offset</code> and <code>count</code> exceeds 
107     *   <code>length</code> then all 16-bit units from <code>offset</code> 
108     *   to the end of the data are deleted.
109     * @exception DOMException
110     *   INDEX_SIZE_ERR: Raised if the specified <code>offset</code> is 
111     *   negative or greater than the number of 16-bit units in 
112     *   <code>data</code>, or if the specified <code>count</code> is 
113     *   negative.
114     *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
115     */
116    public void deleteData(int offset, 
117                           int count)
118                           throws DOMException;
119
120    /**
121     * Replace the characters starting at the specified 16-bit unit offset 
122     * with the specified string.
123     * @param offsetThe offset from which to start replacing.
124     * @param countThe number of 16-bit units to replace. If the sum of 
125     *   <code>offset</code> and <code>count</code> exceeds 
126     *   <code>length</code>, then all 16-bit units to the end of the data 
127     *   are replaced; (i.e., the effect is the same as a <code>remove</code>
128     *    method call with the same range, followed by an <code>append</code>
129     *    method invocation).
130     * @param argThe <code>DOMString</code> with which the range must be 
131     *   replaced.
132     * @exception DOMException
133     *   INDEX_SIZE_ERR: Raised if the specified <code>offset</code> is 
134     *   negative or greater than the number of 16-bit units in 
135     *   <code>data</code>, or if the specified <code>count</code> is 
136     *   negative.
137     *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
138     */
139    public void replaceData(int offset, 
140                            int count, 
141                            String arg)
142                            throws DOMException;
143
144}