secondaryindex

## Class IndexViewService

- java.lang.Object
- - secondaryindex.IndexViewService

-     public class IndexViewService
      extends Object

  This class implements the methods for creating, updating and deleting Index Views.

  Index Views are a kind of custom secondary index implemented using the KVStore APIs and are a mappings between the secondary keys and the primary key. The Index View records are stored in the NoSQL Database as key-only records where the Value part of the record is Value.EMPTY_VALUE.

  It is important to keep minimize key sizes in order to reduce memory usage by NoSQL Database. Therefore, when designing applications that implement Index Views you should also consider an alternative design that uses key-value pairs rather than the key-only records in this example. Such an implementation would instead store the primary keys (which are stored in the minor key in this implementation) in the value portion of each record.

  The Key of each pair follows the following schema:

  /INDEX_KEY_PREFIX/INDEX_NAME/FIELD_VALUE1/FIELD_VALUE2/.../-/PRIMARY_KEY/

  INDEX_KEY_PREFIX is a prefix used to distinguish Index View data from other data.

  INDEX_NAME represents the index type. It is generated from the index metadata info by the "MD5" message digest algorithm. an INDEX_NAME is the unique identity of a kind of index in the index global name space.

  FIELD_VALUEs is a list holding values of index fields related to INDEX_NAME. The values are stored in multiple components and its order depends on the sequence of indexFieldNames list specified when the user calls `buildIndexes(List, String)`.

  Index View metadata info is also stored in the NoSQL Database. Each metadata is a KV pair in which the Value is empty and the Key follows the following schema:

  /INDEX_METADATA_KEY_PREFIX/INDEX_NAME/-/SCHEMA_NAME/FIELD_NAME1/FIELD_NAME2/ .../INDEX_STATE

  INDEX_METADATA_KEY_PREFIX is a prefix used to distinguish index metadata from other data.

  INDEX_NAME is the index unique identity.

  SCHEMA_NAME is the name of primary data schema associated with the current index.

  FIELD_NAMEs is a list holding names of index fields related to INDEX_NAME. Names are stored in multiple components and just like INDEX_FIELD_VALUES its order is specified while calling `buildIndexes(List, String)`.

  INDEX_STATE is a flag denoting if the current index is available for the index operations. It includes three types: "BUILDING", "DELETING" and "READY". The index can be used only when its status is "READY".

  Inconsistencies between user records and Index View data if multiple JVM clients perform concurrent index operations using IndexViewService instances or KVStore APIs directly. The implementation of this class uses a status flag in the index metadata to denote whether the index is available for operations. An Index View can be used only when its status is "READY". The status is "BUILDING" until Index View records have been created for all user records. However a complete consistency can not be guaranteed because all index operations including checking the status flag of index metadata are not atomic. Multiple threads can work while sharing the same IndexViewService instance without any synchronization. Using this class is not recommended for multi-process applications.

  Initialize this class like this:

       Binding binding = new Binding(kvstore.getAvroCatalog());
       IndexViewService indexViewService = new IndexViewService(kvstore, binding);

  This class implements the following methods:

  `buildIndexes(List, String)`: Builds Index Views on the input fields for primary DB records associated in the given schema. Since this method iterates over primary DB records, it may take an arbitrarily long time to complete.

  `dropIndexes(List, String)`: Drops one or more Index Views specified by the input fields for primary DB records in the given schema. Since this method iterates over primary DB records, it may take an arbitrarily long time to complete.

  `putIndexKV(Key)`: Creates Index View records for a primary DB record.

  `putIndexKV(Key, Value)`: Updates Index View records when a primary DB record is updated.

  `deleteIndexKV(Key)` Deletes Index View records when a primary DB record is deleted.

  `getPrimaryKV(List, List, String)`: Gets primary DB KV pairs associated with an Index View.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `class` | `IndexViewService.IndexMetadata` A structure holding all info for an Index View.
    `(package private) static class` | `IndexViewService.IndexState` An enum for the current status of an Index View.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `IndexViewService(KVStore kvstore, Binding binding)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `buildIndexes(List<String> indexFieldNames, String schemaName)` Builds an Index View(s) for primary DB records associated with the given schema.
    `boolean` | `deleteIndexKV(Key primaryKey)` Deletes an Index View record for a user record being deleted.
    `boolean` | `dropIndexes(List<String> indexFieldNames, String schemaName)` Drops Index Views on the given fields.
    `Set<IndexViewService.IndexMetadata>` | `getIndexMetadatas()` Returns all Index View metadata.
    `SortedMap<Key,ValueVersion>` | `getPrimaryKV(List<String> indexFieldNames, List<Object> indexFieldValues, String schemaName)` Returns a Map mapping primary DB KV keys to their related values.
    `static boolean` | `isIndexOrMetadata(Key key)` Checks whether the given Key is an index or metadata key.
    `boolean` | `putIndexKV(Key primaryKey)` Creates Index View records for a newly inserted user record.
    `boolean` | `putIndexKV(Key primaryKey, Value newValue)` Updates Index View(s) for a user record being updated.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### IndexViewService

          public IndexViewService(KVStore kvstore,
                          Binding binding)

  - ### Method Detail

    - #### isIndexOrMetadata

          public static boolean isIndexOrMetadata(Key key)

      Checks whether the given Key is an index or metadata key.

    - #### getPrimaryKV

          public SortedMap<Key,ValueVersion> getPrimaryKV(List<String> indexFieldNames,
                                                 List<Object> indexFieldValues,
                                                 String schemaName)

      Returns a Map mapping primary DB KV keys to their related values. Returns an empty map if there are no records found in the database. Returns null if there are no proper indexes that can be used to query or the index state is not READY.

    - #### buildIndexes

          public boolean buildIndexes(List<String> indexFieldNames,
                             String schemaName)

      Builds an Index View(s) for primary DB records associated with the given schema. If all indexes have been built successfully, returns true sets the index state to READY. Returns false if the indexes to be built already exist in the database or a FaultException occurs in the process of building indexes, in which case this method will iterate over the KVStore to delete the metadata and related indexes that have been created.

    - #### dropIndexes

          public boolean dropIndexes(List<String> indexFieldNames,
                            String schemaName)

      Drops Index Views on the given fields. Returns true if all indexes and metadata are successfully deleted. Returns false if the status of indexes to be dropped is not READY or a FaultException occurs in the process of dropping indexes. If a failure occurs during this operation this method does nothing else to unwind and the user should call `buildIndexes(List, String)` to rebuild the Index Views that have been deleted to keep the consistency between user records and indexes.
      Parameters:
        `indexFieldNames` -
        `schemaName` -
      Returns:
        boolean

    - #### putIndexKV

          public boolean putIndexKV(Key primaryKey)

      Creates Index View records for a newly inserted user record. This function is called when a new record is inserted into the primary DB. Returns true if indexes are created successfully. Returns false if one of the following cases occurs: 1. the given Key does not exist in the database, 2. the Value related to the given Key is not an Avro data record, 3. The status of some types of indexes to be built is not READY in which case this method will undo all executed operations before return.

    - #### putIndexKV

          public boolean putIndexKV(Key primaryKey,
                           Value newValue)

      Updates Index View(s) for a user record being updated. Generally this function is called before an existing record is updated in the primary DB. Returns true if indexes are updated successfully. Returns false if one of the following occur: 1. the given Key does not exist in the database, 2. the Value related to the given Key is not an Avro record. 3.the new Value is inconsistent with the old Value in schema. 4. the status of some types of indexes to be updated is not READY in which case this method will undo all executed operations before returning.

    - #### deleteIndexKV

          public boolean deleteIndexKV(Key primaryKey)

      Deletes an Index View record for a user record being deleted. Generally this function is called before a primary DB record is deleted. Returns true if indexes are deleted successfully. Returns false if one of the following cases occurs: 1. the given Key does not exist in the database. 2. the Value related to the given Key is not an Avro data. 3. the status of some types of indexes to be deleted is not READY in which case this method will undo all executed operations before return.

    - #### getIndexMetadatas

          public Set<IndexViewService.IndexMetadata> getIndexMetadatas()

      Returns all Index View metadata.

Copyright (c) 2011, 2014 Oracle and/or its affiliates. All rights reserved.