src/docbkx/identifiable-entities.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <chapter version="5.0" xml:id="identifiable-entities"
   3          xmlns="http://docbook.org/ns/docbook"
   4          xmlns:xlink="http://www.w3.org/1999/xlink"
   5          xmlns:ns5="http://www.w3.org/1999/xhtml"
   6          xmlns:ns4="http://www.w3.org/2000/svg"
   7          xmlns:ns3="http://www.w3.org/1998/Math/MathML"
   8          xmlns:ns="http://docbook.org/ns/docbook">
   9   <info>
  10     <title>Identifiable Entities</title>
  11   </info>
  12
  13   <caution>
  14     <title>Likely to change</title>
  15
  16     <para>Globally unique identifiers, their use and implementation are still
  17     an unresolved topic. The implementaton of objects that are identifiable
  18     and resolvable in a global sense must, given an open world, reflect the
  19     standards and best practices being used by the community as a whole.
  20     Consequently this area of the CDM is likely to change to reflect
  21     this.</para>
  22   </caution>
  23
  24   <section>
  25     <para>Some entities in the CDM extend
  26     <classname>IdentifiableEntity</classname>. In general there is one or two
  27     abstract base classes that extend
  28     <classname>IdentifiableEntity</classname> in each package. These classes
  29     represent important objects that an application might want to share with
  30     another application (and hence, publish globally unique identifiers
  31     for).</para>
  32
  33     <para>Current implemetation of the GUID in the CDM is based on the <link
  34     xlink:href="http://www.omg.org/cgi-bin/doc?dtc/04-05-01">LSID Resolution
  35     Service</link> implementation of the <link
  36     xlink:href="http://www.cate-project.org">CATE project</link>. Each
  37     <classname>IdentifiableEntity</classname> has an <varname>lsid</varname>
  38     property. See the section on <link linkend="guid-resolution">GUID
  39     Resolution</link> to see how the CDM Java Library makes it easier for you
  40     to manage and publish your data.</para>
  41   </section>
  42
  43   <section>
  44     <!--ben: I must admit, I think I prefer formatter to cacheStrategyGenerator, because the purpose of the property seems clearer to me-->
  45
  46     <title><varname>titleCache</varname> and
  47     <varname>cacheStrategyGenerator</varname></title>
  48
  49     <para>Classes that extend <classname>IdentifiableEntity</classname> have a
  50     <varname>titleCache</varname> attribute. This property is used represent
  51     the object (for example, in a list of objects or the title for a page
  52     displaying metadata about that object). The <varname>titleCache</varname>
  53     is also used by default when sorting lists of entities. Applications are
  54     free to use other properties or combinations of properties in representing
  55     objects and can supply their own implementations of the interfaces in the
  56     <package>eu.etaxonomy.cdm.strategy.cache</package> package. If you do wish
  57     to supply custom cache strategies, you will need to inject them into your
  58     data entities, overriding the default strategy (using something like
  59     Spring's <emphasis>spring-managed</emphasis> configuration
  60     mechanism).</para>
  61   </section>
  62
  63   <section>
  64     <title>Recording Provenance using
  65     <varname>originalSource</varname></title>
  66
  67     <!-- ben: I must admit, I don't really understand how OriginalSource is supposed to work, but then I've not needed to use it. Perhaps someone else has a more clear vision for its use.-->
  68   </section>
  69
  70   <section>
  71     <title>Indicating ownership and use using <varname>rights</varname>
  72     property</title>
  73
  74     <para>Identifiable entities are significant enough that users may wish to
  75     indicate ownership of the copyright of the thing that they represent, or
  76     to provide some statement of a licence under which that data may be used.
  77     This information is held in the <varname>rights</varname> element as a
  78     series of <classname>Right</classname> objects, each representing a single
  79     rights statement.</para>
  80
  81     <para>Note that the assertation of rights in the data is not the same as
  82     access rights in terms of application-level security which is dealt with
  83     in a <link linkend="security">later section</link>.</para>
  84   </section>
  85 </chapter>