org.web3d.vrml.scripting.external.eai
Class EAIBrowser

java.lang.Object
  org.web3d.vrml.scripting.external.eai.EAIBrowser

All Implemented Interfaces:

BrowserCoreListener, Browser

public class EAIBrowser
extends java.lang.Object
implements Browser, BrowserCoreListener

EAIBrowser implements the Browser interface, largely by translating and interfacing between the wrapper classes and the implementation class represented by {org.web3d.vrml.scripting.CommonBrowser}.

To function correctly, EAIBrowser needs to be constructed using CommonBrowser and BrowserCore instances. The EAIBrowser then registers as a listener so that BrowserCoreListener BrowserInitialized and browserShutdown messages. The BrowserCore instance is necessary mainly for the global namespace and VRMLExecutionSpace information.

Version:

$Revision: 1.18 $

Author:

Brad Vender

Constructor Summary

EAIBrowser(BrowserCore browserCore, VRML97CommonBrowser browserImpl, ExternalEventQueue eventQueue, ErrorReporter reporter)
Construct an EAIBrowser for the given VrmlDisplayPanel

Method Summary

void	addBrowserListener(BrowserListener theListener) addBrowserListener adds the specified listener to the set of listeners for this browser.
void	addRoute(Node fromNode, java.lang.String fromEventName, Node toNode, java.lang.String toEventName) Add a route between two nodes, from an eventOut to an eventIn.
void	beginUpdate() Lock the output from the external interface to the browser as the code is about to begin a series of updates.
void	browserDisposed() The browser has been disposed, all resources may be freed.
void	browserInitialized(VRMLScene newScene) The browser has been initialised with new content.
void	browserShutdown() The browser has been shut down and the previous content is no longer valid.
Node[]	createVrmlFromString(java.lang.String string) Parse the given string and turn this into a list of VRML nodes.
void	createVrmlFromURL(java.lang.String[] urls, Node targetNode, java.lang.String eventInName) Create and load VRML from the given URL and place the returned values as nodes into the given VRML node in the scene.
void	deleteRoute(Node fromNode, java.lang.String fromEventName, Node toNode, java.lang.String toEventName) Delete a route between two nodes.
void	dispose() Clean up and get rid of this browser.
void	endUpdate() Release the output of events from the external interface into the VRML browser.
float	getCurrentFrameRate() Get the current frame rate of the browser in frames per second.
float	getCurrentSpeed() Get the current velocity of the bound viewpoint in meters per second.
java.lang.String	getName() Returns the name of the Browser.
Node	getNode(java.lang.String nodeName) Get a DEF node by name.
java.lang.String	getVersion() Returns the version string for this Browser.
java.lang.String	getWorldURL() Get the fully qualified URL of the currently loaded world.
void	initializeWorld() Initialize the world to a known and default state.
void	loadURL(java.lang.String[] urls, java.lang.String[] params) Load the URL as the new root of the scene.
void	removeBrowserListener(BrowserListener listener) removeBrowserListener removes the specified listener from the set of listeners for this browser.
void	replaceWorld(Node[] nodes) Replace the current world with the given nodes.
void	setDescription(java.lang.String newDescription) Set the description of the current world.
void	urlLoadFailed(java.lang.String msg) The tried to load a URL and failed.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EAIBrowser

public EAIBrowser(BrowserCore browserCore,
                  VRML97CommonBrowser browserImpl,
                  ExternalEventQueue eventQueue,
                  ErrorReporter reporter)

Construct an EAIBrowser for the given VrmlDisplayPanel

Parameters:

browserCore - The BrowserCore to use as the implementation.

browserImpl - The VRML97CommonBrowser to use.

eventQueue - The queue for sending events to the internals.

reporter - The ErrorReporter for messages and errors.

Method Detail

getName

public java.lang.String getName()
                         throws InvalidBrowserException

Returns the name of the Browser.

Specified by:

getName in interface Browser

Returns:

The name of the Browser

Throws:

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

See Also:

Browser.getName()

getVersion

public java.lang.String getVersion()
                            throws InvalidBrowserException

Returns the version string for this Browser.

Specified by:

getVersion in interface Browser

Returns:

The version string for this Browser

Throws:

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

See Also:

Browser.getVersion()

getCurrentSpeed

public float getCurrentSpeed()
                      throws InvalidBrowserException

Description copied from interface: Browser

Get the current velocity of the bound viewpoint in meters per second. The velocity is defined in terms of the world values, not the local coordinate system of the viewpoint.

Specified by:

getCurrentSpeed in interface Browser

Returns:

The velocity in m/s or 0.0 if not supported

Throws:

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

See Also:

Browser.getCurrentSpeed()

getCurrentFrameRate

public float getCurrentFrameRate()
                          throws InvalidBrowserException

Description copied from interface: Browser

Get the current frame rate of the browser in frames per second.

Specified by:

getCurrentFrameRate in interface Browser

Returns:

The current frame rate or 0.0 if not supported

Throws:

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

See Also:

Browser.getCurrentFrameRate()

