Class BrowserFactory

java.lang.Object
org.web3d.x3d.sai.BrowserFactory

public class BrowserFactory
extends java.lang.Object
Factory class for obtaining references to browser instances.


Package hint: This specification class is defined by the X3D Java Language Binding Specification for the Scene Authoring Interface (SAI). An implementation-independent representation of the class used to access and create browsers. The model follows that used by java.net.Socket. A setImpl method is provided for browser writers to provide the internal implementations of the browser. An alternative way of doing this is through properties. The class, when it loads first looks for a System property with the key: x3d.sai.factory.class If a non-null value is found for this key, it is used as the name of the class to load as the default browser implementation. If no matching System property is found, the initializer looks for the file x3d.properties in the class path. (For more information on how this works read java.lang.ClassLoader.getSystemResourceAsStream()). If found, and the file contains a non-null value for the x3d.sai.factory.class key, this value is used as the name of the class to load as the default browser implementation. In either case (System properties or x3d.properties file), this name must represent the full package qualified name of the class. If a System property with the required key does not exist, or an x3d.properties file does not exist or the x3d.properties file does not contain a property with the required key for the name of the factory class, then the default class name org.web3d.x3d.sai.DefaultBrowserImpl is assigned. The class is loaded when a call is made to getBrowser() or createX3DComponent() using the following method: Class factory_class = Class.forName(factory_class_name); factory = (BrowserFactoryImpl)factory_class.newInstance(); If a class cast exception is raised at the end, then an error is printed but nothing is done about it. The result would be NullPointerExceptions later in the code. Also, this may cause some security errors in some web browsers. To provide a custom implementation of the factory (which all implementations must do) the user has the choice of the above options of either setting a System property, making sure that an x3d.properties file appears in the classpath before the sample implementation that comes with the classes from the X3DC, or by calling setImpl. If setBrowserFactoryImpl has not been called at the time that any of the other methods have been, then the class will attempt to load the implementation defined in the properties file. Attempting to call the set implementation method after this point shall result in a X3DException being generated. Otherwise, it shall use the set implementation.
See Also:
SAI Java Specification: B.5.2 BrowserFactory, X3D Tooltips: BrowserFactory, X3D Scene Authoring Hints
  • Method Summary

    Modifier and Type Method Description
    static X3DComponent createX3DComponent​(java.util.Map<java.lang.String,​java.lang.Object> params)
    Create an X3D player that can be used as an AWT component.
    static ExternalBrowser getBrowser​(java.applet.Applet applet)
    Get a browser from the given java applet reference as a base in the current HTML page.
    static ExternalBrowser getBrowser​(java.applet.Applet applet, java.lang.String frameName, int index)
    Get a browser from the given java applet reference one some named page and at some embed location.
    static ExternalBrowser getBrowser​(java.net.InetAddress address, int port)
    Get a reference to a browser that is located on a remote machine.
    static void setBrowserFactoryImpl​(BrowserFactoryImpl fac)
    Set the factory implementation to use.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Method Details

    • setBrowserFactoryImpl

      public static void setBrowserFactoryImpl​(BrowserFactoryImpl fac) throws java.lang.IllegalArgumentException, X3DException, java.lang.SecurityException
      Set the factory implementation to use. If the parameter value is null an exception will be thrown.
      Parameters:
      fac - - The new implementation to use
      Throws:
      java.lang.SecurityException - The environment does not allow a factory to be set
      java.lang.IllegalArgumentException - The argument factory instance is null
      X3DException - The factory is already defined.
    • createX3DComponent

      public static X3DComponent createX3DComponent​(java.util.Map<java.lang.String,​java.lang.Object> params) throws NotSupportedException
      Create an X3D player that can be used as an AWT component. The component returned is guaranteed to be an instance of X3DComponent.
      Parameters:
      params - - Parameters to control the look and feel.
      Returns:
      The component browser initialised to be empty.
      Throws:
      NotSupportedException - The implementation does not support this type of X3D player.
      See Also:
      X3DComponent
    • getBrowser

      public static ExternalBrowser getBrowser​(java.applet.Applet applet) throws NotSupportedException, NoSuchBrowserException, ConnectionException
      Get a browser from the given java applet reference as a base in the current HTML page. Used when attempting to access a browser on the current page as this applet and is the first browser on the page. Generically, the same as calling getBrowser(applet, "", 0);
      Parameters:
      applet - The applet reference to use
      Returns:
      A reference to the Browser implementation
      Throws:
      NotSupportedException - The implementation does not support this type of X3D player
      NoSuchBrowserException - Could not locate an X3D player on the same page as the applet.
      ConnectionException - An error occurred during the connecting process
    • getBrowser

      public static ExternalBrowser getBrowser​(java.applet.Applet applet, java.lang.String frameName, int index) throws NotSupportedException, NoSuchBrowserException, ConnectionException
      Get a browser from the given java applet reference one some named page and at some embed location. Used when attempting to access a browser on another HTML page within a multi-framed environment, or if there are a number of X3D player instances located on the same page.

      If the frame name is a zero length string or null then it is assumed to be located on the same HTML page as the applet. The index is the number of the embed X3D player starting from the top of the page. If there are other non-X3D plugins embedded in the page these are not taken into account in calculating the embed index.

      Parameters:
      applet - - The applet reference to use
      frameName - - The name of the frame to look into for the browser
      index - - The embed index of the X3D player in the page
      Returns:
      A reference to the Browser implementation
      Throws:
      NotSupportedException - The implementation does not support this type of X3D player.
      NoSuchBrowserException - Could not locate an X3D player on the same page as the applet.
      ConnectionException - An error occurred during the connecting process
    • getBrowser

      public static ExternalBrowser getBrowser​(java.net.InetAddress address, int port) throws NotSupportedException, NoSuchBrowserException, java.net.UnknownHostException, ConnectionException
      Get a reference to a browser that is located on a remote machine. This a server application to send scene updates to a number of client browsers located on remote machines. If there are a number of browsers running on a remote machine, they can be differentiated by the port number they are listening on.

      There is no default port number for X3D players.

      Parameters:
      address - - The address of the machine to connect to
      port - - The port number on that machine to connect to.
      Returns:
      A reference to the Browser implementation
      Throws:
      NotSupportedException - The implementation does not support this type of X3D player.
      NoSuchBrowserException - Could not locate an X3D player on the same page as the applet.
      java.net.UnknownHostException - Could not find the machine named in the address.
      ConnectionException - An error occurred during the connecting process