JsObject


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 }
398
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags