<199607310711.QAA18942@yoritomo.soft.arch.sony.co.jp> <199607300150.SAA03932@homey.engr.sgi.com> <199607300330.TAA14414@mole.dimensionx.com> <31FE4D45.3359@sgi.com> VRML 2.0, Part1: Appendix C. Java API

The Virtual Reality Modeling Language

Appendix C. Java Scripting Reference

Version 2.0, ISO/IEC WD 14772

August 4, 1996

This annex describes the Java classes and methods that allow Script nodes (see "Nodes Reference - Script") to interact with associated scenes. See "Concepts - Scripting" for a general description of scripting languages in VRML.

C.1 Language

C.2 Supported Protocol in the Script Node's url Field

C.2.1 File Extension

C.2.2 MIME Type

C.3 EventIn Handling

C.3.1 Parameter Passing and the EventIn Field/Method

C.3.2 processEvents() and processEvent() Methods

C.3.3 eventsProcessed() Method

C.3.4 shutdown() Method

C.3.5 initialize() Method

C.4 Accessing Fields and Events

C.4.1 Accessing Fields and EventOuts of the Script

C.4.2 Accessing Fields and EventOuts of Other Nodes

C.4.3 Sending EventOuts

C.5 Exposed Classes and Methods for Nodes and Fields

C.5.1 Field Class and ConstField Class

C.5.2 Node Class

C.5.3 Browser Class

C.5.4 User-defined Classes and Packages

C.5.5 Standard Java Packages

C.6 Exceptions

C.7 Example

C.8 Class Definitions

C.8.1 Class Hierarchy

C.8.2 VRML Packages

C.8.2.1 vrml Package
C.8.2.2 vrml.field Package
C.8.2.3 vrml.node Package

C.9 Example of Exception Class

C.1 Language

