vrml.eai
Interface Browser

public interface Browser

Reference to a Browser instance. The Browser object is the central interface to the X3D browser and the scene currently displayed by the browser. You cannot create instances of this interface directly, instead you have to use one of the methods of the BrowserFactory class.

When you do not need the Browser object anymore, you should call its dispose method to release all resources as soon as possible.

The following example demonstrates how to create a new instance of the Browser interface:

 java.net.InetAddress address = java.net.InetAddress.getByName("localhost");
 vrml.eai.Browser browser = vrml.eai.BrowserFactory.getBrowser(address, 4848);
 ...
 browser.dispose();
 

Method Summary

void	addBrowserListener(BrowserListener l) Adds a listener to the browser.
void	addRoute(Node fromNode, java.lang.String eventOut, Node toNode, java.lang.String eventIn) Creates a new route.
void	beginUpdate() Starts scene update.
Node[]	createVrmlFromString(java.lang.String vrmlString) Creates new nodes from a VRML source string.
void	createVrmlFromURL(java.lang.String[] url, Node node, java.lang.String eventIn) Creates new nodes from an URL.
void	deleteRoute(Node fromNode, java.lang.String eventOut, Node toNode, java.lang.String eventIn) Removes a route.
void	dispose() Releases all resources held by this browser object.
void	endUpdate() Stops scene update.
float	getCurrentFrameRate() Returns the current frame rate.
float	getCurrentSpeed() Returns the current navigation speed.
java.lang.String	getName() Returns the name of the X3D browser.
Node	getNode(java.lang.String name) Returns a named node.
java.lang.String	getVersion() Returns the version of the X3D browser.
java.lang.String	getWorldURL() Returns the URL of the scene currently loaded.
void	loadURL(java.lang.String[] url, java.lang.String[] parameter) Loads a new scene.
void	removeBrowserListener(BrowserListener l) Removes a listener from the browser.
void	replaceWorld(Node[] nodes) Replaces the currently loaded scene with the given nodes.
void	setDescription(java.lang.String desc) Sets the description of the current scene.

Method Detail

getName

java.lang.String getName()
                         throws InvalidBrowserException,
                                ConnectionException

Returns the name of the X3D browser. The contents of this string are unspecified and browser-specific.

The following example prints the name of the browser to the console:

 vrml.eai.Browser browser = ...;
 System.out.println("Browser.Name = \"" + browser.getName() + '"');
 

Returns:

The name of the X3D browser.

Throws:

InvalidBrowserException - when you try to call this method after calling the dispose method.

ConnectionException - when the connection to the browser failed.

getVersion

java.lang.String getVersion()
                            throws InvalidBrowserException,
                                   ConnectionException

Returns the version of the X3D browser. The contents of this string are unspecified and browser-specific.

The following example prints the version of the browser to the console:

 vrml.eai.Browser browser = ...;
 System.out.println("Browser.Version = \"" + browser.getVersion() + '"');
 

Returns:

The version of the X3D browser.

Throws:

InvalidBrowserException - when you try to call this method after calling the dispose method.

ConnectionException - when the connection to the browser failed.

getCurrentSpeed

float getCurrentSpeed()
                      throws InvalidBrowserException,
                             ConnectionException

Returns the current navigation speed. This is the speed of the currently bound Viewpoint, in units per second. This can be 0 when the browser does not support to provide this information.

The following example prints the current navigation speed to the console:

 vrml.eai.Browser browser = ...;
 System.out.println("Browser.CurrentSpeed = " + browser.getCurrentSpeed());
 

Returns:

The current navigation speed.

Throws:

InvalidBrowserException - when you try to call this method after calling the dispose method.

ConnectionException - when the connection to the browser failed.

getCurrentFrameRate

float getCurrentFrameRate()
                          throws InvalidBrowserException,
                                 ConnectionException

Returns the current frame rate. This is the rendering speed, in frames per second. This can be 0 when the browser does not support to provide this information.

The following example prints the current frame rate to the console:

 vrml.eai.Browser browser = ...;
 System.out.println("Browser.CurrentFrameRate = " + browser.getCurrentFrameRate());
 

Returns:

The current frame rate

Throws:

InvalidBrowserException - when you try to call this method after calling the dispose method.

ConnectionException - when the connection to the browser failed.

