Package com.couchbase.client.core.io.netty.kv

Enum MemcacheProtocol

java.lang.Object
java.lang.Enum<MemcacheProtocol>
com.couchbase.client.core.io.netty.kv.MemcacheProtocol
All Implemented Interfaces:
Serializable, Comparable<MemcacheProtocol>, java.lang.constant.Constable
public enum MemcacheProtocol extends Enum<MemcacheProtocol>
The MemcacheProtocol class holds static helpers that deal with the encoding and decoding as well as access of the memcache binary protocol.
Since:
2.0.0

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    MemcacheProtocol.Datatype
     
    static class 
    MemcacheProtocol.FlexibleExtras
     
    static enum 
    MemcacheProtocol.Magic
     
    static enum 
    MemcacheProtocol.Opcode
    Contains all known/used kv protocol opcodes.
    static enum 
    MemcacheProtocol.ServerPushOpcode
     
    static enum 
    MemcacheProtocol.Status
     

    Nested classes/interfaces inherited from class java.lang.Enum

    Enum.EnumDesc<E extends Enum<E>>

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final byte
    FRAMING_EXTRAS_READ_UNITS_USED
    Signals that read/write units have been returned.
    static final byte
    FRAMING_EXTRAS_TRACING
    The byte used to signal this is a tracing extras frame.
    static final byte
    FRAMING_EXTRAS_WRITE_UNITS_USED
     
    static final byte
    PRESERVE_TTL_FLEXIBLE_IDENT
    Flag which indicates that this flexible extra frame is for preserve ttl.
    static final byte
    SYNC_REPLICATION_FLEXIBLE_IDENT
    Flag which indicates that this flexible extra frame is for syc replication.
    static final short
    SYNC_REPLICATION_TIMEOUT_FLOOR_MS
    Minimum sync durability timeout that can be set and which will override any lower user-provided value.
    static final int
    UNITS_NOT_PRESENT
    The server did not return units.
    static final int
    UNSIGNED_SHORT_MAX
    Holds the max value a unsigned short can represent.

  • Method Summary

    Modifier and Type
    Method
    Description
    static Optional<com.couchbase.client.core.deps.io.netty.buffer.ByteBuf>
    body(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
    Returns the decompressed body of the message, or an empty Optional if the body length is zero.
    static byte[]
    bodyAsBytes(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
    Returns the decompressed body of this message as a byte array.
    static String
    bodyAsString(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
    Returns the decompressed body of this message as a UTF-8 string.
    static long
    cas(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
    Helper method to extract the cas from a message.
    static byte
    datatype(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
    Helper method to return the datatype from a request or response.
    static ResponseStatus
    decodeStatus(short status)
    Converts the KeyValue protocol status into its generic format.
    static ResponseStatus
    decodeStatus(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
    Decodes and converts the status from a message.
    static SubDocumentOpResponseStatus
    decodeSubDocumentStatus(short status)
    Converts a KeyValue protocol status into its generic format.
    static Optional<MutationToken>
    extractToken(boolean enabled, short partition, com.couchbase.client.core.deps.io.netty.buffer.ByteBuf msg, String bucket)
    Tries to extract the mutation token if the surround msg and environment allows for it.
    static Optional<com.couchbase.client.core.deps.io.netty.buffer.ByteBuf>
    extras(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
     
    static int
    extrasAsInt(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message, int offset, int defaultValue)
    Tries to extract the extras as an integer value and if not possible returns the default value.
    static byte
    extrasLength(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
     
    static byte
    flexExtrasLength(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
     
    static MemcacheProtocol.FlexibleExtras
    flexibleExtras(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
    Retrieve the flexible extras from the packet.
    static com.couchbase.client.core.deps.io.netty.buffer.ByteBuf
    flexibleRequest(com.couchbase.client.core.deps.io.netty.buffer.ByteBufAllocator alloc, MemcacheProtocol.Opcode opcode, byte datatype, short partition, int opaque, long cas, com.couchbase.client.core.deps.io.netty.buffer.ByteBuf framingExtras, com.couchbase.client.core.deps.io.netty.buffer.ByteBuf extras, com.couchbase.client.core.deps.io.netty.buffer.ByteBuf key, com.couchbase.client.core.deps.io.netty.buffer.ByteBuf body)
    Create a flexible memcached protocol request with all fields necessary.
    static boolean
    isFlexible(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
     
    static boolean
    isRequest(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
     
    static Optional<com.couchbase.client.core.deps.io.netty.buffer.ByteBuf>
    key(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
     
    static short
    keyLength(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
     
    static byte
    magic(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
     
    static CouchbaseException
    mapSubDocumentError(KeyValueRequest<?> request, SubDocumentOpResponseStatus status, String path, int index, MemcacheProtocol.FlexibleExtras flexibleExtras)
    For any response that can be returned by a SubDocument command - path, document, or execution-based - map it to an appropriate SubDocumentException.
    static String
    messageToString(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
    Helper method during development and debugging to dump the raw message as a verbose string.
    static com.couchbase.client.core.deps.io.netty.buffer.ByteBuf
    mutationFlexibleExtras(KeyValueRequest<?> request, KeyValueChannelContext ctx, com.couchbase.client.core.deps.io.netty.buffer.ByteBufAllocator alloc, Optional<DurabilityLevel> durabilityLevel)
     
    static com.couchbase.client.core.deps.io.netty.buffer.ByteBuf
    mutationFlexibleExtras(KeyValueRequest<?> request, KeyValueChannelContext ctx, com.couchbase.client.core.deps.io.netty.buffer.ByteBufAllocator alloc, Optional<DurabilityLevel> durabilityLevel, boolean preserveExpiry)
     
    static com.couchbase.client.core.deps.io.netty.buffer.ByteBuf
    noBody()
    Helper to express no body is used for this message.
    static long
    noCas()
    Helper to express no cas is used for this message.
    static byte
    noDatatype()
    Helper to express no datatype is used for this message.
    static com.couchbase.client.core.deps.io.netty.buffer.ByteBuf
    noExtras()
    Helper to express no extras are used for this message.
    static com.couchbase.client.core.deps.io.netty.buffer.ByteBuf
    noFramingExtras()
    Helper to express no framing extras are used for this message.
    static com.couchbase.client.core.deps.io.netty.buffer.ByteBuf
    noKey()
    Helper to express no key is used for this message.
    static int
    noOpaque()
    Helper to express no opaque is used for this message.
    static short
    noPartition()
    Helper to express no partition is used for this message.
    static int
    opaque(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
    Helper method to return the opaque value for the given request or response.
    static byte
    opcode(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
    Helper method to return the opcode for the given request or response.
    static long
    parseServerDurationFromResponse(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf response)
    Parses the server duration from the frame.
    static Optional<com.couchbase.client.core.deps.io.netty.buffer.ByteBuf>
    rawBody(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
    Returns the raw (possibly compressed) content of the message, or an empty Optional if the raw content length is zero.
    static com.couchbase.client.core.deps.io.netty.buffer.ByteBuf
    request(com.couchbase.client.core.deps.io.netty.buffer.ByteBufAllocator alloc, MemcacheProtocol.Opcode opcode, byte datatype, short partition, int opaque, long cas, com.couchbase.client.core.deps.io.netty.buffer.ByteBuf extras, com.couchbase.client.core.deps.io.netty.buffer.ByteBuf key, com.couchbase.client.core.deps.io.netty.buffer.ByteBuf body)
    Create a regular, non-flexible memcached protocol request with all fields necessary.
    static com.couchbase.client.core.deps.io.netty.buffer.ByteBuf
    response(com.couchbase.client.core.deps.io.netty.buffer.ByteBufAllocator alloc, MemcacheProtocol.Opcode opcode, byte datatype, short status, int opaque, long cas, com.couchbase.client.core.deps.io.netty.buffer.ByteBuf extras, com.couchbase.client.core.deps.io.netty.buffer.ByteBuf key, com.couchbase.client.core.deps.io.netty.buffer.ByteBuf body)
    Create a regular, non-flexible memcached protocol response with all fields necessary.
    static short
    status(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
    Returns the status of that response.
    static boolean
    successful(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
    Helper method to check if the given response has a successful status.
    static int
    totalBodyLength(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
     
    static com.couchbase.client.core.deps.io.netty.buffer.ByteBuf
    tryCompression(byte[] input, double minRatio)
    Try to compress the input, but if it is below the min ratio then it will return null.
    static byte[]
    tryDecompression(byte[] input, byte datatype)
    Try to decompress the input if the datatype has the snappy flag enabled.
    static MemcacheProtocol
    valueOf(String name)
    Returns the enum constant of this type with the specified name.
    static MemcacheProtocol[]
    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, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

    Methods inherited from class java.lang.Object

    getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • UNSIGNED_SHORT_MAX

      public static final int UNSIGNED_SHORT_MAX
      Holds the max value a unsigned short can represent.
      See Also:

    • SYNC_REPLICATION_FLEXIBLE_IDENT

      public static final byte SYNC_REPLICATION_FLEXIBLE_IDENT
      Flag which indicates that this flexible extra frame is for syc replication.
      See Also:

    • PRESERVE_TTL_FLEXIBLE_IDENT

      public static final byte PRESERVE_TTL_FLEXIBLE_IDENT
      Flag which indicates that this flexible extra frame is for preserve ttl.
      See Also:

    • SYNC_REPLICATION_TIMEOUT_FLOOR_MS

      public static final short SYNC_REPLICATION_TIMEOUT_FLOOR_MS
      Minimum sync durability timeout that can be set and which will override any lower user-provided value.
      See Also:

    • FRAMING_EXTRAS_TRACING

      public static final byte FRAMING_EXTRAS_TRACING
      The byte used to signal this is a tracing extras frame.
      See Also:

    • FRAMING_EXTRAS_READ_UNITS_USED

      public static final byte FRAMING_EXTRAS_READ_UNITS_USED
      Signals that read/write units have been returned.
      See Also:

    • FRAMING_EXTRAS_WRITE_UNITS_USED

      public static final byte FRAMING_EXTRAS_WRITE_UNITS_USED
      See Also:

    • UNITS_NOT_PRESENT

      public static final int UNITS_NOT_PRESENT
      The server did not return units.
      See Also:

  • Method Details

    • values

      public static MemcacheProtocol[] values()
      Returns an array containing the constants of this enum type, in the order they are declared.
      Returns:
      an array containing the constants of this enum type, in the order they are declared

    • valueOf

      public static MemcacheProtocol 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

    • flexibleRequest

      public static com.couchbase.client.core.deps.io.netty.buffer.ByteBuf flexibleRequest(com.couchbase.client.core.deps.io.netty.buffer.ByteBufAllocator alloc, MemcacheProtocol.Opcode opcode, byte datatype, short partition, int opaque, long cas, com.couchbase.client.core.deps.io.netty.buffer.ByteBuf framingExtras, com.couchbase.client.core.deps.io.netty.buffer.ByteBuf extras, com.couchbase.client.core.deps.io.netty.buffer.ByteBuf key, com.couchbase.client.core.deps.io.netty.buffer.ByteBuf body)
      Create a flexible memcached protocol request with all fields necessary.

    • request

      public static com.couchbase.client.core.deps.io.netty.buffer.ByteBuf request(com.couchbase.client.core.deps.io.netty.buffer.ByteBufAllocator alloc, MemcacheProtocol.Opcode opcode, byte datatype, short partition, int opaque, long cas, com.couchbase.client.core.deps.io.netty.buffer.ByteBuf extras, com.couchbase.client.core.deps.io.netty.buffer.ByteBuf key, com.couchbase.client.core.deps.io.netty.buffer.ByteBuf body)
      Create a regular, non-flexible memcached protocol request with all fields necessary.

    • response

      public static com.couchbase.client.core.deps.io.netty.buffer.ByteBuf response(com.couchbase.client.core.deps.io.netty.buffer.ByteBufAllocator alloc, MemcacheProtocol.Opcode opcode, byte datatype, short status, int opaque, long cas, com.couchbase.client.core.deps.io.netty.buffer.ByteBuf extras, com.couchbase.client.core.deps.io.netty.buffer.ByteBuf key, com.couchbase.client.core.deps.io.netty.buffer.ByteBuf body)
      Create a regular, non-flexible memcached protocol response with all fields necessary.

      This method is mostly used for testing purposes.

    • status

      public static short status(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
      Returns the status of that response.
      Parameters:
      message - the memcache message to extract from.
      Returns:
      the status field.

    • keyLength

      public static short keyLength(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)

    • isFlexible

      public static boolean isFlexible(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)

    • flexExtrasLength

      public static byte flexExtrasLength(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)

    • extrasLength

      public static byte extrasLength(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)

    • magic

      public static byte magic(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)

    • isRequest

      public static boolean isRequest(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)

    • totalBodyLength

      public static int totalBodyLength(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)

    • successful

      public static boolean successful(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
      Helper method to check if the given response has a successful status.
      Parameters:
      message - the memcache message to extract from.
      Returns:
      true if success.

    • opcode

      public static byte opcode(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
      Helper method to return the opcode for the given request or response.
      Parameters:
      message - the message to get the opcode from.
      Returns:
      the opcode as a byte.

    • datatype

      public static byte datatype(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
      Helper method to return the datatype from a request or response.
      Parameters:
      message - the message to get the datatype from.
      Returns:
      the datatype as a byte.

    • opaque

      public static int opaque(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
      Helper method to return the opaque value for the given request or response.
      Parameters:
      message - the message to get the opaque from.
      Returns:
      the opaque as an int.

    • cas

      public static long cas(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
      Helper method to extract the cas from a message.
      Parameters:
      message - the message to extract the cas from.
      Returns:
      the cas as a long.

    • body

      public static Optional<com.couchbase.client.core.deps.io.netty.buffer.ByteBuf> body(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
      Returns the decompressed body of the message, or an empty Optional if the body length is zero.

    • rawBody

      public static Optional<com.couchbase.client.core.deps.io.netty.buffer.ByteBuf> rawBody(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
      Returns the raw (possibly compressed) content of the message, or an empty Optional if the raw content length is zero.

    • key

      public static Optional<com.couchbase.client.core.deps.io.netty.buffer.ByteBuf> key(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)

    • bodyAsBytes

      public static byte[] bodyAsBytes(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
      Returns the decompressed body of this message as a byte array.

    • bodyAsString

      public static String bodyAsString(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
      Returns the decompressed body of this message as a UTF-8 string.

    • extras

      public static Optional<com.couchbase.client.core.deps.io.netty.buffer.ByteBuf> extras(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)

    • extrasAsInt

      public static int extrasAsInt(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message, int offset, int defaultValue)
      Tries to extract the extras as an integer value and if not possible returns the default value.

      Note that while this method looks a bit too specific, in profiling it has been shown that extras extraction on the get command otherwise needs a buffer slice and has to box the integer due to the optional. So this avoids two small performance hits and it can be used on the hot code path.

      Parameters:
      message - the message to extract from.
      offset - the offset in the extras from where the int should be loaded.
      defaultValue - the default value to use.
      Returns:
      th extracted integer or the default value.

    • flexibleExtras

      @Nullable public static MemcacheProtocol.FlexibleExtras flexibleExtras(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
      Retrieve the flexible extras from the packet. These are AKA "framing extras" and "flexible framing extras". These are distinct from just "extras".

    • noKey

      public static com.couchbase.client.core.deps.io.netty.buffer.ByteBuf noKey()
      Helper to express no key is used for this message.

    • noExtras

      public static com.couchbase.client.core.deps.io.netty.buffer.ByteBuf noExtras()
      Helper to express no extras are used for this message.

    • noFramingExtras

      public static com.couchbase.client.core.deps.io.netty.buffer.ByteBuf noFramingExtras()
      Helper to express no framing extras are used for this message.

    • noBody

      public static com.couchbase.client.core.deps.io.netty.buffer.ByteBuf noBody()
      Helper to express no body is used for this message.

    • noDatatype

      public static byte noDatatype()
      Helper to express no datatype is used for this message.

    • noPartition

      public static short noPartition()
      Helper to express no partition is used for this message.

    • noOpaque

      public static int noOpaque()
      Helper to express no opaque is used for this message.

    • noCas

      public static long noCas()
      Helper to express no cas is used for this message.

    • decodeStatus

      public static ResponseStatus decodeStatus(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
      Decodes and converts the status from a message.

      This is a convenience method usually used in decoders.

      Parameters:
      message - the message to extract from.
      Returns:
      the decoded status.

    • mutationFlexibleExtras

      public static com.couchbase.client.core.deps.io.netty.buffer.ByteBuf mutationFlexibleExtras(KeyValueRequest<?> request, KeyValueChannelContext ctx, com.couchbase.client.core.deps.io.netty.buffer.ByteBufAllocator alloc, Optional<DurabilityLevel> durabilityLevel)

    • mutationFlexibleExtras

      public static com.couchbase.client.core.deps.io.netty.buffer.ByteBuf mutationFlexibleExtras(KeyValueRequest<?> request, KeyValueChannelContext ctx, com.couchbase.client.core.deps.io.netty.buffer.ByteBufAllocator alloc, Optional<DurabilityLevel> durabilityLevel, boolean preserveExpiry)

    • parseServerDurationFromResponse

      public static long parseServerDurationFromResponse(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf response)
      Parses the server duration from the frame. It reads through the byte stream looking for the tracing frame and if found extracts the info. If a different frame is found it is just skipped. Per algorithm, the found server duration is round up/down using the Math.round(float) function and has microsecond precision.
      Parameters:
      response - the response to extract it from.
      Returns:
      the extracted duration, 0 if not found.

    • decodeStatus

      public static ResponseStatus decodeStatus(short status)
      Converts the KeyValue protocol status into its generic format.

      Note that only the most likely statuses are covered here, the rest is in decodeOtherStatus(short) so that the JIT can inline the method efficiently.

      Parameters:
      status - the protocol status.
      Returns:
      the response status.

    • decodeSubDocumentStatus

      public static SubDocumentOpResponseStatus decodeSubDocumentStatus(short status)
      Converts a KeyValue protocol status into its generic format. It must be a status that can be returned from a sub-document operation.
      Parameters:
      status - the protocol status.
      Returns:
      the response status.

    • mapSubDocumentError

      public static CouchbaseException mapSubDocumentError(KeyValueRequest<?> request, SubDocumentOpResponseStatus status, String path, int index, @Nullable MemcacheProtocol.FlexibleExtras flexibleExtras)
      For any response that can be returned by a SubDocument command - path, document, or execution-based - map it to an appropriate SubDocumentException.

    • tryCompression

      public static com.couchbase.client.core.deps.io.netty.buffer.ByteBuf tryCompression(byte[] input, double minRatio)
      Try to compress the input, but if it is below the min ratio then it will return null.
      Parameters:
      input - the input array.
      minRatio - the minimum ratio to accept and return the buffer.
      Returns:
      a ByteBuf if compressed, or null if below the min ratio.

    • tryDecompression

      public static byte[] tryDecompression(byte[] input, byte datatype)
      Try to decompress the input if the datatype has the snappy flag enabled.

      If datatype does not indicate snappy enabled, then the input is returned as presented.

      Parameters:
      input - the input byte array.
      datatype - the datatype for the response.
      Returns:
      the byte array, either decoded or the input straight.

    • messageToString

      public static String messageToString(com.couchbase.client.core.deps.io.netty.buffer.ByteBuf message)
      Helper method during development and debugging to dump the raw message as a verbose string.

    • extractToken

      public static Optional<MutationToken> extractToken(boolean enabled, short partition, com.couchbase.client.core.deps.io.netty.buffer.ByteBuf msg, String bucket)
      Tries to extract the mutation token if the surround msg and environment allows for it.
      Parameters:
      enabled - if enabled
      partition - the partition id
      msg - the msg to check
      bucket - the bucket for this msg
      Returns:
      an optional with content if successful, false otherwise.