Source for org.w3c.dom.CharacterData

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