Java(TM) is an object-oriented, platform-independent, multi-threaded, general-purpose programming environment developed at Sun Microsystems, Inc. See the Java web site for a full description of the Java programming language (http://java.sun.com/). This appendix describes the Java bindings of VRML to the Script node.

C.2 Supported Protocol in the Script Node's url Field

The url field of the Script node contains the URL of a file containing the Java byte code, for example:

     Script { 
         url "http://foo.co.jp/Example.class"
         eventIn SFBool start
     }

C.2.1 File Extension

The file extension for Java byte code is .class.

C.2.2 MIME Type

The MIME type for Java byte code is defined as follows:

        application/x-java

C.3 EventIn Handling

Events to the Script node are passed to the corresponding Java method (processEvent or processEvents) in the script. It is necessary to specify the script in the url field of the Script node.

If a Java byte code file is specified in the url field, the following two conditions must hold:

  • it must contain the class definition whose name is exactly the same as the body of the file name, and
  • it must be a subclass of 'Script' class in "vrml.node Package".

For example, the following Script node has one eventIn field whose name is 'start'.

    Script { 
           url "http://foo.co.jp/Example.class"
           eventIn SFBool start
    }

This node points to the script file 'Example.class' - its source ('Example.java') looks like this:

    import vrml.*;
    import vrml.field.*;
    import vrml.node.*;

    class Example extends Script {
        ...
        // This method is called when any event is received
        public void processEvent (Event e) {
           // ... perform some operation ...
        }
    }

In the above example, when the start eventIn is sent the processEvent() method is executed and receives the eventIn.

C.3.1 Parameter Passing and the EventIn Field/Method

When a Script node receives an eventIn, a processEvent() or processEvents() method in the file specified in url field of the Script node is called, which receives the eventIn as Java objects (Event object). See "processEvent() or processEvents() Method".

The Event object has three information associated with it: name, value and timestamp of the eventIn. These can be retrieved using the corresponding method on the Event object.

   class Event {
      public String getName();
      public ConstField getValue();
      public double getTimeStamp();
   }

Suppose that the eventIn type is SFXXX and eventIn name is eventInYYY, then

  • the getName() should return "eventInYYY"
  • the getValue() should return ConstField.
  • getTimeStamp() should return the timestamp when the eventIn was occurred

In the above example, the eventIn name would be "start" and eventIn value could be casted to be ConstSFBool. Also, the timestamp for the time when the eventIn was occurred is available as a double. These are passed as an Event object to processEvent() method:

        public void processEvent (Event e) {
            if(e.getName().equals("start")){
                  ConstSFBool v = (ConstSFBool)e.getValue();
                  if(v.getValue()==true){
                       // ... perform some operation ...
                  }
             }
        }

C.3.2 processEvents() and processEvent() Method

Authors can define a processEvents method within a class that is called when the script receives some set of events. The prototype of processEvents method is

    public void processEvents(int count, Event events[]);

count indicates the number of events delivered. events is the array of events delivered. Its default behavior is to iterate over each event, calling processEvent() on each one as follows:

    public void processEvents(int count, Event events[])
    {
        for (int i = 0; i < count; i++) {
            processEvent( events[i] );
        }
    }

Although authors could change this operation by giving a user-defined processEvents() method, in most cases, they would only change processEvent() method and eventsProcessed() method described below.

When multiple eventIns are routed from single node to single script node and then the eventIns which have the same timestamp are occurred, the processEvents() receives multiple events as the event array. Otherwise, each coming event invokes separate processEvents().

For example, processEvents() method receives two events in the following case :

    Transform {
        children [
            DEF TS TouchSensor {}
            Shape { geometry Cone {} }
        ]
    }
    DEF SC Script {
        url     "Example.class"
        eventIn SFBool isActive
        eventIn SFTime touchTime
    }
    ROUTE TS.isActive  TO SC.isActive
    ROUTE TS.touchTime TO SC.touchTime

Authors can define a processEvent method within a class. The prototype of processEvent is

    public void processEvent(Event event);

Its default behavior is no operation.

C.3.3 eventsProcessed() Method

Authors can define an eventsProcessed method within a class that is called after some set of events has been received. It allows Scripts that do not rely on the ordering of events received to generate fewer events than an equivalent Script that generates events whenever events are received. It is called after every invocation of processEvents().

Events generated from an eventsProcessed routine are given the timestamp of the last event processed.

The prototype of eventsProcessed method is

    public void eventsProcessed();

Its default behavior is no operation.

C.3.4 shutdown() Method

Authors can define a shutdown method within a class that is called when the corresponding Script node is deleted.

The prototype of shutdown method is

    public void shutdown();

Its default behavior is no operation.

C.3.5 initialize() Method

Authors can define an initialize method within a class that is called before any event is generated. The various methods on Script such as getEventIn, getEventOut, getExposedField, and getField are not guaranteed to return correct values before the call to initialize (i.e. in the constructor). initialize() is called once during the life of Script object.

The prototype of initialize method is

    public void initialize();

Its default behavior is no operation.

C.4 Accessing Fields and Events

The fields, eventIns and eventOuts of a Script node are accessible from their corresponding Java classes.

C.4.1 Accessing Fields, EventIns and EventOuts of the Script

Each field defined in the Script node is available to the script by using its name. Its value can be read or written. This value is persistent across function calls. EventOuts defined in the script node can also be read.

Accessing fields of Script node can be done by using Script class methods. Script class has several methods to do that: getField(), getEventOut(), getEventIn() and getExposedField().

  • Field getField(String fieldName)
    is the method to get the reference to the Script node's 'field' whose name is fieldName. The return value can be converted to an appropriate Java "Field Class".
  • Field getEventOut(String eventName)
    is the method to get the reference to the Script node's 'eventOut' whose name is eventName. The return value can be converted to an appropriate Java "Field Class".
  • Field getEventIn(String eventName)
    is the method to get the reference to the Script node's 'eventIn' whose name is eventName. The return value can be converted to an appropriate Java "Field Class". When you call getValue() method on a 'field' object obtained by getEventIn() method, the return value is unspecified. Therefore, you can not rely on it. 'EventIn' is a write-only field.

When you call setValue(), set1Value(), addValue() or insertValue() method on a 'field' object obtained by getField() method, the value specified as an argument is stored in the corresponding VRML node's field.

When you call setValue(), set1Value(), addValue() or insertValue() method on a 'field' object obtained by getEventOut() method, the value specified as an argument generates an event in VRML scene. The effect of this event is specified by the associated Route in the VRML scene.

When you call setValue(), set1Value(), addValue() or insertValue() methods on a 'field' object obtained by getEventIn() method, the value specified an argument generates an event to the Script node. For example, the following Script node defines an eventIn, start, a field, state, and an eventOut, on. The method initialize() is invoked before any events are received, and the method processEvent() is invoked when start receives an event:


    Script {
        url       "Example.class"
        eventIn   SFBool start
        eventOut  SFBool on
        field     SFBool state TRUE
    }


  Example.class:

    import vrml.*;
    import vrml.field.*;
    import vrml.node.*;

    class Example extends Script {
       private SFBool state;
       private SFBool on;

       public void initialize(){
            state = (SFBool) getField("state");
            on = (SFBool) getEventOut("on");
        }

        public void processEvent(Event e) {
            if(state.getValue()==true){
                on.setValue(true); // set true to eventOut 'on'
                state.setValue(false);
            }
            else {
                on.setValue(false); // set false to eventOut 'on'
                state.setValue(true);
            }
        }
    }

C.4.2 Accessing Fields, EventIns and EventOuts of Other Nodes

If a script program has an access to any node, any eventIn, eventOut or exposedField of that node is accessible by using the getEventIn(), getEventOut() method or getExposedField() method defined on the node's class (see "Exposed Classes and Methods for Nodes and Fields" ).

The typical way for a script program to have an access to another VRML node is to have an SFNode field which provides a reference to the other node. The following example shows how this is done:

    DEF SomeNode Transform { }
    Script {
         field SFNode node USE SomeNode
         eventIn SFVec3f pos
         url "Example.class"
    }


Example.class:

    import vrml.*;
    import vrml.field.*;
    import vrml.node.*;

    class Example extends Script {
        private SFNode node;
        private SFVec3 trans;

       public void initialize(){
            private SFNode node = (SFNode) getField("node");
       }

        public void processEvent(Event e) {
             // gets the ref to 'translation' field of Transform node

             trans = (SFVec3f)(node.getValue())
                                       .getExposedField("translation");
             trans.setValue((ConstSFVec3f)e.getValue());
        }
    }

C.4.3 Sending EventIns or EventOuts

Sending eventOuts from script is done by setting value to the reference to the 'eventOut' of the script by setValue(), set1Value(), addValue() or insertValue() method. Sending eventIns from script is done by setting value to the reference to the 'eventIn' by setValue(), set1Value(), addValue() or insertValue() method.

C.5 Exposed Classes and Methods for Nodes and Fields

Java classes for VRML are defined in the packages: vrml, vrml.node and vrml.field.

The Field class extends Java's Object class by default; thus, Field has the full functionality of the Object class, including the getClass() method. The rest of the package defines a "Const" read-only class for each VRML field type, with a getValue() method for each class; and another read/write class for each VRML field type, with both getValue() and setValue() methods for each class. A getValue() method converts a VRML-type value into a Java-type value. A setValue() method converts a Java-type value into a VRML-type value and sets it to the VRML field.

Most of the setValue() methods and set1Value() methods are listed as "throws exception," meaning that errors are possible -- you may need to write exception handlers (using Java's catch() method) when you use those methods. Any method not listed as "throws exception" is guaranteed to generate no exceptions. Each method that throws an exception includes a prototype showing which exception(s) can be thrown.

C.5.1 Field Class and ConstField Class

All VRML data types have an equivalent classes in Java.

    class Field {
    }

Field class is the root of each field types. This class has two subclasses : read-only class and writable class

  • Read-only class
    This class supports getValue() method. In addition, some classes support some convenient methods to get value from the object.

    ConstSFBool, ConstSFColor, ConstMFColor, ConstSFFloat, ConstMFFloat, ConstSFImage, ConstSFInt32, ConstMFInt32, ConstSFNode, ConstMFNode, ConstSFRotation, ConstMFRotation, ConstSFString, ConstMFString, ConstSFVec2f, ConstMFVec2f, ConstSFVec3f, ConstMFVec3f, ConstSFTime, ConstMFTime

  • Writable class
    This type of classes support both getValue() and setValue() methods. If the class name is prefixed with MF meaning that it is a multiple valued field class, the class also supports the set1Value(), addValue() and insertValue() method.
    In addition, some classes support some convenient methods to get and set value from the object.

    SFBool, SFColor, MFColor, SFFloat, MFFloat, SFImage, SFInt32, MFInt32, SFNode, MFNode, SFRotation, MFRotation, SFString, MFString, SFVec2f, MFVec2f, SFVec3f, MFVec3f, SFTime, MFTime

The Java Field class and its subclasses have several methods to get and set values: getSize(), getValue(), get1Value(), setValue(), set1Value(), addValue() or insertValue().

  • getSize()
    is the method to return the number of elements of each multiple value field class(MF class).
  • getValue()
    is the method to convert a VRML-type value into a Java-type value and returns it.
  • get1Value(int index)
    is the method to convert a VRML-type value (index-th element) into a Java-type value and returns it. The index of the first element is 0. Getting the element beyond the existing elements throws exception.
  • setValue(value)
    is the method to convert a Java-type value into a VRML-type value and sets it to the VRML field.
  • set1Value(int index, value)
    is the method to convert from a Java-type value to a VRML-type value and set it to the index-th element.
  • addValue(value)
    is the method to convert from a Java-type value to a VRML-type value and add it to the last element.
  • insertValue(int index, value)
    is the method to convert from a Java-type value to a VRML-type value and insert it to the index-th element. The index of the first element is 0. Setting the element beyond the existing elements throws exception.

In these methods, getSize(), get1Value(), set1Value(), addValue() and insertValue() are only available for multiple value field classes(MF classes). See "vrml Package" for each classes' methods definition.

C.5.2 Node Class

Node class has several methods: getType(), getEventOut(), getEventIn(), getExposedField(), getBrowser()

  • String getType()
    is the method to returns the type of the node.
  • ConstField getEventOut(String eventName)
    is the method to get the reference to the node's 'eventOut' whose name is eventName. The return value can be converted to an appropriate Java "Field Class".
  • Field getEventIn(String eventName)
    is the method to get the reference to the node's 'eventIn' whose name is eventName. The return value can be converted to an appropriate Java "Field Class". When you call getValue() method on a 'field' object obtained by getEventIn() method, the return value is unspecified. Therefore, you can not rely on it. 'EventIn' is a write-only field.
  • Field getExposedField(String eventName)
    is the method to get the reference to the node's 'exposedField' whose name is eventName. The return value can be converted to an appropriate Java "Field Class".
  • Browser getBrowser()
    is method to get the browser that this node is contained in. See "Browser Class".

When you call setValue(), set1Value(), addValue() or insertValue() method on a 'field' object obtained by getEventIn() method, the value specified as an argument generates an event to the node.

When you call setValue(), set1Value(), addValue() or insertValue() method on a 'field' object obtained by getExposedField() method, the value specified as an argument generates an event in VRML scene. The effect of this event is specified by the associated Route in the VRML scene.

C.5.3 Browser Class

This section lists the public Java interfaces to the Browser class, which allows scripts to get and set browser information. For descriptions of the following methods see the "Concepts - Scripting - Browser Interface".

Return value

Method name

String getName()
String getVersion()
float getCurrentSpeed()
float getCurrentFrameRate()
String getWorldURL()
void replaceWorld(Node[] nodes)
Node[] createVrmlFromString(String vrmlSyntax)
void createVrmlFromURL(String[] url, Node node, String event)
void addRoute(Node fromNode, String fromEventOut, Node toNode,                   String toEventIn)
void deleteRoute(Node fromNode, String fromEventOut, Node toNode,                      String toEventIn)
void loadURL(String[] url, String[] parameter)
void setDescription(String description)

See "vrml Package"for each method's definition.

Conversion table from the types used in Browser class to Java type.

VRML type Java type
SFString String
SFFloat float
MFString String[]
MFNode Node[]

C.5.4 User-defined Classes and Packages

The Java classes defined by a user can be used in the Java program. They are searched from the directory where the Java program is placed.

If the Java class is in a package, this package is searched from the directory where the Java program is placed.

C.5.5 Standard Java Packages

Java programs have access to the full set of classes available in java.* The handling of these classes - especially AWT, and the security model of networking - will be browser specific. Threads are required to work as normal for Java.

C.6 Exceptions

Java methods may throw the following exceptions:

  • InvalidFieldException
    is thrown at the time getField() is executed and the field name is invalid.
  • InvalidEventInException
    is thrown at the time getEventIn() is executed and the eventIn name is invalid.
  • InvalidEventOutException
    is thrown at the time getEventOut() or getEventOut() is executed and the eventOut name is invalid.
  • InvalidExposedFieldException
    is thrown at the time getExposedField() is executed and the exposedField name is invalid.
  • InvalidVRMLSyntaxException
    is thrown at the time createVrmlFromString(), createVrmlFromURL() or loadURL() is executed and the vrml string is invalid.
  • InvalidRouteException
    is thrown at the time addRoute() or deleteRoute() is executed and one or more the arguments is invalid.
  • InvalidFieldChangeException
    may be thrown as a result of all sorts of illegal field changes, for example:
    • Adding a node from one World as the child of a node in another World.
    • Creating a circularity in a scene graph.
    • Setting an invalid string on enumerated fields, such as the fogType field of the Fog node.

    It is not guaranteed that such exceptions will be thrown, but a browser should do the best job it can.

  • InvalidNavigationTypeException
    is thrown at the time setNavigationType() is executed and the argument is invalid.
  • ArrayIndexOutOfBoundsException
    is generated at the time setValue(), set1Value(), addValue() or insertValue() is executed and the index is out of bound. This is the standard exception defined in the Java Array class.

If exceptions are not redefined by authors, a browser's behavior is unspecified - see "Example of Exception Class".

C.7 Example

Here's an example of a Script node which determines whether a given color contains a lot of red. The Script node exposes a color field, an eventIn, and an eventOut:

Script {
    field    SFColor currentColor 0 0 0
    eventIn  SFColor colorIn
    eventOut SFBool  isRed
    url "ExampleScript.class"
}

And here's the source code for the "ExampleScript.java" file that gets called every time an eventIn is routed to the above Script node:

import vrml.*;
import vrml.field.*;
import vrml.node.*;

class ExampleScript extends Script {
    // Declare field(s)
    private SFColor currentColor;
  
    // Declare eventOut field(s)
    private SFBool isRed;
  
    public void initialize(){
       currentColor = (SFColor) getField("currentColor");
       isRed = (SFBool) getEventOut("isRed");
    }
  
    public void processEvent(Event e){
        // This method is called when a colorIn event is received
        currentColor.setValue((ConstSFColor)e.getValue());
    }
  
    public void eventsProcessed() {
        if (currentColor.getValue()[0] >= 0.5) // if red is at or above 50%
            isRed.setValue(TRUE);
    }
}

For details on when the methods defined in ExampleScript are called - see "Concepts -Execution Model".

Browser class examples:

  • createVrmlFromUrl method
    DEF Example Script {
        url "Example.class"
        field   MFString target_url "foo.wrl"
        eventIn MFNode   nodesLoaded
        eventIn SFBool   trigger_event
      }
    
    Example.class:
      import vrml.*;
      import vrml.field.*;
      import vrml.node.*;
      
      class Example extends Script {
          private MFString target_url;
          private Browser browser;
    
          public void initialize(){
              target_url = (MFString)getField("target_url");
              browser = this.getBrowser();
          }
    
          public void processEvent(Event e){
              if(e.getName().equals("trigger_event")){
                  // do something and then fetch values
                  browser.createVRMLFromURL(target_url.getValue(), this, "nodesLoaded");
             }
              if(e.getName().equals("nodesLoaded")){
                  // do something
              }
          }
      }
    
  • addRoute method
      DEF Sensor TouchSensor {}
      DEF Example Script {
        url "Example.class"
        field   SFNode fromNode USE Sensor
        eventIn SFBool clicked
        eventIn SFBool trigger_event
      }
    
    Example.class:
      import vrml.*;
      import vrml.field.*;
      import vrml.node.*;
      
      class Example extends Script {
          private SFNode fromNode;
          private Browser browser;
         
          public void initialize(){
              fromNode = (SFNode) getField("fromNode");
              browser = this.getBrowser();
          }
    
          public void processEvent(Event e){
             if(e.getName().equals("trigger_event")){
                  // do something and then add routing
                  browser.addRoute(fromNode.getValue(), "isActive", this, "clicked");
             }
             if(e.getName().equals("clicked")){
                  // do something
              }
          }
      }
    

C.8 Class Definitions

C.8.1 Class Hierarchy

The classes are divided into three packages: vrml, vrml.field and vrml.node.

java.lang.Object
     |
     +- vrml.Event
     +- vrml.Browser
     +- vrml.Field
     |       +- vrml.field.SFBool
     |       +- vrml.field.SFColor
     |       +- vrml.field.SFFloat
     |       +- vrml.field.SFImage
     |       +- vrml.field.SFInt32
     |       +- vrml.field.SFNode
     |       +- vrml.field.SFRotation
     |       +- vrml.field.SFString
     |       +- vrml.field.SFTime
     |       +- vrml.field.SFVec2f
     |       +- vrml.field.SFVec3f
     |       |
     |       +- vrml.MField
     |       |       +- vrml.field.MFColor
     |       |       +- vrml.field.MFFloat
     |       |       +- vrml.field.MFInt32
     |       |       +- vrml.field.MFNode
     |       |       +- vrml.field.MFRotation
     |       |       +- vrml.field.MFString
     |       |       +- vrml.field.MFTime
     |       |       +- vrml.field.MFVec2f
     |       |       +- vrml.field.MFVec3f
     |       |
     |       +- vrml.ConstField
     |               +- vrml.field.ConstSFBool
     |               +- vrml.field.ConstSFColor
     |               +- vrml.field.ConstSFFloat
     |               +- vrml.field.ConstSFImage
     |               +- vrml.field.ConstSFInt32
     |               +- vrml.field.ConstSFNode
     |               +- vrml.field.ConstSFRotation
     |               +- vrml.field.ConstSFString
     |               +- vrml.field.ConstSFTime
     |               +- vrml.field.ConstSFVec2f
     |               +- vrml.field.ConstSFVec3f
     |               |
     |               +- vrml.ConstMField
     |                       +- vrml.field.ConstMFColor
     |                       +- vrml.field.ConstMFFloat
     |                       +- vrml.field.ConstMFInt32
     |                       +- vrml.field.ConstMFNode
     |                       +- vrml.field.ConstMFRotation
     |                       +- vrml.field.ConstMFString
     |                       +- vrml.field.ConstMFTime
     |                       +- vrml.field.ConstMFVec2f
     |                       +- vrml.field.ConstMFVec3f
     |
     +- vrml.BaseNode
             +- vrml.node.Node
             +- vrml.node.Script

java.lang.Exception
        java.lang.RuntimeException
                vrml.InvalidRouteException
                vrml.InvalidFieldException
                vrml.InvalidEventInException
                vrml.InvalidEventOutException
                vrml.InvalidExposedFieldException
                vrml.InvalidNavigationTypeException
                vrml.InvalidFieldChangeException
        vrml.InvalidVRMLSyntaxException

C.8.2 vrml Packages

C.8.2.1 vrml Package

package vrml;

public abstract class Field implements Cloneable
{
   public Object clone();
}

public abstract class ConstField extends Field
{
}

public class ConstMField extends ConstField
{
   public int getSize();
}

public class MField extends Field
{
   public int getSize();
   public void clear();
   public void delete(int index);
}

public class Event implements Cloneable {
  public String getName();
  public double getTimeStamp();
  public ConstField getValue();
  public Object clone();
}

public class Browser {
  // Browser interface
  public String getName();    
  public String getVersion();    

  public float getCurrentSpeed();

  public float getCurrentFrameRate();

  public String getWorldURL();
  public void replaceWorld(Node[] nodes);

  public Node[] createVrmlFromString(String vrmlSyntax)
    throws InvalidVRMLSyntaxException;

  public void createVrmlFromURL(String[] url, Node node, String event)
    throws InvalidVRMLSyntaxException;

  public void addRoute(Node fromNode, String fromEventOut,
    Node toNode, String toEventIn);
  public void deleteRoute(Node fromNode, String fromEventOut,
    Node toNode, String toEventIn);

  public void loadURL(String[] url, String[] parameter)
    throws InvalidVRMLSyntaxException;
  public void setDescription(String description);
}

//
// This is the general BaseNode class
// 
public abstract class BaseNode 
{
  // Returns the type of the node.  If the node is a prototype
  //   it returns the name of the prototype.
  public String getType();

  // Get the Browser that this node is contained in.
  public Browser getBrowser();
}

C.8.2.2 vrml.field Package

package vrml.field;

public class ConstSFBool extends ConstField
{
   public boolean getValue();
}

public class ConstSFColor extends ConstField
{
   public void getValue(float color[]);
   public float getRed();
   public float getGreen();
   public float getBlue();
}

public class ConstSFFloat extends ConstField
{
   public float getValue();
}

public class ConstSFImage extends ConstField
{
   public int getWidth();
   public int getHeight();
   public int getComponents();
   public void getPixels(byte pixels[]);
}

public class ConstSFInt32 extends ConstField
{
   public int getValue();
}

public class ConstSFNode extends ConstField
{
  /* *****************************************
   * Return value of getValue() must extend Node class.
   * The concrete class is implementation dependent 
   * and up to browser implementation. 
   ****************************************** */
   public Node getValue();
}

public class ConstSFRotation extends ConstField
{
   public void getValue(float[] rotation);
}

public class ConstSFString extends ConstField
{
   public String getValue();
}

public class ConstSFTime extends ConstField
{
   public double getValue();
}

public class ConstSFVec2f extends ConstField
{
   public void getValue(float vec2[]);
   public float getX();
   public float getY();
}

public class ConstSFVec3f extends ConstField
{
   public void getValue(float vec3[]);
   public float getX();
   public float getY();
   public float getZ();
}

public class ConstMFColor extends ConstMField
{
   public void getValue(float colors[][]);
   public void getValue(float colors[]);
   public void get1Value(int index, float color[]);
   public void get1Value(int index, SFColor color);
}

public class ConstMFFloat extends ConstMField
{
   public void getValue(float values[]);
   public float get1Value(int index);
}

public class ConstMFInt32 extends ConstMField
{
   public void getValue(int values[]);
   public int get1Value(int index);
}

public class ConstMFNode extends ConstMField
{
  /******************************************
   * Return value of getValue() must extend Node class.
   * The concrete class is implementation dependent 
   * and up to browser implementation. 
   *******************************************/ 
   public void getValue(Node values[]);
   public Node get1Value(int index);
}

public class ConstMFRotation extends ConstMField
{
   public void getValue(float rotations[][]);
   public void getValue(float rotations[]);
   public void get1Value(int index, float rotation[]);
   public void get1Value(int index, SFRotation rotation);
}

public class ConstMFString extends ConstMField
{
   public void getValue(String values[]);
   public String get1Value(int index);
}

public class ConstMFTime extends ConstMField
{
   public void getValue(double times[]);
   public double get1Value(int index);
}

public class ConstMFVec2f extends ConstMField
{
   public void getValue(float vecs[][]);
   public void getValue(float vecs[]);
   public void get1Value(int index, float vec[]);
   public void get1Value(int index, SFVec2f vec);
}

public class ConstMFVec3f extends ConstMField
{
   public void getValue(float vecs[][]);
   public void getValue(float vecs[]);
   public void get1Value(int index, float vec[]);
   public void get1Value(int index, SFVec3f vec);
}

public class SFBool extends Field
{
   public SFBool(boolean value);
   public boolean getValue();
   public void setValue(boolean b);
   public void setValue(ConstSFBool b);
   public void setValue(SFBool b);
}

public class SFColor extends Field
{
   public SFColor(float red, float green, float blue);
   public void getValue(float color[]);
   public float getRed();
   public float getGreen();
   public float getBlue();
   public void setValue(float color[]);
   public void setValue(float red, float green, float blue);
   public void setValue(ConstSFColor color);
   public void setValue(SFColor color);
}

public class SFFloat extends Field
{
   public SFFloat(float f);
   public float getValue();
   public void setValue(float f);
   public void setValue(ConstSFFloat f);
   public void setValue(SFFloat f);
}

public class SFImage extends Field
{
   public SFImage(int width, int height, int components, byte pixels[]);
   public int getWidth();
   public int getHeight();
   public int getComponents();
   public void getPixels(byte pixels[]);
   public void setValue(int width, int height, int components,
                        byte pixels[]);
   public void setValue(ConstSFImage image);
   public void setValue(SFImage image);
}

public class SFInt32 extends Field
{
   public SFInt32(int value);
   public int getValue();
   public void setValue(int i);
   public void setValue(ConstSFInt32 i);
   public void setValue(SFInt32 i);
}

public class SFNode extends Field
{
   public SFNode(Node node);

  /******************************************
   * Return value of getValue() must extend Node class.
   * The concrete class is implementation dependent 
   * and up to browser implementation. 
   *******************************************/ 
  public Node getValue();
   public void setValue(Node node);
   public void setValue(ConstSFNode node);
   public void setValue(SFNode node);
}

public class SFRotation extends Field
{
   public SFRotation(float axisX, float axisY, float axisZ, float rotation);
   public void getValue(float[] rotation);
   public void setValue(float[] rotation);
   public void setValue(float axisX, float axisY, float axisZ, float rotation);
   public void setValue(ConstSFRotation rotation);
   public void setValue(SFRotation rotation);
}

public class SFString extends Field
{
   public SFString(String s);
   public String getValue();
   public void setValue(String s);
   public void setValue(ConstSFString s);
   public void setValue(SFString s);
}

public class SFTime extends Field
{
   public SFTime(double time);
   public double getValue();
   public void setValue(double time);
   public void setValue(ConstSFTime time);
   public void setValue(SFTime time);
}

public class SFVec2f extends Field
{
   public SFVec2f(float x, float y);
   public void getValue(float vec[]);
   public float getX();
   public float getY();
   public void setValue(float vec[]);
   public void setValue(float x, float y);
   public void setValue(ConstSFVec2f vec);
   public void setValue(SFVec2f vec);
}

public class SFVec3f extends Field
{
   public SFVec3f(float x, float y, float z);
   public void getValue(float vec[]);
   public float getX();
   public float getY();
   public float getZ();
   public void setValue(float vec[]);
   public void setValue(float x, float y, float z);
   public void setValue(ConstSFVec3f vec);
   public void setValue(SFVec3f vec);
}

public class MFColor extends MField
{
   public MFColor(float value[][]);
   public MFColor(float value[]);
   public MFColor(int size, float value[]);

   public void getValue(float colors[][]);
   public void getValue(float colors[]);

   public void setValue(float colors[][]);
   public void setValue(int size, float colors[]);
   /****************************************************
    color[0] ... color[size - 1] are used as color data
    in the way that color[0], color[1], and color[2] 
    represent the first color. The number of colors
    is defined as "size / 3".
    ***************************************************/

   public void setValue(ConstMFColor colors);

   public void get1Value(int index, float color[]);
   public void get1Value(int index, SFColor color);

   public void set1Value(int index, ConstSFColor color);
   public void set1Value(int index, SFColor color);
   public void set1Value(int index, float red, float green, float blue);

   public void addValue(ConstSFColor color);
   public void addValue(SFColor color);
   public void addValue(float red, float green, float blue);

   public void insertValue(int index, ConstSFColor color);
   public void insertValue(int index, SFColor color);
   public void insertValue(int index, float red, float green, float blue);
}

public class MFFloat extends MField
{
   public MFFloat(float values[]);

   public void getValue(float values[]);

   public void setValue(float values[]);
   public void setValue(int size, float values[]);
   public void setValue(ConstMFFloat value);

   public float get1Value(int index);

   public void set1Value(int index, float f);
   public void set1Value(int index, ConstSFFloat f);
   public void set1Value(int index, SFFloat f);

   public void addValue(float f);
   public void addValue(ConstSFFloat f);
   public void addValue(SFFloat f);

   public void insertValue(int index, float f);
   public void insertValue(int index, ConstSFFloat f);
   public void insertValue(int index, SFFloat f);
}

public class MFInt32 extends MField
{
   public MFInt32(int values[]);

   public void getValue(int values[]);

   public void setValue(int values[]);
   public void setValue(int size, int values[]);
   public void setValue(ConstMFInt32 value);

   public int get1Value(int index);

   public void set1Value(int index, int i);
   public void set1Value(int index, ConstSFInt32 i);
   public void set1Value(int index, SFInt32 i);

   public void addValue(int i);
   public void addValue(ConstSFInt32 i);
   public void addValue(SFInt32 i);

   public void insertValue(int index, int i);
   public void insertValue(int index, ConstSFInt32 i);
   public void insertValue(int index, SFInt32 i);
}

public class MFNode extends MField
{
   public MFNode(Node node[]);

  /******************************************
   * Return value of getValue() must extend Node class.
   * The concrete class is implementation dependent 
   * and up to browser implementation. 
   *******************************************/ 
   public void getValue(Node node[]);

   public void setValue(Node node[]);
   public void setValue(int size, Node node[]);
   public void setValue(ConstMFNode node);

   public Node get1Value(int index);

   public void set1Value(int index, Node node);
   public void set1Value(int index, ConstSFNode node);
   public void set1Value(int index, SFNode node);

   public void addValue(Node node);
   public void addValue(ConstSFNode node);
   public void addValue(SFNode node);

   public void insertValue(int index, Node node);
   public void insertValue(int index, ConstSFNode node);
   public void insertValue(int index, SFNode node);
}

public class MFRotation extends MField
{
   public MFRotation(float rotations[][]);
   public MFRotation(float rotations[]);
   public MFRotation(int size, float rotations[]);

   public void getValue(float rotations[][]);
   public void getValue(float rotations[]);

   public void setValue(float rotations[][])
   public void setValue(int size, float rotations[]);
   public void setValue(ConstMFRotation rotations);

   public void get1Value(int index, float rotation[]);
   public void get1Value(int index, SFRotation rotation);

   public void set1Value(int index, ConstSFRotation rotation);
   public void set1Value(int index, SFRotation rotation);
   public void set1Value(int index, float ax, float ay, float az, float angle);

   public void addValue(ConstSFRotation rotation);
   public void addValue(SFRotation rotation);
   public void addValue(float ax, float ay, float az, float angle);

   public void insertValue(int index, ConstSFRotation rotation);
   public void insertValue(int index, SFRotation rotation);
   public void insertValue(int index, float ax, float ay, float az, float angle);
}

public class MFString extends MField
{
   public MFString(String s[]);

   public void getValue(String s[]);

   public void setValue(String s[]);
   public void setValue(int size, String s[]);
   public void setValue(ConstMFString s);

   public String get1Value(int index);

   public void set1Value(int index, String s);
   public void set1Value(int index, ConstSFString s);
   public void set1Value(int index, SFString s);

   public void addValue(String s);
   public void addValue(ConstSFString s);
   public void addValue(SFString s);

   public void insertValue(int index, String s);
   public void insertValue(int index, ConstSFString s);
   public void insertValue(int index, SFString s);
}

public class MFTime extends MField
{
   public MFTime(double times[]);

   public void getValue(double times[]);

   public void setValue(double times[]);
   public void setValue(int size, double times[]);
   public void setValue(ConstMFTime times);

   public double get1Value(int index);

   public void set1Value(int index, double time);
   public void set1Value(int index, ConstSFTime time);
   public void set1Value(int index, SFTime time);

   public void addValue(double time);
   public void addValue(ConstSFTime time);
   public void addValue(SFTime time);

   public void insertValue(int index, double time);
   public void insertValue(int index, ConstSFTime time);
   public void insertValue(int index, SFTime time);
}

public class MFVec2f extends MField
{
   public MFVec2f(float vecs[][]);
   public MFVec2f(float vecs[]);
   public MFVec2f(int size, float vecs[]);

   public void getValue(float vecs[][]);
   public void getValue(float vecs[]);

   public void setValue(float vecs[][]);
   public void setValue(int size, vecs[]);
   public void setValue(ConstMFVec2f vecs);

   public void get1Value(int index, float vec[]);
   public void get1Value(int index, SFVec2f vec);

   public void set1Value(int index, float x, float y);
   public void set1Value(int index, ConstSFVec2f vec);
   public void set1Value(int index, SFVec2f vec);

   public void addValue(float x, float y);
   public void addValue(ConstSFVec2f vec);
   public void addValue(SFVec2f vec);

   public void insertValue(int index, float x, float y);
   public void insertValue(int index, ConstSFVec2f vec);
   public void insertValue(int index, SFVec2f vec);
}

public class MFVec3f extends MField
{
   public MFVec3f(float vecs[][]);
   public MFVec3f(float vecs[]);
   public MFVec3f(int size, float vecs[]);

   public void getValue(float vecs[][]);
   public void getValue(float vecs[]);

   public void setValue(float vecs[][]);
   public void setValue(int size, float vecs[]);
   public void setValue(ConstMFVec3f vecs);

   public void get1Value(int index, float vec[]);
   public void get1Value(int index, SFVec3f vec);

   public void set1Value(int index, float x, float y, float z);
   public void set1Value(int index, ConstSFVec3f vec);
   public void set1Value(int index, SFVec3f vec);

   public void addValue(float x, float y, float z);
   public void addValue(ConstSFVec3f vec);
   public void addValue(SFVec3f vec);

   public void insertValue(int index, float x, float y, float z);
   public void insertValue(int index, ConstSFVec3f vec);
   public void insertValue(int index, SFVec3f vec);
}

C.8.2.3 vrml.node Package

package vrml.node;

//
// This is the general Node class
// 
public abstract class Node extends BaseNode { 
  
  // Get an EventIn by name. Return value is write-only.
  //   Throws an InvalidEventInException if eventInName isn't a valid
  //   event in name for a node of this type.
  public final Field getEventIn(String fieldName);

  // Get an EventOut by name. Return value is read-only.
  //   Throws an InvalidEventOutException if eventOutName isn't a valid
  //   event out name for a node of this type.
  public final ConstField getEventOut(String fieldName);

  // Get an exposed field by name. 
  //   Throws an InvalidExposedFieldException if fieldName isn't a valid
  //   exposed field name for a node of this type.
  public final Field getExposedField(String fieldName);
}

//
// This is the general Script class, to be subclassed by all scripts.
// Note that the provided methods allow the script author to explicitly
// throw tailored exceptions in case something goes wrong in the
// script.
//
public abstract class Script extends BaseNode { 
 
  // This method is called before any event is generated
  public void initialize();

  // Get a Field by name.
  //   Throws an InvalidFieldException if fieldName isn't a valid
  //   event in name for a node of this type.
  protected final Field getField(String fieldName);

  // Get an EventOut by name.
  //   Throws an InvalidEventOutException if eventOutName isn't a valid
  //   event out name for a node of this type.
  protected final Field getEventOut(String fieldName);

  // processEvents() is called automatically when the script receives 
  //   some set of events. It should not be called directly except by its subclass.
  //   count indicates the number of events delivered.
  public void processEvents(int count, Event events[]);

  // processEvent() is called automatically when the script receives 
  // an event. 
  public void processEvent(Event event);

  // eventsProcessed() is called after every invocation of processEvents().
  public void eventsProcessed()

  // shutdown() is called when this Script node is deleted.
  public void shutdown(); 
}

C.9 Example of Exception Class


public class InvalidEventInException extends IllegalArgumentException
{
   /**
    * Constructs an InvalidEventInException with no detail message.
    */
   public InvalidEventInException(){
      super();
   }
   /**
    * Constructs an InvalidEventInException with the specified detail message.
    * A detail message is a String that describes this particular exception.
    * @param s the detail message
    */
   public InvalidEventInException(String s){
      super(s);
   }
}

public class InvalidEventOutException extends IllegalArgumentException
{
   public InvalidEventOutException(){
      super();
   }
   public InvalidEventOutException(String s){
      super(s);
   }
}

public class InvalidFieldException extends IllegalArgumentException
{
   public InvalidFieldException(){
      super();
   }
   public InvalidFieldException(String s){
      super(s);
   }
}

public class InvalidExposedFieldException extends IllegalArgumentException
{
   public InvalidExposedFieldException(){
      super();
   }
   public InvalidExposedFieldException(String s){
      super(s);
   }
}

public class InvalidVRMLSyntaxException extends Exception
{
   public InvalidVRMLSyntaxException(){
      super();
   }
   public InvalidVRMLSyntaxException(String s){
      super(s);
   }
}

public class InvalidRouteException extends IllegalArgumentException
{
   public InvalidRouteException(){
      super();
   }
   public InvalidRouteException(String s){
      super(s);
   }
}

public class InvalidNavigationTypeException extends IllegalArgumentException
{
   public InvalidNavigationTypeException(){
      super();
   }
   public InvalidNavigationTypeException(String s){
      super(s);
   }
}

public class InvalidFieldChangeException extends IllegalArgumentException
{
   public InvalidFieldChangeException(){
      super();
   }
   public InvalidFieldChangeException(String s){
      super(s);
   }
}

 Contact matsuda@arch.sony.co.jp(Kou1 Ma2da), sugino@ssd.sony.co.jp, or honda@arch.sony.co.jp with questions or comments.
This URL: http://vrml.sgi.com/moving-worlds/spec/part1/java.html.