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/forrest/src/documentation/content/xdocs/docu advanced-technique.xml faq.xml metadata.xml repository.xml
Date Wed, 12 May 2004 00:47:35 GMT
arminw      2004/05/11 17:47:35

  Modified:    forrest/src/documentation/content/xdocs/docu
                        advanced-technique.xml faq.xml metadata.xml
                        repository.xml
  Log:
  add new doc, update doc
  
  Revision  Changes    Path
  1.7       +2 -1      db-ojb/forrest/src/documentation/content/xdocs/docu/advanced-technique.xml
  
  Index: advanced-technique.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/forrest/src/documentation/content/xdocs/docu/advanced-technique.xml,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- advanced-technique.xml	9 May 2004 13:50:29 -0000	1.6
  +++ advanced-technique.xml	12 May 2004 00:47:35 -0000	1.7
  @@ -95,6 +95,7 @@
                   </p>
               </section>
   
  +            <anchor id="extents"/>
               <section>
                   <title>Extents</title>
                   <p>
  
  
  
  1.6       +60 -126   db-ojb/forrest/src/documentation/content/xdocs/docu/faq.xml
  
  Index: faq.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/forrest/src/documentation/content/xdocs/docu/faq.xml,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- faq.xml	5 May 2004 13:15:30 -0000	1.5
  +++ faq.xml	12 May 2004 00:47:35 -0000	1.6
  @@ -953,14 +953,36 @@
                   </p>
                   <source><![CDATA[
   PBKey pbKey = new PBKey("myJcdAliasName");
  -PersistenceBroker broker = PersitenceBrokerFactory.createPersistenceBroker(pbKey);
  -                ]]></source>
  +PersistenceBroker broker = PersitenceBrokerFactory.createPersistenceBroker(pbKey);]]></source>
                   <p>
                       See <link href="#userPasswordNeeded">here too</link>.
                   </p>
               </answer>
           </faq>
   
  +
  +        <faq id="lookupODMG">
  +            <question>
  +                How to access ODMG?
  +            </question>
  +            <answer>
  +                <p>
  +                    Obtain a <code>org.odmg.Implementation</code> instance
first, then create new
  +                    <code>org.odmg.Database</code> instance and open this instance
by setting the used
  +                    <link href="site:repository/jdbc-connection-descriptor">jcd-alias</link>
name:
  +                </p>
  +                <source><![CDATA[
  +Implementation odmg = OJB.getInstance();
  +Database database = odmg.newDatabase();
  +database.open("jcdAliasName#user#password", Database.OPEN_READ_WRITE);]]></source>
  +                <p>
  +                    The <em>user</em> and <em>password</em> separated
by <em>#</em> hash only needed, when
  +                    the user/passwd not specified in the connection metadata (jdbc-connection-descriptor).
  +                </p>
  +            </answer>
  +        </faq>
  +
  +
           <faq id="userPasswordNeeded">
               <question>
                   Needed to put user/password of database connection in repository file?
  @@ -983,14 +1005,15 @@
                       </link>
                   </p>
                   <p>
  -                    See <link href="#lookupPB">here too</link>.
  +                    See <link href="#lookupPB">lookup PB api</link>.
  +                    <br/>
  +                    See <link href="#lookupODMG">lookup ODMG api</link>.
                   </p>
                   <source>
   PBKey pbKey = new PBKey(jcdAlias, user, passwd);
   PersistenceBroker broker = PersistenceBrokerFactory.createPersistenceBroker(pbKey);
   // or using a convenience (when default-connection was set in jdbc-connection-descriptor)
  -PersistenceBroker broker = PersistenceBrokerFactory.defaultPersistenceBroker();
  -                </source>
  +PersistenceBroker broker = PersistenceBrokerFactory.defaultPersistenceBroker();</source>
   
               </answer>
           </faq>
  @@ -1026,8 +1049,7 @@
   PBKey user_1 = new PBKey(jcdAlias,username, passwd);
   PersistenceBroker broker =
   PersistenceBrokerFactory.createPersistenceBroker(user_1);
  -...
  -                </source>
  +...</source>
                   <p>
                       ODMG-api example:
                   </p>
  @@ -1035,8 +1057,7 @@
   Implementation odmg = OJB.getInstance();
   Database db = odmg.newDatabase();
   db.open("jcdAlias#username#passwd", Database.OPEN_READ_WRITE);
  -...
  -                </source>
  +...</source>
                   <p>
                       Keep in mind, when the
                       <code>connection-pool</code> element enables connection
