db-ojb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From arm...@apache.org
Subject cvs commit: db-ojb/xdocs repository.xml
Date Mon, 02 Feb 2004 09:32:34 GMT
arminw      2004/02/02 01:32:34

  Modified:    xdocs    repository.xml
  Log:
  - add object-cache docu
  - minor changes
  
  Revision  Changes    Path
  1.26      +215 -47   db-ojb/xdocs/repository.xml
  
  Index: repository.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/xdocs/repository.xml,v
  retrieving revision 1.25
  retrieving revision 1.26
  diff -u -r1.25 -r1.26
  --- repository.xml	1 Feb 2004 16:36:51 -0000	1.25
  +++ repository.xml	2 Feb 2004 09:32:33 -0000	1.26
  @@ -1,10 +1,12 @@
   <?xml version="1.0"?>
  +<!-- @version $Id$ -->
   <document>
   
     <properties>
       <author email="thma@apache.org">Thomas Mahler</author>
       <author email="daren@softwarearena.com">Daren Drummond</author>
  -    <author email="brianm@apache,org">Brian McCallister</author>
  +    <author email="brianm@apache.org">Brian McCallister</author>
  +    <author email="arminw@apache.org">Armin Waibel</author>
       <author email="tomdz@apache.org">Thomas Dudziak</author>
       <title>ObJectRelationalBridge Repository Documentation</title>
     </properties>
  @@ -28,6 +30,7 @@
                   <li><a href="#connection-pool">connection-pool</a></li>
                   <li><a href="#sequence-manager">sequence-manager</a></li>
               </ul>
  +            <li><a href="#object-cache">object-cache</a></li>
               <li><a href="#custom attribute">custom attribute</a></li>
               <li><a href="#class-descriptor">class-descriptor</a></li>
               <ul>
  @@ -58,31 +61,43 @@
   </p>
   
   <p>
  -    The actual repository is split up into four separate files:
  -    <ol>
  +	The actual repository metadta declaration is split up into several separate
  +    files, here is an excerpt of the most important files:
  +	<ol>
  +		<li>
  +			<a href="repository.xml.txt">the repository.xml</a>.
  +			Main file for metadata declaration. This file is split into several sub files
  +            using xml-Entity references.
  +		</li>
  +		<li>
  +			<a href="repository_database.xml.txt">the repository_database.xml</a>.
  +			This file contains the mapping information for database/connection handling.
  +		</li>
           <li>
  -            <a href="repository.xml.txt">the repository.xml</a>.
  -            This file contains the global <i>jdbc-connection-descriptor</i>
  -            and includes the following three files.
  -        </li>
  +			<a href="repository_internal.xml.txt">the repository_internal.xml</a>.
  +			This file contains the mapping information for the OJB internal tables.
  +			These tables are used for implementing SequenceManagers and
  +			persistent collections.
  +		</li>
           <li>
  -            <a href="repository_internal.xml.txt">the repository_internal.xml</a>.
  -            This file contains the mapping information for the OJB internal tables.
  -            These tables are used for implementing SequenceManagers and
  -            persistent collections.
  -        </li>
  +			<a href="repository_user.xml.txt">the repository_user.xml</a>.
  +			This file contains mappings for the tutorial applications
  +			and may be used to hold further user defined class mappings.
  +		</li>
  +		<li>
  +			<a href="repository_junit.xml.txt">the repository_junit.xml</a>.
  +			This file contains mapping information for the OJB JUnit regression
  +			test suite. In production environments these tables are not needed.
  +		</li>
           <li>
  -            <a href="repository_junit.xml.txt">the repository_junit.xml</a>.
  -            This file contains the mapping information for the OJB JUnit regression
  -            test suite. In production environments these tables are not needed.
  -        </li>
  +			other repository_junit_XYZ.xml<br/>
  +			More junit test mapping. In production environments these tables are not needed.
  +		</li>
           <li>
  -            <a href="repository_user.xml.txt">the repository_user.xml</a>.
  -            This file contains mappings for the tutorial applications
  -            and may be used to hold further user defined class mappings.
  -        </li>
  -
  -    </ol>
  +			There are some more files, for more information see comment in appropriate
  +            xml-file.
  +		</li>
  +	</ol>
   </p>
   
   </section>
  @@ -91,17 +106,22 @@
   <section name="Repository semantics">
   <p/>
   <subsection name="descriptor-repository">
  -
   <p>
  -The <i>descriptor-repository</i> is the root element of a repository.xml file.
  -It consists of one <i>jdbc-connection-descriptor</i> and at least one
  -<i>class-descriptor</i> element.
  +	The <i>descriptor-repository</i> is the root element of a repository.xml file.
  +    It consists of one <i>jdbc-connection-descriptor</i> and at least one
  +    <i>class-descriptor</i> element.
  +</p><p>
  +	The <i>documentation</i> element can be used to store arbitrary
  +	information.
  +</p><p>
  +	The <i>attribute</i> element allows to add <a href="#custom attribute">custom