getWorldURL

public java.lang.String getWorldURL()
                             throws InvalidBrowserException,
                                    URLUnavailableException

Description copied from interface: Browser

Get the fully qualified URL of the currently loaded world. This returns the entire URL including any possible arguments that might be associated with a CGI call or similar mechanism. If the initial world is replaced with loadURL then the string will reflect the new URL. If replaceWorld is called then the URL still represents the original world.

Specified by:

getWorldURL in interface Browser

Returns:

A string of the URL or null if not supported.

Throws:

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

URLUnavailableException - The URL is not available because a world has not been loaded

See Also:

Browser.getWorldURL()

replaceWorld

public void replaceWorld(Node[] nodes)
                  throws java.lang.IllegalArgumentException,
                         InvalidBrowserException

Description copied from interface: Browser

Replace the current world with the given nodes. Replaces the entire contents of the VRML world with the new nodes. Any node references that belonged to the previous world are still valid but no longer form part of the scene graph (unless it is these nodes passed to this method). The URL of the world still represents the just unloaded world.

Calling this method causes a SHUTDOWN event followed by an INITIALIZED event to be generated.

Specified by:

replaceWorld in interface Browser

Parameters:

nodes - The list of nodes to use as the new root of the world

Throws:

java.lang.IllegalArgumentException - if the nodes are not valid VRML nodes

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

See Also:

Browser.replaceWorld(vrml.eai.Node[])

loadURL

public void loadURL(java.lang.String[] urls,
                    java.lang.String[] params)
             throws InvalidBrowserException,
                    InvalidURLException

Description copied from interface: Browser

Load the URL as the new root of the scene. Replaces all the current scene graph with the new world. A non-blocking call that will change the contents at some time in the future.

Generates an immediate SHUTDOWN event and then when the new contents are ready to be loaded, sends an INITIALIZED event.

Specified by:

loadURL in interface Browser

Parameters:

urls - The list of URLs in decreasing order of preference as defined in the VRML97 specification.

params - The list of parameters to accompany the load call as defined in the Anchor node specification of VRML97

Throws:

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

InvalidURLException - All of the URLs passed to this method are bogus and cannot be translated to usable values

See Also:

Browser.loadURL(java.lang.String[], java.lang.String[])

setDescription

public void setDescription(java.lang.String newDescription)
                    throws InvalidBrowserException

Description copied from interface: Browser

Set the description of the current world. If the world is operating as part of a web browser then it shall attempt to set the title of the window. If the browser is from a component then the result is dependent on the implementation

Specified by:

setDescription in interface Browser

Parameters:

newDescription - The description string to set.

Throws:

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

See Also:

Browser.setDescription(java.lang.String)

createVrmlFromString

public Node[] createVrmlFromString(java.lang.String string)
                            throws InvalidBrowserException,
                                   InvalidVrmlException

Description copied from interface: Browser

Parse the given string and turn this into a list of VRML nodes. Method is a blocking call that won't return until all of the top level nodes defined in the string have been returned.

At the point that this method returns, external files such as textures, sounds and inlines may not have been loaded.

The string may contain all legal VRML syntax. The VRML header line is not required to be present in the string.

Specified by:

createVrmlFromString in interface Browser

Parameters:

string - The string containing VRML string syntax

Returns:

A list of the top level nodes in VRML representation as defined in the parameter

Throws:

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

InvalidVrmlException - If the string does not contain legal VRML syntax or no node instantiations

See Also:

Browser.createVrmlFromString(java.lang.String)

createVrmlFromURL

public void createVrmlFromURL(java.lang.String[] urls,
                              Node targetNode,
                              java.lang.String eventInName)
                       throws InvalidBrowserException,
                              InvalidNodeException,
                              InvalidURLException,
                              InvalidEventInException

Description copied from interface: Browser

Create and load VRML from the given URL and place the returned values as nodes into the given VRML node in the scene. The difference between this and loadURL is that this method does not replace the entire scene with the contents from the URL. Instead, it places the return values as events in the nominated node and MFNode eventIn.

Specified by:

createVrmlFromURL in interface Browser

Parameters:

urls - The list of URLs in decreasing order of preference as defined in the VRML97 specification.

targetNode - The destination node for the VRML code to be sent to.

eventInName - The name of the MFNode eventIn to send the nodes to.

Throws:

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

InvalidNodeException - The nominated destination node has been disposed of

InvalidURLException - All of the URLs passed to this method are bogus and cannot be translated to usable values

InvalidEventInException

See Also:

Browser.createVrmlFromURL(java.lang.String[], vrml.eai.Node, java.lang.String)

getNode

public Node getNode(java.lang.String nodeName)
             throws InvalidNodeException,
                    InvalidBrowserException,
                    URLUnavailableException

Description copied from interface: Browser

Get a DEF node by name. Nodes given DEF names in the root scene graph are available to be retrieved by this method. DEFed nodes in Inlines, createVrmlFromString and createVrmlFromURL are not available.

Specified by:

getNode in interface Browser

