org.web3d.x3d.sai
Interface Browser

All Known Subinterfaces:

ExternalBrowser, Xj3DBrowser

All Known Implementing Classes:

SAIBrowser

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:

$Revision: 1.15 $

Author:

Justin Couch

Method Summary

X3DScene	createScene(ProfileInfo profile, ComponentInfo[] components) Create a new, empty scene that can be used to programmatically fill in new scenes.
X3DScene	createX3DFromStream(java.io.InputStream is) Parse the contents of the stream and interpret it as X3D content.
X3DScene	createX3DFromString(java.lang.String x3dString) Parse the given string and turn this into a list of X3D nodes.
X3DScene	createX3DFromURL(java.lang.String[] url) Create and load X3D from the given URL.
void	firstViewpoint() Bind the first viewpoint in the list.
void	firstViewpoint(int layer) Bind the first viewpoint in the list of the given layer.
java.util.Map	getBrowserProperties() Get the collection of browser properties that the browser provides.
ComponentInfo	getComponent(java.lang.String name, int level) Get a specific component at the requested support level.
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	getDescription() Get the description of the current world.
X3DExecutionContext	getExecutionContext() Get the information about the current scene.
java.lang.String	getName() Get the name of the browser.
ProfileInfo	getProfile(java.lang.String name) Get a specific profile.
java.util.Map	getRenderingProperties() Get the collection of rendering properties that the browser provides.
ComponentInfo[]	getSupportedComponents() Get a listing of all the components that this browser implementation is capable of supporting.
ProfileInfo[]	getSupportedProfiles() Get a listing of the profiles that this browser implementation is capable of supporting.
java.lang.String	getVersion() Get the version of the browser.
X3DScene	importDocument(org.w3c.dom.Node element) A utility request to import a W3C DOM document or document fragment and convert it to an X3D scene.
void	lastViewpoint() Bind the last viewpoint in the list.
void	lastViewpoint(int layer) Bind the last viewpoint in the list of the given layer.
void	loadURL(java.lang.String[] url, java.util.Map parameters) Load the URL as the new root of the scene.
void	nextViewpoint() Bind the next viewpoint in the list.
void	nextViewpoint(int layer) Bind the next viewpoint in the list of the given layer.
void	previousViewpoint() Bind the previous viewpoint in the list.
void	previousViewpoint(int layer) Bind the previous viewpoint in the list of the given layer.
void	print(java.lang.Object msg) Print the message to the browser console without wrapping a new line onto it.
void	println(java.lang.Object msg) Print the message to the browser console and append a new line onto it.
void	replaceWorld(X3DScene scene) Replace the current world with the given nodes.
void	setDescription(java.lang.String desc) Set the description of the current world.

Method Detail

getName

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

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.

getSupportedProfiles

ProfileInfo[] getSupportedProfiles()
                                   throws InvalidBrowserException

Get a listing of the profiles that this browser implementation is capable of supporting.

Returns:

The listing of all supported profiles

Throws:

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

InvalidBrowserException

getProfile

ProfileInfo getProfile(java.lang.String name)
                       throws InvalidBrowserException,
                              NotSupportedException

Get a specific profile.

Parameters:

name - The profile name

Returns:

The specified profile

Throws:

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

NotSupportedException - The reqested profile is not supported

InvalidBrowserException

getSupportedComponents

ComponentInfo[] getSupportedComponents()
                                       throws InvalidBrowserException

Get a listing of all the components that this browser implementation is capable of supporting.

Returns:

The listing of all supported components

Throws:

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

InvalidBrowserException

getComponent

ComponentInfo getComponent(java.lang.String name,
                           int level)
                           throws InvalidBrowserException,
                                  NotSupportedException

Get a specific component at the requested support level.

Parameters:

name - The component name

level - The minimum component level

Returns:

The specified component

Throws:

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

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

NotSupportedException - The reqested profile is not supported

getExecutionContext

X3DExecutionContext getExecutionContext()
                                        throws InvalidBrowserException

Get the information about the current scene. If no scene has been set then this will return null.

Returns:

The current scene data

Throws:

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

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

createScene

X3DScene createScene(ProfileInfo profile,
                     ComponentInfo[] components)
                     throws InvalidBrowserException,
                            java.lang.IllegalArgumentException

Create a new, empty scene that can be used to programmatically fill in new scenes. This scene has the give profile and/or component information set, and is not currently being rendered. Either argument may be null, but not both arguments. If the profile is null, then the default profile of "NONE" is used, and only the components are used. The scene version is set to the highest supported version of the specification that this browser currently implements.

Parameters:

profile - The profile to use for this scene or null for none

components - The list of components to use or null

Returns:

A new empty scene to work with

Throws:

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

java.lang.IllegalArgumentException - Both arguments provided are null or zero length

getCurrentSpeed

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

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.

replaceWorld

void replaceWorld(X3DScene scene)
                  throws 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:

scene - The new scene to render in the browser

Throws:

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

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

loadURL

void loadURL(java.lang.String[] url,
             java.util.Map parameters)
             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.

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

getDescription

java.lang.String getDescription()
                                throws InvalidBrowserException

Get the description of the current world.

Returns:

A description string or null if none set

Throws:

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

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

setDescription

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.

createX3DFromString

X3DScene createX3DFromString(java.lang.String x3dString)
                             throws InvalidBrowserException,
                                    InvalidX3DException

