[enhancement] improve Cardinality

[line-o]

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]

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:

1. a version to support the API in 4.x.x, 5.x.x, and 6.x.x
2. 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.

[line-o]

_MANY was introduced in 5310f056d09923f2b262f66c9ac5d27e1679303b

[line-o]

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]

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]

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]

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

[adamretter]

@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]

@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]

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.