org.web3d.x3d.jsail.fields

Class MFStringObject

java.lang.Object

org.web3d.x3d.jsail.fields.X3DConcreteField

org.web3d.x3d.jsail.fields.MFStringObject

All Implemented Interfaces:

MField, MFString, X3DField

public class MFStringObject
extends X3DConcreteField
implements MFString

This utility class provides a concrete implementation corresponding to MFString X3D field type.

MFString is an array of SFString values, each "quoted" and separated by whitespace. Individual SFString array values are optionally separated by commas.

Related field object: SFStringObject
Package hint: This specification class is defined by the X3D Java Language Binding Specification for the Scene Authoring Interface (SAI).

See Also:

SAI Java Specification: B.4.11 X3DFieldTypes, SAI Abstract Specification: 5.2.15 SAIFieldType, X3D Abstract Specification: SFStringAndMFString, X3D Tooltips, X3D Tooltips: field, X3D Tooltips: fieldValue, X3D Scene Authoring Hints

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String[]	DEFAULT_VALUE Default value for this field type is an empty array.
static java.lang.String	NAME String constant NAME provides name of this element: MFString.

Fields inherited from class org.web3d.x3d.jsail.fields.X3DConcreteField

validationResult

Constructor Summary

Constructors

Constructor and Description
MFStringObject() Constructor for MFStringObject performs value initialization.
MFStringObject(MFStringObject newValue) Constructor to copy an MFStringObject value as initial value for this new field object.
MFStringObject(java.lang.String newValue) Constructor to parse String as new initial value.
MFStringObject(java.lang.String[] newValue) Constructor for MFStringObject using a corresponding Java primitive String[] array as new initial value.

Method Summary