Parameters:

nodeName - The name of the DEF node to retrieve

Returns:

A reference to that node

Throws:

InvalidNodeException - The named node does not exist or is not accessible.

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

URLUnavailableException - The URL is not available because a world has not been loaded

See Also:

Browser.getNode(java.lang.String)

addRoute

public void addRoute(Node fromNode,
                     java.lang.String fromEventName,
                     Node toNode,
                     java.lang.String toEventName)
              throws InvalidBrowserException,
                     InvalidEventOutException,
                     InvalidEventInException,
                     InvalidNodeException

Description copied from interface: Browser

Add a route between two nodes, from an eventOut to an eventIn. If the ROUTE already exists, this method silently exits. It does not attempt to add a second parallel ROUTE.

Specified by:

addRoute in interface Browser

Parameters:

fromNode - The source node for the route

fromEventName - The eventOut source of the route

toNode - The destination node of the route

toEventName - The eventIn destination of the route

Throws:

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

InvalidEventOutException - if the named eventOut does not exist

InvalidEventInException - if the named eventIn does not exist.

InvalidNodeException - The nominated destination or source node has been disposed of

See Also:

Browser.addRoute(vrml.eai.Node, java.lang.String, vrml.eai.Node, java.lang.String)

deleteRoute

public void deleteRoute(Node fromNode,
                        java.lang.String fromEventName,
                        Node toNode,
                        java.lang.String toEventName)
                 throws InvalidBrowserException,
                        InvalidEventOutException,
                        InvalidEventInException,
                        InvalidNodeException

Description copied from interface: Browser

Delete a route between two nodes. If the route does not exist, the method silently exits.

Specified by:

deleteRoute in interface Browser

Parameters:

fromNode - The source node for the route

fromEventName - The eventOut source of the route

toNode - The destination node of the route

toEventName - The eventIn destination of the route

Throws:

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

InvalidEventOutException - if the named eventOut does not exist

InvalidEventInException - if the named eventIn does not exist.

InvalidNodeException - The nominated destination or source node has been disposed of

See Also:

Browser.deleteRoute(vrml.eai.Node, java.lang.String, vrml.eai.Node, java.lang.String)

beginUpdate

public void beginUpdate()
                 throws InvalidBrowserException

Description copied from interface: Browser

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.

Specified by:

beginUpdate in interface Browser

Throws:

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

See Also:

Browser.beginUpdate()

endUpdate

public void endUpdate()
               throws InvalidBrowserException

Description copied from interface: Browser

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 oppourtunity.

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.

Specified by:

endUpdate in interface Browser

Throws:

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

See Also:

Browser.endUpdate()

addBrowserListener

public void addBrowserListener(BrowserListener theListener)
                        throws InvalidBrowserException

addBrowserListener adds the specified listener to the set of listeners for this browser.

Specified by:

addBrowserListener in interface Browser

Parameters:

theListener - The listener to add to the list of listeners for this browser

Throws:

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

removeBrowserListener

public void removeBrowserListener(BrowserListener listener)
                           throws InvalidBrowserException

removeBrowserListener removes the specified listener from the set of listeners for this browser.

Specified by:

removeBrowserListener in interface Browser

Parameters:

listener - The listener to remove from the list.

Throws:

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

browserInitialized

public void browserInitialized(VRMLScene newScene)

Description copied from interface: BrowserCoreListener

The browser has been initialised with new content. The content given is found in the accompanying scene and description.

Specified by:

browserInitialized in interface BrowserCoreListener

Parameters:

newScene - The scene of the new content

See Also:

BrowserCoreListener.browserInitialized(org.web3d.vrml.nodes.VRMLScene)

urlLoadFailed

public void urlLoadFailed(java.lang.String msg)

The tried to load a URL and failed. It is typically because none of the URLs resolved to anything valid or there were network failures.

Specified by:

urlLoadFailed in interface BrowserCoreListener

Parameters:

msg - An error message to go with the failure

browserShutdown

public void browserShutdown()

Description copied from interface: BrowserCoreListener

The browser has been shut down and the previous content is no longer valid.

Specified by:

browserShutdown in interface BrowserCoreListener

See Also:

BrowserCoreListener.browserShutdown()

browserDisposed

public void browserDisposed()

The browser has been disposed, all resources may be freed.

Specified by:

browserDisposed in interface BrowserCoreListener

dispose

public void dispose()

Clean up and get rid of this browser. When this method is called, the event queue will be processed, the browser will shut down, and any subsequent calls to browser methods (except getName() and getVersion()) will result in InvalidBrowserException's being generated.

Since this version does not support sharing between clients, shutdown also initiates the termination of the Xj3D to EAI event adapter system.

Specified by:

dispose in interface Browser

initializeWorld

public void initializeWorld()

Initialize the world to a known and default state. The initialization is done so that the event model and other internals of the system will be functioning, and to prevent special cases in the various event buffering routines. Since the event buffering routines are assumed to not be functioning, this method calls down to the VRML97CommonBrowser directly.