Wiring javadoc claims that instances are effectively immutable

[tjwatson]

See Wiring javadoc. It claims:

Instances of this type must be effectively immutable.
That is, for a given instance of this interface, the methods defined
by this interface must always return the same result.

This is incorrect for at least the method org.osgi.resource.Wiring.getProvidedResourceWires(String) which will change over time as new resources get wired to capabilities provided by the wiring. For BundleWiring which extends Wiring this is also untrue for the method org.osgi.resource.Wiring.getRequiredResourceWires(String) for bundle revisions that have dynamic imports and get wired to new packages dynamically.

the get methods on Wiring all use the language:

A list containing a snapshot of the ...

It is unclear why the returned lists use the term "snapshot" if the instance is immutable. Why would a snapshot be used for something that never changes? Assuming the results can change, is it acceptable for an implementation to return immutable "snapshot" lists? Or does this language imply the return list is mutable?

[bjhargrave]

The lists returned from the wiring types must be mutable copies. That is, they are a snapshot (copy) and since they are a copy, there is no reason that they should not be mutable. This allows the caller to do things like sort the returned list, combine lists, etc., without having to make another copy.

[HannesWell]

The lists returned from the wiring types must be mutable copies. That is, they are a snapshot (copy) and since they are a copy, there is no reason that they should not be mutable. This allows the caller to do things like sort the returned list, combine lists, etc., without having to make another copy.

On the other hand, if a caller obtains the list without the need to mutate it (for example just iterates over it), returning a mutable copy just adds a performance penalty.
But the other way around, if the returned List is immutable and a mutable copy is required, creating a copy in the calling code adds no performance penality.
But of course it is not as convenient as having a mutable copy directly, but if the documentation is clear about the mutability of the returned list, I would be in favour of an immutable list.

[bjhargrave]

Generally, in OSGi api when we state a returned value is a snapshot, we mean that it is a copy and thus wont change underneath the user. Had the api said an immutable value, then it would allow us to return an immutable value. But snapshot allows for the caller to mutate the value.

In a framework implementation, it can use a list implementation which wraps an immutable list and converts to a mutable list upon first mutation request (copy-on-write). Then, for many users which don't mutate, there is little additional memory overhead.

[HannesWell]

Generally, in OSGi api when we state a returned value is a snapshot, we mean that it is a copy and thus wont change underneath the user. Had the api said an immutable value, then it would allow us to return an immutable value. But snapshot allows for the caller to mutate the value.

In this case it should be mutable.

In a framework implementation, it can use a list implementation which wraps an immutable list and converts to a mutable list upon first mutation request (copy-on-write). Then, for many users which don't mutate, there is little additional memory overhead.

That's a good solution to meet the APIs convention and maintain a good performance and memory-usage.