1 /* -*- Mode: java; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
\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
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
13 * The Original Code is Rhino code, released
\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
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
38 package org.mozilla.javascript;
\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
45 * Host system implementors may find it easier to extend the ScriptableObject
\r
46 * class rather than implementing Scriptable when writing host objects.
\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
53 * @see org.mozilla.javascript.ScriptableObject
\r
54 * @author Norris Boyd
\r
55 * @author Nick Thompson
\r
56 * @author Brendan Eich
\r
59 public interface Scriptable {
\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
67 public String getClassName();
\r
70 * Value returned from <code>get</code> if the property is not
\r
73 public static final Object NOT_FOUND = new Object();
\r
76 * Get a named property from the object.
\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
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
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
98 * The values that may be returned are limited to the following:
\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
105 * <LI>The value returned by Context.getUndefinedValue()</LI>
\r
106 * <LI>NOT_FOUND</LI>
\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
113 public Object get(String name, Scriptable start);
\r
116 * Get a property from the object selected by an integral index.
\r
118 * Identical to <code>get(String, Scriptable)</code> except that
\r
119 * an integral index is used to select the property.
\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
126 public Object get(int index, Scriptable start);
\r
129 * Indicates whether or not a named property is defined in an object.
\r
131 * Does not traverse the prototype chain.<p>
\r
133 * The property is specified by a String name
\r
134 * as defined for the <code>get</code> method.<p>
\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
142 public boolean has(String name, Scriptable start);
\r
145 * Indicates whether or not an indexed property is defined in an object.
\r
147 * Does not traverse the prototype chain.<p>
\r
149 * The property is specified by an integral index
\r
150 * as defined for the <code>get</code> method.<p>
\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
158 public boolean has(int index, Scriptable start);
\r
161 * Sets a named property in this object.
\r
163 * The property is specified by a string name
\r
164 * as defined for <code>get</code>.
\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
182 * The values that may be set are limited to the following:
\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
189 * <LI>The value returned by Context.getUndefinedValue()</LI>
\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
207 public void put(String name, Scriptable start, Object value);
\r
210 * Sets an indexed property in this object.
\r
212 * The property is specified by an integral index
\r
213 * as defined for <code>get</code>.<p>
\r
215 * Identical to <code>put(String, Scriptable, Object)</code> except that
\r
216 * an integral index is used to select the property.
\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
226 public void put(int index, Scriptable start, Object value);
\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
237 * A property can be made permanent by ignoring calls to remove
\r
239 * The property is specified by a String name
\r
240 * as defined for <code>get</code>.
\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
248 public void delete(String name);
\r
251 * Removes a property from this object.
\r
253 * The property is specified by an integral index
\r
254 * as defined for <code>get</code>.
\r
256 * To delete properties defined in a prototype chain,
\r
257 * see deleteProperty in ScriptableObject.
\r
259 * Identical to <code>delete(String)</code> except that
\r
260 * an integral index is used to select the property.
\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
266 public void delete(int index);
\r
269 * Get the prototype of the object.
\r
270 * @return the prototype
\r
272 public Scriptable getPrototype();
\r
275 * Set the prototype of the object.
\r
276 * @param prototype the prototype to set
\r
278 public void setPrototype(Scriptable prototype);
\r
281 * Get the parent scope of the object.
\r
282 * @return the parent scope
\r
284 public Scriptable getParentScope();
\r
287 * Set the parent scope of the object.
\r
288 * @param parent the parent scope to set
\r
290 public void setParentScope(Scriptable parent);
\r
293 * Get an array of property ids.
\r
295 * Not all property ids need be returned. Those properties
\r
296 * whose ids are not returned are considered non-enumerable.
\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
301 public Object[] getIds();
\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
309 * A <code>hint</code> of null means "no hint".
\r
311 * See ECMA 8.6.2.6.
\r
313 * @param hint the type hint
\r
314 * @return the default value
\r
316 public Object getDefaultValue(Class hint);
\r
319 * The instanceof operator.
\r
322 * The JavaScript code "lhs instanceof rhs" causes rhs.hasInstance(lhs) to
\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
330 * <p>This operator corresponds to the proposed EMCA [[HasInstance]] operator.
\r
332 * @param instance The value that appeared on the LHS of the instanceof
\r
335 * @return an implementation dependent value
\r
337 public boolean hasInstance(Scriptable instance);
\r