File Coverage

blib/lib/Elastic/Model/UID.pm

Criterion	Covered	Total	%
statement	12	51	23.5
branch	0	2	0.0
condition			n/a
subroutine	4	13	30.7
pod	7	7	100.0
total	23	73	31.5

package Elastic::Model::UID;
$Elastic::Model::UID::VERSION = '0.51';
use Moose;
use MooseX::Types::Moose qw(Str Int Maybe Bool);
use namespace::autoclean;

#===================================
has index => (
#===================================
    is       => 'ro',
    isa      => Str,
    required => 1,
    writer   => '_index'
);

#===================================
has type => (
#===================================
    is       => 'ro',
    isa      => Str,
    required => 1
);

#===================================
has id => (
#===================================
    is     => 'ro',
    isa    => Str,
    writer => '_id'
);

#===================================
has version => (
#===================================
    is     => 'ro',
    isa    => Int,
    writer => '_version'
);

#===================================
has routing => (
#===================================
    is     => 'ro',
    isa    => Maybe [Str],
    writer => '_routing'
);

#===================================
has from_store => (
#===================================
    is     => 'ro',
    isa    => Bool,
    writer => '_from_store'
);

#===================================
has 'is_partial' => (
#===================================
    is  => 'ro',
    isa => Bool,
);

#===================================
has cache_key => (
#===================================
    is      => 'ro',
    isa     => Str,
    lazy    => 1,
    builder => '_build_cache_key',
    clearer => '_clear_cache_key',
);

no Moose;

#===================================
sub new_from_store {
#===================================
    my $class  = shift;
    my %params = %{ shift() };
    $class->new(
        from_store => 1,
        routing    => $params{fields}{_routing},
        map { $_ => $params{"_$_"} } qw(index type id version)
    );
}

#===================================
sub new_partial {
#===================================
    my $class  = shift;
    my %params = %{ shift() };
    $class->new(
        from_store => 1,
        is_partial => 1,
        routing    => $params{fields}{_routing},
        map { $_ => $params{"_$_"} } qw(index type id version)
    );
}

#===================================
sub update_from_store {
#===================================
    my $self   = shift;
    my $params = shift;
    $self->$_( $params->{$_} ) for qw(_index _id _version);
    $self->_from_store(1);
    $self->_clear_cache_key;
    $self;
}

#===================================
sub update_from_uid {
#===================================
    my $self = shift;
    my $uid  = shift;
    $self->_index( $uid->index );
    $self->_routing( $uid->routing );
    $self->_version( $uid->version );
    $self->_from_store(1);
    $self->_clear_cache_key;
    $self;
}

#===================================
sub clone {
#===================================
    my $self = shift;
    bless {%$self}, ref $self;
}

#===================================
sub read_params  { shift->_params(qw(index type id routing)) }
sub write_params { shift->_params(qw(index type id routing version)) }
#===================================

#===================================
sub _params {
#===================================
    my $self = shift;
    my %vals;
    for (@_) {
        my $val = $self->$_ or next;
        $vals{$_} = $val;
    }
    return \%vals;
}

#===================================
sub _build_cache_key {
#===================================
    my $self = shift;
    return join ";", map { s/;/;;/g; $_ } map { $self->$_ } qw(type id);
}

__PACKAGE__->meta->make_immutable;

1;

=pod

=encoding UTF-8

=head1 NAME

Elastic::Model::UID - The Unique ID of a document in an Elasticsearch cluster

=head1 VERSION

version 0.51

=head1 SYNOPSIS

    $doc = $domain->new_doc(
        $type => {
            id      => $id,             # optional
            routing => $routing,        # optional
            ....
        }
    );

    $doc = $domain->get( $type => $id                      );
    $doc = $domain->get( $type => $id, routing => $routing );

    $uid = $doc->uid;

    $index   = $uid->index;
    $type    = $uid->type;
    $id      = $uid->id;
    $version = $uid->version;
    $routing = $uid->routing;

=head1 DESCRIPTION

