Save This Page
1 /*
2 * The Apache Software License, Version 1.1
3 *
4 * Copyright (c) 2002 The Apache Software Foundation. All rights
5 * reserved.
6 *
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
9 * are met:
10 *
11 * 1. Redistributions of source code must retain the above copyright
12 * notice, this list of conditions and the following disclaimer.
13 *
14 * 2. Redistributions in binary form must reproduce the above copyright
15 * notice, this list of conditions and the following disclaimer in
16 * the documentation and/or other materials provided with the
17 * distribution.
18 *
19 * 3. The end-user documentation included with the redistribution, if
20 * any, must include the following acknowlegement:
21 * "This product includes software developed by the
22 * Apache Software Foundation (http://www.apache.org/)."
23 * Alternately, this acknowlegement may appear in the software itself,
24 * if and wherever such third-party acknowlegements normally appear.
25 *
26 * 4. The names "Apache BSF", "Apache", and "Apache Software Foundation"
27 * must not be used to endorse or promote products derived from
28 * this software without prior written permission. For written
29 * permission, please contact apache@apache.org.
30 *
31 * 5. Products derived from this software may not be called "Apache"
32 * nor may "Apache" appear in their names without prior written
33 * permission of the Apache Group.
34 *
35 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
36 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
37 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
38 * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
39 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
40 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
41 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
42 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
43 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
44 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
45 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
46 * SUCH DAMAGE.
47 * ====================================================================
48 *
49 * This software consists of voluntary contributions made by many individuals
50 * on behalf of the Apache Software Foundation and was originally created by
51 * Sanjiva Weerawarana and others at International Business Machines
52 * Corporation. For more information on the Apache Software Foundation,
53 * please see <http://www.apache.org/>.
54 */
55
56 package org.apache.bsf.debug.jsdi;
57
58 import java.rmi.Remote;
59 import java.rmi.RemoteException;
60
61 /**
62 * This is interface that all objects in JavaScript must implement.
63 * The interface provides for the management of properties and for
64 * performing conversions.
65 * <p>
66 * Host system implementors may find it easier to extend the ScriptableObject
67 * class rather than implementing Scriptable when writing host objects.
68 * <p>
69 * There are many static methods defined in ScriptableObject that perform
70 * the multiple calls to the Scriptable interface needed in order to
71 * manipulate properties in prototype chains.
72 * <p>
73 *
74 * @author: Olivier Gruber
75 */
76
77 public interface JsObject extends Remote {
78
79 /**
80 * Property attribute indicating property cannot be deleted.
81 *
82 * @see org.mozilla.javascript.ScriptableObject#delete
83 * @see org.mozilla.javascript.ScriptableObject#getAttributes
84 * @see org.mozilla.javascript.ScriptableObject#setAttributes
85 */
86 public static final int DONTDELETE = 0x04;
87 /**
88 * Property attribute indicating property is not enumerated.
89 *
90 * Only enumerated properties will be returned by getIds().
91 *
92 * @see org.mozilla.javascript.ScriptableObject#getIds
93 * @see org.mozilla.javascript.ScriptableObject#getAttributes
94 * @see org.mozilla.javascript.ScriptableObject#setAttributes
95 */
96 public static final int DONTENUM = 0x02;
97 /**
98 * The empty property attribute.
99 *
100 * Used by getAttributes() and setAttributes().
101 *
102 * @see org.mozilla.javascript.ScriptableObject#getAttributes
103 * @see org.mozilla.javascript.ScriptableObject#setAttributes
104 */
105 public static final int EMPTY = 0x00;
106 /**
107 * Property attribute indicating property cannot be deleted.
108 *
109 * @see org.mozilla.javascript.ScriptableObject#delete
110 * @see org.mozilla.javascript.ScriptableObject#getAttributes
111 * @see org.mozilla.javascript.ScriptableObject#setAttributes
112 */
113 public static final int INTERNAL = 0x05;
114 /**
115 * Property attribute indicating assignment to this property is ignored.
116 *
117 * @see org.mozilla.javascript.ScriptableObject#put
118 * @see org.mozilla.javascript.ScriptableObject#getAttributes
119 * @see org.mozilla.javascript.ScriptableObject#setAttributes
120 */
121 public static final int READONLY = 0x01;
122
123 /**
124 * The value can be any of the following type:
125 *
126 * java.lang.Boolean
127 * java.lang.Number
128 * java.lang.String
129 * org.apache.bsf.debug.jsdi.JsObject
130 */
131 public void define(String propertyName, Object value, int attributes)
132 throws RemoteException;
133 /**
134 * Removes a property from this object.
135 * The prototype chain is not walked to find the
136 * property.
137 *
138 * This operation corresponds to the ECMA [[Delete]] except that
139 * the no result is returned. The runtime will guarantee that this
140 * method is called only if the property exists. After this method
141 * is called, the runtime will call Scriptable.has to see if the
142 * property has been removed in order to determine the boolean
143 * result of the delete operator as defined by ECMA 11.4.1.
144 * <p>
145 * A property can be made permanent by ignoring calls to remove
146 * it.
147 *
148 * The property is specified by an integral index
149 * as defined for <code>get</code>.
150 * <p>
151 * To delete properties defined in a prototype chain,
152 * first find the owner object of the property and then
153 * call deleteProperty on that owner object.
154 *
155 * Identical to <code>delete(String)</code> except that
156 * an integral index is used to select the property.
157 *
158 * @param index the numeric index for the property
159 * @see org.mozilla.javascript.Scriptable#get
160 * @see org.mozilla.javascript.ScriptableObject#deleteProperty
161 */
162 public void delete(int index) throws RemoteException;
163 /**
164 * Removes a property from this object.
165 * This operation corresponds to the ECMA [[Delete]] except that
166 * the no result is returned. The runtime will guarantee that this
167 * method is called only if the property exists. After this method
168 * is called, the runtime will call Scriptable.has to see if the
169 * property has been removed in order to determine the boolean
170 * result of the delete operator as defined by ECMA 11.4.1.
171 * <p>
172 * A property can be made permanent by ignoring calls to remove
173 * it.<p>
174 * The property is specified by a String name
175 * as defined for <code>get</code>.
176 * <p>
177 * To delete properties defined in a prototype chain,
178 * first find the owner object of the property and then
179 * call deleteProperty on that owner object.
180 *
181 * @param name the identifier for the property
182 * @see org.mozilla.javascript.Scriptable#get
183 * @see org.mozilla.javascript.ScriptableObject#deleteProperty
184 */
185 public void delete(String name) throws RemoteException;
186
187 /**
188 * Get a named property from the object.
189 * Does not walk the prototype chain.
190 *
191 * Looks property up in this object and returns the associated value
192 * if found. Returns NOT_FOUND if not found.
193 * Note that this method is not expected to traverse the prototype
194 * chain. This is different from the ECMA [[Get]] operation.
195 *
196 * Depending on the property selector, the runtime will call
197 * this method or the form of <code>get</code> that takes an
198 * integer:
199 * <table>
200 * <tr><th>JavaScript code</th><th>Java code</th></tr>
201 * <tr><td>a.b </td><td>a.get("b", a)</td></tr>
202 * <tr><td>a["foo"] </td><td>a.get("foo", a)</td></tr>
203 * <tr><td>a[3] </td><td>a.get(3, a)</td></tr>
204 * <tr><td>a["3"] </td><td>a.get(3, a)</td></tr>
205 * <tr><td>a[3.0] </td><td>a.get(3, a)</td></tr>
206 * <tr><td>a["3.0"] </td><td>a.get("3.0", a)</td></tr>
207 * <tr><td>a[1.1] </td><td>a.get("1.1", a)</td></tr>
208 * <tr><td>a[-4] </td><td>a.get(-4, a)</td></tr>
209 * </table>
210 * <p>
211 * The values that may be returned are limited to the following:
212 * <UL>
213 * <LI>java.lang.Boolean objects</LI>
214 * <LI>java.lang.String objects</LI>
215 * <LI>java.lang.Number objects</LI>
216 * <LI>org.apache.bsf.debug.jsdi.JsObject objects</LI>
217 * <LI>null</LI>
218 * <LI>The value returned by Context.getUndefinedValue()</LI>
219 * <LI>NOT_FOUND</LI>
220 * </UL>
221 * @param name the name of the property
222 * @return the value of the property (may be null), or NOT_FOUND
223 */
224 public Object get(String name) throws RemoteException;
225 public Object get(int index) throws RemoteException;
226
227 /**
228 * Get the name of the set of objects implemented by this Java class.
229 * This corresponds to the [[Class]] operation in ECMA and is used
230 * by Object.prototype.toString() in ECMA.<p>
231 * See ECMA 8.6.2 and 15.2.4.2.
232 */
233 public String getClassName() throws RemoteException;
234
235 /**
236 * Get the default value of the object with a given hint.
237 * The hints are String.class for type String, Number.class for type
238 * Number, Scriptable.class for type Object, and Boolean.class for
239 * type Boolean. <p>
240 *
241 * A <code>hint</code> of null means "no hint".
242 *
243 * See ECMA 8.6.2.6.
244 *
245 * @param hint the type hint
246 * @return the default value
247 */
248 public Object getDefaultValue(Class hint) throws RemoteException;
249
250 /**
251 * Returns an array of property ids defined on this object.
252 * The prototype chain is not walked.
253 * However, modified properties that were prototype properties
254 * will be seen.
255 * The parameter indicates to enumerate the "DONTENUM" properties
256 * or not.
257 * <p>
258 * @return an array of all ids from all object in the prototype chain.
259 * If a given id occurs multiple times in the prototype chain,
260 * it will occur only once in this list.
261 * The elements are limited to:
262 * - java.lang.String for the property name if it has one.
263 * - java.lang.Integer for properties without a name, it is their index.
264 * @since 1.5R2
265 */
266 public Object[] getIds(boolean all) throws RemoteException;
267
268 /**
269 * Get the prototype of the object.
270 * @return the prototype
271 */
272 public JsObject getPrototype() throws RemoteException;
273
274 /**
275 * The scope is for supporting two things.
276 *
277 * If the object is a function, the scope is the "execution" scope
278 * of the function. It will be used when calling the function to
279 * initialize the Context scope.
280 *
281 * If the object is not a function, the scope is used for the scope
282 * chain of execution context.
283 */
284 public JsObject getScope() throws RemoteException;
285
286 /**
287 * Indicates whether or not an indexed property is defined in an object.
288 * Does not traverse the prototype chain.<p>
289 *
290 * The property is specified by an integral index
291 * as defined for the <code>get</code> method.<p>
292 *
293 * @param index the numeric index for the property
294 * @return true if and only if the indexed property is found in the object
295 * @see org.mozilla.javascript.Scriptable#get
296 * @see org.mozilla.javascript.ScriptableObject#getProperty
297 */
298 public boolean has(int index) throws RemoteException;
299
300 /**
301 * Indicates whether or not a named property is defined in an object.
302 * Does not traverse the prototype chain.<p>
303 *
304 * The property is specified by a String name
305 * as defined for the <code>get</code> method.<p>
306 *
307 * @param name the name of the property
308 * @return true if and only if the named property is found in the object
309 * @see org.mozilla.javascript.Scriptable#get
310 * @see org.mozilla.javascript.ScriptableObject#getProperty
311 */
312 public boolean has(String name) throws RemoteException;
313
314 /**
315 * The instanceof operator.
316 *
317 * <p>
318 * The JavaScript code "lhs instanceof rhs" causes rhs.hasInstance(lhs) to
319 * be called.
320 *
321 * <p>
322 * The return value is implementation dependent so that embedded host objects can
323 * return an appropriate value. See the JS 1.3 language documentation for more
324 * detail.
325 *
326 * <p>This operator corresponds to the proposed EMCA [[HasInstance]] operator.
327 *
328 * @param instance The value that appeared on the LHS of the instanceof
329 * operator
330 *
331 * @return an implementation dependent value
332 */
333 public boolean hasInstance(JsObject instance) throws RemoteException;
334 public boolean isFunction() throws RemoteException;
335 public boolean isScript() throws RemoteException;
336
337 /**
338 * Sets an indexed property in this object.
339 * <p>
340 * The property is specified by an integral index
341 * as defined for <code>get</code>.<p>
342 *
343 * @param index the numeric index for the property
344 * @param value value to set the property to
345 */
346 public void put(int index, Object value) throws RemoteException;
347
348 /**
349 * Sets a named property in this object.
350 * <p>
351 * The property is specified by a string name
352 * as defined for <code>get</code>.
353 * <p>
354 * Note that if a property <i>a</i> is defined in the prototype <i>p</i>
355 * of an object <i>o</i>, then evaluating <code>o.a = 23</code> will cause
356 * <code>set</code> to be called on the prototype <i>p</i> with
357 * <i>o</i> as the <i>start</i> parameter.
358 * To preserve JavaScript semantics, it is the Scriptable
359 * object's responsibility to modify <i>o</i>. <p>
360 * This design allows properties to be defined in prototypes and implemented
361 * in terms of getters and setters of Java values without consuming slots
362 * in each instance.<p>
363 * <p>
364 * The values that may be set are limited to the following:
365 * <UL>
366 * <LI>java.lang.Boolean objects</LI>
367 * <LI>java.lang.String objects</LI>
368 * <LI>java.lang.Number objects</LI>
369 * <LI>org.apache.bsf.debug.jsdi.JsObject</LI>
370 * <LI>null</LI>
371 * <LI>The value returned by Context.getUndefinedValue()</LI>
372 * </UL><p>
373 *
374 * IMPORTANT: JAVA OBJECTS.
375 * The wrapping is not yet supported.
376 */
377 public void put(String name, Object value) throws RemoteException;
378
379 /**
380 * Set the prototype of the object.
381 * @param prototype the prototype to set
382 */
383 public void setPrototype(JsObject prototype) throws RemoteException;
384
385
386 /**
387 * Set the prototype of the object.
388 * @param prototype the prototype to set
389 */
390 public void setScope(JsObject scope) throws RemoteException;
391
392 /* For Native Objects, allow to unwrap them.
393 public Object unwrap() throws RemoteException;
394 public boolean wrapsJavaObject() throws RemoteException;
395 public boolean isWrapper() throws RemoteException;
396 */
397 }