Package org.web3d.x3d.sai

Interface ExternalBrowser

public interface ExternalBrowser

Abstract node interface, defined by X3D Java Scene Access Interface (SAI) Specification to support X3D Java interoperability.

Warning: this is an abstract interface that cannot be instantiated as a concrete object. Java programmers typically only need to use concrete objects provided by the org.web3d.x3d.jsail classes.
Package hint: This interface is defined by the X3D Java Language Binding Specification for the Scene Authoring Interface (SAI).

Browser interface that represents the additional abilities an external application is granted to the X3D 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:

See Also:

• SAI Java Specification: B.5.2 BrowserFactory
• X3D Tooltips: ExternalBrowser
• X3D Scene Authoring Hints

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 X3D browser.
void	removeBrowserListener(BrowserListener l)	Remove a listener for browser events.

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 X3D 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 X3D 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 X3D browser. All events posted to this point from the last time that beginUpdate was called are released into the X3D 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 X3D 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.