com.sun.j3d.utils.universe

## Class ConfigContainer

- java.lang.Object
- - com.sun.j3d.utils.universe.ConfigContainer

-     public class ConfigContainer
      extends java.lang.Object

  Loads a Java 3D configuration file and creates a container of named objects that will effect the viewing configuration specified in the file. These can include Viewers, ViewingPlatforms, ViewPlatformBehaviors, InputDevices, Sensors, and other objects.

  Clients can construct the view side of a scene graph by retrieving these objects using the accessor methods provided by this class. This could involve as little as just attaching ViewingPlatforms to a Locale, depending upon how completely the viewing configuration is specified in the file. The ConfiguredUniverse class is an example of a ConfigContainer client and how it can be used.

  ConfigContainer can be useful for clients other than ConfiguredUniverse. InputDevice and ViewPlatformBehavior configuration is fully supported, so a given Java 3D installation can provide configuration files to an application that will allow it to fully utilize whatever site-specific devices and behaviors are available. The configuration mechanism can be extended for any target object through the use of the `NewObject` and `ObjectProperty` configuration commands.

  Since:
    Java 3D 1.3.1
  See Also:
    `ConfiguredUniverse`, The Java 3D Configuration File, Example Configuration Files

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ConfigContainer(java.net.URL userConfig)` Creates a new ConfigContainer and loads the configuration file at the specified URL.
    `ConfigContainer(java.net.URL userConfig, boolean setVisible, int transformCount)` Creates a new ConfigContainer and loads the configuration file at the specified URL.
    `ConfigContainer(java.net.URL userConfig, boolean setVisible, int transformCount, java.lang.ClassLoader classLoader)` Creates a new ConfigContainer and loads the configuration file at the specified URL.
    `ConfigContainer(java.net.URL userConfig, java.lang.ClassLoader classLoader)` Creates a new ConfigContainer and loads the configuration file at the specified URL.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clear()` Release memory references used by this ConfigContainer.
    `static java.net.URL` | `getConfigURL()` Returns the config file URL based on system properties.
    `static java.net.URL` | `getConfigURL(java.lang.String defaultURLString)` Returns the config file URL based on system properties.
    `java.util.Set` | `getGenericObjects()` Returns a read-only Set of all generic configuration object instances in the order they were defined in the configuration file.
    `java.util.Set` | `getInputDevices()` Returns a read-only Set of all configured InputDevice instances in the order they were defined in the configuration file.
    `java.util.Map` | `getNamedCanvases(java.lang.String viewName)` Returns a read-only Map containing the named Canvas3D instances used by the specified Viewer.
    `java.util.Map` | `getNamedGenericObjects()` Returns a read-only Map that maps generic object names to instances.
    `java.util.Map` | `getNamedInputDevices()` Returns a read-only Map that maps InputDevice names to instances.
    `java.util.Map` | `getNamedPhysicalBodies()` Returns a read-only Map that maps PhysicalBody names to instances.
    `java.util.Map` | `getNamedPhysicalEnvironments()` Returns a read-only Map that maps PhysicalEnvironment names to instances.
    `java.util.Map` | `getNamedSensors()` Returns a read-only Map that maps Sensor names to instances.
    `java.util.Map` | `getNamedViewers()` Returns a read-only Map that maps Viewer names to instances.
    `java.util.Map` | `getNamedViewingPlatforms()` Returns a read-only Map that maps ViewingPlatform names to instances.
    `java.util.Map` | `getNamedViewPlatformBehaviors()` Returns a read-only Map that maps ViewPlatformBehavior names to instances.
    `java.util.Set` | `getPhysicalBodies()` Returns a read-only Set of all configured PhysicalBody instances in the order they were defined in the configuration file.
    `java.util.Set` | `getPhysicalEnvironments()` Returns a read-only Set of all configured PhysicalEnvironment instances in the order they were defined in the configuration file.
    `java.util.Set` | `getSensors()` Returns a read-only Set of all configured Sensor instances in the order they were defined in the configuration file.
    `java.util.Set` | `getViewers()` Returns a read-only Set of all configured Viewer instances in the order they were defined in the configuration file.
    `boolean` | `getViewerVisibility()` Returns whether Viewers should be created with their AWT components initially visible or invisible.
    `java.util.Set` | `getViewingPlatforms()` Returns a read-only Set of all configured ViewingPlatform instances in the order they were defined in the configuration file.
    `java.util.Set` | `getViewPlatformBehaviors()` Returns a read-only Set of all configured ViewPlatformBehavior instances in the order they were defined in the configuration file.
    `int` | `getViewPlatformTransformCount()` Returns the number of TransformGroups with which ViewingPlatforms should be created.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### ConfigContainer

          public ConfigContainer(java.net.URL userConfig)

      Creates a new ConfigContainer and loads the configuration file at the specified URL. All ViewingPlatform instances are created with a single TransformGroup and all Viewer components are initially invisible.
      Parameters:
        `userConfig` - URL of the configuration file to load

    - #### ConfigContainer

          public ConfigContainer(java.net.URL userConfig,
                         java.lang.ClassLoader classLoader)

      Creates a new ConfigContainer and loads the configuration file at the specified URL. All ViewingPlatform instances are created with a single TransformGroup and all Viewer components are initially invisible.
      Parameters:
        `userConfig` - URL of the configuration file to load
        `classLoader` - the class loader to use to load classes specified in the config file.

    - #### ConfigContainer

          public ConfigContainer(java.net.URL userConfig,
                         boolean setVisible,
                         int transformCount)

      Creates a new ConfigContainer and loads the configuration file at the specified URL. Any ViewingPlatform instantiated by the configuration file will be created with the specified number of transforms. Viewer components may be set initially visible or invisible with the `setVisible` flag.
      Parameters:
        `userConfig` - URL of the configuration file to load
        `setVisible` - if true, `setVisible(true)` is called on all Viewers
        `transformCount` - number of transforms to be included in any ViewingPlatform created; must be greater than 0

    - #### ConfigContainer

          public ConfigContainer(java.net.URL userConfig,
                         boolean setVisible,
                         int transformCount,
                         java.lang.ClassLoader classLoader)

      Creates a new ConfigContainer and loads the configuration file at the specified URL. Any ViewingPlatform instantiated by the configuration file will be created with the specified number of transforms. Viewer components may be set initially visible or invisible with the `setVisible` flag.
      Parameters:
        `userConfig` - URL of the configuration file to load
        `setVisible` - if true, `setVisible(true)` is called on all Viewers
        `transformCount` - number of transforms to be included in any ViewingPlatform created; must be greater than 0
        `classLoader` - the class loader to use to load classes specified in the config file.

  - ### Method Detail

    - #### getPhysicalBodies

          public java.util.Set getPhysicalBodies()

      Returns a read-only Set of all configured PhysicalBody instances in the order they were defined in the configuration file. PhysicalBody instances are created with the following command:

      > (NewPhysicalBody <instance name> [Alias <alias name>])

      The PhysicalBody is configured through the following command:

      > (PhysicalBodyProperty <instance name> <property name> <property value>)

      Returns:
        read-only Set of all unique instances, or null

    - #### getNamedPhysicalBodies

          public java.util.Map getNamedPhysicalBodies()

      Returns a read-only Map that maps PhysicalBody names to instances. Names may be aliases and if so will map to the original instances.
      Returns:
        read-only Map from names to PhysicalBody instances, or null if no instances

    - #### getPhysicalEnvironments

          public java.util.Set getPhysicalEnvironments()

      Returns a read-only Set of all configured PhysicalEnvironment instances in the order they were defined in the configuration file.

      PhysicalEnvironment instances are created with the following command:

      > (NewPhysicalEnvironment <instance name> [Alias <alias name>])

      The PhysicalEnvironment is configured through the following command:

      > (PhysicalEnvironmentProperty <instance name> <property name> <property value>)

      Returns:
        read-only Set of all unique instances, or null

    - #### getNamedPhysicalEnvironments

          public java.util.Map getNamedPhysicalEnvironments()

      Returns a read-only Map that maps PhysicalEnvironment names to instances. Names may be aliases and if so will map to the original instances.
      Returns:
        read-only Map from names to PhysicalEnvironment instances, or null if no instances

    - #### getViewers

          public java.util.Set getViewers()

      Returns a read-only Set of all configured Viewer instances in the order they were defined in the configuration file. The Viewers will have incorporated any PhysicalEnvironment and PhysicalBody objects specfied for them in the configuration file, and will be attached to any ViewingPlatforms specified for them.

      Viewer instances are created with the following command:

      > (NewView <instance name> [Alias <alias name>])

      The Viewer is configured through the following command:

      > (ViewProperty <instance name> <property name> <property value>)

      Returns:
        read-only Set of all unique instances, or null

    - #### getNamedViewers

          public java.util.Map getNamedViewers()

      Returns a read-only Map that maps Viewer names to instances. Names may be aliases and if so will map to the original instances. The Viewers will have incorporated any PhysicalEnvironment and PhysicalBody objects specfied for them in the configuration file, and will be attached to any ViewingPlatforms specified for them.

      Returns:
        read-only Map from names to Viewer instances, or null if no instances

    - #### getInputDevices

          public java.util.Set getInputDevices()

      Returns a read-only Set of all configured InputDevice instances in the order they were defined in the configuration file. All InputDevice instances in the set are initialized and registered with any PhysicalEnvironments that reference them.

      InputDevice instances are created with the following command:

      > (NewDevice <instanceName> <className> [Alias <alias name>])

      className must be the fully-qualified name of a class that implements the InputDevice interface. The implementation must provide a parameterless constructor.

      The InputDevice is configured through the DeviceProperty command:

      > (DeviceProperty <instanceName> <propertyName> <arg0> ... <argn>)

      propertyName must be the name of a input device method that takes an array of Objects as its only parameter; the array is populated with the values of arg0 through argn when the method is invoked to set the property. These additional requirements for configurable input devices can usually be fulfilled by extending or wrapping available InputDevice implementations.
      Returns:
        read-only Set of all unique instances, or null

    - #### getNamedInputDevices

          public java.util.Map getNamedInputDevices()

      Returns a read-only Map that maps InputDevice names to instances. Names may be aliases and if so will map to the original instances. All InputDevice instances in the map are initialized and registered with any PhysicalEnvironments that reference them.
      Returns:
        read-only Map from names to InputDevice instances, or null if no instances
      See Also:
        `getInputDevices()`

    - #### getSensors

          public java.util.Set getSensors()

      Returns a read-only Set of all configured Sensor instances in the order they were defined in the configuration file. The associated InputDevices are all initialized and registered with any PhysicalEnvironments that reference them.

      Sensor instances are named with the following command:

      > (NewSensor <instance name> <device name> <sensor index> [Alias <alias name>])

      device name is the instance name of a previously defined InputDevice, and sensor index is the index of the Sensor to be bound to instance name. The InputDevice implementation is responsible for creating its own Sensor objects, so this command does not create any new instances.

      The Sensor is configured through the SensorProperty command:

      > (SensorProperty <instance name> <property name> <property value>)

      With the sole exception of the Sensor assigned to the head tracker, none of the Sensors defined in the configuration file are placed into the Sensor array maintained by a PhysicalEnvironment.
      Returns:
        read-only Set of all unique instances, or null

    - #### getNamedSensors

          public java.util.Map getNamedSensors()

      Returns a read-only Map that maps Sensor names to instances. Names may be aliases and if so will map to the original instances. The associated InputDevices are all initialized and registered with any PhysicalEnvironments that reference them.

      With the sole exception of the Sensor assigned to the head tracker, none of the Sensors defined in the configuration file are placed into the Sensor array maintained by a PhysicalEnvironment.

      Returns:
        read-only Map from names to Sensor instances, or null if no instances

    - #### getViewingPlatforms

          public java.util.Set getViewingPlatforms()

      Returns a read-only Set of all configured ViewingPlatform instances in the order they were defined in the configuration file. The ConfigContainer class itself does not attach the ViewingPlatform instances to any scengraph components or universe Locales; they are not "live" until made so by a separate client such as ConfiguredUniverse. ViewingPlatform instances are created with the following command:

      > (NewViewPlatform <instance name> [Alias <alias name>])

      The ViewingPlatform is configured through the following command:

      > (ViewPlatformProperty <instance name> <property name> <property value>)

      Returns:
        read-only Set of all unique instances, or null

    - #### getNamedViewingPlatforms

          public java.util.Map getNamedViewingPlatforms()

      Returns a read-only Map that maps ViewingPlatform names to instances. Names may be aliases and if so will map to the original instances. The ConfigContainer class itself does not attach the ViewingPlatform instances to any scengraph components or universe Locales; they are not "live" until made so by a separate client such as ConfiguredUniverse.
      Returns:
        read-only Map from names to ViewingPlatform instances, or null if no instances

    - #### getViewPlatformBehaviors

          public java.util.Set getViewPlatformBehaviors()

      Returns a read-only Set of all configured ViewPlatformBehavior instances in the order they were defined in the configuration file.

      The behaviors are attached to any ViewingPlatforms that specified them; that is, the `setViewPlatformBehavior` and `setViewingPlatform` methods of ViewingPlatform and ViewPlatformBehavior have been called if appropriate. However, a behavior's `initialize` method is not called until the ViewingPlatform to which it is attached is made live.

      ViewPlatformBehavior instances are created by the following command:

      > (NewViewPlatformBehavior <instanceName> <className>)

      className must be the fully qualified name of a concrete class that extends the abstract ViewPlatformBehavior class. The implementation must provide a parameterless constructor.

      The behavior is configured using ViewPlatformBehaviorProperty:

      > (ViewPlatformBehaviorProperty <instanceName> <propertyName> <arg0> ... <argn>)

      ViewPlatformBehavior subclasses inherit a number of pre-defined properties that can be directly specified with the propertyName string; see the configuration file documentation for details.

      Concrete ViewPlatformBehavior instances can also define their own unique properties. In those cases, propertyName must be the name of a behavior method that takes an array of Objects as its only parameter; the array is populated with the values of arg0 through argn when the method is invoked to set the property. These additional requirements for configurable behaviors can usually be fulfilled by extending or wrapping available ViewPlatformBehavior subclasses.

      Returns:
        read-only Set of all unique instances, or null

    - #### getNamedViewPlatformBehaviors

          public java.util.Map getNamedViewPlatformBehaviors()

      Returns a read-only Map that maps ViewPlatformBehavior names to instances. Names may be aliases and if so will map to the original instances.

      The behaviors are attached to any ViewingPlatforms that specified them; that is, the `setViewPlatformBehavior` and `setViewingPlatform` methods of ViewingPlatform and ViewPlatformBehavior have been called if appropriate. However, a behavior's `initialize` method is not called until the ViewingPlatform to which it is attached is made live.

      Returns:
        read-only Map from names to ViewPlatformBehavior instances, or null if no instances
      See Also:
        `getViewPlatformBehaviors()`

    - #### getNamedCanvases

          public java.util.Map getNamedCanvases(java.lang.String viewName)

      Returns a read-only Map containing the named Canvas3D instances used by the specified Viewer. Names may be aliases and if so will map to the original instances. The set of unique Canvas3D instances used by a Viewer may be obtained by calling the Viewer's accessor methods directly.

      A named Canvas3D is created and added to a Viewer whenever any of the following configuration commands are used:

      > (ViewProperty <view> Screen <screenName>)
      > (ViewProperty <view> Window <windowName>)

      view is the name of a Viewer created with the NewView command. The screenName and windowName parameters of the above commands are the keys to use when looking up the associated Canvas3D instances in the Map returned by this method. Note: the NewScreen and NewWindow commands do not create Canvas3D instances themselves; they are created only by the above configuration commands.
      Parameters:
        `viewName` - the name of the Viewer
      Returns:
        read-only Map containing the Viewer's named Canvas3D instances

    - #### getGenericObjects

          public java.util.Set getGenericObjects()

      Returns a read-only Set of all generic configuration object instances in the order they were defined in the configuration file.

      Generic object instances are created with the following command:

      > (NewObject <instanceName> <className>)

      className must be the fully-qualified name of a class that provides a parameterless constructor.

      The object is configured through the ObjectProperty command:

      > (ObjectProperty <instanceName> <propertyName> <arg0> ... <argn>)

      propertyName must be the name of a method provided by object instanceName. It must take an array of Objects as its only parameter; the array is populated with the values of arg0 through argn when the method is invoked to set the property. These additional requirements for configurable objects can usually be fulfilled by extending or wrapping available object classes.
      Returns:
        read-only Set of all unique instances, or null

    - #### getNamedGenericObjects

          public java.util.Map getNamedGenericObjects()

      Returns a read-only Map that maps generic object names to instances. Names may be aliases and if so will map to the original instances.
      Returns:
        read-only Map from names to generic object instances, or null if no instances
      See Also:
        `getGenericObjects()`

    - #### getViewPlatformTransformCount

          public int getViewPlatformTransformCount()

      Returns the number of TransformGroups with which ViewingPlatforms should be created. This is useful for clients that wish to provide a default ViewingPlatform if the configuration file doesn't specify one.
      Returns:
        the number of TransformGroups

    - #### getViewerVisibility

          public boolean getViewerVisibility()

      Returns whether Viewers should be created with their AWT components initially visible or invisible. This is useful for clients that wish to provide a default Viewer if the configuration file doesn't specify one.
      Returns:
        true if Viewer components should be initially visible; false otherwise

    - #### clear

          public void clear()

      Release memory references used by this ConfigContainer. All Sets and Maps obtained from this ConfigContainer are cleared.

    - #### getConfigURL

          public static java.net.URL getConfigURL()

      Returns the config file URL based on system properties. The current implementation of this method parses the j3d.configURL property as a URL string. For example, the following command line would specify that the config file is taken from the file "j3dconfig" in the current directory:
      `java -Dj3d.configURL=file:j3dconfig ...`
      Returns:
        the URL of the config file; null is returned if no valid URL is defined by the system properties

    - #### getConfigURL

          public static java.net.URL getConfigURL(java.lang.String defaultURLString)

      Returns the config file URL based on system properties. The current implementation of this method parses the j3d.configURL property as a URL string. For example, the following command line would specify that the config file is taken from the file "j3dconfig" in the current directory:
      `java -Dj3d.configURL=file:j3dconfig ...`
      Parameters:
        `defaultURLString` - the default string used to construct the URL if the appropriate system properties are not defined
      Returns:
        the URL of the config file; null is returned if no valid URL is defined either by the system properties or the default URL string

Copyright 1996-2008 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.