Modifier and Type	Method and Description
MFStringObject	append(MFStringObject newValue) Appends a new MFStringObject to the end of the existing value array, increasing the field length accordingly.
MFStringObject	append(SFStringObject newValue) Appends a new singleton typed value at the end of the existing value array, increasing the field length accordingly.
void	append(java.lang.String newValue) Places new value(s) at the end of the existing value array, increasing the field length accordingly.
void	append(java.lang.String[] newValue) Appends another array at the end of the existing value array, increasing the field length accordingly.
static java.lang.String	cleanupEnumerationValue(java.lang.String value) Utility method for single enumeration value to ignore all whitespace, remove all embedded quotes, remove all commas, and remove all square brackets to create an unadorned enumeration String.
MFStringObject	cleanupEnumerationValues() Modify current object values to ignore all whitespace, remove all embedded quotes, remove all commas, and remove all square brackets.
static java.util.ArrayList<java.lang.String>	cleanupEnumerationValues(java.util.ArrayList<java.lang.String> values) Utility method for multiple enumeration values to ignore all whitespace, remove all embedded quotes, remove all commas, and remove all square brackets from a ArrayList of values.
static java.lang.String[]	cleanupEnumerationValues(java.lang.String values) Utility method for a single String containing multiple enumeration values to ignore all whitespace, remove all embedded quotes, remove all commas, and remove all square brackets to create unadorned MFString elements as a String[] array.
static java.lang.String[]	cleanupEnumerationValues(java.lang.String[] values) Utility method for multiple enumeration values to ignore all whitespace, remove all embedded quotes, remove all commas, and remove all square brackets in a String[] array.
MFStringObject	cleanupUnescapedEnclosingQuotes() Modify current object values to trim enclosing quotes and outer whitespace.
static java.util.ArrayList<java.lang.String>	cleanupUnescapedEnclosingQuotes(java.util.ArrayList<java.lang.String> values) Utility method to trim enclosing quotes and outer whitespace from elements in an ArrayList of arbitrary String values.
static java.lang.String	cleanupUnescapedEnclosingQuotes(java.lang.String singleValue) Utility method to trim enclosing quotes and outer whitespace from an arbitrary String value, without removing escaped quotation marks (\").
static java.lang.String[]	cleanupUnescapedEnclosingQuotes(java.lang.String[] values) Utility method to trim enclosing quotes and outer whitespace from elements in an arbitrary String[] array.
void	clear() Removes all values in the field array, changing the array size to zero.
java.lang.String	get1Value(int index) Get an individual value from the existing field array.
java.lang.String[]	getPrimitiveValue() Provides current value of the field as a Java primitive type.
void	getValue(java.lang.String[] valueDestination) Get the current value of this MFStringObject by copying it into the valueDestination array, leaving the current object unchanged.
void	initialize() Initialization for MFStringObject applies default initial value.
void	insertValue(int index, java.lang.String newValue) Insert a new value prior to the index location in the existing value array, increasing the field length accordingly.
void	remove(int index) Remove one SFString element of the field array at index position, if found.
void	set1Value(int index, java.lang.String newValue) Replace a single value at the appropriate location in the existing value array.
void	setValue(int size, java.lang.String[] newValue) Assign an array subset to this field.
MFStringObject	setValue(MFStringObject newValue) Apply an MFStringObject value to this field.
MFStringObject	setValue(SFStringObject newValue) Assign a single-field SFStringObject as new array value.
void	setValue(java.lang.String[] newValue) Assign a new String[] value to this field.
MFStringObject	setValueByString(java.lang.String newValue) Utility accessor for MFStringObject using String value
int	size() Get the size of the underlying data array, meaning the number of simple SFString elements for the given data type.
java.lang.String	toString() Provides current value as a String.
static java.lang.String	toString(java.lang.String[] value) Static utility method to provide String representation of a correctly typed input value.
java.lang.String	toStringX3D() Provide String representation of this object, properly escaped for XML-based X3D syntax.

Methods inherited from class org.web3d.x3d.jsail.fields.X3DConcreteField

addX3DEventListener, getDefinition, getTupleSize, getValidationResult, isReadable, isWritable, removeX3DEventListener, setReadable, setWritable

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

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

addX3DEventListener, getDefinition, isReadable, isWritable, removeX3DEventListener

Field Detail

NAME

public static final java.lang.String NAME

String constant NAME provides name of this element: MFString.

See Also:

Constant Field Values

DEFAULT_VALUE

public static final java.lang.String[] DEFAULT_VALUE

Default value for this field type is an empty array.

See Also:

Java Tutorials: Primitive Data Types

Constructor Detail

MFStringObject

public MFStringObject()

Constructor for MFStringObject performs value initialization.

MFStringObject

public MFStringObject(MFStringObject newValue)

Constructor to copy an MFStringObject value as initial value for this new field object.

Parameters:

newValue - The newValue to apply

MFStringObject

public MFStringObject(java.lang.String[] newValue)

Constructor for MFStringObject using a corresponding Java primitive String[] array as new initial value.

Parameters:

newValue - is new value to assign setContainerFieldOverride(containerFieldName); // apply checksConcreteField#getTupleSize(String)

MFStringObject

public MFStringObject(java.lang.String newValue)

Constructor to parse String as new initial value.

Parameters:

newValue - is new value to assign

Method Detail

initialize

public void initialize()

Initialization for MFStringObject applies default initial value.

Specified by:

initialize in class X3DConcreteField

cleanupEnumerationValues

public MFStringObject cleanupEnumerationValues()

Modify current object values to ignore all whitespace, remove all embedded quotes, remove all commas, and remove all square brackets.

Returns:

MFStringObject - namely this same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).

See Also:

cleanupUnescapedEnclosingQuotes()

cleanupEnumerationValue

public static java.lang.String cleanupEnumerationValue(java.lang.String value)

Utility method for single enumeration value to ignore all whitespace, remove all embedded quotes, remove all commas, and remove all square brackets to create an unadorned enumeration String.

Parameters:

value - single enumeration string intended for use as an SFString or MFString value

Returns:

unquoted string values containing no whitespace as MFString list

See Also:

cleanupUnescapedEnclosingQuotes(String)

cleanupEnumerationValues

public static java.lang.String[] cleanupEnumerationValues(java.lang.String values)

Utility method for a single String containing multiple enumeration values to ignore all whitespace, remove all embedded quotes, remove all commas, and remove all square brackets to create unadorned MFString elements as a String[] array.

Parameters:

values - zero or more enumeration values intended for use as an MFString list

Returns:

unquoted string values containing no whitespace as MFString list

See Also:

cleanupUnescapedEnclosingQuotes(String)

