.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.14)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DlfSchema 3pm"
.TH DlfSchema 3pm "2006-07-23" "Lire 2.1.1" "LogReport's Lire Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Lire::DlfSchema \- Interface to Lire DLF Schema XML specifications
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
In \s-1DLF\s0 converters:
.PP
.Vb 1
\&    use Lire::DlfSchema;
\&
\&    my $schema = Lire::DlfSchema::load_schema( "email" );
\&    my $fields = $schema\->fields();
\&
\&    my $dlf_id = $schema\->field( \*(Aqdlf_id\*(Aq );
\&    my $dlf_src = $schema\->field( \*(Aqdlf_source\*(Aq );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is the interface to the Lire \s-1DLF\s0 Schemas defined in \s-1XML\s0
files. A schema defines the order of the fields along with their
names, descriptions and types.
.PP
Each DlfSchema have at least two predefined fields:
.IP "dlf_id" 4
.IX Item "dlf_id"
This is an integer which uniquely identify a \s-1DLF\s0 record in its stream.
Its used to link the record to its extended schemas fields and also to
link the record to the derived schemas records.
.IP "dlf_source" 4
.IX Item "dlf_source"
This is an identifier which can be used to track the record the
ImportJob that created it.
.SH "ACCESSING A SCHEMA OBJECT"
.IX Header "ACCESSING A SCHEMA OBJECT"
The way to access a schema for a superservice is through the
\&\fIload_schema()\fR module function. You use it like this:
.PP
.Vb 1
\&    my $schema = Lire::DlfSchema::load_schema( $superservice);
.Ve
.PP
This function will return a schema object which can then be used to
query information about the schema. This function will \fIdie()\fR on error.
.ie n .SS "has_superservice( $superservice )"
.el .SS "has_superservice( \f(CW$superservice\fP )"
.IX Subsection "has_superservice( $superservice )"
Returns true if there is superservice named \f(CW$schema_name\fR available. An
error will be thrown if the schema name isn't valid for a superservice.
.ie n .SS "has_schema( $schema_name )"
.el .SS "has_schema( \f(CW$schema_name\fP )"
.IX Subsection "has_schema( $schema_name )"
Returns true if there is \f(CW$schema_name\fR available. An error will be
thrown if the schema name isn't valid.
.SS "\fIsuperservices()\fP"
.IX Subsection "superservices()"
Returns the name of the available superservices in an array.
.SS "\fIschemas()\fP"
.IX Subsection "schemas()"
Returns the name of the available schemas in an array.
.SH "SCHEMA OBJECT METHODS"
.IX Header "SCHEMA OBJECT METHODS"
.SS "\fIid()\fP"
.IX Subsection "id()"
.Vb 1
\&    my $id = $schema\->id();
.Ve
.PP
This method will return the id of the schema. This will be the
superservice's name for superservice's main schema. (There are other
types of schemas (derived and extended schemas) for which the id will be
different than the superservice's name.)
.SS "\fIsuperservice()\fP"
.IX Subsection "superservice()"
.Vb 1
\&    my $super = $schema\->superservice();
.Ve
.PP
This method will return the superservice's name of the schema.
.SS "title( [$new_title] )"
.IX Subsection "title( [$new_title] )"
This method will return (or change) the human readable title of the
schema. (This is the content of the title element in the \s-1XML\s0
specification.)
.SS "description( [$new_description] )"
.IX Subsection "description( [$new_description] )"
This method will return (or change) the description of the schema.
(This is the content of the description element in the \s-1XML\s0
specification.) Be aware that this will most likely contain DocBook
markup.
.SS "\fIfield_by_pos()\fP"
.IX Subsection "field_by_pos()"
.Vb 1
\&    my $field = $schema\->field_by_pos( 0 );
.Ve
.PP
This method takes an integer as parameter and return the field at that
position in the schema. Fields are indexed starting at 0. This method
will \fIdie()\fR if an invalid position is passed as parameter.
.PP
The method returns a \fILire::Field\fR\|(3pm) object.
.ie n .SS "add_field( $field )"
.el .SS "add_field( \f(CW$field\fP )"
.IX Subsection "add_field( $field )"
Adds the Lire::Field \f(CW$field\fR to this schema.
.SS "\fIhas_field()\fP"
.IX Subsection "has_field()"
.Vb 3
\&    if ( $schema\->has_field( \*(Aqtest ) ) { 
\&        print "schema has field \*(Aqtest\*(Aq\en"; 
\&    }
.Ve
.PP
This method takes a string as parameter and returns a boolean value.
That value will be true if there is a field in the schema with that
name, it will be false otherwise.
.SS "\fIfield()\fP"
.IX Subsection "field()"
.Vb 1
\&    my $field = $schema\->field( \*(Aqfrom_email\*(Aq );
.Ve
.PP
This method takes a field's name as parameter and returns the
\&\fILire::Field\fR\|(3pm) object describing that field in the schema. The
method will \fIdie()\fR if there is no field with that name in the schema.
.SS "\fIfields()\fP"
.IX Subsection "fields()"
.Vb 2
\&    my $fields = $schema\->fields();
\&    my @fields = $schema\->fields();
.Ve
.PP
In array context, this method will return an array containing all the
fields (as \fILire::Field\fR\|(3pm) objects) in the schema. The order of the
fields in the array is the order of the fields in the schema.
.PP
In scalar context, it will return an array reference. This method is
more efficient than creating an array. \s-1DO\s0 \s-1NOT\s0 \s-1MODIFY\s0 \s-1THE\s0 \s-1RETURNED\s0
\&\s-1ARRAY\s0.
.SS "\fIfield_names()\fP"
.IX Subsection "field_names()"
Returns the name of the fields in this schema. The names are in the
same order than the fields.
.SS "\fIfield_count()\fP"
.IX Subsection "field_count()"
.Vb 1
\&    my $number_of_field = $schema\->field_count;
.Ve
.PP
This method returns the number of fields in the schema.
.SS "\fItimestamp_field()\fP"
.IX Subsection "timestamp_field()"
.Vb 1
\&    my $time_field = $schema\->timestamp_field;
.Ve
.PP
This method will return the \fILire::Field\fR\|(3pm) object representing the
timestamp field in the schema. The timestamp field is the one that
defines the sort order of the \s-1DLF\s0 records.
.SS "\fIis_schema_compatible()\fP"
.IX Subsection "is_schema_compatible()"
.Vb 1
\&    if ( $schema\->is_schema_compatible( $other_schema ) ) {
\&
\&    }
.Ve
.PP
This method takes a \fILire::DlfSchema\fR\|(3pm) object as parameter and returns a
boolean value. That value will be true if the schema passed as parameter is
compatible with the other, it will be false otherwise.
.PP
For a superservice's schema, the only compatible schema is an object
representing the same superservice's schema.
.ie n .SS "can_join_schema( $schema )"
.el .SS "can_join_schema( \f(CW$schema\fP )"
.IX Subsection "can_join_schema( $schema )"
Returns true if \f(CW$schema\fR can be joined with this schema. For a
DlfSchema, this will be true only when \f(CW$schema\fR is an ExtendedSchema of
this schema.
.SH "SQL Related Methods"
.IX Header "SQL Related Methods"
These methods are used to map \s-1DLF\s0 record into \s-1SQL\s0 tables.
.SS "\fIsql_table()\fP"
.IX Subsection "sql_table()"
Returns the \s-1SQL\s0 table used to hold the \s-1DLF\s0 records of this schema.
.ie n .SS "create_sql_schema( $dlf_store, [ $remove ] )"
.el .SS "create_sql_schema( \f(CW$dlf_store\fP, [ \f(CW$remove\fP ] )"
.IX Subsection "create_sql_schema( $dlf_store, [ $remove ] )"
This will create the \s-1SQL\s0 schemas necessary to hold the \s-1DLF\s0 records for
this schema in the Lire::DlfStore. If \f(CW$remove\fR is true, a \s-1DROP\s0 \s-1TABLE\s0
will be done before creating the schema.
.ie n .SS "needs_sql_schema_migration( $dlf_store )"
.el .SS "needs_sql_schema_migration( \f(CW$dlf_store\fP )"
.IX Subsection "needs_sql_schema_migration( $dlf_store )"
This method will return true if the \s-1SQL\s0 schema isn't up-to-date in the
DlfStore. The method \fImigrate_sql_schema()\fR can be used to bring the
schema up to date.
.ie n .SS "migrate_sql_schema( $dlf_store )"
.el .SS "migrate_sql_schema( \f(CW$dlf_store\fP )"
.IX Subsection "migrate_sql_schema( $dlf_store )"
Updates the \s-1SQL\s0 schemas to the current version.
.ie n .SS "dlf_query( $sort_spec )"
.el .SS "dlf_query( \f(CW$sort_spec\fP )"
.IX Subsection "dlf_query( $sort_spec )"
Returns a Lire::DlfQuery object which can be use to return all \s-1DLF\s0
records sorted according to \f(CW$sort_spec\fR. Sort spec is a white-space
delimited list of sort field names. They must be present in the
current schema. If the field's name is prefixed by '\-', descending
sort order will be used.
.SS "\fIinsert_sql_query()\fP"
.IX Subsection "insert_sql_query()"
Returns the \s-1INSERT\s0 \s-1SQL\s0 statement that should be used to insert \s-1DLF\s0
records in the stream. A DBI::st handle prepared with that query needs
to be passed as parameter to \fIexecute_insert_query()\fR.
.ie n .SS "sql_clean_query( $with_time )"
.el .SS "sql_clean_query( \f(CW$with_time\fP )"
.IX Subsection "sql_clean_query( $with_time )"
Returns the \s-1DELETE\s0 statement that can be use to delete the \s-1DLF\s0 records
in this schema. If \f(CW$with_time\fR is true, the query can be use for
selective cleaning. One bind timestamp parameter should be passed when
the query is executed and all records which are older than this
timestamp will be deleted.
.SS "\fIsql_clean_period_query()\fP"
.IX Subsection "sql_clean_period_query()"
Returns the \s-1DELETE\s0 statement that can be use to delete the \s-1DLF\s0 records
in this schema. The query should be passed two bind parameters. These
parameters will be the time boundaries between which records should be
deleted from the schema.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fILire::Field\fR\|(3pm), \fILire::ExtendedSchema\fR\|(3pm), \fILire::DlfConverter\fR\|(3pm),
\&\fILire::DerivedSchema\fR\|(3pm)
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 1
\&  Francis J. Lacoste <flacoste@logreport.org>
.Ve
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW$Id:\fR DlfSchema.pm,v 1.58 2006/07/23 13:16:28 vanbaal Exp $
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2001, 2002, 2004 Stichting LogReport Foundation LogReport@LogReport.org
.PP
This file is part of Lire.
.PP
Lire is free software; you can redistribute it and/or modify
it under the terms of the \s-1GNU\s0 General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.PP
This program is distributed in the hope that it will be useful,
but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.  See the
\&\s-1GNU\s0 General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License
along with this program (see \s-1COPYING\s0); if not, check with
http://www.gnu.org/copyleft/gpl.html.