To truly identify a document as unique in Elasticsearch, you need to know
the L<index|Elastic::Model::Terminology/Index> where it is stored, the
L<type|Elastic::Model::Terminology/Type> of the document, its
L<id|Elastic::Model::Terminology/ID>, and
possibly its L<routing|Elastic::Model::Terminology/Routing> value (which
defaults to the ID).  Also, each object
has a L</version> number which is incremented on every change.
L<Elastic::Model::UID> wraps up all of these details into an object.

=head1 ATTRIBUTES

=head2 index

The L<index|Elastic::Model::Terminology/Index> (or
L<domain|Elastic::Model::Terminology/Domain>) name.  When you create a new
document, its UID will set C<index> to C<< $domain->name >>, which may be an index
or an L<index alias|Elastic::Manual::Terminology/Alias>. However, when you
save the document, the L</index> will be updated to reflect the actual index
name.

=head2 type

The L<type|Elastic::Model::Terminology/Type> of the document, eg C<user>.

=head2 id

The string L<id|Elastic::Model::Terminology/ID> of the document - if not set
when creating a new document, then a unique ID is auto-generated when the
document is saved.

=head2 routing

The L<routing|Elastic::Model::Terminology/Routing> string is used to determine
in which shard the document lives. If not specified, then Elasticsearch
generates a routing value using a hash of the ID.  If you use a custom
routing value, then you can't change that value as the new routing B<may>
point to a new shard.  Instead, you should delete the old doc, and create a
new doc with the new routing value.

=head2 version

The version is an integer representing the current version of the document.
Each write operation will increment the C<version>, and attempts to update
an older version of the document will throw an exception.

=head2 from_store

A boolean value indicating whether the C<UID> was loaded from Elasticsearch
(C<true>) or created via L</"new()">.

=head2 is_partial

A boolean value indicating whether the C<UID> represents a partial or full
object. Partial objects cannot be saved.

=head2 cache_key

A generated string combining the L</"type"> and the L</"id">

=head1 METHODS

=head2 new()

    $uid = Elastic::Model::Uid->new(
        index   => $domain->name,               # required
        type    => $type,                       # required
        id      => $id,                         # optional
        routing => $routing,                    # optional
    );

Creates a new UID with L</"from_store"> set to false.

=head2 new_from_store()

    $uid = Elastic::Model::UID->new_from_store(
        _index   => $index,
        _type    => $type,
        _id      => $id,
        _version => $version,
        fields   => { routing => $routing }
    );

This is called when creating a new UID for a doc that has been loaded
from Elasticsearch. You shouldn't need to use this method directly.

=head2 new_partial()

    $uid = Elastic::Model::UID->new_partial(
        _index   => $index,
        _type    => $type,
        _id      => $id,
        _version => $version,
        fields   => { routing => $routing }
    );

This is called when creating a new UID for a partial doc that has been loaded
from Elasticsearch. You shouldn't need to use this method directly.

=head2 clone()

    $new_uid = $uid->clone();

Clones an existing UID.

=head2 update_from_store()

    $uid->update_from_store(
        _index   => $index,
        _id      => $id,
        _version => $version,
    );

When a doc is saved, we update the UID to use the real index name (as opposed
to an alias or domain name), the ID (in case it has been auto-generated)
and the current version number.  It also sets the L</"from_store"> attribute
to C<true>. You shouldn't need to use this method directly.

=head2 update_from_uid()

    $uid->update_from_uid($new_uid);

Updates the L</"index">, L</"routing"> and L</"id"> parameters of one UID
from a newer UID. You shouldn't need to use this method directly.

=head2 read_params()

    $params = $uid->read_params()

Returns a hashref containing L</"index">, L</"type">, L</"id"> and L</"routing">
values.

=head2 write_params()

    $params = $uid->write_params()

Returns a hashref containing L</"index">, L</"type">, L</"id">, L</"routing">
and L</"version"> values.

=head1 AUTHOR

Clinton Gormley <[e-mail]>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Clinton Gormley.

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

__END__

# ABSTRACT: The Unique ID of a document in an Elasticsearch cluster