[enhancement] improve Cardinality #5967

line-o · 2025-12-08T22:28:24Z

Description:

Slightly improve developer experience when working with Java extensions.

BREAKING CHANGE: rename enum constant MANY to MORE and _MANY to MANY in Cardinality.java

Reference:

This PR aims to continue our discussion from todays community call 2025-12-08.

Type of tests:

none added all existing pass

adamretter · 2025-12-09T04:47:33Z

exist-core/src/main/java/org/exist/xquery/Cardinality.java

    EXACTLY_ONE(ONE),

    //TODO(AR) eliminate this in favour of probably ONE_OR_MORE
-    _MANY(MANY),


I put the _ here to denote that this is a private internal value that should only be used inside eXist-db's internals. This should not be renamed. As my TODO in the code there states, if anything this should be completely removed. Removing the underscore sends a message to users that this is just any old Enum option that they can use, which is not what you or they want, as this should never be used.

Do you recall what getting rid of them entails?
I just stumbled over very recently, when fixing exist-xqts-runner to work with exist-7.0.0-SNAPSHOT
Which means that up until a certain point in the not so distant past this was changed in exist.

Do you recall what getting rid of them entails?

Yes fixing the weird code that uses it, its just a few places. You can find it via Find References in IntelliJ.

Which means that up until a certain point in the not so distant past this was changed in exist.

Actually this was done almost 6 years ago now - so definitely the distant past!

adamretter · 2025-12-09T04:59:42Z

I would highly advise against changing anything in Cardinality, Type, Function, Basic Function, or any class that is required by a user to build an external XQuery function module in Java. As doing so will break every user's 3rd party Java Extension Module for eXist-db.

Users have already experienced this pain once due to the long incubation period of 7.0.0-SNAPSHOT (~3 years) and have had to maintain two versions of their Java extensions:

a version to support the API in 4.x.x, 5.x.x, and 6.x.x
and a separate version to support 7.0.0-SNAPSHOT

If you change the APIs that are used in external function modules, then you will now force them to maintain 3 versions of their extensions. This is particularly problematic as it is being done during a long SNAPSHOT period, that makes it almost impossible for them to create a 3rd version of their extension and know whether their 2nd or 3rd version should be used against a particular 7.0.0-SNAPSHOT.

If you absolutely have to do this, which I don't think you do (as it is a cosmetic change only), because of the long incubation period of 7.0.0 you should wait until 8.0.0; otherwise there will be more upset users. I don't just speak for myself here, I know multiple organisations using eXist-db for which this has been a real PITA.

This PR aims to continue our discussion from todays community call 2025-12-08.

There is no information in the minutes of the Community Call about this.

BREAKING CHANGE: rename enum constants MANY to MORE and _MANY to MANY

line-o · 2025-12-10T09:41:55Z

_MANY was introduced in 5310f05

line-o · 2025-12-10T12:41:13Z

Removing the public constant Cardinality._MANY introduces the exact same breaking change with java library authors having to maintain separate versions for 6 and 7.
We do however introduce a number of breaking changes once we release exist 7 (beta or RC1).
So the necessity to maintain two different versions is already the case. This is true even for our own java libs and apps (see monex, crypto-lib and others).
This is why up until the point that exist 7 is released in any form other than SNAPSHOTS is the last chance to introduce this.

The above summarizes what was discussed on the community call. Since it was the last any other business we simply forgot to note it down.

adamretter · 2025-12-10T22:14:33Z

Removing the public constant Cardinality._MANY introduces the exact same breaking change with java library authors having to maintain separate versions for 6 and 7.

No it does not. No Java Library Authors should be using it, because simply there is no need for anyone to use it. AFAIK it has never been used outside of the core of eXist-db (where it should be removed also).

We do however introduce a number of breaking changes once we release exist 7 (beta or RC1).
So the necessity to maintain two different versions is already the case. This is true even for our own java libs and apps (see monex, crypto-lib and others).
This is why up until the point that exist 7 is released in any form other than SNAPSHOTS is the last chance to introduce this.

I am afraid that you may have completely missed the point. Please re-read what I wrote, and then if you have questions about why your statements are not correct feel free to ask.

