[x3d-public] X3DJSAIL: Desired chaining methods. Modify return value or provide new method.

[Don Brutzman]

This turns out to be trickier than first suspected.  The conflicting issue is that the legacy SAI methods use a pattern that returns void (i.e. no value) instead of a copy of the object for subsequent method pipelining.

So instead of modifying the existing methods, I added "append" methods that take a single child for appending to the subject array.

http://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/HAnim/HAnimHumanoidObject.html#method.summary

HAnimHumanoidObject 	appendJoints(HAnimJoint newValue)
			Append single child joints node to array of existing nodes (if any).
HAnimHumanoidObject 	appendSegments(HAnimSegment newValue)
			Append single child segments node to array of existing nodes (if any).
HAnimHumanoidObject 	appendSites(HAnimSite newValue)
			Append single child sites node to array of existing nodes (if any).
HAnimHumanoidObject 	appendSkeleton(X3DNode newValue)
			Append single child skeleton node to array of existing nodes (if any).
HAnimHumanoidObject 	appendSkin(X3DChildNode newValue)
			Append single child skin node to array of existing nodes (if any).
HAnimHumanoidObject 	appendViewpoints(HAnimSite newValue)
			Append single child viewpoints node to array of existing nodes (if any).

Similar methods appear elsewhere for appending a single node to an MFNode array field.

For clarity and to have a consistent pattern (which helps code generators like yours)
we should probably change utility methods like "addChild" to "appendChild" throughout.
What do you think?

Specification considerations noted as follows:

X3dJavaSpecificationChangesAndIssues.txt                             14 March 2017
http://www.web3d.org/x3d/stylesheets/java/X3dJavaSpecificationChangesAndIssues.txt
============================================================
3. SFNode/MFNode return types void

Numerous interface return types are void, preventing a method from returning the
current object from returning a copy of itself to permit method pipelining.

Various utility methods have been added (typically named append* instead of add*)
in order to circumvent this restriction.

Need to consider changing SFNode/MFNode return signatures to support pipelining.
Of note is that a method returning a null value is essentially the same as a
void return, so no loss of functionality seems involved with this approach.

============================================================
On 3/10/2017 1:14 PM, yottzumm at gmail.com wrote:
> Maybe all these methods of HAnimHumanoiObject should return an HAnimHumanoidObject for chaining:
>
>
>
>         public void addJoints(HAnimJoint newValue)
>
>         public void addJoints(X3DNode[] newValue)
>
>         public void addSegments(HAnimSegment newValue)
>
>         public void addSegments(X3DNode[] newValue)
>
>         public void addSites(HAnimSite newValue)
>
>         public void addSites(X3DNode[] newValue)
>
>        public void addSkeleton(X3DNode newValue)
>
>         public void addSkeleton(X3DNode[] newValue)
>
>         public void addSkin(X3DChildNode newValue)
>
>         public void addSkin(X3DNode[] newValue)
>
>         public void addViewpoints(HAnimSite newValue)
>
>         public void addViewpoints(X3DNode[] newValue)
>
> John

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