If the slot was in importing state in the node receiving the command, and the command assigns the slot to this node (which happens in the target node at the end of the resharding of a hash slot from one node to another), the command has the following side effects: A) the importing state is cleared. If a reason is not present on why the node does not have a role or why it is in the failed state simply try to use the synchronize stacking slot command and then reboot the failed slot. The command 'synchronize stacking' synchronizes the following NVRAM-based parameters.

Implementing Script nodes in Java

Keywords:
Script, Java
Author(s): Patrick Dähne
Date: 2011-04-12

Summary: This tutorial explains how to implement X3D Script nodes in Java.

Introduction

X3D, like many other 3D file formats, describes geometries of 3D objects that make up the scene and their materials in a hierarchical graph structure called the 'Scene graph'. Geometries and materials are defined as nodes in that scene graph that keep their data in fields. But X3D differs from most other 3D file formats in its ability to also describe the dynamic behaviour of the scene. X3D nodes are small 'state machines'. They can receive events via event-in slots, change their state according to the event, and send resulting events via event-out slots. Event-out slots and event-in slots are connected by 'routes'. As a result, the classical scene graph gets augmented by a data flow graph that describes the dynamic properties of the scene.

VRML/X3D already contains a large set of nodes that can be used to build typical VR applications, e.g. interpolator nodes that allow to define key frame animations. But of course the standard set of nodes cannot cover all possible applications. For that reason, you can extend the standard set of nodes by your own nodes. This can be done with a special kind of node, the 'Script' node.

The Script node is some kind of node framework. It only has a minimal number of fields that control the operation of the Script node, and it does not have any behaviour of its own. The idea is that the application programmer defines additional fields, event-in slots and event-out slots when instantiating the Script node in the scene, i.e. he can define the interface of the respective Script node. Furthermore, he can define the behaviour of the respective Script node, i.e. how it reacts to incoming events, by using a piece of code written in a programming language that the browser supports. VRML/X3D defines how to use JavaScript and Java to program the behaviour of Script nodes. Instant Player supports both of these languages. This tutorial only explains how to use Java in Script nodes. There is another tutorial that explains how to use JavaScript in Script nodes.

Warning: Instant Player fully supports the old VRML Java API. The new X3D JAVA-SAI Script-interface is not implemented. Look at the API-Specification for details

Warning: The current implementation is unstable and might crash. When you create new threads, do not try to access the X3D scene graph from these thread - the scene graph is not yet thread safe!

For more information about Java in Script nodes, have a look into the VRML specification available from http://www.web3d.org/.

In the following sections, we will extend a simple scene consisting of a red sphere with a Script node with some simple behaviour written in Java: Whenever the user clicks onto the sphere, it should toggle its color between red and green. To detect click events, we have to add a 'TouchSensor' to the scene. TouchSensors detect click events on neighbouring subtrees of the scene graph, i.e. on subtrees that are siblings of the TouchSensor. So usually you add the shape node you want to click on as well as the TouchSensor to a 'Group' node. But in this example, the sphere is the only object in the scene, so we can omit the Group node. So the resulting example without the Script node looks like this when using classic VRML encoding:

Code: Scene used in the following examples (VRML encoding)

In XML encoding, the same scene looks like this:

Warning Node Has Slots In Importing State

Code: Scene used in the following examples (XML encoding)

You can download the complete example scenes at the end of this tutorial.

Defining the Interface

First of all, we have to define the interface of the Script node, i.e. its field, event-in slots and event-out slots. Like when instantiating other nodes in the scene, we start with the type of the node ('Script'). Because we have to connect the script node via routes with other nodes in the scene, we also have to give it a name ('script' in this example). So we start as always:

In XML encoding, the Script node looks like this:

Code: The plain Script node (XML encoding)

As you can see in the code above, there are two SFBool fields of the Script node ('directOutput' and 'mustEvaluate') that we set to TRUE. I won't go into detail what these fields are good for - actually, Instant Player ignores these fields, but you might run into problems on other players when you do not set them to TRUE. When you're curious, have a look at the Script node specification to find out what these fields are good for. As rule of thumb, start your own Script nodes as shown above.

Now, how do we define the fields and slots of our Script node? Normally, we write a list of field names followed by their field values between the braces (when using VRML encoding), or we specify the field values as attribues of the opening XML tag. For script nodes, we do more or less the same. The only difference is that we also have to specify whether we have a field, an event-in slot or an event-out slot, as well as the X3D data type.

So, what do we need? First of all, we need to receive click events from the TouchSensor. The TouchSensor has an SFBool event-out slot 'isActive' that provides these events. So we need an SFBool event-in slot. We'll call it also 'isActive' (we could use any name here, but it's always a good idea to use names that make clear what the event-in slot is good for). Furthermore, we want to change the color of the sphere, so we need an SFColor event-out slot. We'll call that event-out slot 'color_changed'. Finally, we want to toggle the color, so we need an SFBool field that saves the current state (whether the sphere currently is red or green). We'll call that field 'flag'). So the complete interface of our Script node looks like this:

Code: Script node with interface declarations (VRML encoding)

In XML encoding, the Script node with the interface declarations looks like this:

Code: Script node with interface declarations (XML encoding)

As you can see, we have to specify an initial value for our 'flag' field, in this case 'FALSE'. You have to specify initial values for all the fields of your Script node. On the other hand, you cannot specifiy initial values for event-in slots and event-out slots.

By the way, exposed fields (or inputOutput fields in X3D slang) where forbidden in the original VRML-Spec but are allowed in X3D Script nodes. Instant Player now (with Beta7) supports exposed/inputOutput-Fields but there are still incompatibilities between different browsers so you have to be carefull.

Before we finally write the code, we connect the Script node to the TouchSensor and the Material node:

In XML encoding, the routes look like this:

Code: Connecting the Script node (XML encoding)

Writing the Code

After defining the interface, we have to write the Java code that handles incoming events, changes the state of the node accordingly, and sends resulting events. In our case, we need code that listens to the 'isActive' event-in slot, toggles the state of the 'flag' field, and sends a red or green color to the 'color_changed' event-out slot depending on the state of the 'flag' field.

Warning Node Has Slots In Importing State