Java tutorial
/******************************************************************************* * Copyright (c) 2008, 2018 IBM Corporation and others. * * This program and the accompanying materials * are made available under the terms of the Eclipse Public License 2.0 * which accompanies this distribution, and is available at * https://www.eclipse.org/legal/epl-2.0/ * * SPDX-License-Identifier: EPL-2.0 * * Contributors: * IBM Corporation - initial API and implementation *******************************************************************************/ package org.eclipse.swt.browser; import java.util.*; import org.eclipse.swt.*; /** * Instances of this class represent java-side "functions" that * are invokable from javascript. Browser clients define these * functions by subclassing <code>BrowserFunction</code> and * overriding its <code>function(Object[])</code> method. This * method will be invoked whenever javascript running in the * Browser makes a call with the function's name. * * <p> * Application code must explicitly invoke the * <code>BrowserFunction.dispose()</code> method to release the * resources managed by each instance when those instances are no * longer required. Since there is usually a correlation between * the registering of BrowserFunction(s) in a Browser and the * loading of a page in the Browser that is aware of these * functions, the <code>LocationListener.changed()</code> listener * is often a good place to do this. * </p><p> * Note that disposing a Browser automatically disposes all * BrowserFunctions associated with it. * </p> * * @see #dispose() * @see #function(Object[]) * @see org.eclipse.swt.browser.LocationListener#changed(LocationEvent) * * @since 3.5 */ public class BrowserFunction { Browser browser; String name; String functionString; int index; boolean isEvaluate, top; String token; String[] frameNames; /** * Constructs a new instance of this class, which will be invokable * by javascript running in the specified Browser. The function will * be accessible in the top-level window and all child frames. To * create a function with a reduced scope of accessibility use the * <code>BrowserFunction</code> constructor that accepts frame names * instead. * <p> * You must dispose the BrowserFunction when it is no longer required. * A common place to do this is in a <code>LocationListener.changed()</code> * listener. * </p> * @param browser the browser whose javascript can invoke this function * @param name the name that javascript will use to invoke this function * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the browser is null</li> * <li>ERROR_NULL_ARGUMENT - if the name is null</li> * </ul> * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the browser has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * * @see #dispose() * @see #BrowserFunction(Browser, String, boolean, String[]) * @see org.eclipse.swt.browser.LocationListener#changed(LocationEvent) */ public BrowserFunction(Browser browser, String name) { this(browser, name, true, null, true); } /** * Constructs a new instance of this class, which will be invokable * by javascript running in the specified Browser. The accessibility * of the function to the top-level window and its child frames is * determined by the <code>top</code> and <code>frameNames</code> * arguments. To create a function that is globally accessible to * the top-level window and all child frames use the * <code>BrowserFunction</code> constructor that does not accept frame * names instead. * <p> * You must dispose the BrowserFunction when it is no longer required. * A common place to do this is in a <code>LocationListener.changed()</code> * listener. * </p> * @param browser the browser whose javascript can invoke this function * @param name the name that javascript will use to invoke this function * @param top <code>true</code> if the function should be accessible to the * top-level window and <code>false</code> otherwise * @param frameNames the names of the child frames that the function should * be accessible in * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the browser is null</li> * <li>ERROR_NULL_ARGUMENT - if the name is null</li> * </ul> * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the browser has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * * @see #dispose() * @see #BrowserFunction(Browser, String) * @see org.eclipse.swt.browser.LocationListener#changed(LocationEvent) * * @since 3.8 */ public BrowserFunction(Browser browser, String name, boolean top, String[] frameNames) { this(browser, name, top, frameNames, true); } BrowserFunction(Browser browser, String name, boolean top, String[] frameNames, boolean create) { super(); if (browser == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); if (name == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); if (browser.isDisposed()) SWT.error(SWT.ERROR_WIDGET_DISPOSED); browser.checkWidget(); this.browser = browser; this.name = name; this.top = top; this.frameNames = frameNames; Random random = new Random(); byte[] bytes = new byte[16]; random.nextBytes(bytes); StringBuilder buffer = new StringBuilder(); for (int i = 0; i < bytes.length; i++) { buffer.append(Integer.toHexString(bytes[i] & 0xff)); } token = buffer.toString(); if (create) browser.webBrowser.createFunction(this); } /** * Disposes of the resources associated with this BrowserFunction. * Applications must dispose of all BrowserFunctions that they create. * <p> * Note that disposing a Browser automatically disposes all * BrowserFunctions associated with it. * </p> */ public void dispose() { dispose(true); } void dispose(boolean remove) { if (index < 0) return; if (remove) browser.webBrowser.destroyFunction(this); browser = null; name = functionString = null; index = -1; } /** * Subclasses should override this method. This method is invoked when * the receiver's function is called from javascript. If all of the * arguments that are passed to the javascript function call are of * supported types then this method is invoked with the argument values * converted as follows: * * javascript null or undefined -> <code>null</code> * javascript number -> <code>java.lang.Double</code> * javascript string -> <code>java.lang.String</code> * javascript boolean -> <code>java.lang.Boolean</code> * javascript array whose elements are all of supported types -> <code>java.lang.Object[]</code> * * If any of the javascript arguments are of unsupported types then the * function invocation will fail and this method will not be called. * * This method must return a value with one of these supported java types to * the javascript caller. Note that <code>null</code> values are converted * to javascript's <code>null</code> value (not <code>undefined</code>), and * instances of any <code>java.lang.Number</code> subclass will be converted * to a javascript number. * * @param arguments the javascript arguments converted to java equivalents * @return the value to return to the javascript caller * * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li> * <li>ERROR_FUNCTION_DISPOSED when the BrowserFunction has been disposed</li> * </ul> */ public Object function(Object[] arguments) { if (index < 0) SWT.error(SWT.ERROR_FUNCTION_DISPOSED); browser.checkWidget(); return null; } /** * Returns the Browser whose pages can invoke this BrowserFunction. * * @return the Browser associated with this BrowserFunction * * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li> * <li>ERROR_FUNCTION_DISPOSED when the BrowserFunction has been disposed</li> * </ul> */ public Browser getBrowser() { if (index < 0) SWT.error(SWT.ERROR_FUNCTION_DISPOSED); browser.checkWidget(); return browser; } /** * Returns the name that javascript can use to invoke this BrowserFunction. * * @return the BrowserFunction's name * * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li> * <li>ERROR_FUNCTION_DISPOSED when the BrowserFunction has been disposed</li> * </ul> */ public String getName() { if (index < 0) SWT.error(SWT.ERROR_FUNCTION_DISPOSED); browser.checkWidget(); return name; } /** * Returns <code>true</code> if this BrowserFunction has been disposed * and <code>false</code> otherwise. * <p> * This method gets the dispose state for the BrowserFunction. * When a BrowserFunction has been disposed it is an error to * invoke any of its methods. * </p><p> * Note that disposing a Browser automatically disposes all * BrowserFunctions associated with it. * </p> * @return <code>true</code> if this BrowserFunction has been disposed * and <code>false</code> otherwise */ public boolean isDisposed() { return index < 0; } }