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 to...@apache.org on 2004/06/20 20:59:50 UTC
cvs commit: db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu getting-started.xml
tomdz 2004/06/20 11:59:50
Modified: src/doc/forrest/src/documentation/content/xdocs site.xml
src/doc/forrest/src/documentation/content/xdocs/docu
getting-started.xml
Log:
Reworked "Getting Started"
Revision Changes Path
1.2 +4 -1 db-ojb/src/doc/forrest/src/documentation/content/xdocs/site.xml
Index: site.xml
===================================================================
RCS file: /home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/site.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- site.xml 20 Jun 2004 09:12:35 -0000 1.1
+++ site.xml 20 Jun 2004 18:59:50 -0000 1.2
@@ -267,9 +267,12 @@
<configuration href="docs/manual.html"/>
</log4j>
<ant href="http://ant.apache.org/"/>
+ <hsqldb href="http://hsqldb.sourceforge.net/"/>
<xdoclet href="http://xdoclet.sourceforge.net/">
<install href="install.html"/>
</xdoclet>
+ <eclipse href="http://www.eclipse.org/"/>
+ <idea href="http://www.jetbrains.com/idea/index.html"/>
<mozilla href="http://www.mozilla.org/"/>
<torque href="http://db.apache.org/torque/">
<gen href="generator/"/>
1.2 +335 -78 db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/getting-started.xml
Index: getting-started.xml
===================================================================
RCS file: /home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/getting-started.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- getting-started.xml 20 Jun 2004 09:12:35 -0000 1.1
+++ getting-started.xml 20 Jun 2004 18:59:50 -0000 1.2
@@ -29,103 +29,360 @@
<body>
<p>
This document will guide you through the very first steps of setting up a project with OJB. To
- make this easier, OJB comes with a blank project template which you're encouraged to use.<br/>
- In the next tutorial parts you'll then learn how to specify your persistent classes and how to
- use OJB's APIs to perform database operations.
+ make this easier, OJB comes with a blank project template called ojb-blank which you're
+ encouraged to use. You can download it <link href="ext:ojb/binaries-version">here</link>.<br/>
</p>
<section>
- <title>Building OJB</title>
+ <title>Acquiring ojb-blank</title>
<p>
- OJB uses <link href="ext:ant"><strong>Ant</strong></link> to build, so please install it
- prior to using OJB. You'll also need the <link href="ext:junit"><strong>Junit</strong></link>
- runtime jar (included in OJB in the lib folder) for running the unit tests; simply put it
- into the lib subfolder of your Ant directory. In addition, please make sure that the
- environment variables <code>ANT_HOME</code> and <code>JAVA_HOME</code> are correctly set
- to the top-level folders of your Ant distribution and your JDK installation, respectively.
+ First off, OJB uses <link href="ext:ant">Ant</link> to build, so please install it prior
+ to using OJB. In addition, please make sure that the environment variables
+ <code>ANT_HOME</code> and <code>JAVA_HOME</code> are correctly set to the top-level folders
+ of your Ant distribution and your JDK installation, respectively.
</p>
<p>
Next download the latest
- <link href="ext:ojb/source-version">OJB source distribution</link>.
- It is easiest to start with the source distribution rather than the binary
- as the unit tests provide excellent sample code, and it makes the ojb-blank
- task available for setting up a basic project.
+ <link href="ext:ojb/binaries-version">ojb-blank and OJB binary distributions</link>.
+ You can also start with the <link href="ext:ojb/source-version">source distribution </link>
+ rather than the binary as the unit tests provide excellent sample code and you can
+ build the ojb-blank project on your own with it.
</p>
<p>
- Unpack the source distribution and retrieve any missing additional
- <link href="site:deployment/additional-jars">required libaries</link>. Place these jar files in the
- <code>lib</code> directory of the OJB distribution.
+ The ojb-blank project contains all libraries necessary to get running. However, there may
+ be additional libraries required when you venture deeper into OJB's APIs. See
+ <link href="site:deployment/additional-jars">here</link> for a list of additional libraries.<br/>
+ Most notably, you'll probably want to add the jdbc driver for you database unless you
+ plan to use the embedded <link href="ext:hsqldb">Hsqldb database</link> for which the
+ ojb-blank project is pre-configured (including all necessary jars).
</p>
+ </section>
+ <section>
+ <title>Contents of ojb-blank</title>
<p>
- Change to the OJB installation directory and run
- </p>
- <source><![CDATA[
-ant ojb-blank]]></source>
+ Copy the <code>ojb-blank.jar</code> file to your project directory and unpack it via
+ the command
+ </p>
+ <source><![CDATA[jar xvf ojb-blank.jar]]></source>
<p>
- This will build OJB as well as an additional jar file called <code>ojb-blank.jar</code>
- containing a rudimentary OJB project for your use. After the build finishes you will find it
- library in the <code>dist</code> directory.
+ This will unpack it into the <code>ojb-blank</code> directory under wherever you unpacked
+ it from. You can move things out of that directory into your project directory, or, more
+ simply, rename the <code>ojb-blank</code> directory to be whatever you want your project
+ directory to be named.<br/>
+ After you unpacked the jar, you'll get the following directory layout:
</p>
+ <source><![CDATA[
+\ojb-blank
+ .classpath
+ .project
+ build.properties
+ build.xml
+ \lib
+ \src
+ \java
+ \resources
+ \schema
+ \test]]></source>
+ <p>
+ Here's a quick rundown on what the individual directories and files are:
+ </p>
+ <dl>
+ <dt><strong>.classpath, .project</strong></dt>
+ <dd>
+ An <link href="ext:eclipse">Eclipse</link> project for your convenience. You can simply
+ import it into Eclipse via
+ <strong>File -> Import... -> Existing Project into Workspace</strong>.
+ </dd>
+ <dt><strong>build.xml, build.properties</strong></dt>
+ <dd>
+ The Ant build script and the build properties. These are described in more detail
+ <link href="#build-files">below</link>.
+ </dd>
+ <dt><strong>lib</strong></dt>
+ <dd>
+ Contains the libraries necessary to compile and run your project. If you want to
+ use a different database than Hsqldb, then put the jars of your jdbc driver in here.
+ </dd>
+ <dt><strong>src/java</strong></dt>
+ <dd>
+ Put your java source code here.
+ </dd>
+ <dt><strong>src/resources</strong></dt>
+ <dd>
+ Contains the runtime configuration files for OJB. For more detail see
+ <link href="#runtime-configuration-files">below</link>.
+ </dd>
+ <dt><strong>src/schema</strong></dt>
+ <dd>
+ Here you will find a schema containing tables that are required by certain components
+ of OJB such as clustered locking and OJB managed sequences. More information on these
+ tables is available in the <link href="site:platform">platform documentation</link>.
+ The schema is in a database-independent format that can be used by
+ <link href="ext:torque">Torque</link> or
+ <link href="ext:jakarta/commons-sql">commons-sql</link> to create the database.<br/>
+ The ojb-blank project contains the runtime files of Torque 3.0.2, and provides a build
+ target that can be invoked on your schema (see <link href="#build-actions">below</link>
+ for details). Therefore, this directory also contains the build script of Torque, but
+ you won't need to invoke it directly.
+ </dd>
+ <dt><strong>src/java</strong></dt>
+ <dd>
+ Place your unit tests in here.
+ </dd>
+ </dl>
+ </section>
+ <anchor id="build-files"/>
+ <section>
+ <title>The build files</title>
+ <section>
+ <title>Configuration via <code>build.properties</code></title>
+ <p>
+ The next step is to adapt the build files, especially the <code>build.properties</code>
+ file to your environment. It basically contains two sets of information, the database
+ settings and the build configuration. While you shouldn't have to change the latter,
+ the database settings probably need to be adapted to suit your needs:
+ </p>
+ <table>
+ <tr>
+ <th>Property</th>
+ <th>Purpose</th>
+ </tr>
+ <tr>
+ <td>jcdAlias</td>
+ <td>The name of the connection. You should leave the default value, which
+ is <code>default</code>.</td>
+ </tr>
+ <tr>
+ <td>databaseName</td>
+ <td>This is the name of the database, per default <code>ojb_blank</code>.</td>
+ </tr>
+ <tr>
+ <td>databaseUser</td>
+ <td>The user name for accessing the database (default: <code>sa</code>). If you're
+ using Torque to create the database, then this user also requires sufficient
+ rights to create databases and tables.</td>
+ </tr>
+ <tr>
+ <td>databasePassword</td>
+ <td>Password for the user, per default empty.</td>
+ </tr>
+ <tr>
+ <td>dbmsName</td>
+ <td>The type of database, which is one of the following:<br/><strong>Db2</strong>,
+ <strong>Firebird</strong>, <strong>Hsqldb</strong>, <strong>Informix</strong>,
+ <strong>MaxDB</strong>, <strong>MsAccess</strong>, <strong>MsSQL</strong>,
+ <strong>MySQL</strong>,<strong>Oracle</strong> (pre-9i versions),
+ <strong>Oracle9i</strong>, <strong>WLOracle9i</strong> (Oracle 9i or above used
+ from WebSphere), <strong>PostgreSQL</strong>, <strong>Sapdb</strong>,
+ <strong>Sybase</strong> (generic), <strong>SybaseASA</strong>,
+ <strong>SybaseASE</strong>.<br/>
+ Please note that this setting is case-sensitive.<br/>
+ Per default, <link href="ext:hsqldb">Hsqldb</link> is used, which is an embedded
+ database. All files required for this database come with the ojb-blank project.</td>
+ </tr>
+ <tr>
+ <td>jdbcRuntimeDriver</td>
+ <td>The fully-qualified classname of the jdbc driver. For Hsqldb this is
+ <code>org.hsqldb.jdbcDriver</code>.</td>
+ </tr>
+ <tr>
+ <td>jdbcLevel</td>
+ <td>The jdbc level that the driver conforms to. Please check the documentation of
+ your jdbc driver for this value, though most jdbc drivers conform to version 2.0 at
+ least.<br/>
+ For the Hsqldb jdbc driver this is 2.0.</td>
+ </tr>
+ <tr>
+ <td>urlProtocol</td>
+ <td>The protocol of the database url (see below), usually <code>jdbc</code></td>
+ </tr>
+ <tr>
+ <td>urlSubprotocol</td>
+ <td>The sub-protocol of the database url which is database- and driver-specific.
+ For Hsqldb, you're using <code>hsqldb</code>.</td>
+ </tr>
+ <tr>
+ <td>urlDbalias</td>
+ <td>This is the address that points the jdbc driver to the database. For Hsqldb
+ this is per default the database name.</td>
+ </tr>
+ <tr>
+ <td>torque.database</td>
+ <td>If you're using Torque to create the database, then you have to set the database
+ here (again). Unfortunately, this value is different from the <code>dbmsName</code>
+ which defines the database for OJB. Currently, these values are defined:<br/>
+ <strong>axion</strong>, <strong>cloudscape</strong>, <strong>db2</strong>,
+ <strong>db2400</strong>, <strong>hypersonic</strong> (which is Hsqldb),
+ <strong>interbase</strong> (use for Firebird), <strong>mssql</strong>,
+ <strong>mysql</strong>, <strong>oracle</strong>, <strong>postgresql</strong>,
+ <strong>sapdb</strong>, and <strong>sybase</strong>.<br/>
+ Default value is <code>hypersonic</code> for use with Hsqldb.
+ </td>
+ </tr>
+ <tr>
+ <td>torque.database.createUrl</td>
+ <td>This specifies the url that Torque will use in order to create the database.
+ Depending on the database, this may be the same as the normal access url
+ (the default value), but for some database this is different. Please
+ check the manual of your database for this url.</td>
+ </tr>
+ </table>
+ <p>
+ If you know how the jdbc url for connecting to your database looks like, then you can
+ derive the settings <code>databaseName</code>, <code>databaseName</code>,
+ <code>databaseName</code> and <code>databaseName</code> easily:<br/>
+ Assume this url is given as:
+ </p>
+ <source><![CDATA[jdbc:mysql://localhost:3306/myDatabase]]></source>
+ <p>
+ then these properties are
+ </p>
+ <table>
+ <tr>
+ <th>Property</th>
+ <th>Value</th>
+ </tr>
+ <tr>
+ <td>databaseName</td>
+ <td><code>myDatabase</code></td>
+ </tr>
+ <tr>
+ <td>urlProtocol</td>
+ <td><code>jdbc</code></td>
+ </tr>
+ <tr>
+ <td>urlSubprotocol</td>
+ <td><code>mysql</code></td>
+ </tr>
+ <tr>
+ <td>urlDbalias</td>
+ <td><code>//localhost/myDatabase</code></td>
+ </tr>
+ </table>
+ </section>
+ <anchor id="build-actions"/>
+ <section>
+ <title>Building via <code>build.xml</code></title>
+ <p>
+ After setting up the build you're probably eager to actually build the project.
+ Here's the actions that you can perform using the Ant build file <code>build.xml</code>:
+ </p>
+ <table>
+ <tr>
+ <th>Action (target in the build.xml file)</th>
+ <th>What it does</th>
+ </tr>
+ <tr>
+ <td>clean</td>
+ <td>Cleans up all files from the previous build.</td>
+ </tr>
+ <tr>
+ <td>compile</td>
+ <td>Compiles your java source files to <code>build/java</code>. Usually, you
+ don't run this target, but rather the next one which includes the
+ compilation step.</td>
+ </tr>
+ <tr>
+ <td>build</td>
+ <td>Compiles your java sources files (using the compile action), and prepares
+ the runtime configuration files using the settings that you specified in
+ the <code>build.properties</code> file, most notably the
+ <link href="ext:repository_database.xml"><code>repository_database.xml</code></link>
+ which will be located in the <code>build/resources</code> directory after the
+ build.<br/>
+ After you run this action, your application is ready to go (if the action ran
+ successfully, of course).</td>
+ </tr>
+ <tr>
+ <td>jar</td>
+ <td>A convenience action that packs your successfully build application
+ into a jar.</td>
+ </tr>
+ <tr>
+ <td>xdoclet</td>
+ <td>Creates the runtime configuration files that describe the repository, from
+ javadoc comments embedded in your java source files. Details on how to
+ this are given in the <link href="site:documentation/index">tutorials</link>
+ and in the documentation of the
+ <link href="site:xdoclet-module">XDoclet OJB module</link>.</td>
+ </tr>
+ <tr>
+ <td>setup-db</td>
+ <td>Creates the database and tables from a database-independent schema using Torque.
+ You'll find more info on this schema in the documentation of the
+ <link href="site:xdoclet-module">XDoclet OJB module</link> and on the
+ <link href="ext:torque">Torque homepage</link>.</td>
+ </tr>
+ </table>
+ <p>
+ So, a typical build would be achieved with this Ant call:
+ </p>
+ <source><![CDATA[ant build]]></source>
+ <p>
+ If you want to create the database as well, and you have javadoc comments in your source code
+ that describe the repository, then you would call Ant this way:
+ </p>
+ <source><![CDATA[ant build xdoclet setup-db]]></source>
+ <p>
+ This will perform in that order the actions <code>build</code>, <code>xdoclet</code>
+ and <code>setup-db</code>.<br/>
+ Of course, you do not need to use Torque to setup your database, but it is a convenient
+ way to do so.<br/>
+ </p>
+ </section>
</section>
+ <anchor id="runtime-configuration-files"/>
<section>
- <title>Preparing your project</title>
+ <title>The runtime configuration files</title>
<p>
- Copy the <code>ojb-blank.jar</code> file to your project directory and unpack it via
- the <code>jar xvf ojb-blank.jar</code> command. This will unpack it into the
- <code>ojb-blank</code> directory under wherever you unpacked it from. You can move things out
- of that directory into your project directory, or, more simply, rename the
- <code>ojb-blank</code>
- directory to be whatever you want your project directory to be named.
- </p>
- <p>
- The ojb-blank project provides the libraries, basic configuration files, and an ant
- build file which can be used to get started with OJB. The first thing you will need to
- do is edit the <code>build.properties</code> file to enter your database information. By
- default it is set up to work against an embedded HSQLDB instance. This will work fine
- for learning, but you will probably want to configure it to run against a different RDBMS for
- most projects. For example configurations you can look in the
- <code>[db-ojb]/profiles</code> directory
- in the OJB install directory. The build file will copy the properties out of the project's
- <code>build.properties</code> into the
- <link href="ext:repository_database.xml"><code>repository_database.xml</code></link> located
- in the <code>src/resources/</code> directory when the project is built.
- </p>
- <p>
- If you are not using HSQLDB make sure to copy your JDBC driver into the
- <code>lib</code> directory and ensure it is in the classpath used by the
- <code>build.xml</code>.
- </p>
- <p>
- Two other files of interest are <code>src/resources/OJB.properties</code> and
- <code>src/resources/OJB-logging.properties</code>. The former is used to configure the OJB
- runtime. Here you can finetune OJB to suit your needs. For the various options see
- <link href="site:ojb-properties">here</link>.<br/>
- The other file defines the logging within OJB, but you can also use it for your own logging
- settings.
- </p>
- <p>
- The ojb-blank project also includes a schema that describes in an RDBMS-independent manner
- a database containing tables that are required for certain OJB operations. This schema is
- intened to be used with <link href="ext:torque">Torque</link> or
- <link href="ext:commons-sql">commons-sql</link>. Of course, you do not need to use this schema
- to build your database, but it is a convenient way to setup your database and it can also be used
- to generate the actual database DDL for you to modify an existing database.<br/>
- The OJB tables are only required for certain options, such as clustered locking and OJB managed
- sequences. More information on these tables is available
- <link href="site:platform">platform documentation</link>. If you do not use these, you can
- safely remove the tables.
- </p>
- <p>
- The repository metadata files are located in the <code>src/resources/</code> directory. The
- <code>repository_user.xml</code> file should be used for describing your specific mappings.
- The tutorials will explain their definition in more detail.
+ The last thing missing for actually running your project is to adapt the runtime
+ configuration files used by OJB. There are basically three sets of configuration that need
+ to be provided: configuration of the OJB runtime, description of the database connection,
+ and description of the repository.
</p>
+ <section>
+ <title>Configuring the OJB runtime</title>
+ <p>
+ With the <link href="site:ojb-properties">OJB.properties</link> file and
+ <link href="site:logging">OJB-logging.properties</link> (both located in
+ <code>src/resources</code>), you configure and finetune the runtime aspects of
+ OJB. For a simple application you'll probably won't have to change anything
+ in them, though.
+ </p>
+ </section>
+ <section>
+ <title>Configuring the database connection</title>
+ <p>
+ For projects that use OJB, you configure the connections to the database via
+ <link href="site:repository/jdbc-connection-descriptor">jdbc connection descriptors</link>.
+ These are usually defined in a file called <code>repository_database.xml</code>
+ (located in <code>src/resources</code>). In the ojb-blank project, the build file will
+ setup this file for you and place it in the <code>build/resources</code> directory.
+ </p>
+ </section>
+ <section>
+ <title>Configuring the repository</title>
+ <p>
+ Finally you need to configure the repository. It consists of descriptors that
+ define which java classes are mapped in what way to which database tables, and
+ it is typically contained in the <code>repository_user.xml</code> file. This is
+ the most complicated configuration part which will be explained in much more
+ detail in the rest of the <link href="site:documentation/tutorials/summary">tutorials</link>.<br/>
+ An convenient way of creating the repository metadata is to use the
+ <link href="site:xdoclet-module">XDoclet OJB module</link>. Basically, you put
+ specific Javadoc comments into your source code, which are then processed by the
+ build file (<code>xdoclet</code> and <code>setup-db</code> targets) and the
+ repository metadata and the database schema are generated.
+ </p>
+ </section>
</section>
<section>
<title>Learning More</title>
<p>
- The next step is to go through the <link href="site:documentation/index">tutorials</link> for the things
- you need to do. The <link href="site:mapping-tutorial">Mapping Tutorial</link> in particular is required
- to learn how to map your objects to relational tables.
+ After you've have learned about building and configuring projects that use OJB,
+ you should check out the <link href="site:documentation/tutorials/summary">tutorials</link>
+ to learn how to specify your persistent classes and how to use OJB's APIs to
+ perform database operations. The <link href="site:mapping-tutorial">Mapping Tutorial</link>
+ in particular shows you how to map your classes to tables in an RDBMS.
</p>
</section>
</body>
---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org