Package org.web3d.x3d.sai

Interface ExternalBrowser

All Superinterfaces:

Browser

All Known Subinterfaces:

Xj3DBrowser

All Known Implementing Classes:

SAIBrowser

public interface ExternalBrowser
extends Browser

Browser interface that represents the additional abilities an external application is granted to the VRML browser.

A number of the methods in this application can take strings representing URLs. Relative URL strings contained in URL fields of nodes or these method arguments are interpreted as follows:

Relative URLs are treated as per clause B.3.5 of the EAI Java Bindings

Version:

$Revision: 1.4 $

Author:

Justin Couch

Method Summary

Modifier and Type	Method	Description
void	addBrowserListener(BrowserListener l)	Add a listener for browser events.
void	beginUpdate()	Lock the output from the external interface to the browser as the code is about to begin a series of updates.
void	dispose()	Dispose the resources that are used by this instance.
void	endUpdate()	Release the output of events from the external interface into the VRML browser.
void	removeBrowserListener(BrowserListener l)	Remove a listener for browser events.

Methods inherited from interface org.web3d.x3d.sai.Browser

createScene, createX3DFromStream, createX3DFromString, createX3DFromURL, firstViewpoint, firstViewpoint, getBrowserProperties, getComponentInfo, getCurrentFrameRate, getCurrentSpeed, getDescription, getExecutionContext, getName, getProfile, getRenderingProperties, getSupportedComponents, getSupportedProfiles, getVersion, importDocument, lastViewpoint, lastViewpoint, loadURL, nextViewpoint, nextViewpoint, previousViewpoint, previousViewpoint, print, println, replaceWorld, setDescription

Method Details

beginUpdate

void beginUpdate()
          throws InvalidBrowserException

Lock the output from the external interface to the browser as the code is about to begin a series of updates. No events will be passed to the VRML world. They will be buffered pending release due to a subsequent call to endUpdate.

This call is a nesting call which means subsequent calls to beginUpdate are kept on a stack. No events will be released to the VRML browser until as many endUpdates have been called as beginUpdate.

Throws:

InvalidBrowserException - The dispose method has been called on this browser reference.

ConnectionException - An error occurred in the connection to the browser.

endUpdate

void endUpdate()
        throws InvalidBrowserException

Release the output of events from the external interface into the VRML browser. All events posted to this point from the last time that beginUpdate was called are released into the VRML browser for processing at the next available opportunity.

This call is a nesting call which means subsequent calls to beginUpdate are kept on a stack. No events will be released to the VRML browser until as many endUpdates have been called as beginUpdate.

If no beginUpdate has been called before calling this method, it has no effect.

Throws:

InvalidBrowserException - The dispose method has been called on this browser reference.

ConnectionException - An error occurred in the connection to the browser.

addBrowserListener

void addBrowserListener(BrowserListener l)
                 throws InvalidBrowserException

Add a listener for browser events. Any changes in the browser will be sent to this listener. The order of calling listeners is not guaranteed. Checking is performed on whether the nominated listener is already registered to ensure that multiple registration cannot take place. Therefore it is possible to multiply register the one class instance while only receiving one event.

Parameters:

l - The listener to add.

Throws:

NullPointerException - If the provided listener reference is null

InvalidBrowserException - The dispose method has been called on this browser reference.

ConnectionException - An error occurred in the connection to the browser.

removeBrowserListener

void removeBrowserListener(BrowserListener l)
                    throws InvalidBrowserException

Remove a listener for browser events. After calling this method, the listener will no longer receive events from this browser instance. If the listener passed as an argument is not currently registered, the method will silently exit.

Parameters:

l - The listener to remove

Throws:

NullPointerException - If the provided listener reference is null

InvalidBrowserException - The dispose method has been called on this browser reference.

ConnectionException - An error occurred in the connection to the browser.

dispose

void dispose()

Dispose the resources that are used by this instance. Should be called just prior to leaving the application. When this method is called, the event queue will be processed, the browser will shut down, and any subsequent calls to browser methods will result in InvalidBrowserException's being generated.