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>

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 class	MemcacheProtocol.Datatype
static class	MemcacheProtocol.FlexibleExtras
static class	MemcacheProtocol.Magic
static class	MemcacheProtocol.Opcode	Contains all known/used kv protocol opcodes.
static class	MemcacheProtocol.ServerPushOpcode
static class	MemcacheProtocol.Status

Field Summary

Fields

Modifier and Type	Field	Description
static byte	FRAMING_EXTRAS_READ_UNITS_USED	Signals that read/write units have been returned.
static byte	FRAMING_EXTRAS_TRACING	The byte used to signal this is a tracing extras frame.
static byte	FRAMING_EXTRAS_WRITE_UNITS_USED
static byte	PRESERVE_TTL_FLEXIBLE_IDENT	Flag which indicates that this flexible extra frame is for preserve ttl.
static byte	SYNC_REPLICATION_FLEXIBLE_IDENT	Flag which indicates that this flexible extra frame is for syc replication.
static short	SYNC_REPLICATION_TIMEOUT_FLOOR_MS	Minimum sync durability timeout that can be set and which will override any lower user-provided value.
static int	UNITS_NOT_PRESENT	The server did not return units.
static 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, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

UNSIGNED_SHORT_MAX

public static final int UNSIGNED_SHORT_MAX

Holds the max value a unsigned short can represent.

See Also:

Constant Field Values

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:

Constant Field Values

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:

Constant Field Values

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:

Constant Field Values

FRAMING_EXTRAS_TRACING

public static final byte FRAMING_EXTRAS_TRACING

The byte used to signal this is a tracing extras frame.

See Also:

Constant Field Values

FRAMING_EXTRAS_READ_UNITS_USED

public static final byte FRAMING_EXTRAS_READ_UNITS_USED

Signals that read/write units have been returned.

See Also:

Constant Field Values

FRAMING_EXTRAS_WRITE_UNITS_USED

public static final byte FRAMING_EXTRAS_WRITE_UNITS_USED

See Also:

Constant Field Values

UNITS_NOT_PRESENT

public static final int UNITS_NOT_PRESENT

The server did not return units.

See Also:

Constant Field Values

Method Detail

values

public static MemcacheProtocol[] 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 (MemcacheProtocol c : MemcacheProtocol.values())
    System.out.println(c);

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.