.\" 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::MapSphere 3pm"
.TH TM::MapSphere 3pm "2008-04-10" "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::MapSphere \- Topic Maps, trait for a hierarchical TM repository
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    # construct an adhoc\-ish map sphere
\&
\&    use TM;
\&    my $tm = new TM;                            # create a map
\&
\&    use Class::Trait;
\&    Class::Trait\->apply ($tm, \*(AqTM::MapSphere\*(Aq); # make it a sphere
\&
\&    $tm\->mount (\*(Aq/abc/\*(Aq => new TM);             # mount a map into location /abc/
\&    # this creates a topic in the map with a reference to another (empty) map
\&
\&    # any subclass of TM can used
\&    $tm\->mount (\*(Aq/def/\*(Aq => new TM::Materialized::AsTMa (file => \*(Aqtest.atm\*(Aq));
\&
\&    # check a mount point
\&    warn "damn" unless $tm\->is_mounted (\*(Aq/xxx/\*(Aq);
\&
\&    # do some sync stuff on any resource\-connected map
\&    $tm\->is_mounted (\*(Aq/def/\*(Aq)\->sync_in;
\&
\&    # get rid of some mount point
\&    $tm\->umount (\*(Aq/abc/\*(Aq);
\&
\&    $tm\->internalize (\*(Aqaaa\*(Aq);         # it is a map, so all map methods work
\&    print $tm\->mids (\*(Aqdef\*(Aq);          # this topic exists and should be a map
\&    # find all child maps
\&    @maps = $tm\->instances  (\e TM::PSI\->TOPICMAP);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This package provides a \fImapspheric\fR trait, i.e. all functionality to convert any map into a
(hierarchical) Topic Maps database. The basic idea is that one map (the \fIroot\fR) contains not only
arbitrary map data, but can also contain references to other maps. On the top level, addressed as
\&\f(CW\*(C`/\*(C'\fR is then the root map. The child maps have addresses such as \f(CW\*(C`/abc/\*(C'\fR and
\&\f(CW\*(C`/internet/web/browsers/\*(C'\fR. The idea is also that a map can contain other maps, simply by having
topics which stand for these child maps. In that sense, a map is always a tree of maps (hence
\&\fIMapSphere\fR).
.PP
These trees are not necessarily static. At any point, a new map can be hooked in, or removed. This
process is quite similar to \fImounting\fR devices into a \s-1UNIX\s0 file system.
.PP
Each of the referenced child maps is represented as a topic of a predefined type \f(CW\*(C`TM::PSI::TOPICMAP\*(C'\fR, 
the subject indicator is interpreted as the \s-1URL\s0 to the resources for these maps.
.PP
The root map can be any subclass of \s-1TM\s0. You can therefore choose to have only a shortlived
mapsphere which will be lost on process termination, or alternatively, to take one of the persistent
storages. Also, the individual child maps can be of different provenances. Any subclass of \s-1TM\s0
will do, consequently also any which have the trait of TM::ResourceAble or
TM::Synchronizable. This implies that this database can be heterogenuous, in that different maps
can be stored differently, or can even be kept remotely.
.PP
Once you have your map sphere, you can write it out via synchronization with the external
resources. You can do this for the whole sphere, or for a particular subtree of maps. Conversely,
you can read in the whole map sphere by starting with the root and letting the system to recursively
bootstrap the whole sphere.
.SS "Tau Objects"
.IX Subsection "Tau Objects"
Map spheres can only store \fITau objects\fR. At the moment, these are only maps. See \s-1TM::PSI\s0 for
predefined things.
.SS "Namespace"
.IX Subsection "Namespace"
To address a particular object in a repository we follow a convention similar to file system paths:
Every object has a path like
.PP
.Vb 1
\&  /something/complete/else/
.Ve
.PP
Note, that all paths for maps should start and end with a \f(CW\*(C`/\*(C'\fR, so that maps can be seen as
\&\fIdirectories\fR. All other objects (constraints, queries, ...) are represented as topics.
.PP
The namespace cannot have \fIholes\fR, so that the following will result in an error:
.PP
.Vb 2
\&   $tm\->mount (\*(Aq/something/\*(Aq, ...);
\&   $tm\->mount (\*(Aq/something/completely/else/\*(Aq, ....);  # we will die here
.Ve
.SS "Map Meta Data"
.IX Subsection "Map Meta Data"
Since a map sphere behaves like a map, any meta data about child maps should be modelled according
to the \s-1TM\s0 paradigm.
.SH "INTERFACE"
.IX Header "INTERFACE"
This interface allows to \fImount\fR and \fIunmount\fR other maps into another.
.SS "Methods"
.IX Subsection "Methods"
.IP "\fBmount\fR" 4
.IX Item "mount"
\&\fI\f(CI$tm\fI\fR\->mount (\fI\f(CI$path\fI\fR => \fI\f(CI$tm2\fI\fR, [ \f(CW$force\fR ])
.Sp
This mounts a map \f(CW$tm2\fR into the map sphere at the given path. Only maps can be mounted,
everything else results in an error. The root will be always mounted to the map sphere itself.  It
is an error to try to change this.
.Sp
If the mount point is already taken, an exception will be raised. This can be suppressed when
the \f(CW\*(C`force\*(C'\fR parameter is set:
.Sp
.Vb 1
\&   $tm\->mount (\*(Aq/xyz/\*(Aq => $child, 1);
.Ve
.Sp
A topic of type \f(CW\*(C`topicmap\*(C'\fR (see \s-1TM::PSI\s0) is created in the map above the mount point. The base
\&\s-1URI\s0 of the map is used as subject address. If the mounted map has a resource \s-1URL\s0 that is used as
subject indicator (identifier in TMDM-speak). Additionally, the topic gets asserted characteristics:
.RS 4
.ie n .IP "mime (default: ""unknown"")" 4
.el .IP "mime (default: \f(CWunknown\fR)" 4
.IX Item "mime (default: unknown)"
A \s-1MIME\s0 type occurrence of type \f(CW\*(C`http://tm.devc.at/mapsphere/mime\*(C'\fR which is a string value.
.IP "created" 4
.IX Item "created"
An occurrence of type \f(CW\*(C`http://tm.devc.at/mapsphere/created\*(C'\fR carrying the \s-1UNIX\s0 time at mounting
time.
.RE
.RS 4
.Sp
Maps can only be mounted into other maps if these already are also mounted. The following code will
not work:
.Sp
.Vb 2
\&   my $tm = new SomeMapSphere;
\&   $tm\->mount (\*(Aq/abc/def/\*(Aq => ....);   # die here because there is no map mounted to /abc/ yet
.Ve
.RE
.IP "\fBumount\fR" 4
.IX Item "umount"
\&\fI\f(CI$tm\fI\fR\->umount (\fI\f(CI$path\fI\fR)
.Sp
This unmounts a map from the object map. Obviously, the path must point to an existing topic of type
\&\f(CW\*(C`topicmap\*(C'\fR. All maps beyond this mount point are removed, i.e. also all children will go down the
drain.
.Sp
The root cannot be unmounted.
.IP "\fBis_mounted\fR" 4
.IX Item "is_mounted"
\&\fI\f(CI$child\fI\fR = \fI\f(CI$tm\fI\fR\->is_mounted (\fI\f(CI$path\fI\fR)
.Sp
Simply returns a map object mounted on that given mount point. \f(CW\*(C`undef\*(C'\fR if there is none.
.IP "\fBmounttab\fR" 4
.IX Item "mounttab"
\&\f(CW%mt\fR = %{ \fI\f(CI$tm\fI\fR\->mounttab }
.Sp
\&\fI\f(CI$tm\fI\fR\->mounttab ( \e \fI$%mt\fR )
.Sp
This accessor sets/gets the mount table.
.Sp
\&\fBNote\fR: You will hardly need access directly to it, normally, and changing it in an uncontrolled
way may corrupt the whole data structure. The reason it exists, though, is that sometimes you
\&\fBhave\fR to indicate that there is a change, such as when using this together with \s-1MLDBM\s0.
.Sp
This, for example, does \s-1NOT\s0 work:
.Sp
.Vb 10
\&  {
\&   my $tm = new ...MapSphericalClassUsingMLDBM...;
\&   ...
\&   $tm\->is_mounted (\*(Aq/whatever/\*(Aq)\->sync_in;
\&   # A: now the child is happily sync\*(Aqed in
\&   # but MLDBM did not realize it, so it is not written back into the
\&   # underlying file
\&   }
\&  {
\&   # regain the MLDBM based MapSphere later
\&   my $tm = new ...MapSphericalClassUsingMLDBM...;
\&   # child is not sync\*(Aqed in as under A: above
\&   }
.Ve
.Sp
This does work:
.Sp
.Vb 8
\&  {
\&   my $tm = new ...MapSphericalClassUsingMLDBM...;
\&   ...
\&   my $mt = $tm\->mounttab;
\&   $tm\->is_mounted (\*(Aq/whatever/\*(Aq)\->sync_in;
\&   $tm\->mounttab ($mt);
\&   # now the changes will be written onto the MLDBM file
\&   }
.Ve
.Sp
Of course, more thought can be spent on \fIhow much\fR actually has to be written back. Above approach
may be wasteful.
.SH "AUTHOR"
.IX Header "AUTHOR"
Robert Barta, <drrho@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 200[4\-7] by Robert Barta
.PP
This library is free software; you can redistribute it and/or modify it under the same terms as Perl
itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have
available.