[x3d-public] setUSE in X3DJSAIL
Don Brutzman
brutzman at nps.edu
Thu Jul 20 12:50:22 PDT 2017
Yes, X3DJSAIL ensures that any X3D model (or scene, or subtree) has sufficient information to serialize itself out in any of the various file encodings (XML, ClassicVRML, JSON). TODO still: .x3db and .exi.
To do this, the programmer has to be able to set values for DEF and USE in the constructed X3D object tree, just as if creating a file.
Hence setDEF()/getDEF() and setUSE()/getUSE() methods.
Example usage excerpts and result:
==================================================
http://www.web3d.org/x3d/stylesheets/java/examples/HelloWorldProgram.java
String worldInfoDEFname = "WorldInfoDEF";
WorldInfoObject worldInfoNode = new WorldInfoObject(worldInfoDEFname);
WorldInfoObject worldInfoCopy1 = new WorldInfoObject();
WorldInfoObject worldInfoCopy2 = new WorldInfoObject();
// [...]
worldInfoNode.setTitle ("HelloWorldProgram produced by X3D Java SAI Library (X3DJSAIL)");
worldInfoCopy1.setUSE(worldInfoDEFname); // setUSE via string
worldInfoCopy2.setUSE(worldInfoNode); // setUSE via node
// worldInfoCopy2.addComments("test exception at runtime"); // test sat: cannot add content to USE node
scene.addChildren(worldInfoNode);
scene.addChildren(worldInfoCopy1);
scene.addChildren(worldInfoCopy2);
==================================================
http://www.web3d.org/specifications/java/examples/HelloWorldProgramOutput.x3d
<WorldInfo DEF='WorldInfoDEF' title='HelloWorldProgram produced by X3D Java SAI Library (X3DJSAIL)'/>
<WorldInfo USE='WorldInfoDEF'/>
<WorldInfo USE='WorldInfoDEF'/>
==================================================
Furthermore, the supporting methods for each element class includes checks when invoking setDEF(String) and setUSE(String) as well as a validate() method so that a programmer cannot create a broken node (such as containing both DEF and USE simultaneously. The validate() method also reports if missing a DEF corresponding to a USE value.
This supports X3DJSAIL goals for making it easy to create an X3D scene graph using Java, while also making it hard to create an incorrect or invalid X3D model.
The following excerpt from autogenerated codes show how this is accomplished inside the X3DJSAIL library. WorldInfoObject.java attached.
==================================================
/**
* Assign String value to inputOutput SFString field named <i>DEF</i>.
* <br><br>
* <i>Tooltip:</i> DEF defines a unique ID name for this node, referenceable by other nodes. Hint: descriptive DEF names improve clarity and help document a model. Hint: well-defined names can simplify design and debugging through improved author understanding. Hint: X3D Scene Authoring Hints, Naming Conventions http://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#NamingConventions.
* <br><br>
* Note that setting the DEF value clears the USE value.
* @param newValue is new value for the DEF field.
* @return {@link WorldInfoObject} - namely <i>this</i> same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).
*/
@Override
public final WorldInfoObject setDEF(String newValue)
{
if (newValue == null)
newValue = new String();
// Check that newValue parameter meets naming requirements before assigning to WorldInfo
if (!newValue.isEmpty() && !org.web3d.x3d.jsail.fields.SFStringObject.isNMTOKEN(newValue))
{
throw new org.web3d.x3d.sai.InvalidFieldValueException("WorldInfo DEF newValue='" + newValue + "'" +
" has illegal name value, cannot be empty and must be defined with valid NMTOKEN name string" +
" (with legal characters and no embedded whitespace).");
}
setConcreteUSE(""); // ensure that no previous USE value remains
setConcreteDEF(newValue); // private superclass methods
return this;
}
==================================================
/**
* Assign String value to inputOutput SFString field named <i>USE</i>.
* <br><br>
* <i>Tooltip:</i> USE means reuse an already DEF-ed node ID, excluding all child nodes and all other attributes (except for containerField, which can have a different value). Hint: USE references to previously defined DEF geometry (instead of duplicating nodes) can improve performance. Warning: do NOT include any child nodes, a DEF attribute, or any other attribute values (except for containerField) when defining a USE attribute. Warning: each USE value must match a corresponding DEF value that is defined earlier in the scene.
* <br><br>
* <i>Note:</i> each <code>USE</code> node is still an independent object, with the <code>USE</code> value matching the <code>DEF</code> value in the preceding object.
* <br><br>
* <i>WARNING:</i> invoking the <code>setUSE()</code> method resets all other fields to their default values and also releases all child nodes.<br><br>
* <i>WARNING:</i> no other operations can be performed to modify a USE node other than setting an alternate containerField value.
* @param newValue is new value for the USE field.
* @return {@link WorldInfoObject} - namely <i>this</i> same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).
*/
@Override
public final WorldInfoObject setUSE(String newValue)
{
if (newValue == null)
newValue = new String();
// Check that newValue parameter meets naming requirements before assigning to WorldInfo
if (!newValue.isEmpty() && !org.web3d.x3d.jsail.fields.SFStringObject.isNMTOKEN(newValue))
{
throw new org.web3d.x3d.sai.InvalidFieldValueException("WorldInfo USE newValue='" + newValue + "'" +
" has illegal name value, cannot be empty and must be defined with valid NMTOKEN name string" +
" (with legal characters and no embedded whitespace).");
}
initialize(); // reset all other field values to default (equivalent to empty)
setConcreteUSE(newValue); // private superclass method
return this;
}
==================================================
/**
* Recursive method to validate this element plus all contained nodes and statements.
* @return validation results (if any)
*/
@Override
public String validate()
{
validationResult = new StringBuilder(); // prepare for updated results
setInfo(getInfo()); // exercise field checks, simple types
setTitle(getTitle()); // exercise field checks, simple types
if (!isUSE()) // be careful! setting DEF via setDEF() method will reset USE value
setDEF(getDEF()); // exercise field checks, simple types
if (isUSE()) // be careful! setting USE via setUSE() method resets all attributes to default values and wipes out all children
setUSE(getUSE()); // exercise field checks, simple types
setCssClass(getCssClass()); // exercise field checks, simple types
if (metadata != null)
{
setMetadata(getMetadata());
((X3DConcreteElement) metadata).validate(); // exercise field checks, SFNode
validationResult.append(((X3DConcreteElement) metadata).getValidationResult());
}
if (metadataProtoInstance != null)
{
setMetadata(getMetadataProtoInstance());
((X3DConcreteElement) metadataProtoInstance).validate(); // exercise field checks, SFNode
validationResult.append(((X3DConcreteElement) metadataProtoInstance).getValidationResult());
}
if ((metadata != null) && (metadataProtoInstance != null))
{
String errorNotice = "Internal X3DJSAIL error: incorrect handling of contained SFNode field, both metadata and metadataProtoInstance are set simultaneously";
validationResult.append(errorNotice);
throw new InvalidProtoException(errorNotice); // report error
}
if (isUSE() && hasMetadata()) // test USE restrictions
{
String errorNotice = "WorldInfo USE='" + getUSE() + "' is not allowed to have contained SFNode metadata";
validationResult.append(errorNotice);
throw new InvalidFieldValueException(errorNotice); // report error
}
if (isUSE() && !commentsList.isEmpty())// test USE restrictions
{
String errorNotice = "WorldInfo USE='" + getUSE() + "' is not allowed to have contained comments";
validationResult.append(errorNotice);
throw new InvalidFieldValueException(errorNotice); // report error
}
if (getIS() != null)
{
if (getIS().getConnectList().isEmpty())
{
String errorNotice = "IS statement present, but contains no connect statements";
validationResult.append(errorNotice).append("\n");
throw new InvalidProtoException(errorNotice); // report error
}
// TODO also check that this node has ancestor ProtoBody, and that a field with same name also exists, so that IS is legal
}
if (!getContainerFieldOverride().isEmpty() &&
!Arrays.asList(containerField_ALTERNATE_VALUES).contains(getContainerFieldOverride()))
{
String errorNotice = ConfigurationProperties.ERROR_ILLEGAL_VALUE +
": illegal value enountered, containerField='" + getContainerFieldOverride() +
"' but allowed values are containerField_ALTERNATE_VALUES='" +
new MFStringObject(containerField_ALTERNATE_VALUES).toStringX3D() + "'.";
validationResult.append(errorNotice).append("\n");
throw new InvalidFieldException(errorNotice); // report error
}
return validationResult.toString();
}
==================================================
On 7/20/2017 7:29 AM, Roy Walmsley wrote:
> Don and John,
>
> If we are talking about the step of writing our a file, then this is a different question.
>
> We can use the SAI methods to query the scene in memory. Methods to actually write the scene are a function of the implementation, and not a formal part of the SAI. So, while an implementation may have a setUSE method as part of the writing out interfaces, it is not a formal SAI method. It would be appropriate to indicate, perhaps in comments, those methods that are provided for the convenience of code that outputs the scene to a specific encoding.
>
> For example, I could consider the following partial algorithm for writing out a file:
>
> 1. Traverse the scene, stepping through each node, using depth first ordering
> 2. For each node:
> 1. Check if this node has already been written
> 2. If not, write out this node in full
> 3. If so, only write this node with a USE atttrbute.
>
> Thus, this function would only write out the node type and the USE attribute for step 2)c. And there would be no “resetting of values” involved.
>
> All the best,
>
> Roy
>
> *From:*John Carlson [mailto:yottzumm at gmail.com]
> *Sent:* 20 July 2017 15:06
> *To:* Roy Walmsley <roy.walmsley at ntlworld.com>; 'Don Brutzman' <brutzman at nps.edu>
> *Cc:* 'list' <x3d-public at web3d.org>
> *Subject:* RE: setUSE in X3DJSAIL
>
> Roy,
>
> I imagine setUSE was chosen because it was either an attribute in XML or property @USE in JSON, and we were translating XML and JSON to Java, Nashorn JavaScript and Python. Please provide an equivalent conversion of an X3D XML file to C,C++, or C# which does not use setUSE and uses SAI as you suggest. If you can do it, we will copy you.
>
> We would like to use chained methods with a minimum of extra variables (ideally, just one variable for whole scenegraph will do—not currently achieved). In addition, we would like to take advantage of type safety as much as possible. Please consider type safety when writing your code.
>
> There are DOM -> various languages examples you can find in X3DJSONLD/src/main/node. JavaScriptSerializer.js and JavaSerializer.js are good ones. You can use any language you want, but if you integrate with X3DJSONLD (json2all.js), it will be integrated into my test suite.
>
> It is also possible that setUSE was required in the concrete classes (not SAI that I know of) and extracting setUSE up to the interface was a good idea. I think this can be solved by providing an intermediate interface.
>
> Thanks,
>
> John
>
> Sent from Mail <https://go.microsoft.com/fwlink/?LinkId=550986> for Windows 10
>
> *From: *Roy Walmsley <mailto:roy.walmsley at ntlworld.com>
> *Sent: *Thursday, July 20, 2017 9:13 AM
> *To: *'Don Brutzman' <mailto:brutzman at nps.edu>
> *Cc: *'John Carlson' <mailto:yottzumm at gmail.com>; 'list' <mailto:x3d-public at web3d.org>
> *Subject: *setUSE in X3DJSAIL
>
> Hi Don,
>
> I note that in X3DJSAIL you have a “setUSE” method defined in all node classes. I don’t see any point of having this method.
>
> My thinking is as follows. Please correct it as necessary.
>
> X3DJSAIL is meant to be an interface for an implementation of the Java Language binding – ISO/IEC 19777-2.
>
> The SAI 19775-2 has no service related to “USE”. So it does not appear in the Java language binding.
>
> Consider that an instance of a node (say Material) has been loaded into memory and added into a scene. Then consider that further down in the scene it is desirable to implement a “USE”. What are the steps?
>
> The first would be to call the Java implementation of the SAI execution context service “getNode”, with the SAIString parameter set to the DEF name, and the SAIAction parameter set to DEFNode. In the standard ISO/IEC 19777-2 V3.0, clause 6.4.6 getNode the defined method is getNamedNode. What is your equivalent function in X3DJSAIL?
>
> Having obtained a node reference for the DEF’d node, let’s assume you also have a node reference for the node that is to be the parent of the USE node, which I will assume for this example will be Appearance.
>
> You now need to obtain a reference for the “material” field of the Appearance node. We need to use the SAI service getField, defined in 6.6.4 getField in ISO/IEC 19775-2. The Java language binding lists this as getField in clause 6.6.4 of ISO/IEC 19777-2. What is your equivalent function in X3DJSAIL?
>
> Now that we have the field reference, and the node reference to add, we can finally make a call to the SAI service setValue, defined in 6.7.6 setValue in ISO/IEC 19775-2. The Java language binding lists this as setValue in 6.7.6 of ISO/IEC 19777-2. What is your equivalent function in X3DJSAIL?
>
> Final comments relate to garbage management. The implementation will probably want some way to remember that the same node reference has been used in multiple places. That is something internal to the implementation, and not anything for the interface.
>
> So, in conclusion, I don’t see a need for your setUSE method. And it is not in the SAI.
>
> All the best,
>
> Roy
>
all the best, Don
--
Don Brutzman Naval Postgraduate School, Code USW/Br brutzman at nps.edu
Watkins 270, MOVES Institute, Monterey CA 93943-5000 USA +1.831.656.2149
X3D graphics, virtual worlds, navy robotics http://faculty.nps.edu/brutzman
-------------- next part --------------
/*
Copyright (c) 1995-2017 held by the author(s). All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer
in the documentation and/or other materials provided with the
distribution.
* Neither the name of the Web3D Consortium (http://www.web3D.org)
nor the names of its contributors may be used to endorse or
promote products derived from this software without specific
prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
*/
package org.web3d.x3d.jsail.Core;
import java.util.*;
import org.web3d.x3d.sai.*; // making sure #2
import org.web3d.x3d.jsail.fields.*; // making sure #4
import org.web3d.x3d.sai.Core.*; // interfaces for this component
import org.web3d.x3d.sai.Grouping.*;
import org.web3d.x3d.sai.Shape.*;
import org.web3d.x3d.sai.Networking.*;
import org.web3d.x3d.sai.Core.*;
import org.web3d.x3d.jsail.*; // again making sure #4
import org.web3d.x3d.jsail.Core.*;
/**
* WorldInfo contains a title and simple persistent metadata information about an X3D scene. This node is strictly for documentation purposes and has no effect on the visual appearance or behaviour of the world.
*
* <br><br>
* <i>X3D node tooltip</i>: WorldInfo contains a title and persistent documentation or simple metadata information about an X3D scene.
* <ul>
* <li> <i> Hint:</i> X3D for Web Authors, Chapter 15, Metadata Information http://x3dgraphics.com/examples/X3dForWebAuthors/Chapter15-Metadata/Chapter15-MetadataInformation.html </li>
* </ul>
* <br>
* <i>Package hint:</i> This org.web3d.x3d.jsail concrete class is used for implementing a standalone X3D object as a Plain Old Java Object (POJO).
* If you are writing Java code for use inside an X3D Script node, compile using the <i>org.web3d.x3d.sai</i> package instead.
*
* @author Don Brutzman and Roy Walmsley
* @see <a href="http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/core.html#WorldInfo" target="blank">X3D Abstract Specification: WorldInfo</a>
* @see <a href="http://www.web3d.org/x3d/tooltips/X3dTooltips.html#WorldInfo" target="_blank">X3D Tooltips: WorldInfo</a>
* @see <a href="http://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html" target="_blank">X3D Scene Authoring Hints</a>
*/
public class WorldInfoObject extends org.web3d.x3d.jsail.X3DConcreteNode implements org.web3d.x3d.sai.Core.WorldInfo
{
private ArrayList<String> commentsList; // provided since no children array present
// Member value declarations are encapsulated and private, using preferred Java types for concretes library
private ArrayList<String> info = new ArrayList<>();
private X3DMetadataObject metadata; // acceptable node types: X3DMetadataObject
private ProtoInstanceObject metadataProtoInstance; // allowed alternative for metadata field
private String title;
/** IS/connect statements might be used if this node is within a ProtoBody and connections are defined between prototype fields and built-in node fields */
private ISObject IS;
// String constants for default field values match X3D Schema definitions
/** String constant <i>NAME</i> provides name of this element: <i>WorldInfo</i>. */
@SuppressWarnings("FieldNameHidesFieldInSuperclass")
public static final String NAME = "WorldInfo";
/** Provides name of this element: WorldInfo.
* @return name of this element
*/
@Override
public final String getElementName()
{
return NAME;
}
/** MFString field named <i>info</i> has default value equal to an empty list. */
public static final ArrayList<String> INFO_DEFAULT_VALUE = new ArrayList<>(Arrays.asList());
/** SFString field named <i>title</i> has default value equal to an empty string. */
public static final String TITLE_DEFAULT_VALUE = "";
/** Indicate type corresponding to given fieldName.
* @param fieldName name of field in this X3D node
* @see ConfigurationProperties#ERROR_UNKNOWN_FIELD_TYPE
* @return X3D type (SFvec3f etc.), otherwise ConfigurationProperties.ERROR_UNKNOWN_FIELD_TYPE if not recognized
*/
@Override
public String getFieldType(String fieldName)
{
String result;
switch (fieldName)
{
// String constants for exact field type values matching X3D Schema definitions,
// thus avoiding spelling errors and allowing type-matching checks
case "containerField":
result = "SFString";
break;
case "info":
result = "MFString";
break;
case "metadata":
result = "SFNode";
break;
case "title":
result = "SFString";
break;
case "DEF":
result = "SFString";
break;
case "USE":
result = "SFString";
break;
case "class":
result = "SFString";
break;
default:
{
// if fieldName has a prefix "set_" prepended (or a suffix "_changed" appended) then try again by stripping it and recursing once
if (fieldName.trim().startsWith("set_"))
result = getFieldType(fieldName.trim().substring(4)); // after "set_"
else if (fieldName.trim().endsWith("_changed"))
result = getFieldType(fieldName.trim().substring(0, fieldName.length() - 8)); // before "_changed"
else result = ConfigurationProperties.ERROR_UNKNOWN_FIELD_TYPE; // unique return value avoids mistaken matches
}
}
return result;
}
/** Indicate accessType corresponding to given fieldName.
* @param fieldName name of field in this X3D node
* @see ConfigurationProperties#ERROR_UNKNOWN_FIELD_ACCESSTYPE
* @return X3D accessType (inputOnly etc.), otherwise ConfigurationProperties.ERROR_UNKNOWN_FIELD_ACCESSTYPE if not recognized
*/
@Override
public String getAccessType(String fieldName)
{
String result; // set by following checks
switch (fieldName)
{
// String constants for field accessType values matching X3D Schema definitions,
// thus avoiding spelling errors and allowing accessType-matching checks
case "info":
result = "inputOutput";
break;
case "metadata":
result = "inputOutput";
break;
case "title":
result = "inputOutput";
break;
case "DEF":
result = "inputOutput";
break;
case "USE":
result = "inputOutput";
break;
case "class":
result = "inputOutput";
break;
default:
{
// if user has added a prefix "set_" or suffix "_changed" then try again by stripping it and recursing once
if (fieldName.trim().startsWith("set_"))
result = getAccessType(fieldName.trim().substring(4)); // after "set_"
else if (fieldName.trim().endsWith("_changed"))
result = getAccessType(fieldName.trim().substring(0, fieldName.length() - 8)); // before "_changed"
else result = ConfigurationProperties.ERROR_UNKNOWN_FIELD_ACCESSTYPE; // unique return value avoids mistaken matches
}
}
return result;
}
/** containerField describes typical field relationship of a node to its parent.
* Usage is not ordinarily needed when using this API, default value is provided for informational purposes. */
String containerField_DEFAULT_VALUE = "children";
// String constants for field names usable in ROUTE statements
/** fromField ROUTE name for MFString field named <i>info</i>. */
public static final String fromField_INFO = "info";
/** toField ROUTE name for MFString field named <i>info</i>. */
public static final String toField_INFO = "info";
/** fromField ROUTE name for SFNode field named <i>metadata</i>. */
public static final String fromField_METADATA = "metadata";
/** toField ROUTE name for SFNode field named <i>metadata</i>. */
public static final String toField_METADATA = "metadata";
/** fromField ROUTE name for SFString field named <i>title</i>. */
public static final String fromField_TITLE = "title";
/** toField ROUTE name for SFString field named <i>title</i>. */
public static final String toField_TITLE = "title";
/** Constructor for WorldInfoObject to initialize member variables with default values. */
public WorldInfoObject()
{
super(); // constructor invocation and corresponding initialize()
initialize();
}
/** Initialize all member variables to default values. */
@Override
public final void initialize()
{
super.initialize();
containerField_ALTERNATE_VALUES = new String[] { "children" };
info = new ArrayList<>(INFO_DEFAULT_VALUE);
metadata = null; // clear out any prior node
title = TITLE_DEFAULT_VALUE;
commentsList = new ArrayList<>(); // instantiate
}
// ==== Accessor methods: strongly typed get/set methods for compile-time strictness
/**
* Provide array of String results from inputOutput MFString field named <i>info</i>.
* <br><br>
* <i>Tooltip:</i> &
* @return value of info field
*/
@Override
public String[] getInfo()
{
final String[] valuesArray = new String[info.size()];
int i = 0;
for (String arrayElement : info) {
valuesArray[i++] = arrayElement;
}
return valuesArray;
}
/**
* Utility method to get ArrayList value of MFString info field, similar to {@link #getInfo()}.
* @return value of info field
*/
public ArrayList<String> getInfoList()
{
return info;
}
/**
* Assign String array to inputOutput MFString field named <i>info</i>.
* <br><br>
* <i>Tooltip:</i> &
* @param newValue is new value for the info field.
* @return {@link WorldInfoObject} - namely <i>this</i> same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).
*/
@Override
public WorldInfoObject setInfo(String[] newValue)
{
if (newValue == null)
{
clearInfo(); // newValueNullSetDEFAULT_VALUE
return this;
}
info.clear(); // reset
for (int i = 0; i < newValue.length; i++)
{
info.add(newValue[i]);
}
return this;
}
/**
* Assign typed object value to MFString info field, similar to {@link #setInfo(String[])}.
* @param newValue is new value for the info field.
* @return {@link WorldInfoObject} - namely <i>this</i> same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).
*/
public WorldInfoObject setInfo(MFStringObject newValue)
{
if (newValue == null)
{
clearInfo(); // newValueNullSetDEFAULT_VALUE
return this;
}
setInfo(newValue.getPrimitiveValue());
return this;
}
/**
* Assign single SFString object value to MFString info field, similar to {@link #setInfo(String[])}.
* @param newValue is new value for the info field.
* @return {@link WorldInfoObject} - namely <i>this</i> same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).
*/
public WorldInfoObject setInfo(SFStringObject newValue)
{
if (newValue == null)
{
clearInfo(); // newValueNullSetDEFAULT_VALUE
return this;
}
setInfo(newValue.getValue());
return this;
}
/**
* Assign singleton String value to MFString info field, similar to {@link #setInfo(String[])}.
* @param newValue is new value for the info field.
* @return {@link WorldInfoObject} - namely <i>this</i> same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).
*/
public WorldInfoObject setInfo(String newValue)
{
if (newValue == null)
{
clearInfo(); // newValueNullSetDEFAULT_VALUE
return this;
}
info.clear();
info.add(newValue);
return this;
}
/**
* Assign ArrayList value of MFString info field, similar to {@link #setInfo(String[])}.
* @param newValue is new value for the info field.
* @return {@link WorldInfoObject} - namely <i>this</i> same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).
*/
public WorldInfoObject setInfo(ArrayList<String> newValue)
{
if (newValue == null)
{
clearInfo(); // newValueNullSetDEFAULT_VALUE
return this;
}
info = newValue;
return this;
}
/**
* Utility method to clear MFString value of info field.
* @return {@link WorldInfoObject} - namely <i>this</i> same object to allow sequential method pipelining (i.e. consecutive
setAttribute method invocations).
*/
public WorldInfoObject clearInfo()
{
info.clear(); // reset
return this;
}
/**
* Provide X3DMetadataObject instance (using a properly typed node) from inputOutput SFNode field <i>metadata</i>.
* @see #getMetadataProtoInstance()
* @see <a href="http://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#Metadata">X3D Scene Authoring Hints: Metadata Nodes</a>
* @return value of metadata field
*/
@Override
public X3DMetadataObject getMetadata()
{
return metadata;
}
/**
* Assign X3DMetadataObject instance (using a properly typed node) to inputOutput SFNode field <i>metadata</i>.
* @see #setMetadata(ProtoInstanceObject)
* @see <a href="http://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#Metadata">X3D Scene Authoring Hints: Metadata Nodes</a>
* @param newValue is new value for the metadata field.
* @return {@link WorldInfoObject} - namely <i>this</i> same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).
*/
@Override
public WorldInfoObject setMetadata(X3DMetadataObject newValue)
{
metadata = newValue;
if (newValue != null)
{
((X3DConcreteElement) metadata).setParentObject(this); // parentTest15
}
if (metadataProtoInstance != null)
{
metadataProtoInstance.setParentObject(null); // housekeeping, clear prior object
metadataProtoInstance = null;
}
return this;
}
/**
* Utility method to clear SFNode value of metadata field.
* @return {@link WorldInfoObject} - namely <i>this</i> same object to allow sequential method pipelining (i.e. consecutive
setAttribute method invocations). */
public WorldInfoObject clearMetadata()
{
((X3DConcreteElement) metadata).clearParentObject(); // remove references to facilitate Java memory management
metadata = null; // reset SFNode field
return this;
}
/**
* Assign ProtoInstance to <i>metadata</i> field;
* <i>WARNING:</i> ProtoInstance must match acceptable node type X3DMetadataObject.
* @param newProtoInstanceNode is the new ProtoInstance node for the metadata field
* @see #setMetadata(X3DMetadataObject)
* @see <a href="http://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#Metadata">X3D Scene Authoring Hints: Metadata Nodes</a>
* @return {@link WorldInfoObject} - namely <i>this</i> same object to allow sequential method pipelining (i.e. consecutive
setAttribute method invocations).
*/
public WorldInfoObject setMetadata(ProtoInstanceObject newProtoInstanceNode)
{
if (metadata != null)
{
((X3DConcreteElement) metadata).setParentObject(null); // housekeeping, clear prior object
metadata = null;
}
metadataProtoInstance = newProtoInstanceNode;
if (newProtoInstanceNode != null)
{
newProtoInstanceNode.setParentObject(this);
}
return this;
}
/**
* Provide properly typed ProtoInstance for inputOutput SFNode field <i>metadata</i>, if available.
* @see #getMetadata()
* @see <a href="http://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#Metadata">X3D Scene Authoring Hints: Metadata Nodes</a>
* @return ProtoInstance value of geometry field
*/
public ProtoInstanceObject getMetadataProtoInstance()
{
return metadataProtoInstance;
}
/**
* Indicate whether an object is available for inputOutput SFNode field <i>metadata</i>.
* @return whether a properly typed node or ProtoInstance or CommentsBlock is available.
* @see #getMetadata()
* @see #getMetadataProtoInstance()
* @see <a href="http://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#Metadata">X3D Scene Authoring Hints: Metadata Nodes</a>
*/
public boolean hasMetadata()
{
return (metadata != null) || (metadataProtoInstance != null);
}
/**
* Provide String value from inputOutput SFString field named <i>title</i>.
* <br><br>
* <i>Tooltip:</i> &
* @return value of title field
*/
@Override
public String getTitle()
{
return title;
}
/**
* Assign String value to inputOutput SFString field named <i>title</i>.
* <br><br>
* <i>Tooltip:</i> &
* @param newValue is new value for the title field.
* @return {@link WorldInfoObject} - namely <i>this</i> same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).
*/
@Override
public WorldInfoObject setTitle(String newValue)
{
if (newValue == null)
newValue = new String(); // Principle of Least Astonishment (POLA)
// https://en.wikipedia.org/wiki/Principle_of_least_astonishment
title = newValue;
return this;
}
/**
* Assign typed object value to SFString title field, similar to {@link #setTitle(String)}.
* @param newValue is new value for the title field.
* @return {@link WorldInfoObject} - namely <i>this</i> same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).
*/
public WorldInfoObject setTitle(SFStringObject newValue)
{
setTitle(newValue.getPrimitiveValue());
return this;
}
/**
* Assign String value to inputOutput SFString field named <i>DEF</i>.
* <br><br>
* <i>Tooltip:</i> DEF defines a unique ID name for this node, referenceable by other nodes. Hint: descriptive DEF names improve clarity and help document a model. Hint: well-defined names can simplify design and debugging through improved author understanding. Hint: X3D Scene Authoring Hints, Naming Conventions http://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#NamingConventions.
* <br><br>
* Note that setting the DEF value clears the USE value.
* @param newValue is new value for the DEF field.
* @return {@link WorldInfoObject} - namely <i>this</i> same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).
*/
@Override
public final WorldInfoObject setDEF(String newValue)
{
if (newValue == null)
newValue = new String();
// Check that newValue parameter meets naming requirements before assigning to WorldInfo
if (!newValue.isEmpty() && !org.web3d.x3d.jsail.fields.SFStringObject.isNMTOKEN(newValue))
{
throw new org.web3d.x3d.sai.InvalidFieldValueException("WorldInfo DEF newValue='" + newValue + "'" +
" has illegal name value, cannot be empty and must be defined with valid NMTOKEN name string" +
" (with legal characters and no embedded whitespace).");
}
setConcreteUSE(""); // ensure that no previous USE value remains
setConcreteDEF(newValue); // private superclass methods
return this;
}
/**
* Assign typed object value to SFString DEF field, similar to {@link #setDEF(String)}.
* @param newValue is new value for the DEF field.
* @return {@link WorldInfoObject} - namely <i>this</i> same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).
*/
public WorldInfoObject setDEF(SFStringObject newValue)
{
setDEF(newValue.getPrimitiveValue());
return this;
}
/**
* Assign String value to inputOutput SFString field named <i>USE</i>.
* <br><br>
* <i>Tooltip:</i> USE means reuse an already DEF-ed node ID, excluding all child nodes and all other attributes (except for containerField, which can have a different value). Hint: USE references to previously defined DEF geometry (instead of duplicating nodes) can improve performance. Warning: do NOT include any child nodes, a DEF attribute, or any other attribute values (except for containerField) when defining a USE attribute. Warning: each USE value must match a corresponding DEF value that is defined earlier in the scene.
* <br><br>
* <i>Note:</i> each <code>USE</code> node is still an independent object, with the <code>USE</code> value matching the <code>DEF</code> value in the preceding object.
* <br><br>
* <i>WARNING:</i> invoking the <code>setUSE()</code> method resets all other fields to their default values and also releases all child nodes.<br><br>
* <i>WARNING:</i> no other operations can be performed to modify a USE node other than setting an alternate containerField value.
* @param newValue is new value for the USE field.
* @return {@link WorldInfoObject} - namely <i>this</i> same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).
*/
@Override
public final WorldInfoObject setUSE(String newValue)
{
if (newValue == null)
newValue = new String();
// Check that newValue parameter meets naming requirements before assigning to WorldInfo
if (!newValue.isEmpty() && !org.web3d.x3d.jsail.fields.SFStringObject.isNMTOKEN(newValue))
{
throw new org.web3d.x3d.sai.InvalidFieldValueException("WorldInfo USE newValue='" + newValue + "'" +
" has illegal name value, cannot be empty and must be defined with valid NMTOKEN name string" +
" (with legal characters and no embedded whitespace).");
}
initialize(); // reset all other field values to default (equivalent to empty)
setConcreteUSE(newValue); // private superclass method
return this;
}
/**
* Assign typed object value to SFString USE field, similar to {@link #setUSE(String)}.
* @param newValue is new value for the USE field.
* @return {@link WorldInfoObject} - namely <i>this</i> same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).
*/
public WorldInfoObject setUSE(SFStringObject newValue)
{
setUSE(newValue.getPrimitiveValue());
return this;
}
/**
* Assign String value to inputOutput SFString field named <i>class</i>.
* <br><br>
* <i>Tooltip:</i> The class attribute is a space-separated list of classes, reserved for use by CSS cascading stylesheets. Warning: currently the class attribute is only supported in XML encoding of X3D scenes. Hint: W3C Cascading Style Sheets https://www.w3.org/Style/CSS.
* @param newValue is new value for the class field.
* @return {@link WorldInfoObject} - namely <i>this</i> same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).
*/
@Override
public final WorldInfoObject setCssClass(String newValue)
{
if (newValue == null)
newValue = new String(); // Principle of Least Astonishment (POLA)
// https://en.wikipedia.org/wiki/Principle_of_least_astonishment
setConcreteCssClass(newValue); // private superclass method
return this;
}
/**
* Assign typed object value to SFString cssClass field, similar to {@link #setCssClass(String)}.
* @param newValue is new value for the class field.
* @return {@link WorldInfoObject} - namely <i>this</i> same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).
*/
public WorldInfoObject setCssClass(SFStringObject newValue)
{
setCssClass(newValue.getPrimitiveValue());
return this;
}
// Additional utility methods for this class ==============================
/**
* Utility constructor that assigns DEF name after initializing member variables with default values
* @param DEFname unique DEF name for this X3D node
*/
public WorldInfoObject (String DEFname)
{
initialize();
setDEF(DEFname); // apply checks
}
/**
* Assign field named <i>IS</i> for establishing IS/connect field connections between ProtoInterface fields and internal ProtoBody nodes.
* The IS statement connects node fields defined inside a ProtoBody declaration back to corresponding ProtoInterface fields.
* @param newValue is new value for the description field.
* @see <a href="http://www.web3d.org/x3d/tooltips/X3dTooltips.html#IS">X3D Tooltips: IS</a>
* @see <a href="http://www.web3d.org/x3d/tooltips/X3dTooltips.html#connect">X3D Tooltips: connect</a>
* @return {@link WorldInfoObject} - namely <i>this</i> same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).
*/
@Override
public WorldInfoObject setIS(ISObject newValue)
{
if (IS != null)
IS.setParentObject(null); // housekeeping, clear prior object
IS = newValue;
IS.setParentObject(this);
return this;
}
/**
* Provide field named <i>IS</i> for establishing IS/connect field connections between ProtoInterface fields and internal ProtoBody nodes.
* The IS statement connects node fields defined inside a ProtoBody declaration back to corresponding ProtoInterface fields.
* @see <a href="http://www.web3d.org/x3d/tooltips/X3dTooltips.html#IS">X3D Tooltips: IS</a>
* @see <a href="http://www.web3d.org/x3d/tooltips/X3dTooltips.html#connect">X3D Tooltips: connect</a>
* @return current ISObject, if any.
*/
@Override
public ISObject getIS()
{
return IS;
}
/**
* Assign a USE reference to another DEF node of same node type, similar to {@link #setUSE(String)}.
* <br ><br >
* <i>WARNING:</i> note that the <code>setUSE()</code> method resets all other fields to their default values and also releases
all child nodes.
* <br><br>
* <i>WARNING.</i> no other operations can be performed to modify a USE node other than setting an alternate containerField value.
* @param DEFnode must have a DEF value defined
* @return {@link WorldInfoObject} - namely <i>this</i> same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).
*/
public WorldInfoObject setUSE(WorldInfoObject DEFnode)
{
if (DEFnode.getDEF().isEmpty())
{
String errorNotice = "setUSE(DEFnode) invoked on WorldInfoObject" +
" that has no DEF name defined, thus a copy cannot be referenced as a USE node";
validationResult.append(errorNotice).append("\n");
throw new org.web3d.x3d.sai.InvalidFieldValueException(errorNotice);
}
setUSE(DEFnode.getDEF());
return this;
}
/**
* Add comment as String to contained commentsList.
* @param newComment initial value
* @return {@link WorldInfoObject} - namely <i>this</i> same object to allow sequential method pipelining (i.e. consecutive
setAttribute method invocations).
*/
@Override
public WorldInfoObject addComments (String newComment)
{
if (isUSE())
{
String errorNotice = "addComments(\"" + newComment + "\")" + "\n" +
"cannot be applied to a USE node (USE='" + getUSE() + "') which only contains a reference to a DEF node";
validationResult.append(errorNotice).append("\n");
throw new org.web3d.x3d.sai.InvalidFieldValueException(errorNotice);
}
commentsList.add(newComment);
return this;
}
/**
* Add comments as String[] array to contained commentsList.
* @param newComments array of comments
* @return {@link WorldInfoObject} - namely <i>this</i> same object to allow sequential method pipelining (i.e. consecutive
setAttribute method invocations).
*/
@Override
public WorldInfoObject addComments (String[] newComments)
{
if (isUSE())
{
String errorNotice = "addComments(" + newComments + ")" + "\n" +
"cannot be applied to a USE node (USE='" + getUSE() + "') which only contains a reference to a DEF node";
validationResult.append(errorNotice).append("\n");
throw new org.web3d.x3d.sai.InvalidFieldValueException(errorNotice);
}
commentsList.addAll(Arrays.asList(newComments));
return this;
}
/**
* Add CommentsBlock to contained commentsList.
* @param newCommentsBlock block of comments to add
* @return {@link WorldInfoObject} - namely <i>this</i> same object to allow sequential method pipelining (i.e. consecutive
setAttribute method invocations).
*/
@Override
public WorldInfoObject addComments (CommentsBlock newCommentsBlock)
{
if (isUSE())
{
String errorNotice = "addComments(CommentsBlock) " +
"cannot be applied to a USE node (USE='" + getUSE() + "') which only contains a reference to a DEF node";
validationResult.append(errorNotice).append("\n");
throw new org.web3d.x3d.sai.InvalidFieldValueException(errorNotice);
}
commentsList.addAll(newCommentsBlock.toStringList());
return this;
}
/**
* Recursive method to provide X3D string serialization of this model subgraph.
* @param level number of levels of indentation for this element
* @return X3D string
*/
@Override
public String toStringX3D(int level)
{
boolean hasAttributes = true; // TODO check for non-default attribute values
boolean hasChild = (IS != null) || (metadata != null) || (metadataProtoInstance != null) || !commentsList.isEmpty();
if (isUSE())
hasChild = false; // USE nodes only include attributes for USE and non-default containerField
StringBuilder indent = new StringBuilder();
int indentIncrement = ConfigurationProperties.getIndentIncrement();
char indentCharacter = ConfigurationProperties.getIndentCharacter();
for (int i = 0; i < (level * indentIncrement); i++)
indent.append(indentCharacter); // level of indentation for this level
StringBuilder stringX3D = new StringBuilder();
stringX3D.append(indent).append("<WorldInfo"); // start opening tag
if (hasAttributes)
{
if (!getDEF().equals(DEF_DEFAULT_VALUE) && !isUSE())
{
stringX3D.append(" DEF='").append(SFStringObject.toString(getDEF())).append("'");
}
if (!getUSE().equals(USE_DEFAULT_VALUE))
{
stringX3D.append(" USE='").append(SFStringObject.toString(getUSE())).append("'");
}
if (!getContainerFieldOverride().isEmpty() && !getContainerFieldOverride().equals(containerField_DEFAULT_VALUE))
{
stringX3D.append(" containerField='").append(getContainerFieldOverride()).append("'");
}
if (((getInfo().length > 0) || ConfigurationProperties.isShowDefaultAttributes()) && !isUSE())
{
stringX3D.append(" info='").append(new MFStringObject(getInfo()).toStringX3D()).append("'");
}
if ((!getTitle().equals(TITLE_DEFAULT_VALUE) || ConfigurationProperties.isShowDefaultAttributes()) && !isUSE())
{
stringX3D.append(" title='").append(new SFStringObject(getTitle()).toStringX3D()).append("'");
}
if ((!getCssClass().equals(CLASS_DEFAULT_VALUE) || ConfigurationProperties.isShowDefaultAttributes()) && !isUSE())
{
stringX3D.append(" class='").append(new SFStringObject(getCssClass()).toStringX3D()).append("'");
}
}
if ((hasChild) && !isUSE()) // has contained node(s), comment(s), IS/connect and/or source code
{
stringX3D.append(">").append("\n"); // finish opening tag
if (getIS() != null)
stringX3D.append(getIS().toStringX3D(level + indentIncrement));
// recursively iterate over child element
if (metadata != null)
{
stringX3D.append(((X3DConcreteElement)metadata).toStringX3D(level + indentIncrement));
}
else if (metadataProtoInstance != null)
{
stringX3D.append(((X3DConcreteElement)metadataProtoInstance).toStringX3D(level + indentIncrement));
}
if (!commentsList.isEmpty())
{
CommentsBlock commentsBlock = new CommentsBlock(commentsList);
stringX3D.append(commentsBlock.toStringX3D(level + indentIncrement));
}
stringX3D.append(indent).append("</WorldInfo>").append("\n"); // finish closing tag
}
else
{
stringX3D.append("/>").append("\n"); // otherwise finish singleton tag
}
return stringX3D.toString();
}
/**
* Recursive method to provide ClassicVRML string serialization.
* @param level number of levels of indentation for this element
* @see <a href="http://www.web3d.org/x3d/content/examples/X3dResources.html#VRML">X3D Resources: Virtual Reality Modeling Language (VRML) 97</a>
* @see <a href="http://www.web3d.org/documents/specifications/19776-2/V3.3/Part02/grammar.html">Extensible 3D (X3D) encodings Part 2: Classic VRML encoding, Annex A: Grammar</a>
* @return ClassicVRML string
*/
@Override
public String toStringClassicVRML(int level)
{
StringBuilder stringClassicVRML = new StringBuilder();
boolean hasAttributes = true; // TODO further refinement
boolean hasChild = (IS != null) || (metadata != null) || (metadataProtoInstance != null) || !commentsList.isEmpty();
if (isUSE())
{
hasAttributes = false;
hasChild = false; // USE nodes include no other fields
}
StringBuilder indent = new StringBuilder();
char indentCharacter = ConfigurationProperties.getIndentCharacter();
int indentIncrement = ConfigurationProperties.getIndentIncrement();
for (int i = 0; i < (level * indentIncrement); i++)
indent.append(indentCharacter); // level of indentation for this level
if (!getDEF().equals(DEF_DEFAULT_VALUE))
{
stringClassicVRML.append("DEF ").append(SFStringObject.toString(getDEF())).append(" ");
}
if (!getUSE().equals(USE_DEFAULT_VALUE))
{
stringClassicVRML.append("USE ").append(SFStringObject.toString(getUSE())).append("\n");
}
else // only have further output if not a USE node
{
stringClassicVRML.append("WorldInfo").append(" { "); // define node name, node content follows
if (hasAttributes || hasChild)
{
stringClassicVRML.append("\n").append(indent).append(indentCharacter); // fields for this node follow
}
if (hasAttributes)
{
boolean hasISconnect = (getIS() != null) && !getIS().getConnectList().isEmpty();
if (hasISconnect)
{
for (connectObject element : getIS().getConnectList())
{
if (element.getNodeField().equals("info"))
{
stringClassicVRML.append(indentCharacter).append("info").append(" IS ").append(element.getProtoField()).append("\n").append(indent).append(indentCharacter); // found matching connect
}
}
}
else
if (getInfo().length > 0)
{
stringClassicVRML.append("info ").append("[ ").append(MFStringObject.toString(getInfo())).append(" ]").append("\n").append(indent).append(indentCharacter);
}
if (hasISconnect)
{
for (connectObject element : getIS().getConnectList())
{
if (element.getNodeField().equals("title"))
{
stringClassicVRML.append(indentCharacter).append("title").append(" IS ").append(element.getProtoField()).append("\n").append(indent).append(indentCharacter); // found matching connect
}
}
}
else
if (!getTitle().equals(TITLE_DEFAULT_VALUE) || ConfigurationProperties.isShowDefaultAttributes())
{
stringClassicVRML.append("title ").append("\"").append(SFStringObject.toString(getTitle())).append("\"").append("\n").append(indent).append(indentCharacter);
}
if (hasISconnect)
{
for (connectObject element : getIS().getConnectList())
{
if (element.getNodeField().equals("class"))
{
stringClassicVRML.append(indentCharacter).append("class").append(" IS ").append(element.getProtoField()).append("\n").append(indent).append(indentCharacter); // found matching connect
}
}
}
else
if (!getCssClass().equals(CLASS_DEFAULT_VALUE) || ConfigurationProperties.isShowDefaultAttributes())
{
stringClassicVRML.append("# class ").append("\"").append(SFStringObject.toString(getCssClass())).append("\"").append("\n").append(indent).append(indentCharacter);
}
}
}
if (hasChild) // has contained node(s), comment(s), IS/connect and/or source code
{
// recursively iterate over child element
if (metadata != null)
{
stringClassicVRML.append(indentCharacter).append("metadata").append(" "); // containerField for SFNode
stringClassicVRML.append(((X3DConcreteElement) metadata).toStringClassicVRML(level + indentIncrement));
stringClassicVRML.append(indent); // end SFNode
}
else if (metadataProtoInstance != null)
{
stringClassicVRML.append(indentCharacter).append("metadata").append(" "); // containerField for SFNode
stringClassicVRML.append(((X3DConcreteElement) metadataProtoInstance).toStringClassicVRML(level + indentIncrement));
stringClassicVRML.append(indent); // end SFNode ProtoInstance
}
if (!commentsList.isEmpty())
{
CommentsBlock commentsBlock = new CommentsBlock(commentsList);
stringClassicVRML.append(commentsBlock.toStringClassicVRML(level));
stringClassicVRML.append(indent); // end SFNode
}
}
if (hasAttributes || hasChild)
{
stringClassicVRML.append("}").append("\n"); // finish node content
}
return stringClassicVRML.toString();
}
/**
* Recursive method to provide VRML97 string serialization.
* @param level number of levels of indentation for this element
* @see <a href="http://www.web3d.org/x3d/content/examples/X3dResources.html#VRML">X3D Resources: Virtual Reality Modeling Language (VRML) 97</a>
* @see <a href="http://www.web3d.org/documents/specifications/14772/V2.0/index.html">Virtual Reality Modeling Language (VRML) 97 specification</a>
* @see <a href="http://www.web3d.org/documents/specifications/14772-1/V2.1/index.html">VRML 97 v2.1 Amendment</a>
* @return VRML97 string
*/
@Override
public String toStringVRML97(int level)
{
return toStringClassicVRML(level);
}
/**
* Recursive method to provide object reference to node by DEF name, if found as this node or in a contained node.
* @param DEFname DEF name of node to find
* @return object reference to node
*/
@Override
public X3DConcreteNode getNodeByDEF(String DEFname)
{
X3DConcreteNode referenceNode;
if (getDEF().equals(DEFname))
return this;
if (metadata != null)
{
referenceNode = ((X3DConcreteNode) metadata).getNodeByDEF(DEFname); // SFNode
if (referenceNode != null)
return referenceNode;
}
return null; // not found, in this node or in children nodes
}
/**
* Recursive method to provide object reference to node or statement by name attribute, if found as part of this element or in a contained element.
* Elements with name fields include meta, Metadata* nodes, field/fieldValue, ProtoDeclare/ExternProtoDeclare/ProtoInstance, HAnim nodes.
* <br ><br >
* <i>WARNING:</i> more than one element may be found that has the same name, this method does not handle that case.
* @param nameValue is value of the name field being searched for in this element and child elements(if any)
* @return object reference to found element, null otherwise
* @see #findNodeByDEF(String)
*/
@Override
public X3DConcreteElement findElementByNameValue(String nameValue)
{
return findElementByNameValue(nameValue, ""); // empty string is wildcard, any element match is allowed
}
/**
* Recursive method to provide object reference to node or statement by name attribute, if found as part of this element or in a contained element.
* Elements with name fields include meta, Metadata* nodes, field/fieldValue, ProtoDeclare/ExternProtoDeclare/ProtoInstance, HAnim nodes.
* <br ><br >
* <i>WARNING:</i> more than one element may be found that has the same name, this method does not handle that case.
* @param nameValue is value of the name field being searched for in this element and child elements(if any)
* @param elementName identifies the element of interest (meta MetadataString ProtoDeclare CADassembly ProtoInstance HAnimHumanoid etc.)
* @return object reference to found element, null otherwise
* @see #findNodeByDEF(String)
*/
@Override
public X3DConcreteElement findElementByNameValue(String nameValue, String elementName)
{
if ((nameValue == null) || nameValue.isEmpty())
{
String errorNotice = "findElementByNameValue(\"\", " + elementName + ") cannot use empty string to find a name attribute";
validationResult.append(errorNotice).append("\n");
throw new org.web3d.x3d.sai.InvalidFieldValueException(errorNotice);
}
// no name field available for this element
X3DConcreteElement referenceElement;
if (metadata != null)
{
referenceElement = ((X3DConcreteElement) metadata).findElementByNameValue(nameValue, elementName);
if (referenceElement != null)
return referenceElement;
}
if (metadataProtoInstance != null)
{
referenceElement = ((X3DConcreteElement) metadataProtoInstance).findElementByNameValue(nameValue, elementName);
if (referenceElement != null)
return referenceElement;
}
return null; // not found
}
/**
* Recursive method to determine whether node or statement with given name attribute is found, meaning both objects are attached to same scene graph.
* @param nameValue is value of the name field being searched for in this element and child elements(if any)
* @param elementName identifies the element of interest (meta MetadataString ProtoDeclare CADassembly ProtoInstance HAnimHumanoid etc.)
* @see #findElementByNameValue(String, String)
* @return whether node is found
*/
public boolean hasElementByNameValue(String nameValue, String elementName)
{
return (findElementByNameValue(nameValue, elementName) != null);
}
/**
* Recursive method to provide object reference to node by DEF, if found as this node or in a contained node.
* <br ><br >
* <i>WARNING:</i> more than one element may be found that has the same DEF, this method does not handle that case.
* @param DEFvalue is value of the name field being searched for in this element and child elements(if any)
* @return object reference to found node, null otherwise
* @see #findElementByNameValue(String)
*/
@Override
public X3DConcreteNode findNodeByDEF(String DEFvalue)
{
if ((DEFvalue == null) || DEFvalue.isEmpty())
{
String errorNotice = "findNodeByDEF(\"\") cannot use empty string to find a name";
validationResult.append(errorNotice).append("\n");
throw new org.web3d.x3d.sai.InvalidFieldValueException(errorNotice);
}
if (getDEF().equals(DEFvalue))
return this;
X3DConcreteNode referenceNode;
if (metadata != null)
{
referenceNode = ((X3DConcreteElement) metadata).findNodeByDEF(DEFvalue);
if (referenceNode != null)
return referenceNode;
}
return null; // not found
}
/**
* Recursive method to determine whether node with DEFvalue is found, meaning both objects are attached to same scene graph.
* @param DEFvalue is value of the name field being searched for in this element and child elements(if any)
* @see #findNodeByDEF(String)
* @return whether node is found
*/
public boolean hasNodeByDEF(String DEFvalue)
{
return (findNodeByDEF(DEFvalue) != null);
}
/**
* Recursive method to validate this element plus all contained nodes and statements.
* @return validation results (if any)
*/
@Override
public String validate()
{
validationResult = new StringBuilder(); // prepare for updated results
setInfo(getInfo()); // exercise field checks, simple types
setTitle(getTitle()); // exercise field checks, simple types
if (!isUSE()) // be careful! setting DEF via setDEF() method will reset USE value
setDEF(getDEF()); // exercise field checks, simple types
if (isUSE()) // be careful! setting USE via setUSE() method resets all attributes to default values and wipes out all children
setUSE(getUSE()); // exercise field checks, simple types
setCssClass(getCssClass()); // exercise field checks, simple types
if (metadata != null)
{
setMetadata(getMetadata());
((X3DConcreteElement) metadata).validate(); // exercise field checks, SFNode
validationResult.append(((X3DConcreteElement) metadata).getValidationResult());
}
if (metadataProtoInstance != null)
{
setMetadata(getMetadataProtoInstance());
((X3DConcreteElement) metadataProtoInstance).validate(); // exercise field checks, SFNode
validationResult.append(((X3DConcreteElement) metadataProtoInstance).getValidationResult());
}
if ((metadata != null) && (metadataProtoInstance != null))
{
String errorNotice = "Internal X3DJSAIL error: incorrect handling of contained SFNode field, both metadata and metadataProtoInstance are set simultaneously";
validationResult.append(errorNotice);
throw new InvalidProtoException(errorNotice); // report error
}
if (isUSE() && hasMetadata()) // test USE restrictions
{
String errorNotice = "WorldInfo USE='" + getUSE() + "' is not allowed to have contained SFNode metadata";
validationResult.append(errorNotice);
throw new InvalidFieldValueException(errorNotice); // report error
}
if (isUSE() && !commentsList.isEmpty())// test USE restrictions
{
String errorNotice = "WorldInfo USE='" + getUSE() + "' is not allowed to have contained comments";
validationResult.append(errorNotice);
throw new InvalidFieldValueException(errorNotice); // report error
}
if (getIS() != null)
{
if (getIS().getConnectList().isEmpty())
{
String errorNotice = "IS statement present, but contains no connect statements";
validationResult.append(errorNotice).append("\n");
throw new InvalidProtoException(errorNotice); // report error
}
// TODO also check that this node has ancestor ProtoBody, and that a field with same name also exists, so that IS is legal
}
if (!getContainerFieldOverride().isEmpty() &&
!Arrays.asList(containerField_ALTERNATE_VALUES).contains(getContainerFieldOverride()))
{
String errorNotice = ConfigurationProperties.ERROR_ILLEGAL_VALUE +
": illegal value enountered, containerField='" + getContainerFieldOverride() +
"' but allowed values are containerField_ALTERNATE_VALUES='" +
new MFStringObject(containerField_ALTERNATE_VALUES).toStringX3D() + "'.";
validationResult.append(errorNotice).append("\n");
throw new InvalidFieldException(errorNotice); // report error
}
return validationResult.toString();
}
}
More information about the x3d-public
mailing list