Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.
`void` | `setBrowser(JRexCanvas browser, boolean useRootDocShell)` 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. This method initializes the JRexLiveConnectSession to only work with the document's primary content nsIDocShell.

  Parameters:
    `browser` - the JRexCanvas, which must already be initialized
  Throws:
    `JRexException` - if an error occurs while initializing live connect
  See Also:
    `setBrowser(JRexCanvas, boolean)`

### setBrowser

    public void setBrowser(JRexCanvas browser,
                           boolean useRootDocShell)
                    throws JRexException

  Sets the browser and intializes live connect for the browser. This method also lets you speicfy whether or not to use the root doc shell, or the primary content doc shell.

  Parameters:
    `browser` - the JRexCanvas, which must already be initialized
    `useRootDocShell` - if `true`, then the document's root nsIDocShell is used. If `false`, then the nsIDocShell for the primary content is used. If using JRexLiveConnectSession on a XUL window, and you want to invoke javascript on the XUL top-level window, this argument must be `true`. Otherwise, if you have an html document, or you only want to use JRexLiveConnectSession on the primary content, set this argument to `False`. Note that the primary content in a XUL window is the browser or editor tagged with "content-primary".
  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()`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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