NAME

Protocol::CassandraCQL::Frames - build or parse frame bodies for specific message types

SYNOPSIS

 use Protocol::CassandraCQL qw( build_frame );
 use Protocol::CassandraCQL::Frames qw( build_query_frame );

 my $bytes = build_frame( 0x01, 0, $streamid, OPCODE_QUERY,
    build_query_frame( 1,
       cql => "CQL STRING",
       consistency => $consistency
    )->bytes
 );

DESCRIPTION

This module provides a number of convenient functions to build and parse frame bodies for specific kinds of CQL message. Each should be paired with a call to build_frame or send_frame with the appropriate opcode constant, or invoked after parse_frame or recv_frame has received a frame with the appropriate opcode.

Each build_* function takes as its first argument the CQL protocol version (the value that will be passed to build_frame or send_frame). This value is used to ensure all the correct information is present in the frame body, and that no optional parameters are passed that the chosen version of the protocol cannot support.

FUNCTIONS

$frame = build_startup_frame( $version, options => \%options )

Builds the frame for an OPCODE_STARTUP message. Takes a reference to a hash of named options. These options should include CQL_VERSION.

$frame = build_credentials_frame( $version, credentials => \%credentials )

Builds the frame for an OPCODE_CREDENTIALS message. Takes a reference to a hash of credentials, the exact keys of which will depend on the authenticator returned by the OPCODE_AUTHENTICATE message.

$frame = build_query_frame( $version, cql => $cql, QUERY_PARAMS )

Builds the frame for an OPCODE_QUERY message. Takes the CQL string and the query parameters.

QUERY_PARAMS contains the following keys:

consistency => INT

The consistency level. (required)

values => ARRAY of STRING

The encoded byte values of the bind parameters (optional, v2+ only)

skip_metadata => BOOL

If true, sets the QUERY_SKIP_METADATA flag. (optional, v2+ only)

page_size => INT

The paging size (optional, v2+ only)

paging_state => STRING

The paging state from the previous result to a query or execute. (optional, v2+ only)

serial_consistency => INT

The consistency level for CAS serialisation operations (optional, v2+ only)

$frame = build_prepare_frame( $version, cql => $cql )

Builds the frame for an OPCODE_PREPARE message. Takes the CQL string.

$frame = build_execute_frame( $version, id => $id, QUERY_PARAMS )

Builds the frame for an OPCODE_EXECUTE message. Takes the prepared statement ID, and the query parameters. QUERY_PARAMS is as for build_query_frame, except that the values key is required and permitted even at protocol version 1.

$frame = build_register_frame( $version, events => \@events )

Builds the frame for an OPCODE_REGISTER message. Takes an ARRAY reference of strings giving the event names.

( $err, $message ) = parse_error_frame( $version, $frame )

Parses the frame from an OPCODE_ERROR message. Returns an error code value and a string message.

( $authenticator ) = parse_authenticate_frame( $version, $frame )

Parses the frame from an OPCODE_AUTHENTICATE message. Returns the authenticator name as a string.

( $options ) = parse_supported_frame( $version, $frame )

Parses the frame from an OPCODE_SUPPORTED message. Returns a HASH reference mapping option names to ARRAYs of supported values.

( $type, $result ) = parse_result_frame( $version, $frame )

Parses the frame from an OPCODE_RESULT message. Returns a type value (one of the TYPE_* constants), and a value whose interpretation depends on the type.

• RESULT_VOID

  $result is undef. (This is returned by data modification queries such as INSERT, UPDATE and DELETE).

• RESULT_ROWS

  $result is an instance of Protocol::CassandraCQL::Result containing the row data. (This is returned by SELECT queries).

• RESULT_SET_KEYSPACE

  $result is a string containing the new keyspace name. (This is returned by USE queries).

• RESULT_PREPARED

  $result is an ARRAY reference containing the query ID as a string, and the bind parameters' metadata as an instance of Protocol::CassandraCQL::ColumnMeta. For v2+ this will also return the result metadata as another Protocol::CassandraCQL::ColumnMeta instance.

• RESULT_SCHEMA_CHANGE

  $result is an ARRAY reference containing three strings, giving the type of change, the keyspace, and the table name. (This is returned by data definition queries such as CREATE, ALTER and DROP).

If any other type is encountered, $result will be the $frame object itself.

( $event, @args ) = parse_event_frame( $version, $frame )

Parses the frame from an OPCODE_EVENT message. Returns the event name and a list of its arguments; which will vary depending on the event name.

• TOPOLOGY_CHANGE

  @args will contain the change type string and a node inet address

• STATUS_CHANGE

  @args will contain the status type string and a node inet address

• SCHEMA_CHANGE

  @args will contain three strings, containing the change type, keyspace, and table name

If the event name is unrecognised, @args will return just the $frame object itself.

SPONSORS

This code was paid for by

• Perceptyx http://www.perceptyx.com/

• Shadowcat Systems http://www.shadow.cat

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

cpanm Protocol::CassandraCQL

perl -MCPAN -e shell
install Protocol::CassandraCQL