com.sun.j3d.utils.universe
Class ConfigContainer

java.lang.Object
  extended by 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
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
 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
equals, 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:

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:

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