cleanupEnumerationValues

public static java.lang.String[] cleanupEnumerationValues(java.lang.String[] values)

Utility method for multiple enumeration values to ignore all whitespace, remove all embedded quotes, remove all commas, and remove all square brackets in a String[] array.

Parameters:

values - zero or more enumeration values intended for use as an MFString list

Returns:

unquoted string values containing no whitespace as String[] array

See Also:

cleanupEnumerationValue(String), cleanupEnumerationValues(String), cleanupUnescapedEnclosingQuotes(String)

cleanupEnumerationValues

public static java.util.ArrayList<java.lang.String> cleanupEnumerationValues(java.util.ArrayList<java.lang.String> values)

Utility method for multiple enumeration values to ignore all whitespace, remove all embedded quotes, remove all commas, and remove all square brackets from a ArrayList of values.

Parameters:

values - zero or more enumeration values intended for use as an MFString list

Returns:

unquoted string values containing no whitespace as MFString list

See Also:

cleanupEnumerationValue(String), cleanupEnumerationValues(String), cleanupUnescapedEnclosingQuotes(String)

cleanupUnescapedEnclosingQuotes

public MFStringObject cleanupUnescapedEnclosingQuotes()

Modify current object values to trim enclosing quotes and outer whitespace.

Returns:

MFStringObject - namely this same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).

See Also:

cleanupEnumerationValues()

cleanupUnescapedEnclosingQuotes

public static java.lang.String cleanupUnescapedEnclosingQuotes(java.lang.String singleValue)

Utility method to trim enclosing quotes and outer whitespace from an arbitrary String value, without removing escaped quotation marks (\").

WARNING: do not use this method on a String that contains multiple quoted values, use cleanupEnumerationValues() instead.

Parameters:

singleValue - input String for use with MFString list, which must be unquoted

Returns:

unquoted String value

See Also:

cleanupEnumerationValue(String)

cleanupUnescapedEnclosingQuotes

public static java.lang.String[] cleanupUnescapedEnclosingQuotes(java.lang.String[] values)

Utility method to trim enclosing quotes and outer whitespace from elements in an arbitrary String[] array.

Parameters:

values - String[] array for use with MFString list, which must be unquoted

Returns:

unquoted String[] array

See Also:

cleanupUnescapedEnclosingQuotes(String), cleanupEnumerationValue(String), cleanupEnumerationValues(String)

cleanupUnescapedEnclosingQuotes

public static java.util.ArrayList<java.lang.String> cleanupUnescapedEnclosingQuotes(java.util.ArrayList<java.lang.String> values)

Utility method to trim enclosing quotes and outer whitespace from elements in an ArrayList of arbitrary String values.

Parameters:

values - existing ArrayList of String values for use with MFString list, which must be unquoted

Returns:

unquoted String[] array

See Also:

cleanupUnescapedEnclosingQuotes(String), cleanupEnumerationValue(String), cleanupEnumerationValues(String)

setValueByString

public MFStringObject setValueByString(java.lang.String newValue)
                                throws InvalidFieldValueException

Utility accessor for MFStringObject using String value

Parameters:

newValue - is new value to assign

Returns:

MFMatrix4dObject - namely this same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).

Throws:

InvalidFieldValueException

toString

public static java.lang.String toString(java.lang.String[] value)

Static utility method to provide String representation of a correctly typed input value.

Parameters:

value - The value to convert to a String

Returns:

XML/X3D-escaped String version of the provided value

See Also:

X3D Tooltips: type, SFStringObject.toStringX3D(java.lang.String), toStringX3D(), X3D Abstract Specification: 5.3.14 SFString and MFString, X3D XML Encoding: 5.15 SFString and MFString, X3D Tooltips: Text, X3D Tooltips: type

toStringX3D

public java.lang.String toStringX3D()

Provide String representation of this object, properly escaped for XML-based X3D syntax.

Returns:

XML/X3D-escaped String version of this object

See Also:

SFStringObject.toStringX3D(java.lang.String), SFStringObject.toStringX3D(String), X3D Tooltips: type

getValue

public void getValue(java.lang.String[] valueDestination)

Get the current value of this MFStringObject by copying it into the valueDestination array, leaving the current object unchanged.

