<?xml version="1.0" encoding="UTF-8"?>
<!-- ====================================================================== -->
<!-- = afnix-rm-tcz.xml                                                   = -->
<!-- = standard tcz service - reference manual                            = -->
<!-- ====================================================================== -->
<!-- = This  program  is  free  software; you  can redistribute it and/or = -->
<!-- = modify it provided that this copyright notice is kept intact.      = -->
<!-- = This program is distributed in the hope that it will be useful but = -->
<!-- = without  any  warranty;  without  even  the  implied  warranty  of = -->
<!-- = merchantability or fitness for  a  particular purpose. In no event = -->
<!-- = shall  the  copyright  holder be liable for any  direct, indirect, = -->
<!-- = incidental  or special  damages arising  in any way out of the use = -->
<!-- = of this software.                                                  = -->
<!-- ====================================================================== -->
<!-- = copyright (c) 1999-2023 - amaury darsch                            = -->
<!-- ====================================================================== -->

<appendix service="tcz" number="i">
  <title>Standard Transmutable Content Zone Reference</title>

  <!-- =================================================================== -->
  <!-- = part object                                                     = -->
  <!-- =================================================================== -->

  <object nameset="afnix:tcz">
    <name>Part</name>

    <p>
      The <code>Part</code> class is a taggable object which is bound
      by a unique key and provide a plist interface access. The part
      object is the foundation of the blob object and is also used to
      feed a collection. The key is represented by a uuid object.
    </p>

    <!-- predicate -->
    <pred>part-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Taggable</name>
    </inherit>

    <!-- constructors -->
    <ctors>
      <ctor>
	<name>Part</name>
	<args>none</args>
	<p>
	  The <code>Part</code> constructor creates an empty part
	</p>
      </ctor>
      <ctor>
	<name>Part</name>
	<args>String</args>
	<p>
	  The <code>Part</code> constructor creates a part by name.
	</p>
      </ctor>
      <ctor>
	<name>Part</name>
	<args>String String</args>
	<p>
	  The <code>Part</code> constructor creates a part by name and
	  info strings.
	</p>
      </ctor>
    </ctors>

    <!-- methods -->
    <methods>
      <meth>
	<name>kid-p</name>
	<retn>Boolean</retn>
	<args>String</args>
	<p>
	  The <code>kip-p</code> predicate returns true if the part
	  kid can be validated.
	</p>
      </meth>
      <meth>
	<name>property-p</name>
	<retn>Boolean</retn>
	<args>String</args>
	<p>
	  The <code>property-p</code> predicate returns true if the property
	  name argument is defined in the part.
	</p>
      </meth>
      <meth>
	<name>get-kid</name>
	<retn>Uuid</retn>
	<args>none</args>
	<p>
	  The <code>get-kid</code> method returns the part kid.
	</p>
      </meth>
      <meth>
	<name>add</name>
	<retn>none</retn>
	<args>String Literal</args>
	<p>
	  The <code>add</code> method adds a property to the part.
	</p>
      </meth>
      <meth>
	<name>get-header</name>
	<retn>Plist</retn>
	<args>none</args>
	<p>
	  The <code>get-header</code> method returns the part header
	  which is a plist with the part name, info and uuid.
	</p>
      </meth>
      <meth>
	<name>get-plist</name>
	<retn>Plist</retn>
	<args>none</args>
	<p>
	  The <code>get-plist</code> method returns the part plist.
	</p>
      </meth>
      <meth>
	<name>get-value</name>
	<retn>String</retn>
	<args>String</args>
	<p>
	  The <code>get-value</code> method returns the a part
	  property value by name.
	</p>
      </meth>
      <meth>
	<name>to-lteral</name>
	<retn>Literal</retn>
	<args>String</args>
	<p>
	  The <code>toliteral</code> method returns the a part
	  property literal by name.
	</p>
      </meth>
    </methods>
  </object>

  <!-- =================================================================== -->
  <!-- = blob object                                                     = -->
  <!-- =================================================================== -->

  <object nameset="afnix:tcz">
    <name>Blob</name>

    <p>
      The <code>Blob</code> class is a base class that models the
      behavior of a registered blob through the use of a registration
      id. The blob is registered as soon as its registration id is
      set. If the registration id is unset, the object is unregistered
      or anonymous. The registration id can be anything as long as as
      it is understood by the implementation that such registration is
      to be interpreted somewhere else. The blob is also a part which
      means that it has a name, info and unique key.
    </p>

    <!-- predicate -->
    <pred>blob-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Part</name>
    </inherit>

    <!-- constructors -->
    <ctors>
      <ctor>
	<name>Blob</name>
	<args>none</args>
	<p>
	  The <code>Blob</code> constructor creates an empty blob.
	</p>
      </ctor>
      <ctor>
	<name>Blob</name>
	<args>String</args>
	<p>
	  The <code>Blob</code> constructor creates a blob by name.
	</p>
      </ctor>
      <ctor>
	<name>Blob</name>
	<args>String String</args>
	<p>
	  The <code>Blob</code> constructor creates a blob by name and
	  info strings.
	</p>
      </ctor>
      <ctor>
	<name>Blob</name>
	<args>String String String</args>
	<p>
	  The <code>Blob</code> constructor creates a blob by rid, name and
	  info strings.
	</p>
      </ctor>
    </ctors>

    <!-- methods -->
    <methods>
      <meth>
	<name>rid-p</name>
	<retn>Boolean</retn>
	<args>none</args>
	<p>
	  The <code>rid-p</code> predicate returns true if the blob
	  registration id is set.
	</p>
      </meth>

      <meth>
	<name>set-rid</name>
	<retn>none</retn>
	<args>String</args>
	<p>
	  The <code>set-rid</code> method sets the blob rid.
	</p>
      </meth>

      <meth>
	<name>get-rid</name>
	<retn>String</retn>
	<args>none</args>
	<p>
	  The <code>get-rid</code> method returns the blob rid.
	</p>
      </meth>
    </methods>
  </object>
  
  <!-- =================================================================== -->
  <!-- = bloc object                                                     = -->
  <!-- =================================================================== -->

  <object nameset="afnix:tcz">
    <name>Bloc</name>

    <p>
      The <code>Bloc</code> class is a derived class which
      encapsulates the functionality of a blob coupled with a plist
      and a table of conditionals.
    </p>

    <!-- predicate -->
    <pred>bloc-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Blob</name>
    </inherit>

    <!-- constructors -->
    <ctors>
      <ctor>
	<name>Bloc</name>
	<args>none</args>
	<p>
	  The <code>Bloc</code> constructor creates an empty bloc.
	</p>
      </ctor>
      <ctor>
	<name>Bloc</name>
	<args>String</args>
	<p>
	  The <code>Bloc</code> constructor creates a bloc by name.
	</p>
      </ctor>
      <ctor>
	<name>Bloc</name>
	<args>String String</args>
	<p>
	  The <code>Bloc</code> constructor creates a bloc by name and
	  info strings.
	</p>
      </ctor>
      <ctor>
	<name>Bloc</name>
	<args>String String String</args>
	<p>
	  The <code>Bloc</code> constructor creates a bloc by rid, name and
	  info strings.
	</p>
      </ctor>
    </ctors>

    <!-- methods -->
    <methods>
      <meth>
	<name>add-credential</name>
	<retn>none</retn>
	<args>Credential</args>
	<p>
	  The <code>add-credential</code> method add a credential to
	  the bloc.
	</p>
      </meth>
      <meth>
	<name>get-credential</name>
	<retn>Credential</retn>
	<args>String</args>
	<p>
	  The <code>get-credential</code> method returns a credential
	  object by name.
	</p>
      </meth>
    </methods>
  </object>

  <!-- =================================================================== -->
  <!-- = carrier object                                                  = -->
  <!-- =================================================================== -->

  <object nameset="afnix:tcz">
    <name>Carrier</name>

    <p>
      The <code>Carrier</code> class is a blob used to transport an
      object. The object transported by the carrier must be serializable.
    </p>

    <!-- predicate -->
    <pred>carrier-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Blob</name>
    </inherit>

    <!-- constructors -->
    <ctors>
      <ctor>
	<name>Carrier</name>
	<args>none</args>
	<p>
	  The <code>Carrier</code> constructor creates an empty carrier.
	</p>
      </ctor>
      <ctor>
	<name>Carrier</name>
	<args>Object</args>
	<p>
	  The <code>Carrier</code> constructor creates a carrier with
	  an object.
	</p>
      </ctor>
      <ctor>
	<name>Carrier</name>
	<args>Object String</args>
	<p>
	  The <code>Carrier</code> constructor creates a carrier with
	  an object by name.
	</p>
      </ctor>
      <ctor>
	<name>Carrier</name>
	<args>Object String String</args>
	<p>
	  The <code>Carrier</code> constructor creates a carrier with
	  an object by name and info strings.
	</p>
      </ctor>
      <ctor>
	<name>Carrier</name>
	<args>Carrier String String String</args>
	<p>
	  The <code>Carrier</code> constructor creates a carrier with
	  an object by rid, name and info strings.
	</p>
      </ctor>
    </ctors>

    <!-- methods -->
    <methods>
      <meth>
	<name>get-object</name>
	<retn>Object</retn>
	<args>none</args>
	<p>
	  The <code>get-object</code> method returns the carrier object.
	</p>
      </meth>
    </methods>
  </object>

  <!-- =================================================================== -->
  <!-- = delegate object                                                  = -->
  <!-- =================================================================== -->

  <object nameset="afnix:tcz">
    <name>Delegate</name>

    <p>
      The <code>Delegate</code> class is a carrier blob which
      delegates its transport to another object. Such approach is used
      when the carried object needs to remains locally (aka it cannot
      be serialized) but a reference to it can be sent to the remote peer.
    </p>

    <!-- predicate -->
    <pred>delegate-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Carrier</name>
    </inherit>

    <!-- constructors -->
    <ctors>
      <ctor>
	<name>Delegate</name>
	<args>none</args>
	<p>
	  The <code>Delegate</code> constructor creates an empty delegate.
	</p>
      </ctor>
      <ctor>
	<name>Delegate</name>
	<args>Object</args>
	<p>
	  The <code>Delegate</code> constructor creates a delegate with
	  an object.
	</p>
      </ctor>
      <ctor>
	<name>Delegate</name>
	<args>Object String</args>
	<p>
	  The <code>Delegate</code> constructor creates a delegate with
	  an object by name.
	</p>
      </ctor>
      <ctor>
	<name>Delegate</name>
	<args>Object String String</args>
	<p>
	  The <code>Delegate</code> constructor creates a delegate with
	  an object by name and info strings.
	</p>
      </ctor>
      <ctor>
	<name>Delegate</name>
	<args>Delegate String String String</args>
	<p>
	  The <code>Delegate</code> constructor creates a delegate with
	  an object by rid, name and info strings.
	</p>
      </ctor>
      <ctor>
	<name>Delegate</name>
	<args>Delegate String String String String</args>
	<p>
	  The <code>Delegate</code> constructor creates a delegate with
	  an object by rid, name, info strings and delegation address.
	</p>
      </ctor>
    </ctors>

    <!-- methods -->
    <methods>
      <meth>
	<name>set-address</name>
	<retn>none</retn>
	<args>String</args>
	<p>
	  The <code>set-address</code> method sets the delegate
	  address.
	</p>
      </meth>
      <meth>
	<name>get-address</name>
	<retn>String</retn>
	<args>none</args>
	<p>
	  The <code>get-address</code> method returns the delegate
	  address.
	</p>
      </meth>
    </methods>
  </object>
  
  <!-- =================================================================== -->
  <!-- = realm object                                                    = -->
  <!-- =================================================================== -->

  <object nameset="afnix:tcz">
    <name>Realm</name>

    <p>
      The <code>Realm</code> class is an abstract class design for the
      storage and management of authorities. The class provides the
      basic methods to create, check and validate an authority.
    </p>

    <!-- predicate -->
    <pred>realm-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Nameable</name>
    </inherit>

    <!-- methods -->
    <methods>
      <meth>
	<name>exists-p</name>
	<retn>Boolean</retn>
	<args>String</args>
	<p>
	  The <code>exists-p</code> predicate checks if an authority
	  exists by kid.
	</p>
      </meth>
      <meth>
	<name>valid-p</name>
	<retn>Boolean</retn>
	<args>String Credential</args>
	<p>
	  The <code>valid-p</code> predicate validates an authority by name
	  and credential.
	</p>
      </meth>
      <meth>
	<name>get-info</name>
	<retn>String</retn>
	<args>none</args>
	<p>
	  The <code>get-info-p</code> method the real information
	  string. Note that the <code>get-name</code> method is also
	  available through the <code>Nameable</code> interface.
	</p>
      </meth>
      <meth>
	<name>create</name>
	<retn>none</retn>
	<args>String Credential</args>
	<p>
	  The <code>create</code> method creates an authority by name
	  and credential.
	</p>
      </meth>

      <meth>
	<name>update</name>
	<retn>none</retn>
	<args>Authority</args>
	<p>
	  The <code>update</code> method updates a workzone by authority.
	</p>
      </meth>
    </methods>
  </object>
</appendix>
