# ***********************************************
# 
# !!!! DO NOT EDIT !!!!
# 
# This file was auto-generated by Build.PL.
# 
# ***********************************************
# 
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements.  See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License.  You may obtain a copy of the License at
# 
#     http://www.apache.org/licenses/LICENSE-2.0
# 
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

=encoding utf8

=head1 NAME

Lucy::Index::DataWriter - Write data to an index.

=head1 SYNOPSIS

    # Abstract base class.

=head1 DESCRIPTION

DataWriter is an abstract base class for writing index data, generally in
segment-sized chunks. Each component of an index – e.g. stored fields,
lexicon, postings, deletions – is represented by a
DataWriter/L<DataReader|Lucy::Index::DataReader> pair.

Components may be specified per index by subclassing
L<Architecture|Lucy::Plan::Architecture>.

=head1 CONSTRUCTORS

=head2 new

    my $writer = MyDataWriter->new(
        snapshot   => $snapshot,      # required
        segment    => $segment,       # required
        polyreader => $polyreader,    # required
    );

Abstract constructor.

=over

=item *

B<snapshot> - The Snapshot that will be committed at the end of the
indexing session.

=item *

B<segment> - The Segment in progress.

=item *

B<polyreader> - A PolyReader representing all existing data in the
index.  (If the index is brand new, the PolyReader will have no
sub-readers).

=back

=head1 ABSTRACT METHODS

=head2 add_segment

    $data_writer->add_segment(
        reader  => $reader   # required
        doc_map => $doc_map  # default: undef
    );

Add content from an existing segment into the one currently being
written.

=over

=item *

B<reader> - The SegReader containing content to add.

=item *

B<doc_map> - An array of integers mapping old document ids to
new.  Deleted documents are mapped to 0, indicating that they should be
skipped.

=back

=head2 finish

    $data_writer->finish();

Complete the segment: close all streams, store metadata, etc.

=head2 format

    my $retval = $data_writer->format();

Every writer must specify a file format revision number, which should
increment each time the format changes. Responsibility for revision
checking is left to the companion DataReader.

=head1 METHODS

=head2 delete_segment

    $data_writer->delete_segment($reader);

Remove a segment’s data.  The default implementation is a no-op, as
all files within the segment directory will be automatically deleted.
Subclasses which manage their own files outside of the segment system
should override this method and use it as a trigger for cleaning up
obsolete data.

=over

=item *

B<reader> - The SegReader containing content to merge, which must
represent a segment which is part of the the current snapshot.

=back

=head2 merge_segment

    $data_writer->merge_segment(
        reader  => $reader   # required
        doc_map => $doc_map  # default: undef
    );

Move content from an existing segment into the one currently being
written.

The default implementation calls L<add_segment()|/add_segment> then L<delete_segment()|/delete_segment>.

=over

=item *

B<reader> - The SegReader containing content to merge, which must
represent a segment which is part of the the current snapshot.

=item *

B<doc_map> - An array of integers mapping old document ids to
new.  Deleted documents are mapped to 0, indicating that they should be
skipped.

=back

=head2 metadata

    my $retval = $data_writer->metadata();

Arbitrary metadata to be serialized and stored by the Segment.  The
default implementation supplies a Hash with a single key-value pair for
“format”.

=head2 get_snapshot

    my $retval = $data_writer->get_snapshot();

Accessor for “snapshot” member var.

=head2 get_segment

    my $retval = $data_writer->get_segment();

Accessor for “segment” member var.

=head2 get_polyreader

    my $retval = $data_writer->get_polyreader();

Accessor for “polyreader” member var.

=head2 get_schema

    my $retval = $data_writer->get_schema();

Accessor for “schema” member var.

=head2 get_folder

    my $retval = $data_writer->get_folder();

Accessor for “folder” member var.

=head1 INHERITANCE

Lucy::Index::DataWriter isa Clownfish::Obj.

=cut