EphemeralType (Apache ZooKeeper - Server 3.7.0 API)
Date: 2021-03-17

org.apache.zookeeper.server

## Enum EphemeralType

- java.lang.Object
- - java.lang.Enum<EphemeralType>
  - - org.apache.zookeeper.server.EphemeralType

- All Implemented Interfaces:
    Serializable, Comparable<EphemeralType>

      public enum EphemeralType
      extends Enum<EphemeralType>

  Abstraction that interprets the `ephemeralOwner` field of a ZNode. Originally, the ephemeralOwner noted that a ZNode is ephemeral and which session created the node. Through an optional system property (`zookeeper.extendedTypesEnabled`) "extended" features such as TTL Nodes can be enabled. Special bits of the ephemeralOwner are used to denote which feature is enabled and the remaining bits of the ephemeralOwner are feature specific.

  When the system property `zookeeper.extendedTypesEnabled` is true, extended types are enabled. An extended ephemeralOwner is defined as an ephemeralOwner whose high 8 bits are set (`0xff00000000000000L`). The two bytes that follow the high 8 bits are used to denote which extended feature the ephemeralOwner represents. The remaining 5 bytes are used by the feature for whatever purpose is needed

  Currently, the only extended feature is TTL Nodes. It is denoted by the extended feature value of 0. i.e. for TTL Nodes, the ephemeralOwner has the high byte set to 0xff and the next 2 bytes are 0 followed by 5 bytes that represent the TTL value in milliseconds. So, an ephemeralOwner with a TTL value of 1 millisecond is: `0xff00000000000001`.

  To add new extended features: a) Add a new name to the enum, b) define a constant EXTENDED_BIT_xxxx that's next in line (after TTLs, that would be `0x0001`), c) add a mapping to the extendedFeatureMap via the static initializer

  NOTE: "Container" nodes technically are extended types but as it was implemented before this feature they are denoted specially. An ephemeral owner with only the high bit set (`0x8000000000000000L`) is by definition a container node (irrespective of whether or not extended types are enabled).

- - ### Enum Constant Summary

    Enum Constants
    Enum Constant and Description
    `CONTAINER` Container node
    `NORMAL` Standard, pre-3.5.x EPHEMERAL
    `TTL` TTL node
    `VOID` Not ephemeral

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static long` | `CONTAINER_EPHEMERAL_OWNER`
    `static long` | `MAX_EXTENDED_SERVER_ID`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static boolean` | `extendedEphemeralTypesEnabled()` Return true if extended ephemeral types are enabled
    `static EphemeralType` | `get(long ephemeralOwner)` Convert a ZNode ephemeral owner to an ephemeral type.
    `long` | `getValue(long ephemeralOwner)` For types that support it, return the extended value from an extended ephemeral owner
    `long` | `maxValue()` For types that support it, the maximum extended value
    `long` | `toEphemeralOwner(long value)` For types that support it, convert a value to an extended ephemeral owner
    `static void` | `validateServerId(long serverId)` Make sure the given server ID is compatible with the current extended ephemeral setting
    `static void` | `validateTTL(CreateMode mode, long ttl)` Utility to validate a create mode and a ttl
    `static EphemeralType` | `valueOf(String name)` Returns the enum constant of this type with the specified name.
    `static EphemeralType[]` | `values()` Returns an array containing the constants of this enum type, in the order they are declared.

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

      `clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf`

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

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Enum Constant Detail

    - #### VOID

          public static final EphemeralType VOID

      Not ephemeral

    - #### NORMAL

          public static final EphemeralType NORMAL

      Standard, pre-3.5.x EPHEMERAL

    - #### CONTAINER

          public static final EphemeralType CONTAINER

      Container node

    - #### TTL

          public static final EphemeralType TTL

      TTL node

  - ### Field Detail

    - #### CONTAINER_EPHEMERAL_OWNER

          public static final long CONTAINER_EPHEMERAL_OWNER

      See Also:
        Constant Field Values

    - #### MAX_EXTENDED_SERVER_ID

          public static final long MAX_EXTENDED_SERVER_ID

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### values

          public static EphemeralType[] values()

      Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

          for (EphemeralType c : EphemeralType.values())
              System.out.println(c);

      Returns:
        an array containing the constants of this enum type, in the order they are declared

    - #### valueOf

          public static EphemeralType valueOf(String name)

      Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
      Parameters:
        `name` - the name of the enum constant to be returned.
      Returns:
        the enum constant with the specified name
      Throws:
        `IllegalArgumentException` - if this enum type has no constant with the specified name
        `NullPointerException` - if the argument is null

    - #### maxValue

          public long maxValue()

      For types that support it, the maximum extended value
      Returns:
        0 or max

    - #### toEphemeralOwner

          public long toEphemeralOwner(long value)

      For types that support it, convert a value to an extended ephemeral owner
      Returns:
        0 or extended ephemeral owner

    - #### getValue

          public long getValue(long ephemeralOwner)

      For types that support it, return the extended value from an extended ephemeral owner
      Returns:
        0 or extended value

    - #### extendedEphemeralTypesEnabled

          public static boolean extendedEphemeralTypesEnabled()

      Return true if extended ephemeral types are enabled
      Returns:
        true/false

    - #### get

          public static EphemeralType get(long ephemeralOwner)

      Convert a ZNode ephemeral owner to an ephemeral type. If extended types are not enabled, VOID or NORMAL is always returned
      Parameters:
        `ephemeralOwner` - the ZNode's ephemeral owner
      Returns:
        type

    - #### validateServerId

          public static void validateServerId(long serverId)

      Make sure the given server ID is compatible with the current extended ephemeral setting
      Parameters:
        `serverId` - Server ID
      Throws:
        `RuntimeException` - extendedTypesEnabled is true but Server ID is too large

    - #### validateTTL

          public static void validateTTL(CreateMode mode,
                                         long ttl)

      Utility to validate a create mode and a ttl
      Parameters:
        `mode` - create mode
        `ttl` - ttl
      Throws:
        `IllegalArgumentException` - if the ttl is not valid for the mode

Copyright © 2008–2021 The Apache Software Foundation. All rights reserved.