Expose MetadataOnly through metadata APIs

[Darlokt]

Hej,

While testing Bio-Formats memoization and diagnosing some other memoization problems which came up due to testing Java 25 build of ome/bioformats#4450 and its use of MetadataOnly, the OME-XML schema failed validation after active memoization.
The failure was initially addressed haphazardly by me in ome/bioformats#4459, but I traced the underlying conversion problem to ome.xml.meta.MetadataConverter, making this an ome-model issue rather than a Bioformats-Memoizer-specific problem.

OME 2016-06 requires each Pixels element to contain one of BinData, TiffData, or MetadataOnly.

Unlike the other alternatives, MetadataOnly is an empty marker element. The metadata code generator exposes values, attributes, references, and repeated entities through MetadataRetrieve and MetadataStore, but it previously generated no API for this marker.

Consequently, MetadataConverter could copy every ordinary Pixels property while silently dropping MetadataOnly. The resulting OME-XML contained a Pixels element without any member of the required schema choice and was therefore invalid.

Changes

Add generated presence accessors for the marker:

• MetadataRetrieve#getPixelsMetadataOnly(int)
• MetadataStore#setPixelsMetadataOnly(Boolean, int)

The getter returns:

• true when the marker is present
• false when it is absent
• null when an implementation cannot determine its presence

Both methods are interface defaults so existing third-party metadata
implementations remain compatible. The default getter returns null, and the
default setter is a no-op.

Implement the accessors in:

• OMEXMLMetadataImpl
• AggregateMetadata
• FilterMetadata

OMEXMLMetadataImpl creates or removes the concrete marker according to the
Boolean value. MetadataConverter now copies the marker exclusively through
the metadata interfaces, without depending on concrete OME model classes.

Tests

Add focused coverage for:

• creating and removing the marker
• nullable compatibility defaults
• aggregate and filtering metadata wrappers
• generic metadata conversion
• validation of converted XML against the bundled OME 2016-06 schema

The branch passes all local tests.

[Darlokt]

#234 fixes the cause of the CI failure. The CI failure here is unrelated to the changes.

[imagesc-bot]

This pull request has been mentioned on Image.sc Forum. There might be relevant details there:

https://forum.image.sc/t/new-bioformats-cv7000-reader-fixing-old-one-quietly-inventing-data/122100/1

[sbesson]

From the perspective of the data model, exposing the MetadataOnly in the interfaces and implementations of the ome.xml.meta package makes sense and restores some parity with the existing API for TiffData or BinData. The proposal makes use of default implementations in interfaces and would constitute a backwards-compatible API addition.

Labelling this PR to have it included it in the nightly builds and check it does not cause any downstream regression.

From the API perspective, the biggest unknown from my side is about the type of object that should be used in the getter and setter methods. The proposal use Boolean while an alternative would be to use an ome.xml.model.MetadataOnly object.

Most methods in the ome.xml.meta interface are getting or setting element attributes so the mapping into data types is more straightforward. MetadataOnly is different as it has no attribute and unlike TiffData and BinData there can only be one instance per Pixels so methods like getMetadataOnlyCount() returning an integer feels unnecessary.

[Darlokt]

Thanks for the review!
I chose Boolean because MetadataOnly is an empty singleton marker and callers only need to distinguish present, absent, and unsupported (null). Exposing an ome.xml.model.MetadataOnly object would couple the generic metadata interfaces to the concrete model without exposing additional information. A count method also seems unnecessary because the schema permits only one marker.
I added documentation clarifying the semantics in 3113fde.

[melissalinkert]

I agree with the approach to accept/return a Boolean, as this is consistent with the existing MetadataStore API which does not accept or return OME model objects. In the unlikely case that MetadataOnly is ever expanded in the OME-XML schema, at worst we could deprecate these methods in favor of whatever matched the updated schema.