pooling, every user get its separate pool.
  @@ -1118,24 +1139,7 @@
               </question>
               <answer>
                   <p>
  -                    It is possible to start OJB with an 'empty' repository.xml file:
  -                </p>
  -                <source><![CDATA[
  -<?xml version="1.0" encoding="UTF-8"?>
  -<!DOCTYPE descriptor-repository SYSTEM "repository.dtd">
  -
  -<descriptor-repository version="1.0" isolation-level="read-uncommitted">
  -
  -</descriptor-repository>]]></source>
  -                <p>
  -                    Now you have to declare the
  -                    <code>jdbc-connection-descriptor</code> and
  -                    <code>class-descriptor</code> at runtime. See
  -                    <link href="#Connect to database at runtime?">
  -                        Connect to database at runtime?</link> and
  -                    <link href="#addPersistentObjects">
  -                        Add new persistent objects (class-descriptors) at runtime?</link>
  -                    for more information.
  +                    See section <link href="site:metadata/without-repository">Metadata
Handling</link>.
                   </p>
               </answer>
           </faq>
  @@ -1146,69 +1150,19 @@
               </question>
               <answer>
                   <p>
  -                    You could add
  -                    <code>jdbc-connection-descriptors</code> at runtime, using
  -                    the
  -                    <code>MetadataManager</code>:
  +                    See section <link href="site:metadata/connect-at-runtime">Metadata
Handling</link>.
                   </p>
  -                <source>
  -ConnectionRepository cr = MetadataManager.
  -getInstance().connectionRepository();
  -
  -JdbcConnectionDescriptor jcd = new JdbcConnectionDescriptor();
  -jcd.setJcdAlias("testConnection");
  -jcd.setUserName("sa");
  -jcd.setPassWord("sa");
  -jcd.setDbAlias("aAlias");
  -jcd.setDbms("aDatabase");
  -// .... the other required setter
  -
  -// add new descriptor
  -cr.addDescriptor(jcd);
  -
  -// Now it's possible to obtain a PB-instance
  -PBKey key = new PBKey("testConnection", "sa", "sa");
  -PersistenceBroker broker = PersistenceBrokerFactory.
  -createPersistenceBroker(key);
  -                </source>
  -
               </answer>
           </faq>
   
           <faq id="addPersistentObjects">
               <question>
  -                Add new persistent objects (
  +                Add new persistent objects metadata (
                   <code>class-descriptor</code>) at runtime?
               </question>
               <answer>
                   <p>
  -                    You could add
  -                    <code>class-descriptors</code> at runtime, using
  -                    the
  -                    <code>MetadataManager</code>:
  -                </p>
  -                <source>
  -DescriptorRepository dr = MetadataManager.
  -getInstance().getRepository();
  -
  -ClassDescriptor cld = new ClassDescriptor(dr);
  -cld.setClassOfObject(A.class);
  -//.... other setter
  -
  -// add the fields of the class
  -FieldDescriptor fd = new FieldDescriptor(cld, 1);
  -fd.setPersistentField(A.class, "someAField");
  -cld.addFieldDescriptor(fd);
  -
  -// now we add the the class descriptor
  -dr.setClassDescriptor(cld);
  -                </source>
  -
  -                <p>
  -                    Please see section
  -                    <link href="site:metadata">Metadata Handling
  -                    </link> in
  -                    system documentation for further information.
  +                    See section <link href="site:metadata/metadata-at-runtime">Metadata
Handling</link>.
                   </p>
               </answer>
           </faq>
  @@ -1220,8 +1174,7 @@
               <answer>
                   <p>
                       Please see section
  -                    <link href="site:metadata">Metadata Handling</link> in
  -                    system documentation.
  +                    <link href="site:metadata">Metadata Handling</link>.
                   </p>
               </answer>
           </faq>
  @@ -1233,8 +1186,7 @@
               <answer>
                   <p>
                       Please see section
  -                    <link href="site:metadata">Metadata Handling</link> in
  -                    system documentation.
  +                    <link href="site:metadata">Metadata Handling</link>.
                   </p>
               </answer>
           </faq>
  @@ -1298,8 +1250,7 @@
     Project project;
   
     /** setters and getters not shown for brevity**/
  -}
  -                ]]></source>
  +}]]></source>
                   <p>
                       Here is the respective extract from the repository :
                   </p>
  @@ -1344,8 +1295,7 @@
         >
           <foreignkey field-ref="projectId" />
         </reference-descriptor>
  -</class-descriptor>
  -                ]]></source>
  +</class-descriptor>]]></source>
   
                   <p>
                       Here is some sample code for storing a relationship :
  @@ -1360,8 +1310,7 @@
   rel.setLanguage(lang);
   rel.setProject(proj);
   
  -broker.store(r);
  -                ]]></source>
  +broker.store(r);]]></source>
   
                   <p>
                       In the next code sample we are looking up all
  @@ -1380,8 +1329,7 @@
   {
       ProjectRelationship rel = (ProjectRelationship)	iter.next();
       System.out.println(rel.getProject().toString());
  -}
  -                ]]></source>
  +}]]></source>
   
                   <p>
                       You could also have on the Project class-descriptor a
  @@ -1396,9 +1344,7 @@
   cirteria.addEquatTo("projectRelationships.language.name","java");
   
   Query q = new QueryByCriteria(Project.class, criteria, true);
  -Collection projects = Broker.getCollectionByQuery(q);
  -                ]]></source>
  -
  +Collection projects = Broker.getCollectionByQuery(q);]]></source>
                   <p>
                       This is the layout of the Project class:
                   </p>
  @@ -1409,9 +1355,7 @@
     Collection projectRelationships;
   
     /** setters and getters not shown for brevity**/
  -}
  -                ]]></source>
  -
  +}]]></source>
                   <p>
                       This is the class-descriptor of the Project class:
                   </p>
  @@ -1437,8 +1381,7 @@
         >
           <inverse-foreignkey field-ref="projectId" />
         </collection-descriptor>
  -</class-descriptor>
  -                ]]></source>
  +</class-descriptor>]]></source>
   
               </answer>
           </faq>
  @@ -1460,8 +1403,7 @@
                       holding a list of Strings:
                   </p>
                   <source><![CDATA[
  -protected Collection listOfStrings;
  -]]></source>
  +protected Collection listOfStrings;]]></source>
   <p>
       The database table mapped to the persistent class has a colum
       <code>LIST_OF_STRINGS</code> of type
  @@ -1474,9 +1416,7 @@
       jdbc-type="VARCHAR"
       conversion=
   "o.a.ojb.broker.accesslayer.conversions.StringVector2VarcharFieldConversion"
  -/>
  -                ]]></source>
  -
  +/>]]></source>
               </answer>
           </faq>
   
  @@ -1499,8 +1439,7 @@
                           You then need a (possibly private) attribute in your java class