getWorldURL

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

Returns the URL of the scene currently loaded.

The following example prints the URL of the currently loaded 3D scene to the console:

 vrml.eai.Browser browser = ...;
 System.out.println("Browser.WorldURL = \"" + browser.getWorldURL() + '"');
 

Returns:

The URL of the scene currently loaded.

Throws:

InvalidBrowserException - when you try to call this method after calling the dispose method.

URLUnavailableException - when there is no URL available.

ConnectionException - when the connection to the browser failed.

replaceWorld

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

Replaces the currently loaded scene with the given nodes.

The following example demonstrates how to replace the currently loaded scene with a box:

 vrml.eai.Browser browser = ...;
 vrml.eai.Node[] nodes = browser.createVrmlFromString("Shape { geometry Box {} }");
 browser.replaceWorld(nodes);
 

Parameters:

nodes - The nodes of the new scene.

Throws:

java.lang.IllegalArgumentException - when the nodes parameter does not contain valid Node objects.

InvalidBrowserException - when you try to call this method after calling the dispose method.

ConnectionException - when the connection to the browser failed.

loadURL

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

Loads a new scene.

The following example demonstrates how to load a scene "Scene.wrl" from the current working directory:

 vrml.eai.Browser browser = ...;
 String[] url = { "Scene.wrl" };
 String[] param = new String[0];
 browser.loadURL(url, param);
 

Parameters:

url - URLs that contain the new scene. The browser consecutively tries to load the scene from these URLs. It stops as soon as a download succeeds.

parameter - Contains additional information to be interpreted by the browser. Each string shall consist of "key=value" pairs. The VRML standard does not specify any of these parameters, so all parameters are browser-specific.

Throws:

InvalidBrowserException - when you try to call this method after calling the dispose method.

InvalidURLException - when you specified an invalid URL for the "url" parameter.

ConnectionException - when the connection to the browser failed.

setDescription

void setDescription(java.lang.String desc)
                    throws InvalidBrowserException,
                           ConnectionException

Sets the description of the current scene. What the browser actually does with the description is implementation-specific. Usually, the description is printed somewhere in the browser GUI or in the title of the browser window.

The following example demonstrates how to set the description of the currently loaded scene:

 vrml.eai.Browser browser = ...;
 browser.setDescription("Hello World!");
 

Parameters:

desc - The description.

Throws:

InvalidBrowserException - when you try to call this method after calling the dispose method.

ConnectionException - when the connection to the browser failed.

createVrmlFromString

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

Creates new nodes from a VRML source string. The newly created nodes are not part of the scene graph, i.e. you have to call the replaceWorld(vrml.eai.Node[]) method, or you have to send them to an EventInSFNode or EventInMFNode event-in slot before they show any effect.

The following example demonstrates how to create a box shape:

 vrml.eai.Browser browser = ...;
 vrml.eai.Node[] nodes = browser.createVrmlFromString("Shape { geometry Box {} }");
 browser.replaceWorld(nodes);
 

Parameters:

vrmlString - A string in VRML (classic) encoding that contains a textual representation of the nodes and their fields.

Returns:

The root nodes of the scene.

Throws:

InvalidVrmlException - when the "vrmlString" parameter does not contain valid, classic VRML code.

InvalidBrowserException - when you try to call this method after calling the dispose method.

ConnectionException - when the connection to the browser failed.

createVrmlFromURL

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

Creates new nodes from an URL. This method works asynchronously, i.e. it returns immediately without waiting for the actual download. As soon as the new nodes are available, they're sent to an EventInMFNode event-in slot.

The following example demonstrates how to create new nodes from the file "Subscene.wrl" in the current working directory and send them to the addChildren event-in slot of a Group node:

 vrml.eai.Browser browser = ...;
 vrml.eai.Node group = ...;
 String[] urls = { "Subscene.wrl" };
 browser.createVrmlFromURL(urls, group, "addChildren");
 

Parameters:

url - URLs of X3D documents that contain the new nodes. The browser consecutively tries to load the scene from these URLs. It stops as soon as a download succeeds.

node - The node that the new nodes become children of.

eventIn - The name of the EventInMFNode event-in slot the new nodes get sent to.

Throws:

InvalidBrowserException - when you try to call this method after calling the dispose method.

InvalidNodeException - when the node specified in the "node" parameter is not valid.

