1 /*
2 * Copyright (c) 2006, 2014, 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.applet.Applet;
29
30 // FIXME: need URL on oracle.com for new LiveConnect spec
31
32 /**
33 * <P> Allows Java code to manipulate JavaScript objects. </P>
34 *
35 * <P> When a JavaScript object is passed or returned to Java code, it
36 * is wrapped in an instance of <CODE>JSObject</CODE>. When a
37 * <CODE>JSObject</CODE> instance is passed to the JavaScript engine,
38 * it is unwrapped back to its original JavaScript object. The
39 * <CODE>JSObject</CODE> class provides a way to invoke JavaScript
40 * methods and examine JavaScript properties. </P>
41 *
42 * <P> Any data returned from the JavaScript engine to Java is
43 * converted to Java data types. Certain data passed to the JavaScript
44 * engine is converted to JavaScript data types. See the section on <A
45 * HREF="https://jdk6.dev.java.net/plugin2/liveconnect/#JAVA_JS_CONVERSIONS">Data
46 * Type Conversions</A> in the <A
47 * HREF="https://jdk6.dev.java.net/plugin2/liveconnect/">new
48 * LiveConnect Specification</A> for details on how values are
49 * converted. </P>
50 *
51 */
52 public abstract class JSObject {
53
54 /**
55 * Constructs a new JSObject. Users should not call this method
56 * nor subclass JSObject.
57 */
58 protected JSObject() {
59 }
60
61 /**
62 * <p> Calls a JavaScript method. Equivalent to
63 * "this.methodName(args[0], args[1], ...)" in JavaScript.
64 * </p>
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 */
70 public abstract Object call(String methodName, Object... args) throws JSException;
71
72 /**
73 * <p> Evaluates a JavaScript expression. The expression is a string of
74 * JavaScript source code which will be evaluated in the context given by
75 * "this".
76 * </p>
77 *
78 * @param s The JavaScript expression.
79 * @return Result of the JavaScript evaluation.
80 */
81 public abstract Object eval(String s) throws JSException;
82
83 /**
84 * <p> Retrieves a named member of a JavaScript object. Equivalent to
85 * "this.name" in JavaScript.
86 * </p>
87 *
88 * @param name The name of the JavaScript property to be accessed.
89 * @return The value of the propery.
90 */
91 public abstract Object getMember(String name) throws JSException;
92
93 /**
94 * <p> Sets a named member of a JavaScript object. Equivalent to
95 * "this.name = value" in JavaScript.
96 * </p>
97 *
98 * @param name The name of the JavaScript property to be accessed.
99 * @param value The value of the propery.
100 */
101 public abstract void setMember(String name, Object value) throws JSException;
102
103 /**
104 * <p> Removes a named member of a JavaScript object. Equivalent
105 * to "delete this.name" in JavaScript.
106 * </p>
107 *
108 * @param name The name of the JavaScript property to be removed.
109 */
110 public abstract void removeMember(String name) throws JSException;
111
112 /**
113 * <p> Retrieves an indexed member of a JavaScript object. Equivalent to
114 * "this[index]" in JavaScript.
115 * </p>
116 *
117 * @param index The index of the array to be accessed.
118 * @return The value of the indexed member.
119 */
120 public abstract Object getSlot(int index) throws JSException;
121
122 /**
123 * <p> Sets an indexed member of a JavaScript object. Equivalent to
124 * "this[index] = value" in JavaScript.
125 * </p>
126 *
127 * @param index The index of the array to be accessed.
128 */
129 public abstract void setSlot(int index, Object value) throws JSException;
130
131 /**
132 * <p> Returns a JSObject for the window containing the given applet.
133 * </p>
134 *
135 * @param applet The applet.
136 * @return JSObject for the window containing the given applet.
137 */
138 public static JSObject getWindow(Applet applet) throws JSException {
139
140 throw new JSException("Unexpected error: This method should not be used unless loaded from plugin.jar");
141
142 /*
143 try
144 {
145 if (applet != null)
146 {
147
148 String obj = (String) applet.getParameter("MAYSCRIPT");
149
150 // Comment out MAYSCRIPT check because Internet Explorer doesn't support
151 // it.
152 // if (obj != null && (obj.equals("") || (new Boolean(obj).booleanValue() == true)))
153 {
154 // MAYSCRIPT is enabled
155
156 AppletContext c = applet.getAppletContext();
157
158 // The applet context must implement the sun.plugin.javascript.JSContext
159 // in order for us to get the handle that can be used when evaluating
160 // JavaScript expression.
161 //
162 JSObject ret = null;
163
164 if (c instanceof sun.plugin.javascript.JSContext)
165 {
166 JSContext j = (JSContext) c;
167 ret = j.getJSObject();
168 }
169
170 if (ret != null) {
171 return ret;
172 }
173 }
174 } else {
175 // new code for CustomProgress to get the JSObject w/o applet
176 AppContext ac = ToolkitStore.get().getAppContext();
177 if (ac != null) {
178 Plugin2Context context = (Plugin2Context)
179 ac.get(sun.plugin2.applet.Plugin2Manager.APPCONTEXT_PLUGIN2CTX_KEY);
180 if (context != null) {
181 Applet2Host host = context.getHost();
182 if (host != null && host instanceof JSContext) {
183 JSContext jsc = (JSContext) host;
184 JSObject ret = jsc.getOneWayJSObject();
185 if (ret != null) {
186 return ret;
187 }
188 }
189 }
190 }
191 }
192 }
193 catch (Throwable e)
194 {
195 throw (JSException) new JSException(JSException.EXCEPTION_TYPE_ERROR, e).initCause(e);
196 }
197
198 throw new JSException();
199 */
200 }
201 }