attributes</a>,
  +    e.g. for passing arbitrary properties.
   </p><p>
   The <i>jdbc-connection-descriptor</i> element specifies a jdbc
   connection for the repository.
   </p><p>
  -<i>class-descriptor</i> elements specify o/r mapping information for
  -persistent classes.
  +	The <i>class-descriptor</i> element specify o/r mapping information for
  +    persistent class.
   </p>
   <source><![CDATA[
   <!ELEMENT descriptor-repository (
  @@ -112,20 +132,22 @@
   >
   ]]></source>
   
  +
  +<br/><br/><hr/>
   <p>
  -    The <a name="descriptor-repository.isolation"><code>isolation</code></a>
attribute
  +    The <a name="descriptor-repository.isolation"><i>isolation</i></a>
attribute
       defines the default isolation level for <i>class-descriptor</i> that do
not define a
       specific isolation level. This isolation level is used within the ODMG-api and does
       not touch the isolation-level off the database.
   </p><p>
  -    The <a name="descriptor-repository.version"><code>version</code></a>
attribute is
  +    The <a name="descriptor-repository.version"><i>version</i></a>
attribute is
       used to bind a repository.xml file to a given version of this dtd.
       A given OJB release will work properly only with the repository version
       shipped with that relase.
       This strictness maybe inconvenient but it does help to avoid the
       most common version conflicts.
   </p><p>
  -    The <a name="descriptor-repository.proxy-prefetching-limit"><code>proxy-prefetching-limit</code></a>
  +    The <a name="descriptor-repository.proxy-prefetching-limit"><i>proxy-prefetching-limit</i></a>
       attribute specifies a default value to be applied to all proxy instances. If none
       is specified a default value of 50 is used. Proxy prefetching specifies how many
       instances of a proxied class should be loaded in a single query when the proxy is
  @@ -143,15 +165,20 @@
   >
   ]]></source>
   </subsection>
  -<p/>
  +
  +
   <subsection name="jdbc-connection-descriptor">
   <p>
  -    The <i>jdbc-connection-descriptor</i> element specifies a jdbc
  +	The <i>jdbc-connection-descriptor</i> element specifies a jdbc
       connection for the repository. It is allowed to define more than
       one <i>jdbc-connection-descriptor</i>. All <i>class-descriptor</i>
       elements are independent from the <i>jdbc-connection-descriptor</i>s.
   </p>
   <p>
  +	The <i>object-cache</i> element specifies the object-cache implementation
  +    class associated with this class.
  +</p>
  +<p>
       A <i>connection-pool</i> element may be used to define connection pool
       properties for the specified JDBC connection.
   </p>
  @@ -160,6 +187,10 @@
       define which sequence manager implementation should be used within
       the defined connection.
   </p>
  +<p>
  +    Use the <a href="#custom attribute">custom-attribute</a> element to pass
  +    implementation specific properties.
  +</p>
   <source><![CDATA[
   <!ELEMENT jdbc-connection-descriptor (
       documentation?,
  @@ -169,6 +200,9 @@
       sequence-manager? )
   >
   ]]></source>
  +
  +
  +<br/><br/><hr/>
   <p>
   The <i>jdbc-connection-descriptor</i> element contains a bunch
   of required and implied attributes:
  @@ -237,6 +271,7 @@
       The <a name="jdbc-connection-descriptor.username"><code>username</code></a>
       and <a name="jdbc-connection-descriptor.password"><code>password</code></a>
       attributes are used as credentials for obtaining a jdbc connections.
  +    <br/>
       If users don't want to keep this information the
       repository.xml file, they could pass user/password
       using a <code>PBKey</code> to obtain a PersistenceBroker
  @@ -282,7 +317,10 @@
       documentation? )
   >
   ]]></source>
  -</p><p>
  +</p>
  +
  +<br/><br/><hr/>
  +<p>
       Valid attributes for the <i>connection-pool</i> element are:
   </p><p>
       <a name="connection-pool.maxActive"><code>maxActive</code></a>
