org.web3d.x3d.sai
Interface MFNode

All Superinterfaces:

MField, X3DField

public interface MFNode
extends MField

Representation of a MFNode field.

Get the values of a node array. The java null reference is treated to be equivalent to the VRML NULL field values.

It is not illegal to construct an array where some members of the array are null pointers. Due to no specification on the intended result in the VRML specification, the response given by the browser is implementation dependent. Calls will not generate an exception, but the value of actual event received from the scenegraph may vary until the issue is resolved.

Version:

1.0 30 April 1998

Method Summary

void	append(X3DNode value) Places a new value at the end of the existing value, increasing the field length accordingly.
void	clear() Removes all values in the field and changes the field size to zero.
X3DNode	get1Value(int index) Get a particular node value in the given eventOut array.
void	getValue(X3DNode[] nodes) Write the value of the array of the nodes to the given array.
void	insertValue(int index, X3DNode value) Inserts a value into an existing index of the field.
void	removeValue(int index) Removes one value from the field.
void	set1Value(int index, X3DNode value) Set a particular node value in the given eventIn array.
void	setValue(int size, X3DNode[] value) Set the value of the array of nodes.

Methods inherited from interface org.web3d.x3d.sai.MField

getSize

Methods inherited from interface org.web3d.x3d.sai.X3DField

addX3DEventListener, getDefinition, getUserData, isReadable, isWritable, removeX3DEventListener, setUserData

Method Detail

append

void append(X3DNode value)

Places a new value at the end of the existing value, increasing the field length accordingly.

Parameters:

value - The value to append

clear

void clear()

Removes all values in the field and changes the field size to zero.

getValue

void getValue(X3DNode[] nodes)

Write the value of the array of the nodes to the given array. Individual elements in the array may be null depending on the implementation of the browser and whether it maintains null references.

Parameters:

nodes - The node array to be filled in

Throws:

java.lang.ArrayIndexOutOfBoundsException - The provided array was too small

get1Value

X3DNode get1Value(int index)

Get a particular node value in the given eventOut array.

If the index is out of the bounds of the current array of data values an ArrayIndexOutOfBoundsException will be generated. If the Node value is NULL because the browser implementation keeps null references then this method will return a null pointer without throwing any exception.

Parameters:

index - The position to read the values from

Returns:

The node reference

Throws:

java.lang.ArrayIndexOutOfBoundsException - The index was outside the current data array bounds.

insertValue

void insertValue(int index,
                 X3DNode value)
                 throws java.lang.ArrayIndexOutOfBoundsException

Inserts a value into an existing index of the field. Current field values from the index to the end of the field are shifted down and the field length is increased by one to accomodate the new element. If the index is out of the bounds of the current field an ArrayIndexOutofBoundsException will be generated.

Parameters:

index - The position at which to insert

value - The new element to insert

Throws:

java.lang.ArrayIndexOutOfBoundsException - The index was outside the current field size.

removeValue

void removeValue(int index)
                 throws java.lang.ArrayIndexOutOfBoundsException

Removes one value from the field. Values at indices above the removed element will be shifted down by one and the size of the field will be reduced by one.

Parameters:

index - The position of the value to remove.

Throws:

java.lang.ArrayIndexOutOfBoundsException - The index was outside the current field size.

setValue

void setValue(int size,
              X3DNode[] value)

Set the value of the array of nodes. Input is an array of valid Node references. If the length is zero or the node reference is null, then the actions to take are according to the class introduction above. If the array contains a null reference then th resulting event passed to the eventIn is implementation dependent

If any of the node references have had their dispose methods called, an InvalidNodeException will be generated and no event sent to the scenegraph.

Parameters:

size - The number of nodes to copy from this array

value - The array of node references

Throws:

InvalidNodeException - At least one node has been "disposed" of

set1Value

void set1Value(int index,
               X3DNode value)

Set a particular node value in the given eventIn array. To the VRML world this will generate a full MFNode event with the nominated index value changed.

If the index is out of the bounds of the current array of data values an ArrayIndexOutOfBoundsException will be generated. If the Node value is null the behaviour will be undefined as far as generating an event to the scenegraph is concerned in order to be consistent with the behaviour described in the class introduction. This method call will not generate an exception if the node reference is null.

If the node reference passed to this method has already had the dispose method called then an InvalidNodeException will be generated.

Parameters:

index - The position to set the colour value

value - The node reference

Throws:

InvalidNodeException - The node has been "disposed" of

java.lang.ArrayIndexOutOfBoundsException - The index was out of bounds of the array currently.