001: /* -*- Mode: java; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
002: *
003: * ***** BEGIN LICENSE BLOCK *****
004: * Version: MPL 1.1/GPL 2.0
005: *
006: * The contents of this file are subject to the Mozilla Public License Version
007: * 1.1 (the "License"); you may not use this file except in compliance with
008: * the License. You may obtain a copy of the License at
009: * http://www.mozilla.org/MPL/
010: *
011: * Software distributed under the License is distributed on an "AS IS" basis,
012: * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
013: * for the specific language governing rights and limitations under the
014: * License.
015: *
016: * The Original Code is Rhino code, released
017: * May 6, 1999.
018: *
019: * The Initial Developer of the Original Code is
020: * Netscape Communications Corporation.
021: * Portions created by the Initial Developer are Copyright (C) 1997-1999
022: * the Initial Developer. All Rights Reserved.
023: *
024: * Contributor(s):
025: * Norris Boyd
026: *
027: * Alternatively, the contents of this file may be used under the terms of
028: * the GNU General Public License Version 2 or later (the "GPL"), in which
029: * case the provisions of the GPL are applicable instead of those above. If
030: * you wish to allow use of your version of this file only under the terms of
031: * the GPL and not to allow others to use your version of this file under the
032: * MPL, indicate your decision by deleting the provisions above and replacing
033: * them with the notice and other provisions required by the GPL. If you do
034: * not delete the provisions above, a recipient may use your version of this
035: * file under either the MPL or the GPL.
036: *
037: * ***** END LICENSE BLOCK ***** */
038:
039: // API class
040: package org.mozilla.javascript;
041:
042: /**
043: * This is interface that all objects in JavaScript must implement.
044: * The interface provides for the management of properties and for
045: * performing conversions.
046: * <p>
047: * Host system implementors may find it easier to extend the ScriptableObject
048: * class rather than implementing Scriptable when writing host objects.
049: * <p>
050: * There are many static methods defined in ScriptableObject that perform
051: * the multiple calls to the Scriptable interface needed in order to
052: * manipulate properties in prototype chains.
053: * <p>
054: *
055: * @see org.mozilla.javascript.ScriptableObject
056: * @author Norris Boyd
057: * @author Nick Thompson
058: * @author Brendan Eich
059: */
060:
061: public interface Scriptable {
062:
063: /**
064: * Get the name of the set of objects implemented by this Java class.
065: * This corresponds to the [[Class]] operation in ECMA and is used
066: * by Object.prototype.toString() in ECMA.<p>
067: * See ECMA 8.6.2 and 15.2.4.2.
068: */
069: public String getClassName();
070:
071: /**
072: * Value returned from <code>get</code> if the property is not
073: * found.
074: */
075: public static final Object NOT_FOUND = UniqueTag.NOT_FOUND;
076:
077: /**
078: * Get a named property from the object.
079: *
080: * Looks property up in this object and returns the associated value
081: * if found. Returns NOT_FOUND if not found.
082: * Note that this method is not expected to traverse the prototype
083: * chain. This is different from the ECMA [[Get]] operation.
084: *
085: * Depending on the property selector, the runtime will call
086: * this method or the form of <code>get</code> that takes an
087: * integer:
088: * <table>
089: * <tr><th>JavaScript code</th><th>Java code</th></tr>
090: * <tr><td>a.b </td><td>a.get("b", a)</td></tr>
091: * <tr><td>a["foo"] </td><td>a.get("foo", a)</td></tr>
092: * <tr><td>a[3] </td><td>a.get(3, a)</td></tr>
093: * <tr><td>a["3"] </td><td>a.get(3, a)</td></tr>
094: * <tr><td>a[3.0] </td><td>a.get(3, a)</td></tr>
095: * <tr><td>a["3.0"] </td><td>a.get("3.0", a)</td></tr>
096: * <tr><td>a[1.1] </td><td>a.get("1.1", a)</td></tr>
097: * <tr><td>a[-4] </td><td>a.get(-4, a)</td></tr>
098: * </table>
099: * <p>
100: * The values that may be returned are limited to the following:
101: * <UL>
102: * <LI>java.lang.Boolean objects</LI>
103: * <LI>java.lang.String objects</LI>
104: * <LI>java.lang.Number objects</LI>
105: * <LI>org.mozilla.javascript.Scriptable objects</LI>
106: * <LI>null</LI>
107: * <LI>The value returned by Context.getUndefinedValue()</LI>
108: * <LI>NOT_FOUND</LI>
109: * </UL>
110: * @param name the name of the property
111: * @param start the object in which the lookup began
112: * @return the value of the property (may be null), or NOT_FOUND
113: * @see org.mozilla.javascript.Context#getUndefinedValue
114: */
115: public Object get(String name, Scriptable start);
116:
117: /**
118: * Get a property from the object selected by an integral index.
119: *
120: * Identical to <code>get(String, Scriptable)</code> except that
121: * an integral index is used to select the property.
122: *
123: * @param index the numeric index for the property
124: * @param start the object in which the lookup began
125: * @return the value of the property (may be null), or NOT_FOUND
126: * @see org.mozilla.javascript.Scriptable#get(String,Scriptable)
127: */
128: public Object get(int index, Scriptable start);
129:
130: /**
131: * Indicates whether or not a named property is defined in an object.
132: *
133: * Does not traverse the prototype chain.<p>
134: *
135: * The property is specified by a String name
136: * as defined for the <code>get</code> method.<p>
137: *
138: * @param name the name of the property
139: * @param start the object in which the lookup began
140: * @return true if and only if the named property is found in the object
141: * @see org.mozilla.javascript.Scriptable#get(String, Scriptable)
142: * @see org.mozilla.javascript.ScriptableObject#getProperty(Scriptable, String)
143: */
144: public boolean has(String name, Scriptable start);
145:
146: /**
147: * Indicates whether or not an indexed property is defined in an object.
148: *
149: * Does not traverse the prototype chain.<p>
150: *
151: * The property is specified by an integral index
152: * as defined for the <code>get</code> method.<p>
153: *
154: * @param index the numeric index for the property
155: * @param start the object in which the lookup began
156: * @return true if and only if the indexed property is found in the object
157: * @see org.mozilla.javascript.Scriptable#get(int, Scriptable)
158: * @see org.mozilla.javascript.ScriptableObject#getProperty(Scriptable, int)
159: */
160: public boolean has(int index, Scriptable start);
161:
162: /**
163: * Sets a named property in this object.
164: * <p>
165: * The property is specified by a string name
166: * as defined for <code>get</code>.
167: * <p>
168: * The possible values that may be passed in are as defined for
169: * <code>get</code>. A class that implements this method may choose
170: * to ignore calls to set certain properties, in which case those
171: * properties are effectively read-only.<p>
172: * For properties defined in a prototype chain,
173: * use <code>putProperty</code> in ScriptableObject. <p>
174: * Note that if a property <i>a</i> is defined in the prototype <i>p</i>
175: * of an object <i>o</i>, then evaluating <code>o.a = 23</code> will cause
176: * <code>set</code> to be called on the prototype <i>p</i> with
177: * <i>o</i> as the <i>start</i> parameter.
178: * To preserve JavaScript semantics, it is the Scriptable
179: * object's responsibility to modify <i>o</i>. <p>
180: * This design allows properties to be defined in prototypes and implemented
181: * in terms of getters and setters of Java values without consuming slots
182: * in each instance.<p>
183: * <p>
184: * The values that may be set are limited to the following:
185: * <UL>
186: * <LI>java.lang.Boolean objects</LI>
187: * <LI>java.lang.String objects</LI>
188: * <LI>java.lang.Number objects</LI>
189: * <LI>org.mozilla.javascript.Scriptable objects</LI>
190: * <LI>null</LI>
191: * <LI>The value returned by Context.getUndefinedValue()</LI>
192: * </UL><p>
193: * Arbitrary Java objects may be wrapped in a Scriptable by first calling
194: * <code>Context.toObject</code>. This allows the property of a JavaScript
195: * object to contain an arbitrary Java object as a value.<p>
196: * Note that <code>has</code> will be called by the runtime first before
197: * <code>set</code> is called to determine in which object the
198: * property is defined.
199: * Note that this method is not expected to traverse the prototype chain,
200: * which is different from the ECMA [[Put]] operation.
201: * @param name the name of the property
202: * @param start the object whose property is being set
203: * @param value value to set the property to
204: * @see org.mozilla.javascript.Scriptable#has(String, Scriptable)
205: * @see org.mozilla.javascript.Scriptable#get(String, Scriptable)
206: * @see org.mozilla.javascript.ScriptableObject#putProperty(Scriptable, String, Object)
207: * @see org.mozilla.javascript.Context#toObject(Object, Scriptable)
208: */
209: public void put(String name, Scriptable start, Object value);
210:
211: /**
212: * Sets an indexed property in this object.
213: * <p>
214: * The property is specified by an integral index
215: * as defined for <code>get</code>.<p>
216: *
217: * Identical to <code>put(String, Scriptable, Object)</code> except that
218: * an integral index is used to select the property.
219: *
220: * @param index the numeric index for the property
221: * @param start the object whose property is being set
222: * @param value value to set the property to
223: * @see org.mozilla.javascript.Scriptable#has(int, Scriptable)
224: * @see org.mozilla.javascript.Scriptable#get(int, Scriptable)
225: * @see org.mozilla.javascript.ScriptableObject#putProperty(Scriptable, int, Object)
226: * @see org.mozilla.javascript.Context#toObject(Object, Scriptable)
227: */
228: public void put(int index, Scriptable start, Object value);
229:
230: /**
231: * Removes a property from this object.
232: * This operation corresponds to the ECMA [[Delete]] except that
233: * the no result is returned. The runtime will guarantee that this
234: * method is called only if the property exists. After this method
235: * is called, the runtime will call Scriptable.has to see if the
236: * property has been removed in order to determine the boolean
237: * result of the delete operator as defined by ECMA 11.4.1.
238: * <p>
239: * A property can be made permanent by ignoring calls to remove
240: * it.<p>
241: * The property is specified by a String name
242: * as defined for <code>get</code>.
243: * <p>
244: * To delete properties defined in a prototype chain,
245: * see deleteProperty in ScriptableObject.
246: * @param name the identifier for the property
247: * @see org.mozilla.javascript.Scriptable#get(String, Scriptable)
248: * @see org.mozilla.javascript.ScriptableObject#deleteProperty(Scriptable, String)
249: */
250: public void delete(String name);
251:
252: /**
253: * Removes a property from this object.
254: *
255: * The property is specified by an integral index
256: * as defined for <code>get</code>.
257: * <p>
258: * To delete properties defined in a prototype chain,
259: * see deleteProperty in ScriptableObject.
260: *
261: * Identical to <code>delete(String)</code> except that
262: * an integral index is used to select the property.
263: *
264: * @param index the numeric index for the property
265: * @see org.mozilla.javascript.Scriptable#get(int, Scriptable)
266: * @see org.mozilla.javascript.ScriptableObject#deleteProperty(Scriptable, int)
267: */
268: public void delete(int index);
269:
270: /**
271: * Get the prototype of the object.
272: * @return the prototype
273: */
274: public Scriptable getPrototype();
275:
276: /**
277: * Set the prototype of the object.
278: * @param prototype the prototype to set
279: */
280: public void setPrototype(Scriptable prototype);
281:
282: /**
283: * Get the parent scope of the object.
284: * @return the parent scope
285: */
286: public Scriptable getParentScope();
287:
288: /**
289: * Set the parent scope of the object.
290: * @param parent the parent scope to set
291: */
292: public void setParentScope(Scriptable parent);
293:
294: /**
295: * Get an array of property ids.
296: *
297: * Not all property ids need be returned. Those properties
298: * whose ids are not returned are considered non-enumerable.
299: *
300: * @return an array of Objects. Each entry in the array is either
301: * a java.lang.String or a java.lang.Number
302: */
303: public Object[] getIds();
304:
305: /**
306: * Get the default value of the object with a given hint.
307: * The hints are String.class for type String, Number.class for type
308: * Number, Scriptable.class for type Object, and Boolean.class for
309: * type Boolean. <p>
310: *
311: * A <code>hint</code> of null means "no hint".
312: *
313: * See ECMA 8.6.2.6.
314: *
315: * @param hint the type hint
316: * @return the default value
317: */
318: public Object getDefaultValue(Class hint);
319:
320: /**
321: * The instanceof operator.
322: *
323: * <p>
324: * The JavaScript code "lhs instanceof rhs" causes rhs.hasInstance(lhs) to
325: * be called.
326: *
327: * <p>
328: * The return value is implementation dependent so that embedded host objects can
329: * return an appropriate value. See the JS 1.3 language documentation for more
330: * detail.
331: *
332: * <p>This operator corresponds to the proposed EMCA [[HasInstance]] operator.
333: *
334: * @param instance The value that appeared on the LHS of the instanceof
335: * operator
336: *
337: * @return an implementation dependent value
338: */
339: public boolean hasInstance(Scriptable instance);
340: }
|