Parse the given string and turn this into a list of X3D 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 X3D syntax - either UTF8 or XML encoding. The X3D header line is not required to be present in the string if UTF8 syntax.

Parameters:

x3dString - The string containing VRML string syntax

Returns:

The scene that was created from the string.

Throws:

InvalidX3DException - If the string does not contain legal X3D/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.

createX3DFromStream

X3DScene createX3DFromStream(java.io.InputStream is)
                             throws InvalidBrowserException,
                                    InvalidX3DException,
                                    java.io.IOException

Parse the contents of the stream and interpret it as X3D content. The browser shall interpret the content using the initial characters of the stream to determine which encoding and file format is used.

Parameters:

is - The input stream that contains the content to parse

Returns:

The scene that was created from the string.

Throws:

InvalidX3DException - If the string does not contain legal X3D/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.

java.io.IOException - An I/O Error occurred while reading the stream

createX3DFromURL

X3DScene createX3DFromURL(java.lang.String[] url)
                          throws InvalidBrowserException,
                                 InvalidURLException,
                                 InvalidX3DException

Create and load X3D from the given URL. The call will not return until the basic top-level scene has been processed or an error has occurred. Inlines, textures, sound and externprotos are not guaranteed to be loaded at this time. If the caller needs to know what the final URL was that loaded, use the getWorldURL() call from the returned scene.

Parameters:

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

Returns:

The scene that was created from the URLs.

Throws:

InvalidX3DException - If the string does not contain legal X3D/VRML syntax or no node instantiations

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.

importDocument

X3DScene importDocument(org.w3c.dom.Node element)
                        throws InvalidBrowserException,
                               InvalidDocumentException,
                               NotSupportedException

A utility request to import a W3C DOM document or document fragment and convert it to an X3D scene. The method only performs a conversion process and does not display the resulting scene. The scene may then be used as the argument for the replaceWorld service. When the conversion is made, there is no lasting connection between the DOM and the generated scene. Each request shall be a one-off conversion attempt (the conversion may not be successful if the DOM does not match the X3D scene graph structure).

Parameters:

element - The root element to convert

Returns:

A scene representation corresponding to the document

Throws:

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

InvalidDocumentException - The document structure cannot be converted to an X3D scene for some reason

NotSupportedException

print

void print(java.lang.Object msg)
           throws InvalidBrowserException

Print the message to the browser console without wrapping a new line onto it.

Parameters:

msg - The object to be printed

Throws:

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

println

void println(java.lang.Object msg)
             throws InvalidBrowserException

Print the message to the browser console and append a new line onto it.

Parameters:

msg - The object to be printed

Throws:

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

nextViewpoint

void nextViewpoint()
                   throws InvalidBrowserException

Bind the next viewpoint in the list. The definition of "next" is not specified, and may be browser dependent. If only one viewpoint is declared, this method does nothing.

Throws:

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

nextViewpoint

void nextViewpoint(int layer)
                   throws InvalidBrowserException

Bind the next viewpoint in the list of the given layer. The definition of "next" is not specified, and may be browser dependent. If only one viewpoint is declared, this method does nothing.

Throws:

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

previousViewpoint

void previousViewpoint()
                       throws InvalidBrowserException

Bind the previous viewpoint in the list. The definition of "previous" is not specified, and may be browser dependent. If only one viewpoint is declared, this method does nothing.

Throws:

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

previousViewpoint

void previousViewpoint(int layer)
                       throws InvalidBrowserException

Bind the previous viewpoint in the list of the given layer. The definition of "previous" is not specified, and may be browser dependent. If only one viewpoint is declared, this method does nothing.

Throws:

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

firstViewpoint

void firstViewpoint()
                    throws InvalidBrowserException

Bind the first viewpoint in the list. This is the first viewpoint declared in the user's file. ie The viewpoint that would be bound by default on loading.

Throws:

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

firstViewpoint

void firstViewpoint(int layer)
                    throws InvalidBrowserException

Bind the first viewpoint in the list of the given layer. This is the first viewpoint declared in the user's file. ie The viewpoint that would be bound by default on loading.

Throws:

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

lastViewpoint

void lastViewpoint()
                   throws InvalidBrowserException

Bind the last viewpoint in the list.

Throws:

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

lastViewpoint

void lastViewpoint(int layer)
                   throws InvalidBrowserException

Bind the last viewpoint in the list of the given layer.

Throws:

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

getRenderingProperties

java.util.Map getRenderingProperties()
                                     throws InvalidBrowserException,
                                            InvalidOperationTimingException

Get the collection of rendering properties that the browser provides. Rendering properties are key/value pairs, as defined in table 9.2 of ISO/IEC 19775-1. Keys are instances of Strings, while the value is dependent on the property. If the property is not defined in the returned map, treat it as not being supported by the browser.

Returns:

A read-only map of the list of properties defined by the browser

Throws:

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

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

InvalidOperationTimingException - This was not called during the correct timing during a script (may be called at any time from external)

getBrowserProperties

java.util.Map getBrowserProperties()
                                   throws InvalidBrowserException,
                                          InvalidOperationTimingException

Get the collection of browser properties that the browser provides. Rendering properties are key/value pairs, as defined in table 9.2 of ISO/IEC 19775-1. Keys are instances of Strings, while the value is dependent on the property. If the property is not defined in the returned map, treat it as not being supported by the browser.

Returns:

A read-only map of the list of properties defined by the browser

Throws:

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

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

InvalidOperationTimingException - This was not called during the correct timing during a script (may be called at any time from external)