What is the replacement for deprecated Iterations.asList methods in 4.1

[aschwarte10]

In 4.1. the utility methods from the Iterations class (e.g. Iterations.asSet or Iterations.asList) have been marked as deprecated and schedule for removal.

We have heavily used these utility methods (specifically in our unit tests).

What would be the preferred replacement for now? And would it be an option to document these in the release notes more clearly (for me I guess an example in the javadoc would help)

Any quick feedback appreciated. Thanks!

[hmottestad]

There should be new matching methods that take CloseableIteration instead of Iteration.

[aschwarte10]

Ok, that explanation makes sense.

Still I am not quite happy with all the deprecated annotations: in my IDE (Eclipse) there is currently a whole lot of warnings making our code hard to maintain

• Iterations class is marked as deprecated (=> warning wherever this is imported or used)
• Iterations.asSet(CloseableIteration) appears with a warning because CloseableIteration is annotated as deprecated, same for asList

Also I see deprecation warnings in my custom implementations that extend org.eclipse.rdf4j.sail.helpers.AbstractSailConnection because it uses CloseableIteration in the signatures. Are these warnings IDE specific? The only solution I do see in our code-base is to suppress those warnings (although I do not really like it)

What would be the proposed best practice?

[hmottestad]

I ended up disabling a lot of the deprecation warnings in IntelliJ. I think was was able to differentiate so that it still gives warnings if the deprecation is marked for removal.

Jeen fixed the user side of things so that regular users who interact with RDF4J through a repository shouldn't notice anything. For developers who extend the Sail side of the code the deprecations should still be visible.

I would prefer if we started working on the next major release. That way we can make the changes to the code that we need and remove the deprecations.

[abrokenjester]

@aschwarte10 it might also be worth switching to using the QueryResults utility instead of Iterations. It's basically a subclass, so it has all the same asList, asModel etc functions. But it's abstracted away a little from the specific Iteration interface and has overrides specifically to make sure there's a non-deprecated variant.

[abrokenjester]

I think was was able to differentiate so that it still gives warnings if the deprecation is marked for removal.

That's something worth discussing. I don't know that all IDEs support making that kind of distinction, and to be honest to me the distinction is not very clear in the first place. I mean, when (in RDF4J) is something deprecated but not intended to be removed? What's the exact meaning of the forRemoval bit for us?

[hmottestad]

It's hard to differentiate between deprecation with and without removal. I've tried to use removal to mean "this class/interface/method/etc is going to be deleted and it's not coming back". So if we are changing the superclass, moving a class or changing a method signature, then I've not marked it for removal.

In the case of the Iteration and CloseableIteration interface we could duplicate all our code and move to a new interface. Instead we will remove Iteration (which is marked for removal) and possibly make some non backwards compatible changes to the CloseableIteration. Code that in some way depends on either of these classes have also been marked with either just deprecated or deprecated for removal (typically for methods that depend on Iteration).

In the cases where I've duplicated a method in order to change the signature, then the old method is marked for removal and I've tried to add a JavaDoc pointing to the new method.

[abrokenjester]

Posting as a separate answer for visibility: the intended replacement for the Iterations utility, generally, is the QueryResults utility. It should have non-deprecated versions of most (all?) utility functions in Iterations.