is the maximum
  @@ -388,7 +426,8 @@
       <code>org.apache.ojb.broker.util.sequence</code> package.
       If no sequence manager is defined, OJB uses the default one.
   </p><p>
  -    Use the attribute element to pass implementation specific properties.
  +    Use the <a href="#custom attribute">custom-attribute</a> element to pass
  +    implementation specific properties.
   </p>
   
   <source><![CDATA[
  @@ -398,6 +437,8 @@
   >
   ]]></source>
   
  +
  +<br/><br/><hr/>
   <p>
       The <a name="sequence-manager.className"><code>className</code></a>
attribute
       represents the full qualified class name of the desired sequence manager
  @@ -417,7 +458,52 @@
   >
   ]]></source>
   </subsection>
  -<p/>
  +
  +
  +<subsection name="object-cache">
  +<p>
  +    The object-cache element can be used to specify the ObjectCache
  +    implementation used by OJB. There are three levels of
  +    declaration:
  +    <ul>
  +        <li>in OJB.properties file, to declare the standard (default)
  +        ObjectCache implementation</li>
  +        <li>on jdbc-connection-descriptor level, to declare ObjectCache implementation
  +        on a per connection/user level</li>
  +        <li>on class-descriptor level, to declare ObjectCache implementation
  +        on a per class level</li>
  +    </ul>
  +
  +    The priority of the declared object-cache elements are:
  +    per class > per jdbc descriptor > standard
  +    <br/>
  +    E.g. if you declare ObjectCache 'cacheDef' as standard, set
  +    ObjectCache 'cacheA' in class-descriptor for class A and class B
  +    does not declare an object-cache element. Then OJB use cacheA as ObjectCache
  +    for class A and cacheDef for class B.
  +</p>
  +<p>
  +    Use the <a href="#custom attribute">custom-attribute</a> element to pass
  +    implementation specific properties.
  +</p>
  +<source><![CDATA[
  +<!ELEMENT object-cache (documentation?, attribute*)>
  +]]></source>
  +
  +
  +<br/><br/><hr/>
  +<p>
  +    Attribute 'class' specifies the full qualified class name of
  +    the used ObjectCache implementation.
  +<source><![CDATA[
  +<!ATTLIST object-cache
  +    class  CDATA  #REQUIRED
  +>
  +]]></source>
  +</p>
  +</subsection>
  +
  +
   <subsection name="custom attribute">
   <p>
       An <i>attribute</i> element allows arbitrary name/value pairs to
  @@ -428,6 +514,7 @@
   <!ELEMENT attribute EMPTY>
   ]]></source>
   
  +<br/><br/><hr/>
   <p>
       The <a name="attribute.attribute-name"><code>attribute-name</code></a>
