<?xml version='1.0' encoding="utf-8"?>
<!-- $Revision: 297078 $ -->

<reference xml:id="ref.sdo" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>SDO &Functions;</title>

 <partintro>
  <section xml:id="sdo.das.table">
   <title>Data Access Services</title>
   <para>
    The table below lists the currently provided SDO Data Access Services:
    <informaltable>
     <tgroup cols='2'>
      <thead>
       <row>
        <entry>DAS Name</entry>
        <entry>Description</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>
         <link linkend="ref.sdo-das-xml">SDO_DAS_XML</link>
        </entry>
        <entry>
         An XML Data Access Service supporting reading/writing
         SDOs as XML documents.
        </entry>
       </row>
       <row>
        <entry>
         <link linkend="ref.sdo.das.rel">SDO_DAS_Relational</link>
        </entry>
        <entry>
         A PDO-based Data Access Service supporting reading/writing SDO 
         to relational databases.  
         Implements an optimistic concurrency policy for updates.
        </entry>
       </row>
      </tbody>
     </tgroup>
    </informaltable>
   </para>
  </section>

  <!-- FIXME: Everything below should be removed and follow our OO skeletons -->

  <!-- class definition section -->
  <section xml:id='sdo.classes'>
   &reftitle.classes;
   <para>
    SDO consists of three sets of interfaces.  The first set covers those
    interfaces for use by typical SDO applications.  These are identified 
    by the package prefix 'SDO_'.  The second set is those used to reflect 
    on, and work with, the model of a data object.  These are identified 
    by the package prefix 'SDO_Model_'.  Finally, the third set are those 
    use by Data Access Service implementations and are identified by the 
    package prefix 'SDO_DAS_'.  The majority of SDO users will not need to 
    use or understand the 'SDO_Model_' and 'SDO_DAS_' interfaces.
   </para>

   <section xml:id='sdo.class.sdo-apis'>
    <title>SDO Application Programmer Interface</title>

    <section xml:id='sdo.class.sdo-dataobject'>
     <title>
      <classname>SDO_DataObject</classname>
     </title>
     <para>
      The main interface through which data objects are manipulated.  In
      addition to the methods below, SDO_DataObject extends the
      ArrayAccess, SDO_PropertyAccess (defines <function>__get</function> /
      <function>__set</function> methods for property access overloading),
      Iterator, and Countable interfaces.
     </para>
     <section xml:id='sdo.class.SDO-DataObject.methods'> &reftitle.methods;
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.sdo-dataobject-getsequence'>getSequence</link>
         - get the sequence for the data object
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-dataobject-createdataobject'>createDataObject</link>
         - create a child data object
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-dataobject-clear'>clear</link>
         - unset the properties of a data object
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-dataobject-getcontainer'>getContainer</link>
         - get the container (also known as 'parent') of this data object
        </para>
       </listitem>      
       <listitem>
        <para>
         <link linkend='function.sdo-dataobject-gettypename'>getTypeName</link>
         - get the name of the type for this data object
        </para>
       </listitem>     
       <listitem>
        <para>
         <link linkend='function.sdo-dataobject-gettypenamespaceuri'>getTypeNamespaceURI</link>
         - get the namespace URI of the type for this data object
        </para>
       </listitem>
      </itemizedlist>
     </section>
    </section>

    <section xml:id='sdo.class.sdo-sequence'>
     <title>
      <classname>SDO_Sequence</classname>
     </title>
     <para>
      The interface through which sequenced data objects can be accessed
      to preserve ordering across a data object's properties and 
      to allow unstructured text.  
      SDO_Sequence preserves contiguous indices and therefore inserting 
      or removing elements may shift other elements up or
      down. In addition to the methods below, SDO_Sequence extends the
      ArrayAccess, Iterator and Countable interface.
     </para>
     <section xml:id='sdo.class.SDO-Sequence.methods'>
      &reftitle.methods;
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.sdo-sequence-getproperty'>getProperty</link> 
         - get the property for a given sequence index
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-sequence-move'>move</link>
         - move an element from one property index to another
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-sequence-insert'>insert</link>
         - insert a new value into the sequence
        </para>
       </listitem>
      </itemizedlist>
     </section>
    </section>

    <section xml:id='sdo.class.sdo-list'>
     <title>
      <classname>SDO_List</classname>
     </title>
     <para>
      The interface through which many-valued properties are manipulated.
      In addition to the method defined below, SDO_List extends ArrayAccess,
      Iterator and Countable.  SDO_List preserves contiguous indices and
      therefore inserting or removing elements may shift other elements
      up or down.
     </para>
     <section xml:id='sdo.class.SDO-List.methods'>
      &reftitle.methods;
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.sdo-list-insert'>insert</link> 
         - insert a new value into the list
        </para>
       </listitem>
      </itemizedlist>
     </section>
    </section>

    <section xml:id='sdo.class.sdo-datafactory'>
     <title>
      <classname>SDO_DataFactory</classname>
     </title>
     <para>
      The interface through which data objects can be created.  
      A Data Access Service is responsible for populating the model 
      (i.e. configuring the data factory with the type and structure 
      information for the data objects it can create.) 
      for the factory and can then optionally return an instance of, 
      or implement, the SDO_DataFactory interface.
     </para>
     <section xml:id='sdo.class.SDO-DataFactory.methods'>
      &reftitle.methods;
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.sdo-datafactory-create'>create</link> 
         - create a new data object
        </para>
       </listitem>
      </itemizedlist>
     </section>
    </section>
        
    <section xml:id='sdo.class.sdo-exception'>
     <title>
      <classname>SDO_Exception</classname>
     </title>
     <para>
      An SDO_Exception is thrown when the caller's request cannot be completed.
      The subclasses of SDO_Exception are:
      <itemizedlist>
       <listitem>
        <para>SDO_PropertyNotSetException -
        the property specified exists but has not been set or does not have a
        default value
        </para>
       </listitem>
       <listitem>
        <para>SDO_PropertyNotFoundException -
        the property specified is not part of the data object's type
        </para>
       </listitem>
       <listitem>
        <para>SDO_TypeNotFoundException -
        the specified namespace URI or type name is unknown
        </para>
       </listitem>
       <listitem>
        <para>SDO_InvalidConversionException -
        conversion between the types of the assignment is not possible 
        </para>
       </listitem>
       <listitem>
        <para>SDO_IndexOutOfBoundsException -
        the numeric index into a data object, sequence or list is not in the
        valid range 
        </para>
       </listitem>
       <listitem>
        <para>SDO_UnsupportedOperationException -
        the request cannot be completed because it is not allowed,
        for example an attempt to set a read-only property.
        </para>
       </listitem>
      </itemizedlist>
     </para>
     <section xml:id='sdo.class.SDO-Exception.methods'> &reftitle.methods;
     <para>One method is added to those inherited from the built in 
     <link linkend='language.exceptions.extending'>Exception</link> class:
     </para>
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.sdo-exception-getcause'>getCause</link> 
         - get the cause of this SDO_Exception
        </para>
       </listitem>

      </itemizedlist>
     </section>
    </section>
    
   </section>



   <section xml:id='sdo.class.sdo-model-apis'>
    <title>SDO Reflection Application Programmer Interfaces</title>

    <section xml:id='sdo.class.sdo-reflectiondataobject'>
     <title>
      <classname>SDO_Model_ReflectionDataObject</classname>
     </title>
     <para>
      The main interface used to reflect on a data object instance 
      to obtain its model type and property information.  
      It is designed to follow the reflection pattern introduced in PHP 5.
     </para>
     <section xml:id='sdo.class.SDO-Model-ReflectionDataObject.constructor'> 
       &reftitle.constructor;     
       <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.sdo-model-reflectiondataobject-construct'>__construct</link>
         - construct a new SDO_Model_ReflectionDataObject.
        </para>
       </listitem>     
      </itemizedlist>
     </section>
     <section xml:id='sdo.class.SDO-Model-ReflectionDataObject.methods'> 
       &reftitle.methods;
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.sdo-model-reflectiondataobject-export'>export</link>
         - get a string describing the data object.
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-model-reflectiondataobject-gettype'>getType</link>
         - get the SDO_Model_Type for the data object.
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend=
          'function.sdo-model-reflectiondataobject-getinstanceproperties'>getInstanceProperties</link>
         - get the instance properties of the data object.
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend=
          'function.sdo-model-reflectiondataobject-getcontainmentproperty'>getContainmentProperty</link>
         - get the property which defines the containment relationship to the data object.
        </para>
       </listitem>
      </itemizedlist>
     </section>
    </section>

    <section xml:id='sdo.class.sdo-type'>
     <title>
      <classname>SDO_Model_Type</classname>
     </title>
     <para>
      The interface through which a data object's type information can be 
      retrieved.  This interface can be used to find out the type name and 
      namespace URI of the type, whether the type allow open content, and so 
      on.
     </para>
     <section xml:id='sdo.class.SDO-Model-Type.methods'> &reftitle.methods;
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.sdo-model-type-getname'>getName</link>
          - get the name of the type.
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-model-type-getnamespaceuri'>getNamespaceURI</link>
         - get the namespace URI of the type.
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-model-type-isinstance'>isInstance</link>
         - test for a data object being an instance of the type.
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-model-type-getproperties'>getProperties</link>
         - get the properties of the type.
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-model-type-getproperty'>getProperty</link>
         - get a property of the type.
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-model-type-isdatatype'>isDataType</link>
         - test to see if this type is a primitive scalar type.
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-model-type-issequencedtype'>isSequencedType</link>
         - test to see if this is a sequenced type.
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-model-type-isopentype'>isOpenType</link>
         - test to see if this is an open type.
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-model-type-isabstracttype'>isAbstractType</link>
         - test to see if this is an abstract type.
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-model-type-getbasetype'>getBaseType</link>
         - get the base type of this type (if one exists).
        </para>
       </listitem>
      </itemizedlist>
     </section>
    </section>

    <section xml:id='sdo.class.sdo-property'>
     <title>
      <classname>SDO_Model_Property</classname>
     </title>
     <para>
      The interface through which a data object's property information can 
      be retrieved.  This interface can be used to find out the type of a 
      property, whether a property has a default value, whether the 
      property is contained or reference by its parent, its cardinality, 
      and so on.
     </para>
     <section xml:id='sdo.class.SDO-Model-Property.methods'> &reftitle.methods;
      <itemizedlist>
        <listitem>
         <para>
          <link linkend='function.sdo-model-property-getname'>getName</link>
          - get the name of the property.
         </para>
        </listitem>
        <listitem>
         <para>
          <link linkend='function.sdo-model-property-gettype'>getType</link>
          - get the type of the property.
         </para>
        </listitem>
        <listitem>
         <para>
          <link linkend='function.sdo-model-property-ismany'>isMany</link>
          - test to see if the property is many-valued.
         </para>
        </listitem>
        <listitem>
         <para>
          <link linkend='function.sdo-model-property-iscontainment'>isContainment</link>
          - test to see if the property describes a containment relationship.
         </para>
        </listitem>
        <listitem>
         <para>
          <link linkend='function.sdo-model-property-getcontainingtype'>getContainingType</link>
          - get the type which contains this property.
         </para>
        </listitem>
        <listitem>
         <para>
          <link linkend='function.sdo-model-property-getdefault'>getDefault</link>
          - get the default value for a property.
         </para>
        </listitem>
      </itemizedlist>
     </section>
    </section>



   </section>

   <section xml:id='sdo.class.sdo-das-spis'>
    <title>
     SDO Data Access Service Developer Interfaces
    </title>

    <section xml:id='sdo.class.sdodas-dataobject'>
     <title>
      <classname>SDO_DAS_DataObject</classname>
     </title>
     <para>
      The interface through which a Data Access Service can access 
      a data object's 
      <link linkend='sdo.class.sdodas-changesummary'>SDO_DAS_ChangeSummary</link>.
      The change summary is used by the Data Access Service to check for 
      conflicts when applying changes back to a data source.
     </para>
     <section xml:id='sdo.class.SDO-DAS-DataObject.methods'> &reftitle.methods;
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.sdo-das-dataobject-getchangesummary'>getChangeSummary</link> 
         - get the change summary for a data object
        </para>
       </listitem>

      </itemizedlist>
     </section>
    </section>

    <section xml:id='sdo.class.sdodas-changesummary'>
     <title>
      <classname>SDO_DAS_ChangeSummary</classname>
     </title>
     <para>
      The interface through which the change history of a data
      object is accessed.  The change summary holds information for any
      modifications on a data object which occurred since logging
      was activated.  In the case of deletions and modifications, the old
      values are also held in the change summary.
     </para>
     <para>
      If logging is no longer active
      then the change summary only holds changes made up to the point when
      logging was deactivated.  
      Reactivating logging clears the change summary.
      This is useful when a set of changes have been written out by a
      DAS and the data object is to be reused.
     </para>
     <section xml:id='sdo.class.SDO-DAS-ChangeSummary.methods'>
      &reftitle.methods;
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.sdo-das-changesummary-beginlogging'>beginLogging</link> 
         - begin logging changes made to a data object
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-das-changesummary-endlogging'>endLogging</link> 
         - end logging changes made to a data object
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-das-changesummary-islogging'>isLogging</link> 
         - test to see if change logging is on
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-das-changesummary-getchangeddataobjects'>getChangedDataObjects</link> 
         - get a list of the data objects which have been changed
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-das-changesummary-getchangetype'>getChangeType</link> 
         - get the type of change which has been made to a data object
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-das-changesummary-getoldvalues'>getOldValues</link> 
         - get a list of old values for a data object
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-das-changesummary-getoldcontainer'>getOldContainer</link> 
         - get the old container data object for a deleted data object
        </para>
       </listitem>
      </itemizedlist>
     </section>
    </section>

    <section xml:id='sdo.class.sdodas-setting'>
     <title>
      <classname>SDO_DAS_Setting</classname>
     </title>
     <para>
      The interface through which the old value for a property is
      accessed. A list of settings is returned by the change summary method
      <link linkend='function.sdo-das-changesummary-getoldvalues'>
       <function>getOldValues</function>
      </link>.
     </para>
     <section xml:id='sdo.class.SDO-DAS-Setting.methods'>
      &reftitle.methods;
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.sdo-das-setting-getpropertyindex'>getPropertyIndex</link> 
         - get the property index for the changed property
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-das-setting-getpropertyname'>getPropertyName</link> 
         - get the property name for the changed property
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-das-setting-getvalue'>getValue</link> 
         - get the old value for the changed property
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-das-setting-getlistindex'>getListIndex</link> 
         - get the list index for the old value if it was part of a 
         many-valued property
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.sdo-das-setting-isset'>isSet</link>
         - test to see if the property was set prior to being modified
         </para>
       </listitem>
      </itemizedlist>
     </section>
    </section>

    <section xml:id='sdo.class.sdodas-datafactory'>
     <title>
      <classname>SDO_DAS_DataFactory</classname>
     </title>
     <para>
      The interface for constructing the model for an SDO_DataObject.
      The SDO_DAS_DataFactory is an abstract class providing a static
      method which returns a concrete data factory implementation.
      The implementation is used by Data Access Services to create an 
      SDO model from their model.
      For example, a Relational Data Access Service might create and populate
      an SDO_DAS_DataFactory model based on a schema for a relational
      database.
     </para>
     <section xml:id='sdo.class.SDO-DAS-DataFactory.methods'>
      &reftitle.methods;
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.sdo-das-datafactory-getdatafactory'>getDataFactory</link> 
         - static methods for getting a concrete data factory instance
        </para>
       </listitem>
      </itemizedlist>
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.sdo-das-datafactory-addtype'>addType</link> 
         - add a new type to the SDO model
        </para>
       </listitem>
      </itemizedlist>
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.sdo-das-datafactory-addpropertytotype'>addPropertyToType</link> 
         - add a new property to a type definition in the SDO model
        </para>
       </listitem>
      </itemizedlist>
     </section>
    </section>
   </section>
  </section>

 </partintro>

 &reference.sdo.entities.functions;

</reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->