You are viewing a plain text version of this content. The canonical link for it is here.
Posted to ojb-dev@db.apache.org by ar...@apache.org on 2004/05/12 02:47:35 UTC
cvs commit: db-ojb/forrest/src/documentation/content/xdocs/docu advanced-technique.xml faq.xml metadata.xml repository.xml
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