identifies
       the name of the attribute.
  @@ -442,7 +529,8 @@
   >
   ]]></source>
   </subsection>
  -<p/>
  +
  +
   <subsection name="class-descriptor">
   <p>
       For interfaces or abstract classes a <i>class-descriptor</i> holds a sequence
  @@ -461,6 +549,10 @@
       <br/>
       A class-descriptor may contain user defined custom attribute elements.
   </p>
  +<p>
  +    Use the <a href="#custom attribute">custom-attribute</a> element to pass
  +    implementation specific properties.
  +</p>
   <source><![CDATA[
   <!ELEMENT class-descriptor (
       (
  @@ -483,6 +575,8 @@
   >
   ]]></source>
   
  +
  +<br/><br/><hr/>
   <p>
       The <a name="class-descriptor.class"><code>class</code></a>
attribute
       contains the full qualified name of the specified class. As this
  @@ -515,6 +609,8 @@
       used as the <code>RowReader</code> implementation used to materialize
       instances of the persistent class.
   </p><p>
  +	The <a name="class-descriptor.extends"><code>extends</code></a>
attribute <font color="#ff0000">TODO</font>
  +</p><p>
       The <a name="class-descriptor.accept-locks"><code>accept-locks</code></a>
       attribute specifies whether implicit locking should propagate to this class.
       Currently relevant for the ODMG layer only.
  @@ -565,6 +661,8 @@
   <!ELEMENT extent-class EMPTY>
   ]]></source>
   
  +
  +<br/><br/><hr/>
   <p>
       The class-ref attribute must contain a fully qualified classname.
       The repository file must contain a class-descriptor for this class.
  @@ -583,10 +681,16 @@
       <br/>
       A field descriptor may contain custom attribute elements.
   </p>
  +<p>
  +    Use the <a href="#custom attribute">custom-attribute</a> element to pass
  +    implementation specific properties.
  +</p>
   <source><![CDATA[
   <!ELEMENT field-descriptor (documentation?, attribute*)>
   ]]></source>
   
  +
  +<br/><br/><hr/>
   <p>
       <b>The id attribute is optional.</b> If not specified, OJB internally
       sorts field-descriptors according to their order of appearance in the
  @@ -706,6 +810,8 @@
   <!ELEMENT reference-descriptor ( foreignkey+)>
   ]]></source>
   
  +
  +<br/><br/><hr/>
   <p>
       The name attribute holds the name of the persistent classes attribute.
       If the PersistentFieldDefaultImpl is used there must be an attribute
  @@ -782,6 +888,8 @@
   <!ELEMENT foreignkey EMPTY>
   ]]></source>
   
  +
  +<br/><br/><hr/>
   <p>
       The field-ref and field-id-ref attributes contain
       the name and the id attributes of the field-descriptor
  @@ -810,6 +918,10 @@
       In this case they contain information on the foreign-key columns of
       the intermediary table.
   </p>
  +<p>
  +    Use the <a href="#custom attribute">custom-attribute</a> element to pass
  +    implementation specific properties.
  +</p>
   <source><![CDATA[
   <!ELEMENT collection-descriptor (
       documentation?,
  @@ -820,6 +932,8 @@
       attribute*)>
   ]]></source>
   
  +
  +<br/><br/><hr/>
   <p>
       The name attribute holds the name of the persistent classes attribute.
       If the PersistentFieldDefaultImpl is used there must be an attribute
  @@ -909,6 +1023,8 @@
   <!ELEMENT inverse-foreignkey EMPTY>
   ]]></source>
   
  +
  +<br/><br/><hr/>
   <p>
       The field-ref and field-id-ref attributes contain
       the name and the id attributes of the field-descriptor
  @@ -932,6 +1048,8 @@
   <!ELEMENT fk-pointing-to-this-class EMPTY>
   ]]></source>
   
  +
  +<br/><br/><hr/>
   <p>
       The column attribute specifies the foreign-key column in the intermediary
       table that points to the class holding the collection.
  @@ -941,7 +1059,8 @@
       column CDATA #REQUIRED
   >]]></source>
   </subsection>
  -<p/>
  +
  +
   <subsection name="fk-pointing-to-element-class">
   <p>
       A fk-pointing-to-element-class element contains information on a foreign-key
  @@ -951,6 +1070,8 @@
   <!ELEMENT fk-pointing-to-element-class EMPTY>
   ]]></source>
   
  +
  +<br/><br/><hr/>
   <p>
       The column attribute specifies the foreign-key column in the intermediary
       table that points to the class of the collection elements.
  @@ -961,11 +1082,16 @@
   >
   ]]></source>
   </subsection>
  -<p/>
  +
  +
   <subsection name="query-customizer">
   <p>
       a queryEnhancer element to enhance the 1:n query
   </p>
  +<p>
  +    Use the <a href="#custom attribute">custom-attribute</a> element to pass
  +    implementation specific properties.
  +</p>
   <source><![CDATA[
   <!ELEMENT query-customizer (
       documentation?,
  @@ -975,7 +1101,8 @@
   >
   ]]></source>
   </subsection>
  -<p/>
  +
  +
   <subsection name="index-descriptor">
   <p>
       An index-descriptor describes an index by listing its columns.  It may be
  @@ -999,7 +1126,8 @@
       name CDATA #REQUIRED>
   ]]></source>
   </subsection>
  -<p/>
  +
  +
   <subsection name="insert-procedure">
   <p>
       Identifies the procedure/function that should be used to handle
  @@ -1009,10 +1137,17 @@
       The nested 'argument' elements define the argument list for the
       procedure/function as well as the source for each argument.
   </p>
  +<p>
  +    Use the <a href="#custom attribute">custom-attribute</a> element to pass
  +    implementation specific properties.
  +</p>
   <source><![CDATA[
   <!ELEMENT insert-procedure
       (documentation?, (runtime-argument | constant-argument)?, attribute*)>
   ]]></source>
  +
  +
  +<br/><br/><hr/>
   <p>
       The name attribute identifies the name of the procedure/function to use
   </p><p>
  @@ -1039,7 +1174,8 @@
   >
   ]]></source>
   </subsection>
  -<p/>
  +
  +
   <subsection name="update-procedure">
   <p>
       Identifies the procedure/function that should be used to handle
  @@ -1048,10 +1184,17 @@
       The nested 'argument' elements define the argument list for the
       procedure/function as well as the source for each argument.
   </p>
  +<p>
  +    Use the <a href="#custom attribute">custom-attribute</a> element to pass
  +    implementation specific properties.
  +</p>
   <source><![CDATA[
   <!ELEMENT update-procedure
       (documentation?, (runtime-argument | constant-argument)?, attribute*)>
   ]]></source>
  +
  +
  +<br/><br/><hr/>
   <p>
       The name attribute identifies the name of the procedure/function to use
   </p><p>
  @@ -1078,7 +1221,8 @@
   >
   ]]></source>
   </subsection>
  -<p/>
  +
  +
   <subsection name="delete-procedure">
   <p>
       Identifies the procedure/function that should be used to handle
  @@ -1088,10 +1232,17 @@
       the argument list for the procedure/function as well as the source
       for each argument.
   </p>
  +<p>
  +    Use the <a href="#custom attribute">custom-attribute</a> element to pass
  +    implementation specific properties.
  +</p>
   <source><![CDATA[
   <!ELEMENT delete-procedure
       (documentation?, (runtime-argument | constant-argument)?, attribute*)>
   ]]></source>
  +
  +
  +<br/><br/><hr/>
   <p>
       The name attribute identifies the name of the procedure/function to use
   </p><p>
  @@ -1119,16 +1270,24 @@
   >
   ]]></source>
   </subsection>
  -<p/>
  +
  +
   <subsection name="runtime-argument">
   <p>
       Defines an argument that is passed to a procedure/function.  Each argument
       will be set to a value from a field-descriptor or null.
   </p>
  +<p>
  +    Use the <a href="#custom attribute">custom-attribute</a> element to pass
  +    implementation specific properties.
  +</p>
   <source><![CDATA[
   <!ELEMENT runtime-argument
       (documentation?, attribute*)>
   ]]></source>
  +
  +
  +<br/><br/><hr/>
   <p>
       The field-ref attribute identifies the field-descriptor in the corresponding
       class-descriptor that provides the value for this argument.  If this attribute
  @@ -1141,15 +1300,23 @@
   >
   ]]></source>
   </subsection>
  -<p/>
  +
  +
   <subsection name="runtime-argument">
   <p>
       Defines a constant value that is passed to a procedure/function.
   </p>
  +<p>
  +    Use the <a href="#custom attribute">custom-attribute</a> element to pass
  +    implementation specific properties.
  +</p>
   <source><![CDATA[
   <!ELEMENT constant-argument
       (documentation?, attribute*)>
   ]]></source>
  +
  +
  +<br/><br/><hr/>
   <p>
       The value attribute identifies the value that is passed to the procedure/
       function.
  @@ -1161,7 +1328,8 @@
   ]]></source>
   </subsection>
   </section>
  -<p/>
  +
  +
   <section name="the repository verifier">
   
   author:     <a href="mailto:daren@softwarearena.com">Daren Drummond</a>
  @@ -1253,7 +1421,7 @@
     <dt><b>verifyclasspath</b></dt>
     <dd>
     The classpath for loading the classes specified by the
  -  <code>&lt;class-descriptor&gt;&lt;/class-descriptor&gt;</code>
tags in the OJB repository.xml
  +  <i>&lt;class-descriptor&gt;&lt;/class-descriptor&gt;</i>
tags in the OJB repository.xml
     file.  Required.
     </dd>
   
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org


Mime
View raw message