InvalidURLException - when the URL specified in the "url" parameter is not valid.

ConnectionException - when the connection to the browser failed.

getNode

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

Returns a named node. This method allows to retrieve references to nodes in the currently loaded 3D scene. To do that, you have to give the nodes names (via the VRML DEF mechanism).

The following example demonstrates how to get a reference to a Group node named "root" (which is defined in the VRML scene as "DEF root Group {}"):

 vrml.eai.Browser browser = ...;
 vrml.eai.Node group = browser.getNode("root");


Parameters:
name - The name of the node.
Returns:
The node.
Throws:
InvalidNodeException - when a node with the given name does not
 exist in the scene.
InvalidBrowserException - when you try to call this method after
 calling the dispose method.
URLUnavailableException
ConnectionException - when the connection to the browser failed.

addRoute

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

Creates a new route.

The following example demonstrates how to create a route from the fraction_changed event-out slot of a TimeSensor node to the set_fraction event-in slot of a PositionInterpolator node:

 vrml.eai.Browser browser = ...;
 vrml.eai.Node timeSensor = ...;
 vrml.eai.Node positionInterpolator = ...;
 browser.addRoute(timeSensor, "fraction_changed", positionInterpolator, "set_fraction");
 

Parameters:

fromNode - The node that sends events.

eventOut - The name of the event-out slot that sends events.

toNode - The node that receives events.

eventIn - The name of the event-in slot that receives events.

Throws:

InvalidBrowserException - when you try to call this method after calling the dispose method.

InvalidEventOutException - when an event-out slot with the given name does not exist.

InvalidEventInException - when an event-in slot with the given name does not exist.

InvalidNodeException - when a node specified in either the "fromNode" or the "toNode" parameter is invalid.

ConnectionException - when the connection to the browser failed.

deleteRoute

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

Removes a route.

The following example demonstrates how to remove a route from the fraction_changed event-out slot of a TimeSensor node to the set_fraction event-in slot of a PositionInterpolator node:

 vrml.eai.Browser browser = ...;
 vrml.eai.Node timeSensor = ...;
 vrml.eai.Node positionInterpolator = ...;
 browser.deleteRoute(timeSensor, "fraction_changed", positionInterpolator, "set_fraction");
 

Parameters:

fromNode - The node that sends events.

eventOut - The name of the event-out slot that sends events.

toNode - The node that receives events.

eventIn - The name of the event-in slot that receives events.

Throws:

InvalidBrowserException - when you try to call this method after calling the dispose method.

InvalidEventOutException - when an event-out slot with the given name does not exist.

InvalidEventInException - when an event-in slot with the given name does not exist.

InvalidNodeException - when a node specified in either the "fromNode" or the "toNode" parameter is invalid.

ConnectionException - when the connection to the browser failed.

beginUpdate

void beginUpdate()
                 throws InvalidBrowserException,
                        ConnectionException

Starts scene update. By default, when you send events to event-in slots in the scene via the EAI, each change is processed immediatly. For many applications, this is perfectly ok, but there are some drawbacks of that approach. First of all, it is quite inefficient when you have to send many events at once. For each event, the EAI has to send the data value to the X3D browser, and then has to wait for the reply, which takes some time, especially when communicating via a network. Furthermore, it is impossible to send two or more events simultaneously, or to combine changes at single elements of a multi-field to a single event. To overcome these drawbacks, a pair of two methods exists, beginUpdate and endUpdate().

When calling endUpdate(), the Browser object stops sending all events immediately, and instead buffers them in memory until you call the beginUpdate method. At that point, all buffered events are sent at the same time, and the Browser object starts sending events immediately again.

The following example demonstrates how to apply two transformations simulataneously to a scene:

 vrml.eai.Browser browser = ...;
 vrml.eai.field.EventInSFVec3f set_translation1 = ...;
 vrml.eai.field.EventInSFVec3f set_translation2 = ...;
 float[] translation1 = ...;
 float[] translation2 = ...;
 browser.endUpdate();
     set_translation1.setValue(translation1);
     set_translation2.setValue(translation2);
 browser.beginUpdate();
 

Throws:

InvalidBrowserException - when you try to call this method after calling the dispose method.

ConnectionException - when the connection to the browser failed.

See Also:

endUpdate()

