CharacterData.java revision f33eae7e84eb6d3b0f4e86b59605bb3de73009f3
1adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project/* 2320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Copyright (c) 2004 World Wide Web Consortium, 3320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 4320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * (Massachusetts Institute of Technology, European Research Consortium for 5320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Informatics and Mathematics, Keio University). All Rights Reserved. This 6320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * work is distributed under the W3C(r) Software License [1] in the hope that 7320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * it will be useful, but WITHOUT ANY WARRANTY; without even the implied 8320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 9320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 10320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 11adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 12adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 13adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectpackage org.w3c.dom; 14adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 15adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project/** 16f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * The <code>CharacterData</code> interface extends Node with a set of 17f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * attributes and methods for accessing character data in the DOM. For 18f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * clarity this set is defined here rather than on each object that uses 19f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * these attributes and methods. No DOM objects correspond directly to 20f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>CharacterData</code>, though <code>Text</code> and others do 21f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * inherit the interface from it. All <code>offsets</code> in this interface 22adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * start from <code>0</code>. 23f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p>As explained in the <code>DOMString</code> interface, text strings in 24f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * the DOM are represented in UTF-16, i.e. as a sequence of 16-bit units. In 25f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * the following, the term 16-bit units is used whenever necessary to 26adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * indicate that indexing on CharacterData is done in 16-bit units. 27320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>See also the <a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>Document Object Model (DOM) Level 3 Core Specification</a>. 28adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 29adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectpublic interface CharacterData extends Node { 30adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 31f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * The character data of the node that implements this interface. The DOM 32f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * implementation may not put arbitrary limits on the amount of data 33f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * that may be stored in a <code>CharacterData</code> node. However, 34f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * implementation limits may mean that the entirety of a node's data may 35f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * not fit into a single <code>DOMString</code>. In such cases, the user 36f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * may call <code>substringData</code> to retrieve the data in 37adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * appropriately sized pieces. 38adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @exception DOMException 39f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * DOMSTRING_SIZE_ERR: Raised when it would return more characters than 40f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * fit in a <code>DOMString</code> variable on the implementation 41adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * platform. 42adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 43adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public String getData() 44adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws DOMException; 45adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 46f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * The character data of the node that implements this interface. The DOM 47f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * implementation may not put arbitrary limits on the amount of data 48f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * that may be stored in a <code>CharacterData</code> node. However, 49f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * implementation limits may mean that the entirety of a node's data may 50f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * not fit into a single <code>DOMString</code>. In such cases, the user 51f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * may call <code>substringData</code> to retrieve the data in 52adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * appropriately sized pieces. 53adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @exception DOMException 54adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly. 55adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 56adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public void setData(String data) 57adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws DOMException; 58adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 59adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 60f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * The number of 16-bit units that are available through <code>data</code> 61f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * and the <code>substringData</code> method below. This may have the 62adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * value zero, i.e., <code>CharacterData</code> nodes may be empty. 63adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 64adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public int getLength(); 65adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 66adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 67adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Extracts a range of data from the node. 68adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param offset Start offset of substring to extract. 69adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param count The number of 16-bit units to extract. 70f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @return The specified substring. If the sum of <code>offset</code> and 71f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>count</code> exceeds the <code>length</code>, then all 16-bit 72adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * units to the end of the data are returned. 73adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @exception DOMException 74f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * INDEX_SIZE_ERR: Raised if the specified <code>offset</code> is 75f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * negative or greater than the number of 16-bit units in 76f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>data</code>, or if the specified <code>count</code> is 77adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * negative. 78f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <br>DOMSTRING_SIZE_ERR: Raised if the specified range of text does 79adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * not fit into a <code>DOMString</code>. 80adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 81f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes public String substringData(int offset, 82adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project int count) 83adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws DOMException; 84adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 85adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 86f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * Append the string to the end of the character data of the node. Upon 87f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * success, <code>data</code> provides access to the concatenation of 88adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <code>data</code> and the <code>DOMString</code> specified. 89adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param arg The <code>DOMString</code> to append. 90adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @exception DOMException 91adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. 92adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 93adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public void appendData(String arg) 94adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws DOMException; 95adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 96adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 97adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Insert a string at the specified 16-bit unit offset. 98adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param offset The character offset at which to insert. 99adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param arg The <code>DOMString</code> to insert. 100adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @exception DOMException 101f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * INDEX_SIZE_ERR: Raised if the specified <code>offset</code> is 102f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * negative or greater than the number of 16-bit units in 103adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <code>data</code>. 104adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. 105adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 106f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes public void insertData(int offset, 107adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String arg) 108adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws DOMException; 109adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 110adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 111f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * Remove a range of 16-bit units from the node. Upon success, 112adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <code>data</code> and <code>length</code> reflect the change. 113adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param offset The offset from which to start removing. 114f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @param count The number of 16-bit units to delete. If the sum of 115f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>offset</code> and <code>count</code> exceeds 116f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>length</code> then all 16-bit units from <code>offset</code> 117adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * to the end of the data are deleted. 118adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @exception DOMException 119f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * INDEX_SIZE_ERR: Raised if the specified <code>offset</code> is 120f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * negative or greater than the number of 16-bit units in 121f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>data</code>, or if the specified <code>count</code> is 122adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * negative. 123adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. 124adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 125f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes public void deleteData(int offset, 126adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project int count) 127adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws DOMException; 128adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 129adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 130f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * Replace the characters starting at the specified 16-bit unit offset 131adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * with the specified string. 132adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param offset The offset from which to start replacing. 133f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @param count The number of 16-bit units to replace. If the sum of 134f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>offset</code> and <code>count</code> exceeds 135f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>length</code>, then all 16-bit units to the end of the data 136adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * are replaced; (i.e., the effect is the same as a <code>remove</code> 137adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * method call with the same range, followed by an <code>append</code> 138adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * method invocation). 139f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @param arg The <code>DOMString</code> with which the range must be 140adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * replaced. 141adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @exception DOMException 142f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * INDEX_SIZE_ERR: Raised if the specified <code>offset</code> is 143f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * negative or greater than the number of 16-bit units in 144f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>data</code>, or if the specified <code>count</code> is 145adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * negative. 146adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. 147adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 148f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes public void replaceData(int offset, 149f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes int count, 150adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String arg) 151adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws DOMException; 152adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 153adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project} 154