vrml.eai
Interface Browser

All Known Implementing Classes:

EAIBrowser

public interface Browser

Basic browser interface that represents the interface to the VRML browser from any application. Individual VRML browser implementors are to extend this interface and provide this functionality. The individual users will not see anything but this interface.

A number of the methods in this applicationcan 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:

1.1 25 April 1998

Method Summary

void	addBrowserListener(BrowserListener l) Add a listener for browser events.
void	addRoute(Node fromNode, java.lang.String eventOut, Node toNode, java.lang.String eventIn) 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.
Node[]	createVrmlFromString(java.lang.String vrmlString) Parse the given string and turn this into a list of VRML nodes.
void	createVrmlFromURL(java.lang.String[] url, Node node, java.lang.String eventIn) 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 eventOut, Node toNode, java.lang.String eventIn) Delete a route between two nodes.
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.
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() Get the name of the browser.
Node	getNode(java.lang.String name) Get a DEF node by name.
java.lang.String	getVersion() Get the version of the browser.
java.lang.String	getWorldURL() Get the fully qualified URL of the currently loaded world.
void	loadURL(java.lang.String[] url, java.lang.String[] parameter) Load the URL as the new root of the scene.
void	removeBrowserListener(BrowserListener l) Remove a listener for browser events.
void	replaceWorld(Node[] nodes) Replace the current world with the given nodes.
void	setDescription(java.lang.String desc) Set the description of the current world.

Method Detail

getName

public java.lang.String getName()
                         throws InvalidBrowserException

Get the name of the browser. The name is an implementation specific string representing the browser.

Returns:

The name of the browser or null if not supported

Throws:

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

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

getVersion

public java.lang.String getVersion()
                            throws InvalidBrowserException

Get the version of the browser. Returns an implementation specific representation of the version number.

Returns:

The version of the browser or null if not supported

Throws:

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

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

getCurrentSpeed

public float getCurrentSpeed()
                      throws InvalidBrowserException

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.

Returns:

The velocity in m/s or 0.0 if not supported

Throws:

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

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

getCurrentFrameRate

public float getCurrentFrameRate()
                          throws InvalidBrowserException

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

Returns:

The current frame rate or 0.0 if not supported

Throws:

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

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

getWorldURL

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

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.

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

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

See Also:

loadURL(java.lang.String[], java.lang.String[]), replaceWorld(vrml.eai.Node[])

replaceWorld

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

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.

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.

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

loadURL

public void loadURL(java.lang.String[] url,
                    java.lang.String[] parameter)
             throws InvalidBrowserException,
                    InvalidURLException

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.

Parameters:

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

parameter - 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

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

setDescription

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

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

Parameters:

desc - The description string to set.

Throws:

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

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

createVrmlFromString

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

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.

Parameters:

vrmlString - The string containing VRML string syntax

Returns:

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

Throws:

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

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

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

createVrmlFromURL

public void createVrmlFromURL(java.lang.String[] url,
                              Node node,
                              java.lang.String eventIn)
                       throws InvalidBrowserException,
                              InvalidNodeException,
                              InvalidURLException

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.

Parameters:

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

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

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

Throws:

InvalidNodeException - The nominated destination node has been disposed of

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

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

getNode

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

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.

Parameters:

name - 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

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

addRoute

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

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.

Parameters:

fromNode - The source node for the route

eventOut - The eventOut source of the route

toNode - The destination node of the route

eventIn - The eventIn destination of the route

Throws:

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

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

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

deleteRoute

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

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

Parameters:

fromNode - The source node for the route

eventOut - The eventOut source of the route

toNode - The destination node of the route

eventIn - The eventIn destination of the route

Throws:

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

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

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

beginUpdate

public 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

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

Throws:

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

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

addBrowserListener

public 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 guarenteed. 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:

java.lang.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

public void removeBrowserListener(BrowserListener l)
                           throws InvalidBrowserException

Remove a listener for browser events. After calling this method, the listener will no longer recieve 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:

java.lang.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

public void dispose()

Dispose the resources that are used by this instance. Should be called just prior to leaving the application.