Java 3D API Specification

A P P E N D I X D

The Java 3D API uses the standard Java exception model for handling errors or exceptional conditions. In addition to using existing exception classes, such as ArrayIndexOutOfBoundsException and IllegalArgumentException, Java 3D defines several new runtime exceptions. These exceptions are thrown by various Java 3D methods or by the Java 3D renderer to indicate an error condition of some kind.

The exceptions defined by Java 3D, as part of the java.media.j3d package, are described in the following sections. They all extend RuntimeException and, as such, need not be declared in the throws clause of methods that might cause the exception to be thrown.

D.1 BadTransformException

This exception indicates an attempt to use a Transform3D object that is inappropriate for the object in which it is being used. Transforms that are used in scene graph nodes must be congruent (i.e., they must be angle- and length-preserving with no shear and only uniform scale). Transforms that are used in the Squash component object must be affine, but may contain a non-uniform scale and/or a shear. Most viewing transformations, other than those in the scene graph, can only contain translation and rotation. The projection transformation is allowed to be non-affine, but it must either be a single point perspective projection or a parallel projection.

Constructors

public BadTransformException()
public BadTransformException(String str)

These create the exception object that outputs the exception message. The first form uses the default message. The second form specifies the message string to be output.

D.2 CapabilityNotSetException

This exception indicates an access to a live or compiled Scene Graph object without the required capability set.

Constructors

public CapabilityNotSetException()
public CapabilityNotSetException(String str)

These create the exception object that outputs the exception message. The first form uses the default message. The second form specifies the message string to be output.

D.3 DanglingReferenceException

This exception indicates that during a cloneTree call, an updated reference was requested for a node that did not get cloned. This happens when a sub-graph is duplicated via cloneTree and has at least one Leaf node that contains a reference to a Node with no corresponding node in the cloned sub-graph. This results in two Leaf nodes wanting to share access to the same Node.

Constructors

public DanglingReferenceException()
public DanglingReferenceException(String str)

These create the exception object that outputs the exception message. The first form uses the default message. The second form specifies the message string to be output.

D.4 IllegalSharingException

This exception indicates an illegal attempt to share a scene graph object. For example, the following are illegal:

• referencing a shared subgraph in more than one virtual universe

• using the same component object both in the scene graph and in an immediate mode graphics context

• including an unsupported type of leaf node within a shared subgraph

• referencing a BranchGroup node in more than one of the following ways:

• attaching it to a (single) Locale
• adding it as a child of a Group node within the scene graph
• referencing it from a (single) Background leaf node as background geometry

Constructors

public IllegalSharingException()
public IllegalSharingException(String str)

These create the exception object that outputs the exception message. The first form uses the default message. The second form specifies the message string to be output.

D.5 MultipleParentException

This exception extends IllegalSharingException and indicates an attempt to add a node that is already a child of one group node into another group node.

Constructors

public MultipleParentException()
public MultipleParentException(String str)

These create the exception object that outputs the exception message. The first form uses the default message. The second form specifies the message string to be output.

D.6 RestrictedAccessException

This exception indicates an attempt to access or modify a state variable without permission to do so. For example, invoking a set method for a state variable that is currently read-only.

Constructors

public RestrictedAccessException()
public RestrictedAccessException(String str)

These create the exception object that outputs the exception message. The first form uses the default message. The second form specifies the message string to be output.

D.7 SceneGraphCycleException

This exception indicates that one of the live scene graphs attached to a viewable Locale has a cycle in it. Java 3D scene graphs are directed acyclic graphs and, as such, do not permit cycles. This exception is either thrown by the Java 3D renderer at scene graph traversal time or when a scene graph containing a cycle is made live (added as a descendant of a Locale object).

Constructors

public SceneGraphCycleException()
public SceneGraphCycleException(String str)

These create the exception object that outputs the exception message. The first form uses the default message. The second form specifies the message string to be output.

D.8 SingularMatrixException

This exception indicates that the inverse of a matrix cannot be computed.

Constructors

public SingularMatrixException()
public SingularMatrixException(String str)

These create the exception object that outputs the exception message. The first form uses the default message. The second form specifies the message string to be output.

D.9 SoundException

This exception indicates a problem in loading or playing a sound sample.

Constructors

public SoundException()
public SoundException(String str)

These create the exception object that outputs the exception message. The first form uses the default message. The second form specifies the message string to be output.

---

Java 3D API Specification

Copyright © 1997, Sun Microsystems, Inc. All rights reserved.