Support authorizedCollections option for listCollections helpers

[stIncMale]

This PR changes API in the following interfaces:

• com.mongodb.client.ListCollectionsIterable
• com.mongodb.reactivestreams.client.ListCollectionsPublisher
• com.mongodb.client.MongoDatabase
• com.mongodb.reactivestreams.client.MongoDatabase

in a way that is backward-compatible from the perspective of the API users, and is breaking from the perspective of API implementors.

You may see a few methods marked as @VisibleForTesting, which are used reflectively either from Java tests, or from Groovy. The code that effectively required the presence of these methods was already in the tests, I simply made the changes to fit into existing test infrastructure.

JAVA-4353

[stIncMale]

Returning a more specific type from interface methods is a breaking change for implementors of the interface (the same happens in the com.mongodb.reactivestreams.client.MongoDatabase interface). In order to not break semantic versioning we must postpone this feature until version 5.0. What do you think?

[jyemin]

It's not just breaking for implementors, but also for consumers, as it requires recompilation.

[stIncMale]

Thanks!, you are right. This thread have useful links https://stackoverflow.com/questions/47476509/can-i-change-a-return-type-to-be-a-strict-subtype-and-retain-binary-compatibilit, including quotes from the JLS.

I don't want to contaminate MongoDatabase interfaces by adding weird methods, because that would make the API less consistent. Returning a more specific type on the opposite makes the existing API more consistent (don't know why it was not done in the first place, but it causes the problem).

The only ways to tackle the problem I see are

• postpone to 5.0 (I prefer this one);
• introduce a method like listCollectionNamesConfigurable that returns ListCollectionsIterable<String>, which is ugly.

[jyemin]

We could also add an overload, but that would make it the only non-fluent method that returns an Iterable.

Given that this was added all the way back in MongoDB 4.0 and no one has yet asked for the feature in the Java driver, I'm also ok with deferring to 5.0.

[rozza]

Users can always use listCollections and map the results to return the names

[stIncMale]

They can but in that case, the nameOnly flag is not set, which means that authorizedCollections is ignored. That's why listCollectionNames (or its overload, or a similar new method - both alternatives are mentioned in previous comments) is the only way to actually use authorizedCollections.

[rozza]

Ah and there is no listCollections.nameOnly(true), I noticed its there in listDatabases

[stIncMale]

I guess, it may also possible to expose nameOnly on ListCollectionsIterable, thus making the listCollections method of full value, while leaving listCollectionNames to be a shortcut for a very specific case. But then again, I don't know what I will encounter when trying to do so, after all, this was not done when nameOnly was introduced.

[rozza]

According to the spec the server will ignore nameOnly prior to its addition in 4.0. Which is lucky, also the spec says:

Drivers MAY allow the nameOnly and authorizedCollections options to be passed when executing the listCollections command for this method.

However, it requires more work to match the spec - checking filters etc. Also it might be surprising to users that one approach is configurable and another isn't. So deferring to 5.0 seems best.

[stIncMale]

This is a breaking change for implementors of the interface. It's possible to make this method a default one with the default implementation that either does nothing or throws an UnsupportedOperationException. However, given the following

• We discussed a similar approach in the context of a different change (I don't remember what it was), and no one was happy about either of the work-arounds.
• The changes in com.mongodb.client.MongoDatabase and com.mongodb.reactivestreams.client.MongoDatabase are also breaking for implementors, and it is impossible to make them backward-compatible.

I decided not to apply such work-arounds.

[jyemin]

We haven't considered these to be breaking changes in the past, and frequently make them in minor releases like 4.5.

[stIncMale]

The documentation says: "When used without nameOnly: true, this option has no effect." That's why we send the option only if nameOnly is true.