1 /*
2  * Copyright (c) 2006, 2016, Oracle and/or its affiliates. All rights reserved.
3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4  *
5  * This code is free software; you can redistribute it and/or modify it
6  * under the terms of the GNU General Public License version 2 only, as
7  * published by the Free Software Foundation.  Oracle designates this
8  * particular file as subject to the "Classpath" exception as provided
9  * by Oracle in the LICENSE file that accompanied this code.
10  *
11  * This code is distributed in the hope that it will be useful, but WITHOUT
12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14  * version 2 for more details (a copy is included in the LICENSE file that
15  * accompanied this code).
16  *
17  * You should have received a copy of the GNU General Public License version
18  * 2 along with this work; if not, write to the Free Software Foundation,
19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20  *
21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22  * or visit www.oracle.com if you need additional information or have any
23  * questions.
24  */
25 
26 package netscape.javascript;
27 
28 import java.security.AccessController;
29 import java.security.PrivilegedAction;
30 import java.util.Iterator;
31 import java.util.ServiceLoader;
32 
33 /**
34  * <p>
35  * Allows Java code to manipulate JavaScript objects.
36  * </p>
37  *
38  * <p>
39  * When a JavaScript object is passed or returned to Java code, it
40  * is wrapped in an instance of {@code JSObject}. When a
41  * {@code JSObject} instance is passed to the JavaScript engine,
42  * it is unwrapped back to its original JavaScript object. The
43  * {@code JSObject} class provides a way to invoke JavaScript
44  * methods and examine JavaScript properties.
45  * </p>
46  *
47  * <p> Any data returned from the JavaScript engine to Java is
48  * converted to Java data types. Certain data passed to the JavaScript
49  * engine is converted to JavaScript data types.
50  * </p>
51  *
52  */
53 @SuppressWarnings("deprecation")
54 public abstract class JSObject {
55     /**
56      * Constructs a new JSObject. Users should neither call this method nor
57      * subclass JSObject.
58      */
JSObject()59     protected JSObject()  {
60     }
61 
62     /**
63      * Calls a JavaScript method. Equivalent to
64      * "this.methodName(args[0], args[1], ...)" in JavaScript.
65      *
66      * @param methodName The name of the JavaScript method to be invoked.
67      * @param args the Java objects passed as arguments to the method.
68      * @return Result of the method.
69      * @throws JSException when an error is reported from the browser or
70      * JavaScript engine.
71      */
call(String methodName, Object... args)72     public abstract Object call(String methodName, Object... args) throws JSException;
73 
74     /**
75      * Evaluates a JavaScript expression. The expression is a string of
76      * JavaScript source code which will be evaluated in the context given by
77      * "this".
78      *
79      * @param s The JavaScript expression.
80      * @return Result of the JavaScript evaluation.
81      * @throws JSException when an error is reported from the browser or
82      * JavaScript engine.
83      */
eval(String s)84     public abstract Object eval(String s) throws JSException;
85 
86     /**
87      * Retrieves a named member of a JavaScript object. Equivalent to
88      * "this.name" in JavaScript.
89      *
90      * @param name The name of the JavaScript property to be accessed.
91      * @return The value of the propery.
92      * @throws JSException when an error is reported from the browser or
93      * JavaScript engine.
94      */
getMember(String name)95     public abstract Object getMember(String name) throws JSException;
96 
97     /**
98      * Sets a named member of a JavaScript object. Equivalent to
99      * "this.name = value" in JavaScript.
100      *
101      * @param name The name of the JavaScript property to be accessed.
102      * @param value The value of the propery.
103      * @throws JSException when an error is reported from the browser or
104      * JavaScript engine.
105      */
setMember(String name, Object value)106     public abstract void setMember(String name, Object value) throws JSException;
107 
108     /**
109      * Removes a named member of a JavaScript object. Equivalent
110      * to "delete this.name" in JavaScript.
111      *
112      * @param name The name of the JavaScript property to be removed.
113      * @throws JSException when an error is reported from the browser or
114      * JavaScript engine.
115      */
removeMember(String name)116     public abstract void removeMember(String name) throws JSException;
117 
118     /**
119      * Retrieves an indexed member of a JavaScript object. Equivalent to
120      * "this[index]" in JavaScript.
121      *
122      * @param index The index of the array to be accessed.
123      * @return The value of the indexed member.
124      * @throws JSException when an error is reported from the browser or
125      * JavaScript engine.
126      */
getSlot(int index)127     public abstract Object getSlot(int index) throws JSException;
128 
129     /**
130      * Sets an indexed member of a JavaScript object. Equivalent to
131      * "this[index] = value" in JavaScript.
132      *
133      * @param index The index of the array to be accessed.
134      * @param value The value to set
135      * @throws JSException when an error is reported from the browser or
136      * JavaScript engine.
137      */
setSlot(int index, Object value)138     public abstract void setSlot(int index, Object value) throws JSException;
139 
140 }
141