src/org/mozilla/javascript/Scriptable.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  * Norris Boyd\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 // API class\r
  37 \r
  38 package org.mozilla.javascript;\r
  39 \r
  40 /**\r
  41  * This is interface that all objects in JavaScript must implement.\r
  42  * The interface provides for the management of properties and for\r
  43  * performing conversions.\r
  44  * <p>\r
  45  * Host system implementors may find it easier to extend the ScriptableObject\r
  46  * class rather than implementing Scriptable when writing host objects.\r
  47  * <p>\r
  48  * There are many static methods defined in ScriptableObject that perform\r
  49  * the multiple calls to the Scriptable interface needed in order to  \r
  50  * manipulate properties in prototype chains.\r
  51  * <p>\r
  52  *\r
  53  * @see org.mozilla.javascript.ScriptableObject\r
  54  * @author Norris Boyd\r
  55  * @author Nick Thompson\r
  56  * @author Brendan Eich\r
  57  */\r
  58 \r
  59 public interface Scriptable {\r
  60 \r
  61     /**\r
  62      * Get the name of the set of objects implemented by this Java class.\r
  63      * This corresponds to the [[Class]] operation in ECMA and is used\r
  64      * by Object.prototype.toString() in ECMA.<p>\r
  65      * See ECMA 8.6.2 and 15.2.4.2.\r
  66      */\r
  67     public String getClassName();\r
  68 \r
  69     /**\r
  70      * Value returned from <code>get</code> if the property is not\r
  71      * found.\r
  72      */\r
  73     public static final Object NOT_FOUND = new Object();\r
  74 \r
  75     /**\r
  76      * Get a named property from the object.\r
  77      *\r
  78      * Looks property up in this object and returns the associated value\r
  79      * if found. Returns NOT_FOUND if not found.\r
  80      * Note that this method is not expected to traverse the prototype\r
  81      * chain. This is different from the ECMA [[Get]] operation.\r
  82      *\r
  83      * Depending on the property selector, the runtime will call\r
  84      * this method or the form of <code>get</code> that takes an\r
  85      * integer:\r
  86      * <table>\r
  87      * <tr><th>JavaScript code</th><th>Java code</th></tr>\r
  88      * <tr><td>a.b      </td><td>a.get("b", a)</td></tr>\r
  89      * <tr><td>a["foo"] </td><td>a.get("foo", a)</td></tr>\r
  90      * <tr><td>a[3]     </td><td>a.get(3, a)</td></tr>\r
  91      * <tr><td>a["3"]   </td><td>a.get(3, a)</td></tr>\r
  92      * <tr><td>a[3.0]   </td><td>a.get(3, a)</td></tr>\r
  93      * <tr><td>a["3.0"] </td><td>a.get("3.0", a)</td></tr>\r
  94      * <tr><td>a[1.1]   </td><td>a.get("1.1", a)</td></tr>\r
  95      * <tr><td>a[-4]    </td><td>a.get(-4, a)</td></tr>\r
  96      * </table>\r
  97      * <p>\r
  98      * The values that may be returned are limited to the following:\r
  99      * <UL>\r
 100      * <LI>java.lang.Boolean objects</LI>\r
 101      * <LI>java.lang.String objects</LI>\r
 102      * <LI>java.lang.Number objects</LI>\r
 103      * <LI>org.mozilla.javascript.Scriptable objects</LI>\r
 104      * <LI>null</LI>\r
 105      * <LI>The value returned by Context.getUndefinedValue()</LI>\r
 106      * <LI>NOT_FOUND</LI>\r
 107      * </UL>\r
 108      * @param name the name of the property\r
 109      * @param start the object in which the lookup began\r
 110      * @return the value of the property (may be null), or NOT_FOUND\r
 111      * @see org.mozilla.javascript.Context#getUndefinedValue\r
 112      */\r
 113     public Object get(String name, Scriptable start);\r
 114 \r
 115     /**\r
 116      * Get a property from the object selected by an integral index.\r
 117      *\r
 118      * Identical to <code>get(String, Scriptable)</code> except that\r
 119      * an integral index is used to select the property.\r
 120      *\r
 121      * @param index the numeric index for the property\r
 122      * @param start the object in which the lookup began\r
 123      * @return the value of the property (may be null), or NOT_FOUND\r
 124      * @see org.mozilla.javascript.Scriptable#get(String,Scriptable)\r
 125      */\r
 126     public Object get(int index, Scriptable start);\r
 127 \r
 128     /**\r
 129      * Indicates whether or not a named property is defined in an object.\r
 130      *\r
 131      * Does not traverse the prototype chain.<p>\r
 132      *\r
 133      * The property is specified by a String name\r
 134      * as defined for the <code>get</code> method.<p>\r
 135      *\r
 136      * @param name the name of the property\r
 137      * @param start the object in which the lookup began\r
 138      * @return true if and only if the named property is found in the object\r
 139      * @see org.mozilla.javascript.Scriptable#get\r
 140      * @see org.mozilla.javascript.ScriptableObject#getProperty\r
 141      */\r
 142     public boolean has(String name, Scriptable start);\r
 143 \r
 144     /**\r
 145      * Indicates whether or not an indexed  property is defined in an object.\r
 146      *\r
 147      * Does not traverse the prototype chain.<p>\r
 148      *\r
 149      * The property is specified by an integral index\r
 150      * as defined for the <code>get</code> method.<p>\r
 151      *\r
 152      * @param index the numeric index for the property\r
 153      * @param start the object in which the lookup began\r
 154      * @return true if and only if the indexed property is found in the object\r
 155      * @see org.mozilla.javascript.Scriptable#get\r
 156      * @see org.mozilla.javascript.ScriptableObject#getProperty\r
 157      */\r
 158     public boolean has(int index, Scriptable start);\r
 159 \r
 160     /**\r
 161      * Sets a named property in this object.\r
 162      * <p>\r
 163      * The property is specified by a string name \r
 164      * as defined for <code>get</code>.\r
 165      * <p>\r
 166      * The possible values that may be passed in are as defined for\r
 167      * <code>get</code>. A class that implements this method may choose\r
 168      * to ignore calls to set certain properties, in which case those\r
 169      * properties are effectively read-only.<p>\r
 170      * For properties defined in a prototype chain,\r
 171      * use <code>putProperty</code> in ScriptableObject. <p>\r
 172      * Note that if a property <i>a</i> is defined in the prototype <i>p</i>\r
 173      * of an object <i>o</i>, then evaluating <code>o.a = 23</code> will cause\r
 174      * <code>set</code> to be called on the prototype <i>p</i> with\r
 175      * <i>o</i> as the  <i>start</i> parameter.\r
 176      * To preserve JavaScript semantics, it is the Scriptable\r
 177      * object's responsibility to modify <i>o</i>. <p>\r
 178      * This design allows properties to be defined in prototypes and implemented\r
 179      * in terms of getters and setters of Java values without consuming slots\r
 180      * in each instance.<p>\r
 181      * <p>\r
 182      * The values that may be set are limited to the following:\r
 183      * <UL>\r
 184      * <LI>java.lang.Boolean objects</LI>\r
 185      * <LI>java.lang.String objects</LI>\r
 186      * <LI>java.lang.Number objects</LI>\r
 187      * <LI>org.mozilla.javascript.Scriptable objects</LI>\r
 188      * <LI>null</LI>\r
 189      * <LI>The value returned by Context.getUndefinedValue()</LI> \r
 190      * </UL><p> \r
 191      * Arbitrary Java objects may be wrapped in a Scriptable by first calling\r
 192      * <code>Context.toObject</code>. This allows the property of a JavaScript\r
 193      * object to contain an arbitrary Java object as a value.<p> \r
 194      * Note that <code>has</code> will be called by the runtime first before\r
 195      * <code>set</code> is called to determine in which object the\r
 196      * property is defined.\r
 197      * Note that this method is not expected to traverse the prototype chain,\r
 198      * which is different from the ECMA [[Put]] operation.\r
 199      * @param name the name of the property\r
 200      * @param start the object whose property is being set\r
 201      * @param value value to set the property to\r
 202      * @see org.mozilla.javascript.Scriptable#has\r
 203      * @see org.mozilla.javascript.Scriptable#get\r
 204      * @see org.mozilla.javascript.ScriptableObject#putProperty\r
 205      * @see org.mozilla.javascript.Context#toObject\r
 206      */\r
 207     public void put(String name, Scriptable start, Object value);\r
 208 \r
 209     /**\r
 210      * Sets an indexed property in this object.\r
 211      * <p>\r
 212      * The property is specified by an integral index\r
 213      * as defined for <code>get</code>.<p>\r
 214      *\r
 215      * Identical to <code>put(String, Scriptable, Object)</code> except that\r
 216      * an integral index is used to select the property.\r
 217      *\r
 218      * @param index the numeric index for the property\r
 219      * @param start the object whose property is being set\r
 220      * @param value value to set the property to\r
 221      * @see org.mozilla.javascript.Scriptable#has\r
 222      * @see org.mozilla.javascript.Scriptable#get\r
 223      * @see org.mozilla.javascript.Scriptable#put(String,Scriptable,Object)\r
 224      * @see org.mozilla.javascript.ScriptableObject#putProperty\r
 225      */\r
 226     public void put(int index, Scriptable start, Object value);\r
 227 \r
 228     /**\r
 229      * Removes a property from this object.\r
 230      * This operation corresponds to the ECMA [[Delete]] except that\r
 231      * the no result is returned. The runtime will guarantee that this\r
 232      * method is called only if the property exists. After this method\r
 233      * is called, the runtime will call Scriptable.has to see if the\r
 234      * property has been removed in order to determine the boolean\r
 235      * result of the delete operator as defined by ECMA 11.4.1.\r
 236      * <p>\r
 237      * A property can be made permanent by ignoring calls to remove\r
 238      * it.<p>\r
 239      * The property is specified by a String name\r
 240      * as defined for <code>get</code>.\r
 241      * <p>\r
 242      * To delete properties defined in a prototype chain,\r
 243      * see deleteProperty in ScriptableObject.\r
 244      * @param name the identifier for the property\r
 245      * @see org.mozilla.javascript.Scriptable#get\r
 246      * @see org.mozilla.javascript.ScriptableObject#deleteProperty\r
 247      */\r
 248     public void delete(String name);\r
 249 \r
 250     /**\r
 251      * Removes a property from this object.\r
 252      *\r
 253      * The property is specified by an integral index\r
 254      * as defined for <code>get</code>.\r
 255      * <p>\r
 256      * To delete properties defined in a prototype chain,\r
 257      * see deleteProperty in ScriptableObject.\r
 258      *\r
 259      * Identical to <code>delete(String)</code> except that\r
 260      * an integral index is used to select the property.\r
 261      *\r
 262      * @param index the numeric index for the property\r
 263      * @see org.mozilla.javascript.Scriptable#get\r
 264      * @see org.mozilla.javascript.ScriptableObject#deleteProperty\r
 265      */\r
 266     public void delete(int index);\r
 267 \r
 268     /**\r
 269      * Get the prototype of the object.\r
 270      * @return the prototype\r
 271      */\r
 272     public Scriptable getPrototype();\r
 273 \r
 274     /**\r
 275      * Set the prototype of the object.\r
 276      * @param prototype the prototype to set\r
 277      */\r
 278     public void setPrototype(Scriptable prototype);\r
 279 \r
 280     /**\r
 281      * Get the parent scope of the object.\r
 282      * @return the parent scope\r
 283      */\r
 284     public Scriptable getParentScope();\r
 285 \r
 286     /**\r
 287      * Set the parent scope of the object.\r
 288      * @param parent the parent scope to set\r
 289      */\r
 290     public void setParentScope(Scriptable parent);\r
 291 \r
 292     /**\r
 293      * Get an array of property ids.\r
 294      *\r
 295      * Not all property ids need be returned. Those properties\r
 296      * whose ids are not returned are considered non-enumerable.\r
 297      *\r
 298      * @return an array of Objects. Each entry in the array is either\r
 299      *         a java.lang.String or a java.lang.Number\r
 300      */\r
 301     public Object[] getIds();\r
 302 \r
 303     /**\r
 304      * Get the default value of the object with a given hint.\r
 305      * The hints are String.class for type String, Number.class for type\r
 306      * Number, Scriptable.class for type Object, and Boolean.class for\r
 307      * type Boolean. <p>\r
 308      *\r
 309      * A <code>hint</code> of null means "no hint".\r
 310      *\r
 311      * See ECMA 8.6.2.6.\r
 312      *\r
 313      * @param hint the type hint\r
 314      * @return the default value\r
 315      */\r
 316     public Object getDefaultValue(Class hint);\r
 317 \r
 318     /**\r
 319      * The instanceof operator.\r
 320      *\r
 321      * <p>\r
 322      * The JavaScript code "lhs instanceof rhs" causes rhs.hasInstance(lhs) to\r
 323      * be called.\r
 324      *\r
 325      * <p>\r
 326      * The return value is implementation dependent so that embedded host objects can\r
 327      * return an appropriate value.  See the JS 1.3 language documentation for more\r
 328      * detail.\r
 329      *\r
 330      * <p>This operator corresponds to the proposed EMCA [[HasInstance]] operator.\r
 331      *\r
 332      * @param instance The value that appeared on the LHS of the instanceof\r
 333      *              operator\r
 334      *\r
 335      * @return an implementation dependent value\r
 336      */\r
 337     public boolean hasInstance(Scriptable instance);\r
 338 }\r
 339 \r