NAME

       TM::MapSphere - Topic Maps, trait for a hierarchical TM repository

SYNOPSIS

           # construct an adhoc-ish map sphere

           use TM;
           my $tm = new TM;                            # create a map

           use Class::Trait;
           Class::Trait->apply ($tm, 'TM::MapSphere'); # make it a sphere

           $tm->mount ('/abc/' => 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 ('/def/' => new TM::Materialized::AsTMa (file => 'test.atm'));

           # check a mount point
           warn "damn" unless $tm->is_mounted ('/xxx/');

           # do some sync stuff on any resource-connected map
           $tm->is_mounted ('/def/')->sync_in;

           # get rid of some mount point
           $tm->umount ('/abc/');

           $tm->internalize ('aaa');         # it is a map, so all map methods work
           print $tm->mids ('def');          # this topic exists and should be a map
           # find all child maps
           @maps = $tm->instances  (\ TM::PSI->TOPICMAP);

DESCRIPTION

       This package provides a mapspheric trait, i.e. all functionality to convert any map into a (hierarchical)
       Topic Maps database. The basic idea is that one map (the root) contains not only arbitrary map data, but
       can also contain references to other maps. On the top level, addressed as "/" is then the root map. The
       child maps have addresses such as "/abc/" and "/internet/web/browsers/". 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 MapSphere).

       These trees are not necessarily static. At any point, a new map can be hooked in, or removed. This
       process is quite similar to mounting devices into a UNIX file system.

       Each of the referenced child maps is represented as a topic of a predefined type "TM::PSI::TOPICMAP", the
       subject indicator is interpreted as the URL to the resources for these maps.

       The root map can be any subclass of TM. 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 TM 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.

       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.

   Tau Objects
       Map spheres can only store Tau objects. At the moment, these are only maps. See TM::PSI for predefined
       things.

   Namespace
       To address a particular object in a repository we follow a convention similar to file system paths: Every
       object has a path like

         /something/complete/else/

       Note, that all paths for maps should start and end with a "/", so that maps can be seen as directories.
       All other objects (constraints, queries, ...) are represented as topics.

       The namespace cannot have holes, so that the following will result in an error:

          $tm->mount ('/something/', ...);
          $tm->mount ('/something/completely/else/', ....);  # we will die here

   Map Meta Data
       Since a map sphere behaves like a map, any meta data about child maps should be modelled according to the
       TM paradigm.

INTERFACE

       This interface allows to mount and unmount other maps into another.

   Methods
       mount
           $tm->mount ($path => $tm2, [ $force ])

           This  mounts  a  map $tm2 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.

           If  the  mount  point  is already taken, an exception will be raised. This can be suppressed when the
           "force" parameter is set:

              $tm->mount ('/xyz/' => $child, 1);

           A topic of type "topicmap" (see TM::PSI) is created in the map above the mount point. The base URI of
           the map is used as subject address. If the mounted map has a resource URL that  is  used  as  subject
           indicator (identifier in TMDM-speak). Additionally, the topic gets asserted characteristics:

           mime (default: "unknown")
               A MIME type occurrence of type "http://tm.devc.at/mapsphere/mime" which is a string value.

           created
               An  occurrence  of  type "http://tm.devc.at/mapsphere/created" carrying the UNIX time at mounting
               time.

           Maps can only be mounted into other maps if these already are also mounted. The following  code  will
           not work:

              my $tm = new SomeMapSphere;
              $tm->mount ('/abc/def/' => ....);   # die here because there is no map mounted to /abc/ yet

       umount
           $tm->umount ($path)

           This  unmounts a map from the object map. Obviously, the path must point to an existing topic of type
           "topicmap". All maps beyond this mount point are removed, i.e. also all children  will  go  down  the
           drain.

           The root cannot be unmounted.

       is_mounted
           $child = $tm->is_mounted ($path)

           Simply returns a map object mounted on that given mount point. "undef" if there is none.

       mounttab
           %mt = %{ $tm->mounttab }

           $tm->mounttab ( \ $%mt )

           This accessor sets/gets the mount table.

           Note:  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  have  to
           indicate that there is a change, such as when using this together with MLDBM.

           This, for example, does NOT work:

             {
              my $tm = new ...MapSphericalClassUsingMLDBM...;
              ...
              $tm->is_mounted ('/whatever/')->sync_in;
              # A: now the child is happily sync'ed 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'ed in as under A: above
              }

           This does work:

             {
              my $tm = new ...MapSphericalClassUsingMLDBM...;
              ...
              my $mt = $tm->mounttab;
              $tm->is_mounted ('/whatever/')->sync_in;
              $tm->mounttab ($mt);
              # now the changes will be written onto the MLDBM file
              }

           Of  course, more thought can be spent on how much actually has to be written back. Above approach may
           be wasteful.

AUTHOR

       Robert Barta, <drrho@cpan.org>

COPYRIGHT AND LICENSE

       Copyright (C) 200[4-7] by Robert Barta

       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.

perl v5.26.0                                       2017-08-24                                 TM::MapSphere(3pm)