corresponding to the column.
                           Say the attribute is defined as:
                       <source>
  -private int versionMaintainedByOjb;
  -                    </source>
  +private int versionMaintainedByOjb;</source>
                       </li>
                       <li>
                           in repository.xml you need a field-descriptor for this attribute.
  @@ -1515,8 +1454,7 @@
       column="VERSION_MAINTAINED_BY_OJB"
       jdbc-type="INTEGER"
       locking="true"
  -/>
  -                        ]]></source>
  +/>]]></source>
                       </li>
                   </ol>
                   <p>
  @@ -1543,27 +1481,29 @@
                       <strong>transactional isolation and locking</strong>
                       <br/>
                       If you are using the PersistenceBroker API
  -                    use optimistic locking (OL) to let OJB handle write conflicts.
  +                    use <link href="site:faq/optimistic-locking">optimistic locking</link>
(OL) to let
  +                    OJB handle write conflicts.
                       To use OL define a TIMESTAMP or INTEGER column and the respective Java
attribute for it.
                       In the field-descriptor of this attribute set the attribute
  -                    locking="true"
  +                    <em>locking="true"</em>.
                       <br/>
  -                    If you are working with the ODMG API use the PersistenLockMapImpl,
  -                    by setting the respective flag in OJB.properties.
  +                    If you are working with the ODMG API
  +                    <link href="site:lock-manager">distributed pessemistic locking</link>
should
  +                    be used, by setting the respective flag in OJB.properties.
                   </p>
   
                   <p>
                       <strong>sequence numbers</strong>
                       <br/>
  -                    Use a SequenceManager that is safe across multiple JVMs.
  -                    The NextVal based SequenceManagers or any other SequenceManager
  +                    Use a <link href="site:sequence-manager">SequenceManager</link>
that is safe
  +                    across multiple JVMs. The NextVal based SequenceManagers or any other
SequenceManager
                       based on database mechanisms will be fine.
                   </p>
   
                   <p>
                       <strong>caching</strong>
                       <br/>
  -                    You could
  +                    You could use different <link href="site:object-cache">caching
implementations</link>
                   </p>
                   <ol>
                       <li>
  @@ -1571,20 +1511,15 @@
                           cannot handle cyclic structures on load!)
                       </li>
                       <li>
  -                        Use the PerBrokerCache Implementation. Could result in dirty reads,
but
  -                        together with Optimistic locking this should be OK.
  +                        Use the PerBrokerCache Implementation to avoid dirty reads.
                       </li>
                       <li>
  -                        Use the JCS cache implementation (see OJB.properties).
  -                        JCS will coordinate the distributed
  -                        caches on all clients. JCS will involve some RMI communication
between the
  -                        caches. Please have a look at the JCS site for configuration details.
  +                        Use the  OSCache cache implementation as distributed object cache.
                       </li>
                   </ol>
                   <p>
                       There is also a
  -                    <link href="howto-work-with-clustering.html">
  -                        complete howto document</link>
  +                    <link href="howto-work-with-clustering.html">complete howto document</link>
                       available that covers these topics.
                   </p>
               </answer>
  @@ -1661,5 +1596,4 @@
               </answer>
           </faq>
       </part>
  -
   </faqs>
  
  
  
  1.2       +345 -27   db-ojb/forrest/src/documentation/content/xdocs/docu/metadata.xml
  
  Index: metadata.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/forrest/src/documentation/content/xdocs/docu/metadata.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- metadata.xml	22 Apr 2004 19:29:50 -0000	1.1
  +++ metadata.xml	12 May 2004 00:47:35 -0000	1.2
  @@ -29,39 +29,71 @@
           <section>
               <title>Introduction</title>
               <p>
  -                To make OJB proper work it needs information about the used
  -                database connections (more info see
  -                <link href="site:connection">connection handling</link>),
  -                <link href="site:faq">FAQ</link>), the used
  -                <link href="site:sequence-manager">sequence managers</link>
and the
  -                <link href="site:faq">connection pool configurations</link>.
  -                Henceforth called
  +                To make OJB proper work information about the used
  +                databases (more info see
  +                <link href="site:connection">connection handling</link>) and
  +                <link href="site:sequence-manager">sequence managers</link>
is needed.
  +                Henceforth these metadata information is called
                   <strong>connection metadata</strong>.
  -                <br/>
  +            </p>
  +            <p>
                   Further on OJB needs information about
  -                the persistent objects and their associations used in the supported API's,
henceforth called
  +                the persistent objects and object relations, henceforth this information
is called
                   <strong>(persistent) object metadata</strong>.
               </p>
               <p>
  -                The connection metadata are completely decoupled from the persistent object
  -                metadata.
  +                All metadata information need to be stored in the OJB
  +                <link href="site:repository">repository file</link>.
               </p>
               <p>
  -                In OJB there are several ways to make metadata available:
  +                The
  +                <em>connection metadata</em> are completely decoupled from
the
  +                <em>persistent object
  +                    metadata</em>. Thus it is possible to use the same
  +                <em>object metadata</em> on different databases.
  +                <br/>
  +                But it is also possible to use different
  +                <link href="#metadata-profiles">
  +                    <em>object metadata</em> profiles
  +                </link>.
  +            </p>
  +            <p>
  +                In OJB there are several ways to make metadata information available:
               </p>
               <ul>
  -                <li>using xml configuration files parsed at start up</li>
  -                <li>set metadata at runtime by handling metadata 'container' classes</li>
  -                <li>parse additional xml configuration files and merge at runtime</li>
  +                <li>using xml configuration files parsed at start up by OJB</li>
  +                <li>set metadata instances at runtime by building metadata class
instances at runtime</li>
  +                <li>parse additional xml configuration files (additional repository
files) and merge at runtime</li>
               </ul>
               <p>
  -                All classes belonging to metadata handling can be find under
  -                <code>org.apache.ojb.broker.metadata</code>-package.
  +                All classes used for managing metadata stuff can be find under
  +                <code>org.apache.ojb.broker.metadata.*</code>-package.
                   <br/>
                   The main class
                   for metadata handling and entry point for metadata manipulation at
                   runtime is
  -                <code>org.apache.ojb.broker.metadata.MetadataManager</code>.
  +                <link href="ext:api/metadata-manager">
  +                    <code>org.apache.ojb.broker.metadata.MetadataManager</code>
  +                </link>.
  +            </p>
  +        </section>
  +
  +
  +        <section>
  +            <title>When does OJB read metadata</title>
  +            <p>
  +                By default all metadata is read at startup of OJB, when the first call
to
  +                <code>PersistenceBrokerFactory</code> (directly or by a top-level
api) or
  +                <code>MetadataManager</code> class was done.
  +            </p>
  +            <p>
  +                OJB expects a
  +                <link href="site:repository">repository file</link> at startup,
but it is also possible
  +                to start OJB
  +                <link href="#without-repository">with an empty repository file</link>
or only
  +                <link href="#load-connection-metadata">load connection metadata</link>
  +                and <link href="#metadata-at-runtime">object metadata at runtime</link>
or what ever
  +                combination fit your requirements.
               </p>
           </section>
   
  @@ -69,7 +101,94 @@
           <section>
               <title>Connection metadata</title>
               <p>
  -                TODO
  +                The
  +                <em>connection metadata</em> encapsulate all information referring
to used database and must be
  +                declared in
  +                <link href="site:repository">OJB repository file</link>.
  +                <br/>
  +                For each database a
  +                <link href="site:repository/jdbc-connection-descriptor">
  +                    <em>jdbc-connection-descriptor</em>
  +                </link>
  +                must be declared. This element encapusaltes the connection specific metadata
information.
  +            </p>
  +            <p>
  +                The <em>JdbcConnectionDescriptor</em> instances are managed
by
  +                <link href="ext:api/connection-repository"><code>org.apache.ojb.broker.metadata.ConnectionRepository</code></link>
  +            </p>
  +
  +
  +            <anchor id="load-connection-metadata"/>
  +            <section>
  +                <title>Load and merge connection metadata</title>
  +                <p>
  +                    It is possible to load additional connection metadata at runtime and
merge it with
  +                    the existing one. The used repository files have to be valid against
the
  +                    <link href="ext:repository.dtd">repository.dtd</link>:
  +                </p>
  +                <source><![CDATA[
  +<?xml version="1.0" encoding="UTF-8"?>
  +<!DOCTYPE descriptor-repository SYSTEM "repository.dtd">
  +
  +<descriptor-repository version="1.0" isolation-level="read-uncommitted">
  +    <jdbc-connection-descriptor
  +        jcd-alias="runtime"
  +        platform="Hsqldb"
  +        jdbc-level="2.0"
  +        driver="org.hsqldb.jdbcDriver"
  +        protocol="jdbc"
  +        subprotocol="hsqldb"
  +        dbalias="../OJB_FarAway"
  +        username="sa"
  +        password=""
  +        batch-mode="false"
  +    >
  +
  +        <object-cache class="org.apache.ojb.broker.cache.ObjectCacheDefaultImpl">
  +            <attribute attribute-name="timeout" attribute-value="900"/>
  +            <attribute attribute-name="autoSync" attribute-value="true"/>
  +        </object-cache>
  +
  +        <connection-pool
  +            maxActive="5"
  +            whenExhaustedAction="0"
  +            validationQuery="select count(*) from OJB_HL_SEQ"
  +        />
  +
  +        <sequence-manager className="org.apache.ojb.broker.util.sequence.SequenceManagerHighLowImpl">
  +            <attribute attribute-name="grabSize" attribute-value="5"/>
  +        </sequence-manager>
  +    </jdbc-connection-descriptor>
  +
  +    <!-- user/passwd at runtime required -->
  +    <jdbc-connection-descriptor
  +        jcd-alias="minimal"
  +        platform="Hsqldb"
  +        jdbc-level="2.0"
  +        driver="org.hsqldb.jdbcDriver"
  +        protocol="jdbc"
  +        subprotocol="hsqldb"
  +        dbalias="../OJB_FarAway"
  +    >
  +    </jdbc-connection-descriptor>
  +</descriptor-repository>]]></source>
  +                <p>
  +                    In the above additional repository file two new <em>jdbc-connection-descriptor</em>
  +                    (new databases) <em>runtime</em> and <em>minimal</em>
are declared, to load and merge
  +                    the additional connection metadata the <em>MetadataManager was
used:</em>
  +                </p>
  +                <source><![CDATA[
  +// get MetadataManager instance
  +MetadataManager mm = MetadataManager.getInstance();
  +
  +// read connection metadata from repository file
  +ConnectionRepository cr = mm.readConnectionRepository("valid path/url to repository file");
  +
  +// merge new connection metadata with existing one
  +mm.mergeConnectionRepository(cr);]]></source>
  +            </section>
  +            <p>
  +                After the merge the access to the new databases is ready for use.
               </p>
           </section>
   
  @@ -77,27 +196,226 @@
           <section>
               <title>Persistent object metadata</title>
               <p>
  -                TODO
  +                The
  +                <em>object metadata</em> encapsulate all information referring
to the persistent capable
  +                java objects and the associated tables in database. <em>Object metadata</em>
must be declared in
  +                <link href="site:repository">OJB repository file</link>.
  +                <br/>
  +                Each persistence capable java object must be declared in a corresponding
  +                <link href="site:repository/class-descriptor">class-descriptor</link>.
  +            </p>
  +            <p>
  +                The <em>ClassDescriptor</em> instances are managed by
  +                <link href="ext:api/descriptor-repository"><code>org.apache.ojb.broker.metadata.DescriptorRepository</code></link>.
  +                Per default OJB use only one global instance of this class.
               </p>
   
  +            <anchor id="load-object-metadata"/>
               <section>
  -                <title>Global metadata changes</title>
  +                <title>Load and merge object metadata</title>
                   <p>
  -                    TODO
  +                    It is possible to load additional object metadata at runtime and merge
it with
  +                    the existing one. The used repository files have to be valid against
the
  +                    <link href="ext:repository.dtd">repository.dtd</link>:
  +                </p>
  +                <p>
  +                    An additional repository file may look like:
  +                </p>
  +                <source><![CDATA[
  +<?xml version="1.0" encoding="UTF-8"?>
  +<!DOCTYPE descriptor-repository SYSTEM "repository.dtd">
  +
  +<descriptor-repository version="1.0" isolation-level="read-uncommitted">
  +
  +    <class-descriptor
  +      class="org.my.MyObject"
  +      table="MY_OBJ"
  +    >
  +        <field-descriptor
  +         name="id"
  +         column="OBJ_ID"
  +         jdbc-type="INTEGER"
  +         primarykey="true"
  +         autoincrement="true"
  +        />
  +
  +        <field-descriptor
  +         name="name"
  +         column="NAME"
  +         jdbc-type="VARCHAR"
  +        />
  +    </class-descriptor>
  +</descriptor-repository>]]></source>
  +            <p>
  +                To load and merge the object metadata of the additional repository files
first read
  +                the metadata using the <link href="ext:api/metadata-manager"><em>MetadataManager</em></link>.
  +            </p>
  +            <source><![CDATA[
  +// get MetadataManager instance
  +MetadataManager mm = MetadataManager.getInstance();
  +
  +// read the additional repository file
  +DescriptorRepository dr = mm.readDescriptorRepository("valid path/url to repository file");
  +
  +// merge the new class-descriptor with existing object metadata
  +mm.mergeDescriptorRepository(dr);]]></source>
  +            <p>
  +                It is also possible to keep the different <em>object metadata</em>
for the same classes
  +                parallel by using <link href="#metadata-profiles"><em>metadata
profiles</em></link>.
  +            </p>
  +                </section>
  +
  +
  +            <section>
  +            <title>Global <em>object metadata</em> changes</title>
  +            <p>
  +                Per default OJB use a global instance of class
  +                <link href="ext:api/descriptor-repository"><em>DescriptorRepository</em></link>
to manage all
  +                <em>object metadata</em>. This means that all <em>PersistenceBroker</em>
instances (kernel component
  +                used by all top-level api) use the same object metadata.
  +            </p>
  +            <p>
  +                So changes of the object metadata (e.g. remove of a collection-descriptor)
will be seen
  +                immediately by all <em>PersistenceBroker</em> instances.
  +                XXXXXXXXXXXXXXXXXXX TODO XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  +            </p>
  +            <p>
  +                The <link href="ext:api/metadata-manager"><em>MetadataManager</em></link>
  +                provide several methods to read/set and manipulate object metadata.
  +            </p>
  +        </section>
  +        </section>
  +
  +
  +
  +        <anchor id="metadata-profiles"/>
  +        <section>
  +            <title>Object metadata profiles</title>
  +            <p>
  +                XXXXXXXXXXXXX TODO XXXXXXXXXXXXXX
  +            </p>
  +        </section>
  +
  +
  +        <section>
  +            <title>Reference runtime changes on per query basis</title>
  +            <fixme author="arminw">
  +                Changes of reference settings on a per query basis will be supported with
  +                next upcoming release 1.1
  +            </fixme>
  +        </section>
  +
  +
  +        <section>
  +            <title>Questions</title>
  +
  +            <anchor id="without-repository"/>
  +            <section>
  +                <title>Start OJB without a repository file?</title>
  +                <p>
  +                    It is possible to start OJB with an 'empty' repository.xml file:
  +                </p>
  +                <source><![CDATA[
  +<?xml version="1.0" encoding="UTF-8"?>
  +<!DOCTYPE descriptor-repository SYSTEM "repository.dtd">
  +
  +<descriptor-repository version="1.0" isolation-level="read-uncommitted">
  +
  +</descriptor-repository>]]></source>
  +                <p>
  +                    Now you have to declare the
  +                    <code>jdbc-connection-descriptor</code> and
  +                    <code>class-descriptor</code> at runtime. See
  +                    <link href="#connect-at-runtime">
  +                        Connect to database at runtime?</link> and
  +                    <link href="#metadata-at-runtime">
  +                        Add new persistent objects (class-descriptors) at runtime?</link>
  +                    for more information.
                   </p>
               </section>
   
   
  +            <anchor id="connect-at-runtime"/>
               <section>
  -                <title>Per thread metadata changes</title>
  +                <title>Connect to database at runtime?</title>
  +                <p>
  +                    There are two possibilities to connect your database at runtime:
  +                </p>
  +                <ul>
  +                    <li>load connection metadata by parsing additional repository
files</li>
  +                    <li>create the <em>JdbcConnectionDescriptor</em>
at runtime</li>
  +                </ul>
  +                <p>
  +                    The first one is described in section
  +                    <link href="#load-connection-metadata">load and merge connection
metadata</link>.
  +                    For the second one a new instance of class
  +                    <link href="ext:api/jdbc-connection-descriptor"><code>org.apache.ojb.broker.metadata.JdbcConnectionDescriptor</code></link>
  +                    is needed. The prepared instance will be passed to class <em>ConnectionRepository</em>:
  +                </p>
  +                <source><![CDATA[
  +ConnectionRepository cr = MetadataManager.getInstance().connectionRepository();
  +
  +JdbcConnectionDescriptor jcd = new JdbcConnectionDescriptor();
  +jcd.setJcdAlias("testConnection");
  +jcd.setUserName("sa");
  +jcd.setPassWord("sa");
  +jcd.setDbAlias("aAlias");
  +jcd.setDbms("aDatabase");
  +// .... the other required setter
  +
  +// add new descriptor
  +cr.addDescriptor(jcd);
  +
  +// Now it's possible to obtain a PB-instance
  +PBKey key = new PBKey("testConnection", "sa", "sa");
  +PersistenceBroker broker = PersistenceBrokerFactory.
  +createPersistenceBroker(key);]]></source>
                   <p>
  -                    TODO
  +                    Please
  +                    <link href="site:metadata">read this section from beginning</link>
for further information.
                   </p>
               </section>
   
  -            <section><title>Reference runtime changes</title>
  +
  +            <anchor id="metadata-at-runtime"/>
  +            <section>
  +                <title>Add new persistent objects metadata (
  +                    <code>class-descriptor</code>) at runtime?
  +                </title>
  +                <p>
  +                    There are two possibilities to add new <em>object metadata</em>
at runtime:
  +                </p>
  +                <ul>
  +                    <li>load object metadata by parsing additional repository files</li>
  +                    <li>create new metadata objects at runtime</li>
  +                </ul>
  +                <p>
  +                    The first one is described in section
  +                    <link href="#load-object-metadata">load object metadata</link>.
  +                </p>
  +                <p>
  +                    To create and add new metadata objects at runtime we create new
  +                    <link href="ext:api/class-descriptor"><code>org.apache.ojb.broker.metadata.ClassDescriptor</code></link>
  +                    instances at runtime and using the
  +                    <code>MetadataManager</code> to add them to OJB:
  +                </p>
  +                <source><![CDATA[
  +DescriptorRepository dr = MetadataManager.getInstance().getRepository();
  +
  +ClassDescriptor cld = new ClassDescriptor(dr);
  +cld.setClassOfObject(A.class);
  +//.... other setter
  +
  +// add the fields of the class
  +FieldDescriptor fd = new FieldDescriptor(cld, 1);
  +fd.setPersistentField(A.class, "someAField");
  +cld.addFieldDescriptor(fd);
  +
  +// now we add the the class descriptor
  +dr.setClassDescriptor(cld);]]></source>
                   <p>
  -                    TODO
  +                    Please
  +                    <link href="site:metadata">read this section from beginning</link>
for further information.
                   </p>
               </section>
           </section>
  
  
  
  1.6       +17 -13    db-ojb/forrest/src/documentation/content/xdocs/docu/repository.xml
  
  Index: repository.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/forrest/src/documentation/content/xdocs/docu/repository.xml,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- repository.xml	5 May 2004 13:15:30 -0000	1.5
  +++ repository.xml	12 May 2004 00:47:35 -0000	1.6
  @@ -211,7 +211,8 @@
                       ]]></source>
                       <p>
                           The
  -                        <em>object-cache</em> element specifies the object-cache
