oracle.kv

## Class KeyRange

- java.lang.Object
- - oracle.kv.KeyRange

- All Implemented Interfaces:
    oracle.kv.impl.util.FastExternalizable

      public class KeyRange
      extends Object
      implements oracle.kv.impl.util.FastExternalizable

  Defines a range of Key components for use in multiple-key operations and iterations.

  The KeyRange defines a range of String values for the key components immediately following the last component of a parent key that is used in a multiple-key operation. In terms of a tree structure, the range defines the parent key's immediate children that are selected by the multiple-key operation.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `KeyRange(String prefix)` Creates a prefix KeyRange.
    `KeyRange(String start, boolean startInclusive, String end, boolean endInclusive)` Creates a start/end KeyRange.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(Object other)`
    `static KeyRange` | `fromByteArray(byte[] keyBytes)` Deserializes the given bytes that were returned earlier by `toByteArray()` and returns the resulting KeyRange.
    `static KeyRange` | `fromString(String keyRangeStringArg)` Converts an encoded KeyRange back to a KeyRange.
    `String` | `getEnd()` Returns the String component that defines upper bound of the key range, or null if no upper bound is enforced.
    `boolean` | `getEndInclusive()` Returns whether end is included in the range, i.e., end is greater than or equal to the last String component in the key range.
    `String` | `getStart()` Returns the String component that defines lower bound of the key range, or null if no lower bound is enforced.
    `boolean` | `getStartInclusive()` Returns whether start is included in the range, i.e., start is less than or equal to the first String component in the key range.
    `int` | `hashCode()`
    `boolean` | `inRange(Key parentKey, Key checkKey)` Returns true if a Key is within the bounds of this range with respect to a parent Key.
    `boolean` | `isPrefix()` Returns whether this is a prefix range, i.e., whether start and end are equal and both inclusive.
    `byte[]` | `toByteArray()` Returns this KeyRange as a serialized byte array, such that `fromByteArray(byte[])` may be used to reconstitute the KeyRange.
    `String` | `toString()` Encodes the KeyRange object and returns the resulting String which can later be decoded using `fromString(java.lang.String)`.

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

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface oracle.kv.impl.util.FastExternalizable

      `writeFastExternal`

- - ### Constructor Detail

    - #### KeyRange

          public KeyRange(String start,
                  boolean startInclusive,
                  String end,
                  boolean endInclusive)

      Creates a start/end KeyRange.
      Parameters:
        `start` - is the String component that defines lower bound of the key range. If null, no lower bound is enforced.
        `startInclusive` - is true if start is included in the range, i.e., start is less than or equal to the first String component in the key range.
        `end` - is the String component that defines upper bound of the key range. If null, no upper bound is enforced.
        `endInclusive` - is true if end is included in the range, i.e., end is greater than or equal to the last String component in the key range.
      Throws:
        `IllegalArgumentException` - if either start and end are null or start is not less than end.

    - #### KeyRange

          public KeyRange(String prefix)

      Creates a prefix KeyRange.

      For a KeyRange created using this constructor, `isPrefix()` will return true.

      Additionally, both `getStart()` and `getEnd()` will return the prefix, and both `getStartInclusive()` and `getEndInclusive()` will return true. However, the `KeyRange` will be treated as a prefix, not an inclusive range.

      Parameters:
        `prefix` - is the value that is a prefix of all matching key components. The KeyRange matches a key component if the component starts with (as in `String.startsWith`) the prefix value.

  - ### Method Detail

    - #### toByteArray

          public byte[] toByteArray()

      Returns this KeyRange as a serialized byte array, such that `fromByteArray(byte[])` may be used to reconstitute the KeyRange.

    - #### fromByteArray

          public static KeyRange fromByteArray(byte[] keyBytes)

      Deserializes the given bytes that were returned earlier by `toByteArray()` and returns the resulting KeyRange.

    - #### getStart

          public String getStart()

      Returns the String component that defines lower bound of the key range, or null if no lower bound is enforced. For a prefix range, this method returns the prefix.

    - #### getStartInclusive

          public boolean getStartInclusive()

      Returns whether start is included in the range, i.e., start is less than or equal to the first String component in the key range. For a prefix range, this method returns true.

    - #### getEnd

          public String getEnd()

      Returns the String component that defines upper bound of the key range, or null if no upper bound is enforced. For a prefix range, this method returns the prefix.

    - #### getEndInclusive

          public boolean getEndInclusive()

      Returns whether end is included in the range, i.e., end is greater than or equal to the last String component in the key range. For a prefix range, this method returns true.

    - #### isPrefix

          public boolean isPrefix()

      Returns whether this is a prefix range, i.e., whether start and end are equal and both inclusive.

    - #### inRange

          public boolean inRange(Key parentKey,
                        Key checkKey)

      Returns true if a Key is within the bounds of this range with respect to a parent Key.
      Parameters:
        `parentKey` - the parent of the key range, or null to check the first key component.
        `checkKey` - the full key being checked.
      Returns:
        true if it's in range, false otherwise.

    - #### equals

          public boolean equals(Object other)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### toString

          public String toString()

      Encodes the KeyRange object and returns the resulting String which can later be decoded using `fromString(java.lang.String)`. The format is: `<startType>/<start>/<end>/<endType>`

      where the `startType/endType` is either `"I"` or `"E"` for Inclusive or Exclusive and `start` and `end` are the start/end key strings. The leading `startType/start` specification is omitted from the String representation if the range does not have a lower bound. Similarly, the trailing `end/endType` specification is omitted if the range does not have an upper bound. Since a `KeyRange` requires at least one bound, at least one of the specifications is always present in the String representation. Here are some examples:

      I/alpha/beta/E - from `alpha` inclusive to `beta` exclusive
    E//0123/I - from "" exclusive to `0123` inclusive
  I/chi/ - from `chi` inclusive to infinity
E//- from "" exclusive to infinity /chi/E - from negative infinity to `chi` exclusive //I - from negative infinity to "" inclusive

Overrides:
  `toString` in class `Object`

- #### fromString

      public static KeyRange fromString(String keyRangeStringArg)

  Converts an encoded KeyRange back to a KeyRange. The argument String should normally be created using `toString()`. See `toString()` for more information about the KeyRange String format.
  Parameters:
    `keyRangeStringArg` - a non null KeyRange encoding string, which should normally be created using `toString()`.
  Returns:
    the resulting KeyRange object.
  Throws:
    `IllegalArgumentException` - if keyRangeStringArg does not contain a valid KeyRange encoding.
  Since:
    2.0

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