line-o · 2025-12-11T09:29:08Z

So, I understand:

Removing Cardinality._MANY is good and should be done, this internal value should never be used outside of exist-core anyway. This fact is communicated by the leading underscore in its name.
Renaming it to Cardinality.MANY, however, should be avoided because it would be an extra burden on Java extension maintainers. They would have to have to maintain three versions just because of this change.

Is this an accurate summary @adamretter ?

adamretter · 2025-12-11T10:37:17Z

Removing Cardinality._MANY is good and should be done, this internal value should never be used outside of exist-core anyway. This fact is communicated by the leading underscore in its name.

Yes.

Renaming it to Cardinality.MANY, however, should be avoided because it would be an extra burden on Java extension maintainers. They would have to have to maintain three versions just because of this change.

Yes... but also, by renaming it you are removing the signal to users that it is internal and should never be used. So you would also be encouraging users to use an API that is internal and will be removed in future (that will then also break their code again at that point).

line-o · 2025-12-11T11:41:22Z

...stxq/src/main/java/org/exist/extensions/exquery/restxq/impl/adapters/CardinalityAdapter.java

        return switch (cardinality) {
            case EMPTY_SEQUENCE -> Cardinality.ZERO;
            case EXACTLY_ONE -> Cardinality.ONE;
-            case _MANY -> Cardinality.MANY;


@adamretter so the many cardinality has to be removed in this extension as well, correct?

@line-o Yes, if the goal is to remove _MANY then this will also need to be cleaned up too.

adamretter · 2025-12-16T16:19:35Z

@line-o So I assume that we are agreed that you don't want to cause any more pain for eXist-db users before an 8.x.x. If so, can you close this or retarget it against a develop-8.x.x branch please?

reinhapa · 2025-12-16T19:27:16Z

@line-o So I assume that we are agreed that you don't want to cause any more pain for eXist-db users before an 8.x.x. If so, can you close this or retarget it against a develop-8.x.x branch please?

@adamretter in the last community meeting it was decided to leave the _MANY enum for now but annotate it as @Deprecatedstarting with 5.x.x and @Deprecate(forRemoval=true) in 7.x.x in order to remove it in 8.x.x

adamretter · 2025-12-17T09:04:02Z

in the last community meeting it was decided to leave the _MANY enum for now but annotate it as @Deprecatedstarting with 5.x.x and @deprecate(forRemoval=true) in 7.x.x in order to remove it in 8.x.x

@reinhapa I am sure many people will be relieved. Thank you.

reinhapa · 2026-01-08T07:25:05Z

Superseded by #6005, #6006 and #6007

adamretter reviewed Dec 9, 2025

View reviewed changes

[enhancement] improve Cardinality

d1a74aa

BREAKING CHANGE: rename enum constants MANY to MORE and _MANY to MANY

line-o force-pushed the cardinality-cleanup branch from 8e266b5 to d1a74aa Compare December 10, 2025 09:37

line-o commented Dec 11, 2025

View reviewed changes

reinhapa closed this Jan 8, 2026

Uh oh!

[enhancement] improve Cardinality #5967

[enhancement] improve Cardinality #5967

Uh oh!

Conversation

line-o commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description:

Reference:

Type of tests:

Uh oh!

adamretter Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

line-o Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

adamretter Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

adamretter commented Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

line-o commented Dec 10, 2025

Uh oh!

line-o commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adamretter commented Dec 10, 2025

Uh oh!

line-o commented Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adamretter commented Dec 11, 2025

Uh oh!

line-o Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

adamretter Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

adamretter commented Dec 16, 2025

Uh oh!

reinhapa commented Dec 16, 2025

Uh oh!

adamretter commented Dec 17, 2025

Uh oh!

reinhapa commented Jan 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

line-o commented Dec 8, 2025 •

edited

Loading

adamretter Dec 9, 2025 •

edited

Loading

adamretter commented Dec 9, 2025 •

edited

Loading

line-o commented Dec 10, 2025 •

edited

Loading

line-o commented Dec 11, 2025 •

edited

Loading