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

[John Carlson]

You’re welcome, Don, I hope to work with X3DJSAIL more in the following
days, but recently, I’ve been working on X3D JSON loading into Castle Game
Engine (CGE), which is an interesting application of my areas of
expertise.  I am relearning Pascal which is kind of “fun,” and the Castle
and Free Pascal “units” aka packages and libraries imported into a program.
  I was impressed by a benchmark where Pascal out performed C.

Thanks, Don, for adding schematron testing to X3DJSAIL!  Note that X3D JSON
can be validated via DOM and X3DJSAIL, or via X3D JSON schema (see npx
x3dvalidate).  With the addition of the Schematron to X3DJSAIL, I plan on
adding schematron testing to X3D JSON in addition to validation via
X3DJSAIL and XML Schema.   These will and do appear under my x3dschema
project:

https://github.com/coderextreme/x3dschema

I already have batch .x3d schematron testing with X3DJSAIL in X3DSONLD.

Onwards with X3DJSAIL!  Maybe eventually I’ll get to real X3D C++ coding!

But first, to download a new CGE version!

John

On Wed, Aug 6, 2025 at 1:24 PM Don Brutzman via x3d-public <
x3d-public at web3d.org> wrote:

> 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
> _______________________________________________
> x3d-public mailing list
> x3d-public at web3d.org
> http://web3d.org/mailman/listinfo/x3d-public_web3d.org
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20250806/cae54958/attachment-0001.html>