.\" 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 "TM::ObjectAble 3pm"
.TH TM::ObjectAble 3pm "2010-10-27" "perl v5.10.1" "User Contributed Perl 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"
TM::Synchronizable \- Topic Maps, trait for storing objects into backends
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&   my $tm = ....          # get a topic map from somewhere
\&   use Class::Trait;
\&   Class::Trait\->apply ($tm, "TM::ObjectAble");
\&
\&   my %store;            # find yourself a proper store, can be anything HASHish
\&                         # append it to the list of stores, or ....
\&   push @{ $tm\->storages }, \e%store;
\&                         # prepend it to the list of stores
\&   unshift @{ $tm\->storages }, \e%store;
\&
\&   # store it (the proper storage will take it)
\&   $tm\->objectify (\*(Aqtm:some\-topic\*(Aq, "whatever object or data");
\&
\&   # get it back
\&   my @objects = $tm\->object (\*(Aqtm:some\-topic\*(Aq, \*(Aqtm:some\-topic2\*(Aq);
\&
\&   # get rid of it
\&   $tm\->deobjectify (\*(Aqtm:some\-topic\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This trait implements functionality to store arbitrary data on a per-topic basis.
.PP
Conceptually, the storage can be thought as one large hash, as keys being use the internal topic
identifiers, as values the object data. But to allow different topics to store their object data in
different places, this interface works with a list of such hashes. Each hash (native or tied to some
implementation) in the list is visited (starting from the start of the list) and can take over the
storage. Whether this is based on the topic id, on some other topic information, or on the \s-1MIME\s0 type
of the data (if it has one), is up to the implementation to decide.
.SH "INTERFACE"
.IX Header "INTERFACE"
.SS "Methods"
.IX Subsection "Methods"
.IP "\fBstorages\fR" 4
.IX Item "storages"
\&\fI\f(CI$listref\fI\fR = \fI\f(CI$tm\fI\fR\->storages
.Sp
This method returns an array reference. You can \f(CW\*(C`unshift\*(C'\fR or \f(CW\*(C`push\*(C'\fR your storage implementation
onto this list.
.Sp
Example:
.Sp
.Vb 2
\&    my %store1;
\&    push @{ $tm\->storages }, \e%store1
.Ve
.IP "\fBobjectify\fR" 4
.IX Item "objectify"
\&\fI\f(CI$tm\fI\fR\->objectify (\fI\f(CI$tid\fI\fR => \fI\f(CI$some_data\fI\fR, ...);
.Sp
This method stores actually the data. It takes a hash, with the topic id as keys and according
values and tries to find for each of the pairs an appropriate storage. If none can be found, it will
raise an exception.
.Sp
\&\fB\s-1NOTE\s0\fR: Yes, this is a stupid name.
.IP "\fBdeobjectify\fR" 4
.IX Item "deobjectify"
\&\fI\f(CI$tm\fI\fR\->deobjectify (\fI\f(CI$tid\fI\fR, ...)
.Sp
This method removes any data stored for the provided topic(s). If no data can be found in the
appropriate storage, an exception will be raised.
.IP "\fBobject\fR" 4
.IX Item "object"
\&\fI\f(CI@objects\fI\fR = \fI\f(CI$tm\fI\fR\->object (\fI\f(CI$tid\fI\fR, ...)
.Sp
This method returns any data stored for the provided objects. If no data can be found for a
particular topic, then \f(CW\*(C`undef\*(C'\fR will be returned.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1TM\s0
.SH "AUTHOR INFORMATION"
.IX Header "AUTHOR INFORMATION"
Copyright 20(10), Robert Barta <drrho@cpan.org>, All rights reserved.
.PP
This library is free software; you can redistribute it and/or modify it under the same terms as Perl
itself.  http://www.perl.com/perl/misc/Artistic.html