CPAN::Groonga

# PODNAME: Google::ProtocolBuffers::Dynamic::Message - abstract interface for message classes

__END__

=pod

=encoding UTF-8

=head1 NAME

Google::ProtocolBuffers::Dynamic::Message - abstract interface for message classes

=head1 VERSION

version 0.43

=head1 DESCRIPTION

Message classes generated by L<Google::ProtocolBuffers::Dynamic> don't
have a base class, but you can think of them as implementing the
interface described below.

=head1 METHODS

=head2 new

    $msg = Message::Class->new({
        field1         => $value1,
        message_field1 => {
            # ...
        },
        message_field2 => Message::OtherClass->new(...),
    });

Constructs a new message instances using the passed-in data.

Construction recurses into message fields, and it takes ownership of
the passed-in hash, so don't use it afterwards.

=head2 new_and_check

Constructs a new message instances using the passed-in data, and then calls L</check>. See also L</new>.

=head2 decode

    $msg = Message::Class->decode($serialized_data);

Deserializes Protocol Buffer binary data into a message instance.

=head2 decode_json

    $msg = Message::Class->decode_json($json_data);

Deserializes Protocol Buffer JSON data into a message instance.

=head2 encode

    $serialized_data = Message::Class->encode({ ... });
    $serialized_data = Message::Class->encode($message_instance);
    $serialized_data = $message_instance->encode;

Serializes the given message instance (or mix of message instances and
plain hashes) to Protocol Buffer binary format.

=head2 encode_json

    $serialized_data = Message::Class->encode_json({ ... });
    $serialized_data = Message::Class->encode_json($message_instance);
    $serialized_data = $message_instance->encode_json;

Serializes the given message instance (or mix of message instances and
plain hashes) to Protocol Buffer JSON format.

=head2 check

    Message::Class->check({ ... });
    Message::Class->check($message_instance);
    $message_instance->check;

Performs a sanity check, verifying (recursively) that the object
structure does not contain unknown fields. Consider this as a typo
protection: this check passing does not imply encoding will succeed
(for example, scalar values are not checked).

=head2 message_descriptor

    $descriptor = Message::Class->message_descriptor();
    $descriptor = $message_instance->message_descriptor();

Returns an introspection object describing the fields and types of
this message. See L<Google::ProtocolBuffers::Dynamic::Introspection> for the
full API.

See also L<Google::ProtocolBuffers::Dynamic::Introspection/enum_descriptor>.

=head1 EXTENSION METHODS

In the list below, C<extension_id> is either the fully-qualified name
of the extension or the generated constant key for that extension.

For example, given the message definitions:

    syntax = "proto2";

    package test;

    message Message1 {
        optional int32 value = 1;
        extensions 100 to 150;
    }

    extend Message1 {
        optional int32 value = 102;
    }

    message Message2 {
        extend Message1 {
            optional int32 extension2 = 101;
        }
    }

and the Perl message mapping:

    $dynamic->map({ package => 'test', to => 'Some::Perl::Package' });

the following Perl code can be used to access extension values:

    $message1 = Some::Perl::Package::Message1->decode(...);

    $value = $message1->get_extension('test.value');
    $value = $message2->get_extension(Some::Perl::Package::TEST_VALUE_KEY());
    $value = $message1->get_extension('test.Message2.extension2');
    $value = $message2->get_extension(Some::Perl::Package::TEST_MESSAGE2_EXTENSION2_KEY());

keep also in mind that getters and setters follow the style set by
L<Google::ProtocolBuffers::Dynamic/accessor_style>.

=head2 has_extension

    $has_field = $msg->has_extension($extension_id);

True if the extension field has a value.

=head2 clear_extension

    $msg->clear_extension($extension_id);

Clears the current value of an extension field.

=head2 get_extension

    $value = $msg->get_extension($extension_id);

Returns the value of a non-repeated extension field.

=head2 set_extension

    $msg->set_extension($extension_id, $value);

Sets the value of a non-repeated extension field.

=head2 get_extension_item

    $value = $msg->get_extension_item($extension_id, $index);

Gets the value of a repeated extension field item.

=head2 set_extension_item

    $msg->set_extension_item($extension_id, $index, $value);

Sets a new value for a repeated extension field item.

=head2 add_extension_item

    $msg->add_extension_item($extension_id, $value);

Appends an item to a repeated extension field.

=head2 extension_size

    $size = $msg->extension_size($extension_id);

Returns the number of items contained in a repeated extension field.

=head2 get_extension_list

    $arrayref = $msg->get_extension_list($extension_id);

Returns a mutable reference to the array backing a repeated extension field.

=head2 set_extension_list

    $msg->set_extension_list($extension_id, $arrayref);

Sets a new value for repeated extension fields.

=head1 AUTHOR

Mattia Barbon <mattia@barbon.org>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2015-2016 by Mattia Barbon.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut