/*
 * Copyright (c) 2006, 2016, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package netscape.javascript;

import java.applet.Applet;
import java.security.AccessController;
import java.security.PrivilegedAction;
import java.util.Iterator;
import java.util.ServiceLoader;

/**
 * <p>
 * Allows Java code to manipulate JavaScript objects.
 * </p>
 *
 * <p>
 * When a JavaScript object is passed or returned to Java code, it
 * is wrapped in an instance of {@code JSObject}. When a
 * {@code JSObject} instance is passed to the JavaScript engine,
 * it is unwrapped back to its original JavaScript object. The
 * {@code JSObject} class provides a way to invoke JavaScript
 * methods and examine JavaScript properties.
 * </p>
 *
 * <p> Any data returned from the JavaScript engine to Java is
 * converted to Java data types. Certain data passed to the JavaScript
 * engine is converted to JavaScript data types.
 * </p>
 *
 */
@SuppressWarnings("deprecation")
public abstract class JSObject {
	/**
	 * Constructs a new JSObject. Users should neither call this method nor
	 * subclass JSObject.
	 */
	protected JSObject()  {
	}

	/**
	 * Calls a JavaScript method. Equivalent to
	 * "this.methodName(args[0], args[1], ...)" in JavaScript.
	 *
	 * @param methodName The name of the JavaScript method to be invoked.
	 * @param args the Java objects passed as arguments to the method.
	 * @return Result of the method.
	 * @throws JSException when an error is reported from the browser or
	 * JavaScript engine.
	 */
	public abstract Object call(String methodName, Object... args) throws JSException;

	/**
	 * Evaluates a JavaScript expression. The expression is a string of
	 * JavaScript source code which will be evaluated in the context given by
	 * "this".
	 *
	 * @param s The JavaScript expression.
	 * @return Result of the JavaScript evaluation.
	 * @throws JSException when an error is reported from the browser or
	 * JavaScript engine.
	 */
	public abstract Object eval(String s) throws JSException;

	/**
	 * Retrieves a named member of a JavaScript object. Equivalent to
	 * "this.name" in JavaScript.
	 *
	 * @param name The name of the JavaScript property to be accessed.
	 * @return The value of the propery.
	 * @throws JSException when an error is reported from the browser or
	 * JavaScript engine.
	 */
	public abstract Object getMember(String name) throws JSException;

	/**
	 * Sets a named member of a JavaScript object. Equivalent to
	 * "this.name = value" in JavaScript.
	 *
	 * @param name The name of the JavaScript property to be accessed.
	 * @param value The value of the propery.
	 * @throws JSException when an error is reported from the browser or
	 * JavaScript engine.
	 */
	public abstract void setMember(String name, Object value) throws JSException;

	/**
	 * Removes a named member of a JavaScript object. Equivalent
	 * to "delete this.name" in JavaScript.
	 *
	 * @param name The name of the JavaScript property to be removed.
	 * @throws JSException when an error is reported from the browser or
	 * JavaScript engine.
	 */
	public abstract void removeMember(String name) throws JSException;

	/**
	 * Retrieves an indexed member of a JavaScript object. Equivalent to
	 * "this[index]" in JavaScript.
	 *
	 * @param index The index of the array to be accessed.
	 * @return The value of the indexed member.
	 * @throws JSException when an error is reported from the browser or
	 * JavaScript engine.
	 */
	public abstract Object getSlot(int index) throws JSException;

	/**
	 * Sets an indexed member of a JavaScript object. Equivalent to
	 * "this[index] = value" in JavaScript.
	 *
	 * @param index The index of the array to be accessed.
	 * @param value The value to set
	 * @throws JSException when an error is reported from the browser or
	 * JavaScript engine.
	 */
	public abstract void setSlot(int index, Object value) throws JSException;

	/**
	 * Returns a JSObject for the window containing the given applet. This
	 * method only works when the Java code is running in a browser as an
	 * applet. The object returned may be used to access the HTML DOM directly.
	 *
	 * @param applet The applet.
	 * @return JSObject representing the window containing the given applet or
	 * {@code null} if we are not connected to a browser.
	 * @throws JSException when an error is reported from the browser or
	 * JavaScript engine or if applet is {@code null}
	 *
	 * @deprecated  The Applet API is deprecated. See the
	 * <a href="{@docRoot}/java.desktop/java/applet/package-summary.html">
	 * java.applet package documentation</a> for further information.
	 */

	@Deprecated(since = "9")
	@SuppressWarnings("exports")
	public static JSObject getWindow(Applet applet) throws JSException {
		return ProviderLoader.callGetWindow(applet);
	}

	private static class ProviderLoader {
		private static final JSObjectProvider provider;

		static {
			provider = AccessController.doPrivileged(
				new PrivilegedAction<JSObjectProvider>() {
					@Override
					public JSObjectProvider run() {
						Iterator<JSObjectProvider> providers =
							ServiceLoader.loadInstalled(JSObjectProvider.class).iterator();
						if (providers.hasNext()) {
							return providers.next();
						}
						return null;
					}
				}
			);
		}

		private static JSObject callGetWindow(Applet applet) {
			if (provider != null) {
				return provider.getWindow(applet);
			}
			return null;
		}
	}
}