Specified by:

getValue in interface MFString

Parameters:

valueDestination - The array to be filled in with current field values.

getPrimitiveValue

public java.lang.String[] getPrimitiveValue()

Provides current value of the field as a Java primitive type.

Returns:

current value

toString

public java.lang.String toString()

Provides current value as a String.

Overrides:

toString in class java.lang.Object

Returns:

String version of the provided value

See Also:

X3D Tooltips: type

get1Value

public java.lang.String get1Value(int index)

Get an individual value from the existing field array.

If the index is outside the bounds of the current array of data values, an ArrayIndexOutOfBoundsException is thrown.

Specified by:

get1Value in interface MFString

Parameters:

index - is position of selected value in current array

Returns:

The selected value

Throws:

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

setValue

public void setValue(int size,
                     java.lang.String[] newValue)

Assign an array subset to this field.

Specified by:

setValue in interface MFString

Parameters:

size - indicates size of result to copy (i.e. the number of typed singleton values) from beginning of newValue array.

newValue - The replacement value array to (potentially) slice and then assign.

See Also:

X3DConcreteField.getTupleSize(String)

setValue

public void setValue(java.lang.String[] newValue)

Assign a new String[] value to this field.

Parameters:

newValue - is replacement value array to assign

See Also:

X3DConcreteField.getTupleSize(String)

setValue

public MFStringObject setValue(SFStringObject newValue)

Assign a single-field SFStringObject as new array value.

Parameters:

newValue - The replacement value to assign.

Returns:

MFStringObject - namely this same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).

set1Value

public void set1Value(int index,
                      java.lang.String newValue)
               throws java.lang.ArrayIndexOutOfBoundsException

Replace a single value at the appropriate location in the existing value array. Size of the current underlying value array does not change.

Specified by:

set1Value in interface MFString

Parameters:

index - is position of selected value in current array

newValue - provides new value to apply

Throws:

java.lang.ArrayIndexOutOfBoundsException

See Also:

X3DConcreteField.getTupleSize(String)

append

public void append(java.lang.String newValue)

Places new value(s) at the end of the existing value array, increasing the field length accordingly.

Specified by:

append in interface MFString

Parameters:

newValue - The newValue to append

See Also:

X3DConcreteField.getTupleSize(String)

append

public void append(java.lang.String[] newValue)

Appends another array at the end of the existing value array, increasing the field length accordingly. WARNING: newValue array length must correspond to tuple size for base type MFVec4f tuple size of 4.

Parameters:

newValue - The newValue to append

See Also:

X3DConcreteField.getTupleSize(String)

append

public MFStringObject append(SFStringObject newValue)

Appends a new singleton typed value at the end of the existing value array, increasing the field length accordingly. Note: this method can be useful for incrementally constructing arrays.

Parameters:

newValue - The newValue to append

Returns:

MFStringObject - namely this same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).

append

public MFStringObject append(MFStringObject newValue)

Appends a new MFStringObject to the end of the existing value array, increasing the field length accordingly. Note: this method can be useful for constructing long arrays.

Parameters:

newValue - The newValue to append

Returns:

MFStringObject - namely this same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).

See Also:

X3DConcreteField.getTupleSize(String)

insertValue

public void insertValue(int index,
                        java.lang.String newValue)

Insert a new value prior to the index location in the existing value array, increasing the field length accordingly.

Specified by:

insertValue in interface MFString

Parameters:

index - The position for the inserted value in the current array

newValue - The newValue to insert

See Also:

X3DConcreteField.getTupleSize(String)

size

public int size()

Get the size of the underlying data array, meaning the number of simple SFString elements for the given data type.

Specified by:

size in interface MField

Returns:

The number of SFString elements in this field array.

clear

public void clear()

Removes all values in the field array, changing the array size to zero.

Specified by:

clear in interface MField

remove

public void remove(int index)

Remove one SFString element of the field array at index position, if found. Initial element is at index 0.

Specified by:

remove in interface MField

Parameters:

index - position of element in field array that gets removed

setValue

public MFStringObject setValue(MFStringObject newValue)

Apply an MFStringObject value to this field.

Parameters:

newValue - The newValue to apply

Returns:

MFStringObject - namely this same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).