De/un-deprecate IndexType ENUM

To be Reviewed By: January 10, 2019

Authors: Joris Melchior

Status: Draft | Discussion | Active | Dropped | Superseded

Superseded by: N/A

Related: N/A

Problem

The org.apache.geode.cache.query.IndexType ENUM has been deprecated for some time and we currently have no alternative to replace it with. The deprecation annotation refers to the org.apache.geode.cache.query.QueryService interface but upon inspection it is clear that while this interface tries to hide the use of the ENUM it continues to use it under the covers.

The ENUM itself is correct in its design and has an internal deprecation of the HASH item which should not be used when configuring new Indexes on Regions.

We would like to be able to use a non-deprecated indicator of the type of index that is in use on a given Region.

Some of the method on our org.apache.geode.cache.query.QueryService interface provided for creating/defining new indexes could be more descriptive to better express intention.

Anti-Goals

  • We are not trying to introduce new types of indexes
  • We are not trying to make HASH a supported index type again

Solution

  1. Remove the "Deprecated" indicator off the org.apache.geode.cache.query.IndexType ENUM.
  2. Maintain the "Deprecated" indicator on the org.apache.geode.cache.query.IndexType.HASH item
  3. Create new methods for creation of IndexType.FUNCTIONAL indexes on the org.apache.geode.cache.query.QueryService interface
    1. createFunctionalIndex
    2. defineFunctionalIndex
  4. Deprecate the less descriptive methods for the creation of IndexType.FUNCTIONAL indexes on the org.apache.geode.cache.query.QueryService interface
    1. createIndex
    2. defineIndex
    3. provide clear deprecation messages indicating the replacement code for the deprecated methods
  5. Propagate implementation of new interface methods on org.apache.geode.cache.query.QueryService interface to known implementations
  6. Refactor code to use new implementations in all code under our control

Changes and Additions to Public Interfaces

  • Four methods on the org.apache.geode.cache.query.QueryService interface will be deprecated
  • Four new methods on the org.apache.geode.cache.query.QueryService will replace the deprecated methods
  • ENUM org.apache.geode.cache.query.IndexType will no longer be deprecated

Performance Impact

The changes are not expected to have any impact on the performance of Geode.

Backwards Compatibility and Upgrade Path

Rolling updates should continue to work after making these changes.

The changes should be backwards compatible as we're only deprecating code and not making any 'hard' changes to the interfaces.

Once we decide to remove the code we are deprecating as part of this change users will be forced to make changes to client code that uses the deprecated interface methods but as part of this change equivalent alternatives are provided. These alternatives will be clearly indicated in the deprecation messages in the code.

Prior Art

We could provide a new ENUM type but this would have a bigger impact on the system without any clear benefits. Other alternatives have not been considered yet.

FAQ

Answers to questions you’ve commonly been asked after requesting comments for this proposal.

Errata

What are minor adjustments that had to be made to the proposal since it was approved?

  • No labels