[ https://issues.apache.org/jira/browse/RNG-136?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17347861#comment-17347861 ]
Alex Herbert commented on RNG-136: ---------------------------------- h2. Updating existing classes changes functional compatibility Although there is no binary compatibility change for existing classes there is functional compatibility change with updating to the new interface. For example: {code:java} public class CollectionSampler<T> implements SharedStateSampler<CollectionSampler<T>> { {code} Becomes: {code:java} public class CollectionSampler<T> implements SharedStateObjectSampler<T> { {code} The implementation signature of {{SharedStateSampler}} remains unchanged: {code:java} public CollectionSampler<T> withUniformRandomProvider(UniformRandomProvider rng) { {code} Due to type erasure the change from {{SharedStateSampler}} to {{SharedStateObjectSampler}} is not detected as binary incompatible as the class still implements {{SharedStateSampler}}. But the {{SharedStateSampler}} is now of type {{SharedStateSampler<SharedStateSampler<T>>}} instead of {{SharedStateSampler<CollectionSampler<T>>}}. If the derived sampler is assigned to the correct type this is functionally compatible: {code:java} CollectionSampler<String> sampler1 = new CollectionSampler<String>(rng1, list); CollectionSampler<String> sampler2 = sampler1.withUniformRandomProvider(rng2); {code} If the derived sampler is assigned to a {{SharedStateSampler}} this is functionally *incompatible*; this will *not* compile with version 1.4 where it will with code from version 1.3: {code:java} CollectionSampler<String> sampler1 = new CollectionSampler<String>(rng1, list); SharedStateSampler<CollectionSampler<String>> sampler2 = sampler1.withUniformRandomProvider(rng2); {code} The functionally incompatible change is to the following existing classes: {code:java} public CollectionSampler<T> implements SharedStateSampler<CollectionSampler<T>> public CombinationSampler implements SharedStateSampler<CombinationSampler> public DiscreteProbabilityCollectionSampler<T> implements SharedStateSampler<DiscreteProbabilityCollectionSampler<T>> public PermutationSampler implements SharedStateSampler<PermutationSampler> public UnitVectorSampler implements SharedStateSampler<UnitVectorSampler> {code} In each of the classes the method implementation {{withUniformRandomProvider}} returns an instance of the class. Thus changing the interface implemented by the class has not changed the signature of the method implementation. If a user has coded their use of the interface to assign the result to an instance of the class (as per the unit tests) then code will be functionally compatible. If they have assigned an instance of {{SharedStateSampler<R>}} then code will not be functionally compatible. Note that the SharedStateSampler<R> interface only has 1 method: {code:java} public interface SharedStateSampler<R> { R withUniformRandomProvider(UniformRandomProvider rng); } {code} So it is unlikely any user will assign the result of the method to an instance of {{SharedStateSampler}} as functionally it can only be used to create more instances. No sampling can actually be done from a {{SharedStateSampler}}. Code that has done this will later have to cast the {{SharedStateSampler}} to some other class to use it for sampling. This usage is incorrect and supporting it is not a priority. I propose to allow this change without updating the major version number of the code. The functional compatibility change can be added to the release notes. > ObjectSampler<T> and SharedStateObjectSampler<T> interfaces > ----------------------------------------------------------- > > Key: RNG-136 > URL: https://issues.apache.org/jira/browse/RNG-136 > Project: Commons RNG > Issue Type: New Feature > Components: sampling > Affects Versions: 1.4 > Reporter: Alex Herbert > Assignee: Alex Herbert > Priority: Major > Time Spent: 40m > Remaining Estimate: 0h > > The sampling package currently contains interfaces for creating int and > double samples and their extensions to implement the SharedStateSampler > interface: > {code:java} > public interface DiscreteSampler { > int sample(); > } > public interface SharedStateDiscreteSampler > extends DiscreteSampler, SharedStateSampler<SharedStateDiscreteSampler> { > // Composite interface > } > public interface ContinuousSampler { > double sample(); > } > public interface SharedStateContinuousSampler > extends ContinuousSampler, > SharedStateSampler<SharedStateContinuousSampler> { > // Composite interface > } > {code} > Add a matching ObjectSampler interface for all samplers that create objects: > {code:java} > public interface ObjectSampler<T> { > T sample(); > } > public interface SharedStateObjectSampler<T> extends > ObjectSampler<T>, > SharedStateSampler<SharedStateObjectSampler<T>> { > // Composite interface > } > {code} > Samplers currently returning an object should implement the new interface: > {code:java} > int[] CombinationSampler.sample() > int[] PermutationSampler.sample() > double[] UnitVectorSampler.nextVector() > T CollectionSampler<T>.sample() > T DiscreteProbabilityCollectionSampler<T>.sample() > double[] BoxSampler.sample() > double[] LineSampler.sample() > double[] TriangleSampler.sample() > double[] TetrahedronSampler.sample() > double[] UnitBallSampler.sample() > {code} > Only the UnitVectorSampler will require a new {{sample}} method. The current > {{nextVector}} method can be marked deprecated. -- This message was sent by Atlassian Jira (v8.3.4#803005)