X3dJavaSpecificationChangesAndIssues.txt                             14 March 2017

http://www.web3d.org/x3d/stylesheets/java/X3dJavaSpecificationChangesAndIssues.txt

Terminology:
- singleton array types are MFBool, MFInt32, MFDouble, MFFloat, MFString, MFNode
  since each element in the array is a singleton value (as opposed to float[3] for MFColor, etc.)

Once this implementation-based review is complete, issues will be discussed and
entered into the Web3D Consortium Mantis Issues database.

Feedback and discussion is always welcome.
mailto:x3d-public@web3D.org
http://www.web3d.org/x3d/content/examples/X3dResources.html#Feedback

============================================================
1. Specification errors
============================================================

B.1.3 Conventions
http://www.web3d.org/documents/specifications/19777-2/V3.0/Part2/abstracts.html#Conventions

change InvalidFieldValue to InvalidFieldValueException

bullet list is more useful if alphabetic

============================================================
B.4 FieldInterfaces
http://www.web3d.org/documents/specifications/19777-2/V3.0/Part2/abstracts.html#FieldInterfaces

naming clarity: see updates to various parameter names to better indicate their purpose

	value to newValue
	value to destinationValue

============================================================
B.4.5 X3DField
http://www.web3d.org/documents/specifications/19777-2/V3.0/Part2/abstracts.html#X3DField

Interface methods need to be omitted for UserData, which is undefined anywhere else in the Abstract SAI or Java SAI specifications.
    public void   setUserData(Object data);
    public Object getUserData();

============================================================
B.4.6 MField

indicate that index-dependent method may throw exception:

    public void remove(int index);
to
    public boolean remove(int index)
        throws ArrayIndexOutOfBoundsException;

============================================================
B.4.14 MFDouble
http://www.web3d.org/documents/specifications/19777-2/V3.0/Part2/abstracts.html#MFDouble

append and insertValue methods should take a singleton parameter like other singleton-type methods:

    public void append(double[] value);
to
    public void append(double value);

and
    public void insertValue(double[] value);
to
    public void insertValue(double value);

Similarly changes for MFFloat, MFInt32, MFString

============================================================
B.4.8 MFBool
http://www.web3d.org/documents/specifications/19777-2/V3.0/Part2/abstracts.html#MFBool

indicate that index-dependent methods may throw exception:

    public boolean get1Value(int index);
to
    public boolean get1Value(int index)
        throws ArrayIndexOutOfBoundsException;

Similarly changes for
	MFColor, MFColorRGBA, MFNode, MFRotation, MFString, MFTime, 
	MFVec2d, MFVec2f, MFVec3d, MFVec3f

============================================================
B.4.17 SFImage
http://www.web3d.org/documents/specifications/19777-2/V3.0/Part2/abstracts.html#SFImage

Missing exception declarations? consider adding

	throws InvalidFieldValueException;

to get accessors

============================================================
B.4.18 MFImage
http://www.web3d.org/documents/specifications/19777-2/V3.0/Part2/abstracts.html#SFImage

Missing exceptions:

============================================================
2. Specification additions
============================================================
a. Missing matrix types.

Need to add sections in B.4 Field interfaces:
- SFMatrix3d, MFMatrix3d, SFMatrix3f and MFMatrix3f
- SFMatrix4d, MFMatrix4d, SFMatrix4f and MFMatrix4f

These will extend the following Service Interfaces, respectively.

b. B.5.4 Matrix3
http://www.web3d.org/documents/specifications/19777-2/V3.0/Part2/abstracts.html#Matrix3

Matrix3 need to be an interface rather than class because multiple inheritance
is not permissible in Java, types must already extend the X3DFieldImpl class.
Also need to fix tabs on first two entries and append semicolons to the remaining entries.
TODO: needs to be included in abstract interface definitions.
TODO: remove constructor from specification interface.
TODO: modify method, refactor into appropriate subclasses:
    public void set(int row, int column)
into
    public void set(int row, int column, float newValue);
and
    public void set(int row, int column, double newValue);

also the get(int row, int column) interface needs to be double (rather than float) for Matrix3d Matrix4d types

B.5.5 Matrix4
http://www.web3d.org/documents/specifications/19777-2/V3.0/Part2/abstracts.html#Matrix

Does Matrix4 need to be an interface or abstract class, rather than class?
Also need to fix tabs on first two entries and append semicolons to the remaining entries.

TODO: needs to be included in abstract interface definitions.
TODO: remove constructor from specification interface.
TODO: modify method, refactor into appropriate subclasses:
    public void set(int row, int column)
as above as described for Matrix3.

Shared issues for Matrix3 and Matrix4:
- TODO Data types for translation, scale fields:
	change SFVec2f to SFVec3f, SFVec2d to SFVec3d
- TODO Data types for rotation, scaleOrientation fields:
	change SFVec3f, SFVec3d to SFRotation
- TODO Matrix4 operator methods should return Matrix4 result, not Matrix3:
	inverse(), transpose(), multiplyLeft, multiplyRight, multiplyRowVector, multiplyColVector
- TODO 3d/3f/4d/4f typed methods need to be shifted to corresponding interfaces
	SFMatrix3d, SFMatrix3f, SFMatrix4d, SFMatrix4f
- the get(int row, int column) interface needs to be double (rather than float) for Matrix3d Matrix4d types

============================================================

3. Specification concerns for consideration

============================================================

a. setValue() methods with size parameter have multiple failure modes at run time.

Example:
	public void setValue(int size, double[] newValue);

- size might be too big,   thus need ArrayIndexOutOfBoundsException.
- size might be too small, thus need ArrayIndexOutOfBoundsException.
- size is artificial, the field array already has a length.
- size is ambiguous:  size of X3D array (e.g. 3 SFColors in an MFColor) or size of java array (9 floats)?
- need to check size of newValue if copying values back out to user program?

Probably should be deprecated.  Relates to following issue as well.

============================================================
b. setValue() methods with no size parameter support more likely usage and also
   are more reliable.

Example:
	public void setValue(double[] newValue);

- Need to be included in specification API, likely as default.
- Added as utility method in concretes library.

============================================================
c. B.5.4 Matrix3, B.5.5 Matrix4
http://www.web3d.org/documents/specifications/19777-2/V3.0/Part2/abstracts.html#Matrix3
http://www.web3d.org/documents/specifications/19777-2/V3.0/Part2/abstracts.html#Matrix4

The following methods always take SFVec3f parameters, should there also be
	SFVec3d methods for double-precision matrices?

    public Matrix3 multiplyRowVector(SFVec3f vec)
    public Matrix3 multiplyColVector(SFVec3f vec)

============================================================
d. Consider inserting new interface X3DMetadataNode

following X3DMaterialNode:

B.2.20.5 X3DMetadataNode
http://www.web3d.org/documents/specifications/19777-2/V3.0/Part2/abstracts.html#X3DMetadataNode

public interface X3DMetadataNode extends X3DNode {
}

Not yet clear how to add X3DMetadataNode for consistency while correctly integrating X3DMetadataObject

============================================================
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.

============================================================