src/org/mozilla/javascript/SourceTextItem.java

   1 /* -*- Mode: java; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-\r
   2  *\r
   3  * The contents of this file are subject to the Netscape Public\r
   4  * License Version 1.1 (the "License"); you may not use this file\r
   5  * except in compliance with the License. You may obtain a copy of\r
   6  * the License at http://www.mozilla.org/NPL/\r
   7  *\r
   8  * Software distributed under the License is distributed on an "AS\r
   9  * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express oqr\r
  10  * implied. See the License for the specific language governing\r
  11  * rights and limitations under the License.\r
  12  *\r
  13  * The Original Code is Rhino code, released\r
  14  * May 6, 1999.\r
  15  *\r
  16  * The Initial Developer of the Original Code is Netscape\r
  17  * Communications Corporation.  Portions created by Netscape are\r
  18  * Copyright (C) 1997-1999 Netscape Communications Corporation. All\r
  19  * Rights Reserved.\r
  20  *\r
  21  * Contributor(s): \r
  22  * John Bandhauer\r
  23  *\r
  24  * Alternatively, the contents of this file may be used under the\r
  25  * terms of the GNU Public License (the "GPL"), in which case the\r
  26  * provisions of the GPL are applicable instead of those above.\r
  27  * If you wish to allow use of your version of this file only\r
  28  * under the terms of the GPL and not to allow others to use your\r
  29  * version of this file under the NPL, indicate your decision by\r
  30  * deleting the provisions above and replace them with the notice\r
  31  * and other provisions required by the GPL.  If you do not delete\r
  32  * the provisions above, a recipient may use your version of this\r
  33  * file under either the NPL or the GPL.\r
  34  */\r
  35 \r
  36 // DEBUG API class\r
  37 \r
  38 package org.mozilla.javascript;\r
  39 \r
  40 /**\r
  41  * This interface supports managing incrementally updated source text items.\r
  42  * <p>\r
  43  * Items have immutable names. They can be valid or invalid. They can \r
  44  * accumulate text, but existing text can not be overwritten. They can be \r
  45  * marked as 'complete', 'aborted', etc. They can be cleared of all text. \r
  46  * See status flags for details.\r
  47  *\r
  48  * @see org.mozilla.javascript.SourceTextManager\r
  49  * @author John Bandhauer\r
  50  */\r
  51 \r
  52 public interface SourceTextItem\r
  53 {\r
  54 \r
  55     /**\r
  56      * Possible status values...\r
  57      */\r
  58 \r
  59     /**\r
  60      * Item just created, no text added yet.\r
  61      */\r
  62     public static final int INITED    = 0;\r
  63 \r
  64     /**\r
  65      * Item has some text, likely that more will be added.\r
  66      */\r
  67     public static final int PARTIAL   = 1;\r
  68 \r
  69     /**\r
  70      * Item has all the text it is going to get.\r
  71      */\r
  72     public static final int COMPLETED = 2;\r
  73 \r
  74     /**\r
  75      * User aborted loading of text, some text may be in item.\r
  76      */\r
  77     public static final int ABORTED   = 3;\r
  78 \r
  79     /**\r
  80      * Loading of text failed, some text may be in item.\r
  81      */\r
  82     public static final int FAILED    = 4;\r
  83 \r
  84     /**\r
  85      * Whatever text was in item has been cleared by a consumer.\r
  86      */\r
  87     public static final int CLEARED   = 5;\r
  88 \r
  89     /**\r
  90      * Item has be marked as invalid and has no useful information.\r
  91      */\r
  92     public static final int INVALID   = 6;\r
  93 \r
  94     /**\r
  95      * Append some text.\r
  96      * <p>\r
  97      * This only succeeds if status is INITED or PARTIAL.\r
  98      *\r
  99      * @param text String to append\r
 100      * @return true if succeeded, false if failed\r
 101      */\r
 102     public boolean append(String text);\r
 103 \r
 104     /**\r
 105      * Append a char.\r
 106      * <p>\r
 107      * This only succeeds if status is INITED or PARTIAL.\r
 108      *\r
 109      * @param c char to append\r
 110      * @return true if succeeded, false if failed\r
 111      */\r
 112     public boolean append(char c);\r
 113 \r
 114     /**\r
 115      * Append a char from a char[].\r
 116      * <p>\r
 117      * This only succeeds if status is INITED or PARTIAL.\r
 118      *\r
 119      * @param buf char[] from which to append\r
 120      * @param offset offset into char[] from which to append\r
 121      * @param count count of chars to append\r
 122      * @return true if succeeded, false if failed\r
 123      */\r
 124     public boolean append(char[] buf, int offset, int count);\r
 125 \r
 126     /**\r
 127      * Set status to COMPLETED.\r
 128      * <p>\r
 129      * meaning: all the text is there, it is complete, no problems.\r
 130      * This only succeeds if status is INITED or PARTIAL.\r
 131      *\r
 132      * @return true if succeeded, false if failed\r
 133      */\r
 134     public boolean complete();\r
 135 \r
 136     /**\r
 137      * Set status to ABORTED.\r
 138      * <p>\r
 139      * meaning: some text might be there, but user aborted text loading.\r
 140      * This only succeeds if status is INITED or PARTIAL.\r
 141      *\r
 142      * @return true if succeeded, false if failed\r
 143      */\r
 144     public boolean abort();\r
 145 \r
 146     /**\r
 147      * Set status to FAILED.\r
 148      * <p>\r
 149      * meaning: some text might be there, but loading failed.\r
 150      * This only succeeds if status is INITED or PARTIAL.\r
 151      *\r
 152      * @return true if succeeded, false if failed\r
 153      */\r
 154     public boolean fail();\r
 155 \r
 156     /**\r
 157      * Clear the text and set status to CLEARED.\r
 158      * <p>\r
 159      * meaning: consumer of the text has what he wants, leave this \r
 160      * as an emptly placeholder.\r
 161      * This succeeds unless status is INVALID.\r
 162      *\r
 163      * @return true if succeeded, false if failed\r
 164      */\r
 165     public boolean clear();\r
 166 \r
 167     /**\r
 168      * Clear the text and set status to INVALID.\r
 169      * <p>\r
 170      * meaning: This item is not to be used, likely the SourceTextManager \r
 171      * has been asked to create a new item (with potentially different \r
 172      * text) in its place.\r
 173      * This succeeds unless status is INVALID.\r
 174      *\r
 175      * @return true if succeeded, false if failed\r
 176      */\r
 177     public boolean invalidate();\r
 178 \r
 179     /**\r
 180      * Get the Current Text.\r
 181      *\r
 182      * @return the text, null if INVALID\r
 183      */\r
 184     public String  getText();\r
 185 \r
 186     /**\r
 187      * Get the name.\r
 188      *\r
 189      * @return the name (immutable).\r
 190      */\r
 191     public String  getName();\r
 192 \r
 193     /**\r
 194      * Get the status.\r
 195      *\r
 196      * @return the current status\r
 197      */\r
 198     public int     getStatus();\r
 199 \r
 200     /**\r
 201      * Get the validity status.\r
 202      *\r
 203      * @return true if item is valid, false if not\r
 204      */\r
 205     public boolean isValid();\r
 206 \r
 207     /**\r
 208      * Get a counter representing the modification count of the item.\r
 209      * <p>\r
 210      * Any consumer of the item may look at this value and store it at one\r
 211      * point in time and then later look at the value again. If the \r
 212      * value has increased, then the consumer can know that the item has \r
 213      * been modified in some way and can then take the appropriate action.\r
 214      * If the count has not changed from one point in time to another, \r
 215      * then the item is guarenteed to not have changed in any way.\r
 216      *\r
 217      * NOTE: this value is not guaranteed to start at 0;\r
 218      *\r
 219      * @return the alter count\r
 220      */\r
 221     public int     getAlterCount();\r
 222 }\r