Exceptions

The Java 3D API Specification |

A P P E N D I X D

Exceptions

> 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 `javax.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. This appendix is not an exhaustive list of all exceptions expected for Java 3D. Additional exceptions will be added as the need arises.

> ## D.1 BadTransformException

> Indicates an attempt to use a Tranform3D object that is inappropriate for the object in which it is being used. For example,

> - Transforms that are used in the scene graph, within a TransformGroup node, must be affine. They may optionally contain a nonuniform scale or a shear, subject to other listed restrictions.

> - All transforms in the TransformGroup nodes above a ViewPlatform object must be congruent. This ensures that the Vworld-coordinates-to-ViewPlatform-coordinates transform is angle- and length-preserving with no shear and with uniform scale. only

> - Most viewing transforms other than those in the scene graph can contain translation and rotation only.

> - The projection transform is allowed to be nonaffine, but it must be either 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 occurs when a subgraph 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 subgraph. This results in two leaf nodes wanting to share access to the same node.

> If dangling references are to be allowed during the `cloneTree` call, `cloneTree` should be called with the `allowDanglingReferences` parameter set to `true`.

> ##### 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 IllegalRenderingStateException

> This exception indicates an illegal state for rendering. It is currently unused.

>     public illegalRenderingStateException()
>     public illegalRenderingStateException(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 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.6 MismatchedSizeException

> This exception indicates that an operation cannot be completed properly because of a mismatch in the sizes of the object attributes.

>     public MismatchedSizeException()
>     public MismatchedSizeException(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 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.8 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.9 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 thrown by the Java 3D renderer either 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.10 SingularMatrixException

> This exception, in the `javax.vecmath` package, 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.11 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.

The Java 3D API Specification |

##### Copyright © 2000, Sun Microsystems, Inc. All rights reserved.