implementation
  +                        <em>object-cache</em> element specifies the
  +                        <link href="site:object-cache">object-cache implementation</link>
                           class associated with this class.
                       </p>
                       <p>
  @@ -696,7 +697,8 @@
                   <p>
                       For interfaces or abstract classes a
                       <em>class-descriptor</em> holds a sequence
  -                    of <em>extent-class </em> elements which specify the types
extending this class.
  +                    of <em>extent-class </em> elements which specify the
  +                    <link href="site:advanced-technique/extents">types extending
this class</link>.
                       <br/>
                       Concrete base classes may specify a sequence of extent-class elements,
                       naming the derived classes.
  @@ -980,7 +982,8 @@
                   <p>
                       A reference-descriptor contains mapping info for an attribute of a
                       persistent class that is not primitive but references another
  -                    persistent entity Object. More about <link href="site:basic-technique">references
here</link>.
  +                    persistent entity Object. More about
  +                    <link href="site:basic-technique/one-to-one">1:1 references here</link>.
                   </p>
                   <p>
                       A <em>foreignkey</em> element contains information on foreign
key columns that
  @@ -1025,13 +1028,13 @@
                       If set to <em>false</em> the reference attribute is set
to null. In this case the
                       user is responsible to fill the reference attribute.
                       <br/>
  -                    More info see <link href="site:basic-technique/auto-retrieve">here</link>.
  +                    More info about <link href="site:basic-technique/auto-retrieve">auto-retrieve
here</link>.
                   </p>
                   <p>
                       The <em>auto-update</em> attribute specifies whether OJB
automatically stores
                       this reference attribute on storing the persistent object.
                       <br/>
  -                    More info see <link href="site:basic-technique/cascading">here</link>.
  +                    More info about the <link href="site:basic-technique/cascading">auto-XXX
settings here</link>.
                   </p>
                   <note>
                       This attribute must be set to false if using the OTM, ODMG or JDO layer.
  @@ -1040,7 +1043,7 @@
                       The <em>auto-delete</em> attribute specifies whether OJB
automatically deletes
                       this reference attribute on deleting the persistent object.
                       <br/>
  -                    More info see <link href="site:basic-technique/cascading">here</link>.
  +                    More info about the <link href="site:basic-technique/cascading">auto-XXX
settings here</link>.
                   </p>
                   <note>
                       This attribute must be set to false if using the OTM, ODMG or JDO layer.
  @@ -1097,9 +1100,10 @@
               <section>
                   <title>collection-descriptor</title>
                   <p>
  -                    A collection-descriptor contains mapping info for a Collection- or
  -                    Array-attribute of a  persistent class that contains persistent
  -                    entity Objects.
  +                    A collection-descriptor contains mapping info for a liCollection- or
  +                    Array-attribute of a persistent class that contains persistent
  +                    entity Objects. See more about <link href="site:basic-technique/one-to-n">1:n</link>
  +                    and <link href="site:basic-technique/m-to-n">m:n</link>
references.
                   </p>
                   <p>
                       The <em>inverse-foreignkey</em> elements contains information
on foreign-key
  @@ -1181,13 +1185,13 @@
                       If set to <em>false</em> the reference attribute is set
to null. In this case the
                       user is responsible to fill the reference attribute.
                       <br/>
  -                    More info see <link href="site:basic-technique/auto-retrieve">here</link>.
  +                    More info about <link href="site:basic-technique/auto-retrieve">auto-retrieve
here</link>.
                   </p>
                   <p>
                       The <em>auto-update</em> attribute specifies whether OJB
automatically stores
                       this reference attribute on storing the persistent object.
                       <br/>
  -                    More info see <link href="site:basic-technique/cascading">here</link>.
  +                    More info about the <link href="site:basic-technique/cascading">auto-XXX
settings here</link>.
                   </p>
                   <note>
                       This attribute must be set to false if using the OTM, ODMG or JDO layer.
  @@ -1196,7 +1200,7 @@
                       The <em>auto-delete</em> attribute specifies whether OJB
automatically deletes
                       this reference attribute on deleting the persistent object.
                       <br/>
  -                    More info see <link href="site:basic-technique/cascading">here</link>.
  +                    More info about the <link href="site:basic-technique/cascading">auto-XXX
settings here</link>.
                   </p>
                   <note>
                       This attribute must be set to false if using the OTM, ODMG or JDO layer.
  
  
  

---------------------------------------------------------------------
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