endUpdate

void endUpdate()
               throws InvalidBrowserException,
                      ConnectionException

Stops scene update. By default, when you send events to event-in slots in the scene via the EAI, each change is processed immediatly. For many applications, this is perfectly ok, but there are some drawbacks of that approach. First of all, it is quite inefficient when you have to send many events at once. For each event, the EAI has to send the data value to the X3D browser, and then has to wait for the reply, which takes some time, especially when communicating via a network. Furthermore, it is impossible to send two or more events simultaneously, or to combine changes at single elements of a multi-field to a single event. To overcome these drawbacks, a pair of two methods exists, beginUpdate() and endUpdate.

When calling endUpdate, the Browser object stops sending all events immediately, and instead buffers them in memory until you call the beginUpdate() method. At that point, all buffered events are sent at the same time, and the Browser object starts sending events immediately again.

The following example demonstrates how to apply two transformations simulataneously to a scene:

 vrml.eai.Browser browser = ...;
 vrml.eai.field.EventInSFVec3f set_translation1 = ...;
 vrml.eai.field.EventInSFVec3f set_translation2 = ...;
 float[] translation1 = ...;
 float[] translation2 = ...;
 browser.endUpdate();
     set_translation1.setValue(translation1);
     set_translation2.setValue(translation2);
 browser.beginUpdate();
 

Throws:

InvalidBrowserException - when you try to call this method after calling the dispose method.

ConnectionException - when the connection to the browser failed.

See Also:

beginUpdate()

addBrowserListener

void addBrowserListener(BrowserListener l)
                        throws InvalidBrowserException,
                               ConnectionException

Adds a listener to the browser. You can add objects that implement the BrowserListener interface as listeners to the Browser object. The BrowserListener.browserChanged(vrml.eai.event.BrowserEvent) method gets called whenever the status of the X3D browser changes.

In practice, you usually do not create a real class that implements the BrowserListener interface, instead you use the special Java language feature called "anonymous classes". The following example demonstrates how to add an anonymous class as a listener to the browser:

 class MyClass
 {
     private static void onBrowserChanged(vrml.eai.event.BrowserEvent evt)
     {
         ...
     }
 
     public static void main(String[] args)
     {
         ...
         vrml.eai.Browser browser = ...;
         vrml.eai.event.BrowserListener listener = new vrml.eai.event.BrowserListener()
         {
             public void browserChanged(vrml.eai.event.BrowserEvent evt)
             {
                 MyClass.onBrowserChanged(evt);
             }
         };
         browser.addBrowserListener(listener);
         ...
         browser.removeBrowserListener(listener);
         ...
     }
 }
 

Parameters:

l - The listener that receives browser events.

Throws:

InvalidBrowserException - when you try to call this method after calling the dispose method.

ConnectionException - when the connection to the browser failed.

removeBrowserListener

void removeBrowserListener(BrowserListener l)
                           throws InvalidBrowserException,
                                  ConnectionException

Removes a listener from the browser. This method allows to remove methods previously added by the addBrowserListener(vrml.eai.event.BrowserListener) method when you do not longer want to get notified of browser events.

The following example demonstrates how to remove a listener from the browser:

 class MyClass
 {
     private static void onBrowserChanged(vrml.eai.event.BrowserEvent evt)
     {
         ...
     }
 
     public static void main(String[] args)
     {
         ...
         vrml.eai.Browser browser = ...;
         vrml.eai.event.BrowserListener listener = new vrml.eai.event.BrowserListener()
         {
             public void browserChanged(vrml.eai.event.BrowserEvent evt)
             {
                 MyClass.onBrowserChanged(evt);
             }
         };
         browser.addBrowserListener(listener);
         ...
         browser.removeBrowserListener(listener);
         ...
     }
 }
 

Parameters:

l - The listener.

Throws:

InvalidBrowserException - when you try to call this method after calling the dispose method.

ConnectionException - when the connection to the browser failed.

dispose

void dispose()

Releases all resources held by this browser object. You should call this method when you do not need access to a browser anymore. Calling it is optional - it gets automatically called by the finalizer of this class - but it is recommended to call this method manually because it allows the system the release resources held by this object as soon as possible. The browser object is not valid anymore after calling this method - do not call any method of the browser object, or you will get an InvalidBrowserException.