org.mozilla.jrex.liveconnect
Interface JRexLiveConnectSession

All Known Implementing Classes:
JRexLiveConnectSessionImpl

public interface JRexLiveConnectSession

LiveConnect support for JRex. JRexLiveConnectSession provides a LiveConnect bridge between the JREX JVM and javascript.

Usage

JRexLiveConnectSession should only be used on a browser loaded with a web page you trust. This is because the web page will have unrestricted access to the JRex JVM. A typical usage of JRexLiveConnectSession is to use it with a custom XUL app or html page that is owned by the application.

To get LiveConnect support for JRex, be sure to edit JRex.properties and set "jrex.liveconnect" to 1 before compiling. To create an instance of JRexLiveConnectSession, create an instance of the class JRexLiveConnectSessionImpl. Before you can use JRexLiveConnectSession, first set the JRexCanvas using the method setBrowser(org.mozilla.jrex.ui.JRexCanvas). Alternatively, you can pass the browser to the constructor for JRexLiveConnectSessionImpl.

The method invokeStringMethod(java.lang.String, java.lang.String) is provided as a simple javascript invocation. This method is used for testing. Most often the caller will want to obtain the JSObject using the method getJSWindow() and evaluate javascript using it. For example, invoking getJSObject().eval("1+1+2") will return a java.lang.Double object with the value 4.

Note that JRex defines its own JSObject class. It is important to make sure JRex's JSObject class is loaded instead of the sun plugin's JSObject class. To be sure of this, always put plugin.jar after JRex.jar in the classpath.

Security

By default the JRexCanvas is untrusted and therefore the javascript cannot create or access java objects in the JRex JVM. This is done to safegaurd against a malicious javascript application.

The method grantBrowserAccessToJVM() is used to let JRexLiveConnectSession know that it is ok for the browser to create and access java objects in the JRex JVM. This method must be called before the method getJSWindow() is called. This method exists for the case that a browser window is loaded that is not trusted. In this case, all the methods of JRexLiveConnectSession will work expect for getJSWindow(). Only call the method grantBrowserAccessToJVM() if the browser is trusted by your java application.

Testing

See test.liveconnect.JRexLiveConnectSessionUnitTest for unit tests. This class also serves as an example of using JRexLiveConnectSession.

JDK Compatibility

JRexLiveConnectSession has been tested on Windows and Linux using jdk 1.4.2 and jdk 1.5.0. On Windows, it is recommended that jdk 1.5.0 be used if java plugins are going to be run.

See Also:
JRexLiveConnectSessionImpl, test.liveconnect.JRexLiveConnectSessionUnitTest

Method Summary
 String evalUntrusted(String script)
          Evaluates javascript in the browser.
 netscape.javascript.JSObject getJSWindow()
          Retrieves a JSObject implementation for the JRexCanvas window.
 void grantBrowserAccessToJVM()
          Makes the LiveConnectSession a 2-way session.
 String invokeStringMethod(String functionName, String arg)
          Invokes a javascript method which accepts a single string and returns a string.
 void setBrowser(JRexCanvas browser)
          Sets the browser and intializes live connect for the browser.
 

Method Detail

setBrowser

public void setBrowser(JRexCanvas browser)
                throws JRexException
Sets the browser and intializes live connect for the browser.

Parameters:
browser - the JRexCanvas, which must already be initialized
Throws:
JRexException - if an error occurs while initializing live connect

grantBrowserAccessToJVM

public void grantBrowserAccessToJVM()
                             throws JRexException
Makes the LiveConnectSession a 2-way session. Before this method is called, the LiveConnect session is only one-way, meaning that Java can call into javascript using any of the methods defined in this interface except for getJSWindow(). After this method is invoked, the javascript will be able to create java objects and invoke methods on those objects, and the caller will be able to use the method getJSWindow() to retrieve the JSObject instance for the javascript window.

Only call this method if the web page loaded into the JRexCanvas is trusted.

Throws:
JRexException - if an error occurs while granting access to the JRex JVM

invokeStringMethod

public String invokeStringMethod(String functionName,
                                 String arg)
                          throws JRexException
Invokes a javascript method which accepts a single string and returns a string. This method is provided as a simple way of invoking a javascript method and is useful for testing the JRexLiveConnectSession code. Note that for more complex javascript evaulations, the method evalUntrusted(java.lang.String) should be used for untrusted javascript, and the JSObject class returned from getJSWindow() should be used for trusted javascript.

Parameters:
functionName - the name of the javascript function
arg - the argument to pass to the javascript function
Returns:
the result from the javascript function call, or null if the call failed
Throws:
JRexException - if an error occurs while invoking the javascript
See Also:
getJSWindow()

evalUntrusted

public String evalUntrusted(String script)
                     throws JRexException
Evaluates javascript in the browser. This method will evaluate unstrusted javascript and return the string result. If the javascript is trusted, it is better to call grantBrowserAccessToJVM() followed by getJSWindow() and invoke the eval method on the JSObject instance. Only use this method if the javascript is not trusted.

Parameters:
script - the javascript to evaluate
Returns:
the result of the evaulation as a string
Throws:
JRexException - if an error occurs while evaulating

getJSWindow

public netscape.javascript.JSObject getJSWindow()
                                         throws JRexException,
                                                SecurityException
Retrieves a JSObject implementation for the JRexCanvas window. The return JSObject can be used to make function calls and evaluate javascript. This method must be invoked after the document has been fully loaded into the browser. Failure to do so will result in unexpected errors.

Note that this method will throw a security violation exception unless the method grantBrowserAccessToJVM() is invoked before this method. Make sure to invoke grantBrowserAccessToJVM() before invoking this method.

Returns:
a JSObject for invoking and manipulating javascript
Throws:
JRexException - if an error prevents the JSObject from being created
SecurityException - if grantBrowserAccessToJVM has not been called yet
See Also:
grantBrowserAccessToJVM()


Copyright © 2004 C.N.Medappa. All Rights Reserved.