[x3d-public] announce: X3DJSAIL updated release, improved immutability and testing documentation

[Don Brutzman]

Further work has resulted in another update release of a valuable
open-source software library.

*X3DJSAIL, the X3D Java Scene Access Interface Library (X3DJSAIL)*

   - X3D Java Scene Access Interface Library (X3DJSAIL) supports
   programmers with standards-based X3D Java interfaces and objects, all as
   open source.
   - https://www.web3d.org/specifications/java/X3DJSAIL.html
   - X3DJSAIL is designed to make it easy for Java programmers to create
   high-quality X3D models, perform conversions, and launch tools.  The
   combined strictness of Java, XML, and the X3D architecture means it is
   actually quite difficult to create an invalid X3D model.

Multiple improvements are included in this X3DJSAIL release, notably:

   - X3DJSAIL, Utility Methods and Functionality
   - https://www.web3d.org/specifications/java/X3DJSAIL.html#UtilityMethods


>    - *Complete.* Checks for optional/required MFString enumeration pairs
>    are much improved, for examples see source for fields Layout.align
>    <https://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/Layout/Layout.html#setAlign(java.lang.String%5B%5D)>
>     (tooltip
>    <https://www.web3d.org/x3d/content/X3dTooltips.html#Layout.align>) and
>    NavigationInfo.type
>    <https://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/Navigation/NavigationInfo.html#setType(java.lang.String%5B%5D)>
>     (tooltip
>    <https://www.web3d.org/x3d/content/X3dTooltips.html#NavigationInfo.type>
>    ).
>
>
>    - *Complete*. Added MFString utility methods for hasDuplicateValues()
>    <https://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/fields/MFString.html#hasDuplicateValues()>
>     and removeDuplicateValues()
>    <https://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/fields/MFString.html#removeDuplicateValues()>.
>    Model authors programming with X3DJSAIL are also prevented from adding
>    illegal duplicate values for special MFString enumeration fields, such as
>    FontStyle.addFamily(newValue)
>    <https://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/Text/FontStyle.html#addFamily(java.lang.String)>,
>    while while still allowing addition of duplicate values for other fields
>    (such as Text.addString(newValue)
>    <https://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/Text/Text.html#addString(java.lang.String)>
>    .
>
> I have added a Testing section to describe all the detailed attention
being paid to correct library operation.

   - X3DJSAIL, Testing
   - https://www.web3d.org/specifications/java/X3DJSAIL.html#Testing

Comprehensive testing is performed during X3DJSAIL codebase development.
> Building a test suite is essential for ensuring that unintended "side
> effects" and problems don't emerge during the evolution of a sophisticated
> software library.
> Smoke testing <https://en.wikipedia.org/wiki/Smoke_testing_(software)> confirms
> correct operation of new features using a single example program.
>
>    - SmokeTestProgram.java
>    <https://www.web3d.org/specifications/java/examples/SmokeTestProgram.java> source
>    exercises many X3DJSAIL features, with execution results shown by
>    build.test.X3DJSAIL.txt
>    <https://www.web3d.org/specifications/java/build.test.X3DJSAIL.txt>.
>
>
>    - Program-generated outputs include X3D model
>    <https://www.web3d.org/specifications/java/examples/SmokeTestProgramOutput.x3d>
>    , ClassicVRML model
>    <https://www.web3d.org/specifications/java/examples/SmokeTestProgramOutput.x3dv>
>    , VRML97 model
>    <https://www.web3d.org/specifications/java/examples/SmokeTestProgramOutput.wrl>
>    , JSON encoding
>    <https://www.web3d.org/specifications/java/examples/SmokeTestProgramOutput.json>
>    , Java source
>    <https://www.web3d.org/specifications/java/examples/SmokeTestProgramOutput.java>
>    , Python source
>    <https://www.web3d.org/specifications/java/examples/SmokeTestProgramOutput.py>
>    , X3DOM scene page
>    <https://www.web3d.org/specifications/java/examples/SmokeTestProgramOutputX3dom.xhtml>
>    , X_ITE scene page
>    <https://www.web3d.org/specifications/java/examples/SmokeTestProgramOutputX_ITE.html>
>
>
>    - A screenshot image
>    <https://www.web3d.org/specifications/java/examples/images/HelloWorldProgramOutput.png>
>     and movie
>    <https://www.web3d.org/specifications/java/examples/images/HelloWorldProgramOutput.mp4> were
>    produced during early versions of program outputs.
>
>
>    - Concise autogenerated java source produces a nearly identical X3D
>    scene-graph program: SmokeTestProgramOutput.java
>    <https://www.web3d.org/specifications/java/examples/SmokeTestProgramOutput.java>
>
>
>    - Stylesheet-generated pretty-print X3D model documentation
>    <https://www.web3d.org/specifications/java/examples/SmokeTestProgramOutput.html>
>
> Round-trip engineering (RTE)
> <https://en.wikipedia.org/wiki/Round-trip_engineering> is another
> excellent test methodology to help confirm full coverage of capabilities.
>
>    - SmokeTestProgramOutput.java
>    <https://www.web3d.org/specifications/java/examples/SmokeTestProgramOutput.java> shows
>    full round-trip conversion from original .java, to .x3d export, to .java
>    source-code serialization.
>
>
>    - Conversions are performed using X3D.toFileJava(filename)
>    <https://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/Core/X3D.html#toFileJava(java.lang.String)>,
>    and the X3dToJava.xslt
>    <https://www.web3d.org/specifications/java/lib/stylesheets/X3dToJava.xslt>
>     stylesheets.
>
>
>    - Export of ClassicVRML .x3dv versions using
>    X3D.toFileClassicVRML(filename)
>    <https://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/Core/X3D.html#toFileClassicVRML(java.lang.String)> are
>    subsequently checked for correct syntax using the Castle Model
>    Converter <https://castle-engine.io/castle-model-converter> and Castle
>    Model Viewer <https://castle-engine.io/castle-model-viewer>.
>
> Unit testing <https://en.wikipedia.org/wiki/Unit_testing> performs
> low-level checks on specific software methods to demonstrate correct
> performance of expected behavior.
>
>    - FieldObjectTests.java
>    <https://sourceforge.net/p/x3d/code/HEAD/tree/www.web3d.org/x3d/stylesheets/java/tests/org/web3d/x3d/tests/FieldObjectTests.java> provides
>    hundreds of tests for each of the of SF/MF field methods and capabilities.
>
>
>    - This program is also useful for exploring how to correctly invoke a
>    large variety of methods in the X3DJSAIL library.
>
>  Examples galore
> <https://www.web3d.org/specifications/java/X3DJSAIL.html#Examples>!
>
>    - Generation, compilation, and execution of thousands of example X3D
>    models effectively provides a gigantic test suite for X3DJSAIL.
>
> Problems can be discussed on x3d-public at web3d.org
> <https://www.web3d.org/mailman/listinfo/x3d-public_web3d.org> mailing
> list (archives <https://web3d.org/pipermail/x3d-public_web3d.org>) and
> reported on SourceForge tickets list
> <https://sourceforge.net/p/x3d/tickets>.
> Issue reports are considered carefully. Correction of reported problems
> often results in adding further checks within this valuable collection of
> tests.
>
Special thanks to John Carlson for pointing out a serious internal flaw
that might have permitted programmers to modify X3D constants and default
values that are supposed to be immutable.  This problem has been fixed by
applying Good Old-fashioned Object-Oriented Programming (GOOP)
encapsulation techniques, only allowing such special values to be reached
via accessor methods.  Much appreciated!

As ever, thanks to Web3D Consortium for sustained support of these
open-source libraries under version control in SourceForge.  License
information:

   - Web3D Consortium Open Source License
   - https://www.web3d.org/x3d/content/examples/license.txt
   - https://www.web3d.org/x3d/content/examples/license.html
   - X3D Resources: License Support
   - https://www.web3d.org/x3d/content/examples/X3dResources.html#license

Membership in Web3D Consortium is not required to use any of this work.
Nevertheless membership has value, please consider Joining Web3D Consortium
<https://www.web3d.org/membership/join>.

Have fun with X3d using X3DJSAIL Java!  😀👍

all the best, Don
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20250806/bf110820/attachment.html>