Sample specifications in LePUS3 and Class-Z:

Java 3D

This page demonstrates LePUS3 Codecharts modelling the API of the Java 3D class library.

Links

Motivation

Java 3D is a platform-independent class library supporting the representation, manipulation, and graphic rendering of three dimensional geometrical objects in ‘virtual worlds’ for use by applications such as games and simulated reality. Java 3D data structures (graphs) are created to specify three-dimensional geometrical objects (such as cones and boxes) populating a simulated ‘universe’, to move these objects about, and to specify some visual properties (such as illumination, fog, and shades). In common with many class libraries, services in Java 3D are offered through a well-defined interface, the library’s API, designed to shield client applications from the complexity of the library’s internal workings. Given the breadth and complexity of the problem domain, it is not surprising that even the library’s API is rather large, consisting over a thousand classes and inner classes. Hence any visualization of the API in terms of individual classes and methods, a fraction of which is depicted below, is ineffective, and that abstraction and scaling are paramount.

 
Few of the individual classes and methods in Java 3D (adapted from [Maniati 2008], screenshot produced by the Design Navigator) (legend)

Three central hierarchies

The three-dimensional entities that populate the universe which Java 3D applications create is called a ‘scene’. These entities and their principal visual properties, are primarily represented using instances of classes in three hierarchies. Classes in the SceneGraphObjectHrc hierarchy (which contains 156 classes) are intimately linked with classes organized in two other class hierarchies: SceneGraphObjectStateHrc (which contains 97 classes), and SceneGraphObjectRetainedHrc (which contains 111 classes).

Three central hierarchies in Java 3D API (legend)
Modre detailed depiction of the three central hierarchies in Java 3D API (legend)

The Node hierarchy

'Nodes’ in the scene graph are objects that represent the three dimensional scene. These objects are instances of subclasses of class Node, which inherits from the root class SceneGraphObject. The Codechart below indicates that internal nodes in the scene graph are instances of subclasses of class Group, such as the three-dimensional objects (e.g., Sphere, Box, and Cylinder), whereas the leaves in scene graph are instances of classes that inherit from class Leaf, which determine the positioning and orienting of a view in the virtual world (e.g., Light and Fog).

The Node hierarchy (legend)

The SceneGraphObjectState hierarchy

Classes in the SceneGraphObjectStateHrc hierarchy are responsible for reading from and writing into a persistent, linear representation of the scene graph data structure. Towards this end, this hierarchy effectively replicates the SceneGraphObjectHrc hierarchy.

The Codechart below indicates that the abstract root class, SceneGraphObject-State, defines a member of type SceneGraphObject, which holds an instance of the respective class. For example, each instance of class linearFogState holds an instance of class LinearFog, whereas each instance of class SphereState holds an instance of class Sphere. In addition, each subclass in the SceneGraphObjectStateHrc hierarchy defines a factory method, called createNode(), which is responsible for producing an instance of the respective class from the SceneGraphObjectState hierarchy. For example, the method linearFogState.createNode() creates and returns an instance of class LinearFog, whereas SphereState.createNode()creates and returns an instance of class Sphere. This suggests that the portion of JAva 3D depicted below contains an instance of the Factory Method design pattern.

Four of the 90 concrete methods with the createNode() signature in the SceneGraphObjectStateHrc hierarchy and their products in the SceneGraphObjectHrc hierarchy (legend)
Each one of the 90 concrete methods with the createNode() signature in the SceneGraphObjectStateHrc hierarchy produces instances of the respective class in the SceneGraphObjectHrc hierarchy (legend)

The SceneGraphObjectRetained hierarchies

A similar mirroring exists between the SceneGraphObjectHrc and the SceneGraphObjectRetained hierarchy, depicted below. The Codecharts demonstrate that, in fact, even the inheritance hierarchy structure is replicated in every detail in large parts of the hierarchy. In addition, each one of the classes in the former is responsible for the creating an instance of the respective class in the latter, whereas each one of the classes in the latter is responsible for the rendering of instance of the respective class in the former. Furthermore, the mirroring is reinforced by a set of methods that change properties (whose names begin with ‘set’) and another set of methods that retrieve properties (whose names begin with ‘get’).

 
The inheritance and method structure of classes in the SceneGraphObjectHrc hierarchy mirror those in the SceneGraphObjectRetainedHrc hierarchy. (legend)