db-ojb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From to...@apache.org
Subject cvs commit: db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu getting-started.xml
Date Sun, 20 Jun 2004 20:58:16 GMT
tomdz       2004/06/20 13:58:16

  Modified:    src/doc/forrest/src/documentation/content/xdocs site.xml
               src/doc/forrest/src/documentation/content/xdocs/docu
                        getting-started.xml
  Log:
  Added sample to "Getting started"
  
  Revision  Changes    Path
  1.3       +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.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- site.xml	20 Jun 2004 18:59:50 -0000	1.2
  +++ site.xml	20 Jun 2004 20:58:16 -0000	1.3
  @@ -268,6 +268,9 @@
           </log4j>
           <ant href="http://ant.apache.org/"/>
           <hsqldb href="http://hsqldb.sourceforge.net/"/>
  +        <mysql href="http://dev.mysql.com/">
  +            <driver href="downloads/connector/j/"/>
  +        </mysql>
           <xdoclet href="http://xdoclet.sourceforge.net/">
               <install href="install.html"/>
           </xdoclet>
  
  
  
  1.3       +344 -10   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.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- getting-started.xml	20 Jun 2004 18:59:50 -0000	1.2
  +++ getting-started.xml	20 Jun 2004 20:58:16 -0000	1.3
  @@ -28,10 +28,16 @@
   
       <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 called ojb-blank which you're
  -    	encouraged to use. You can download it <link href="ext:ojb/binaries-version">here</link>.<br/>
  +    	    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 called ojb-blank which
you're
  +    	    encouraged to use. You can download it <link href="ext:ojb/binaries-version">here</link>.
       	</p>
  +    	<p>
  +    	    For the purpose of this guide, we'll be showing you how to setup the project for
a
  +    	    simple application that handles products and uses MySQL. This is continued later
on
  +    	    in the next <link href="site:documentation/tutorials/summary">tutorial parts</link>.
  +    	</p>
  +
           <section>
               <title>Acquiring ojb-blank</title>
               <p>
  @@ -56,13 +62,16 @@
                   ojb-blank project is pre-configured (including all necessary jars).
               </p>
           </section>
  +
           <section>
               <title>Contents of ojb-blank</title>
               <p>
                   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>
  +            <source><![CDATA[
  +jar xvf ojb-blank.jar
  +]]></source>
               <p>
                   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
  @@ -81,7 +90,8 @@
           \java
           \resources
           \schema
  -        \test]]></source>
  +        \test
  +]]></source>
               <p>
                   Here's a quick rundown on what the individual directories and files are:
               </p>
  @@ -129,10 +139,30 @@
                       Place your unit tests in here.
                   </dd>
               </dl>
  +            <section>
  +                <title>Sample project</title>
  +                <p>
  +                    For our sample project, we should rename the directory to something
more fitting,
  +                    like <code>productmanager</code>.
  +                </p>
  +                <p>
  +                    Also, since we're using MySQL, we put the MySQL jar of the
  +                    <link href="ext:mysql/driver">jdbc driver</link>, which
is called something like
  +                    <code>mysql-connector-java-[version]-stable-bin.jar</code>,
into the <code>lib</code>
  +                    subdirectory.
  +                </p>
  +                <p>
  +                    The only other thing missing is the source code, but since that's what
the other
  +                    tutorials are dealing with, we will silently assume that it is already
present in the
  +                    <code>src/java</code> subdirectory.
  +                </p>
  +            </section>
           </section>
  +
           <anchor id="build-files"/>
           <section>
               <title>The build files</title>
  +
               <section>
                   <title>Configuration via <code>build.properties</code></title>
                   <p>
  @@ -193,7 +223,7 @@
                       </tr>
                       <tr>
                           <td>urlProtocol</td>
  -                        <td>The protocol of the database url (see below), usually
<code>jdbc</code></td>
  +                        <td>The protocol of the database url (see below), usually
<code>jdbc</code>.</td>
                       </tr>
                       <tr>
                           <td>urlSubprotocol</td>
  @@ -259,6 +289,7 @@
                       </tr>
                   </table>
               </section>
  +
               <anchor id="build-actions"/>
               <section>
                   <title>Building via <code>build.xml</code></title>
  @@ -301,7 +332,7 @@
                           <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>
  +                            this are given in the <link href="site:documentation/tutorials/summary">tutorials</link>
                               and in the documentation of the
                               <link href="site:xdoclet-module">XDoclet OJB module</link>.</td>
                       </tr>
  @@ -321,15 +352,225 @@
                       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>
  +                <source><![CDATA[ant build setup-db]]></source>
                   <p>
                       This will perform in that order the actions <code>build</code>,
<code>xdoclet</code>
  -                    and <code>setup-db</code>.<br/>
  +                    (invoked automatically from the next action) 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>
  +                <title>Sample project</title>
  +                <p>
  +                    First we change the database properties to these values (assuming that
Torque will
  +                    be used to setup the database):
  +                </p>
  +                <table>
  +                    <tr>
  +                        <th>Property</th>
  +                        <th>Value</th>
  +                    </tr>
  +                    <tr>
  +                        <td>jcdAlias</td>
  +                        <td>We leave the default value of <code>default</code>.</td>
  +                    </tr>
  +                    <tr>
  +                        <td>databaseName</td>
  +                        <td>Since the application manages products, we call the database
  +                            <code>productmanager</code>.</td>
  +                    </tr>
  +                    <tr>
  +                        <td>databaseUser</td>
  +                        <td>This depends on your setup. For the purposes of this
guide, let's call him
  +                            <code>steve</code>.</td>
  +                    </tr>
  +                    <tr>
  +                        <td>databasePassword</td>
  +                        <td>Again depending on your setup. How about <code>secret</code>
(you know that
  +                            you should not use this password in reality ?!).</td>
  +                    </tr>
  +                    <tr>
  +                        <td>dbmsName</td>
  +                        <td><code>MySQL</code></td>
  +                    </tr>
  +                    <tr>
  +                        <td>jdbcRuntimeDriver</td>
  +                        <td>Its called <code>com.mysql.jdbc.Driver</code>.</td>
  +                    </tr>
  +                    <tr>
  +                        <td>jdbcLevel</td>
  +                        <td>For the newer Mysql drivers this is 3.0.</td>
  +                    </tr>
  +                    <tr>
  +                        <td>urlProtocol</td>
  +                        <td>The default of <code>jdbc</code> will do.</td>
  +                    </tr>
  +                    <tr>
  +                        <td>urlSubprotocol</td>
  +                        <td>For MySQL, we're using <code>mysql</code>.</td>
  +                    </tr>
  +                    <tr>
  +                        <td>urlDbalias</td>
  +                        <td>Assuming that the database runs locally on the default
port, we have
  +                            <code>//localhost/${databaseName}</code>.</td>
  +                    </tr>
  +                    <tr>
  +                        <td>torque.database</td>
  +                        <td>We want to use Torque, so we put <code>mysql</code>
here.</td>
  +                    </tr>
  +                    <tr>
  +                        <td>torque.database.createUrl</td>
  +                        <td>MySQL allows to create a database via jdbc. The url that
we should use
  +                            to do so, is the normal url used to access the database minus
the database
  +                            name. So the value here is:
  +                            <code>${urlProtocol}:${urlSubProtocol}://localhost/</code>.
  +                            Please note that the trailing slash is important.</td>
  +                    </tr>
  +                </table>
  +                <p>
  +                    Ok, now we have everything configured for building. The <code>build.properties</code>
  +                    file now looks like this (the comments have been removed for brevity):
  +                </p>
  +                <source><![CDATA[
  +jcdAlias=default
  +databaseName=productmanager
  +databaseUser=steve
  +databasePassword=secret
  +
  +dbmsName=MySQL
  +jdbcLevel=3.0
  +jdbcRuntimeDriver=com.mysql.jdbc.Driver
  +urlProtocol=jdbc
  +urlSubprotocol=mysql
  +urlDbalias=//localhost/${databaseName}
  +
  +torque.database=mysql
  +torque.database.createUrl=${urlProtocol}:${urlSubprotocol}://localhost/
  +
  +jar.name=projectmanager.jar
  +
  +source.dir=src
  +source.java.dir=${source.dir}/java
  +source.resource.dir=${source.dir}/resources
  +source.test.dir=${source.dir}/test
  +source.schema.dir=${source.dir}/schema
  +
  +build.dir=build
  +build.lib.dir=lib
  +build.classes.dir=${build.dir}/classes/
  +build.resource.dir=${build.dir}/resources/
  +
  +target.dir=target
  +]]></source>
  +                <p>
  +                    Looks like we're ready for building. Again, we're assuming that the
source code is
  +                    already present. So we're invoking Ant now in the top-level folder
  +                    <code>productmanager</code>:
  +                </p>
  +                <source><![CDATA[
  +ant build setup-db
  +]]></source>
  +                <p>
  +                    which should (assuming five java classes) produce an output like this
  +                </p>
  +                <source><![CDATA[
  +Buildfile: build.xml
  +
  +compile:
  +    [mkdir] Created dir: /home/steve/projects/productmanager/build
  +    [mkdir] Created dir: /home/steve/projects/productmanager/build/classes
  +    [javac] Compiling 5 source files to /home/steve/projects/productmanager/build/classes
  +
  +build:
  +     [copy] Copying 10 files to /home/steve/projects/productmanager/build/resources
  +
  +xdoclet:
  +[ojbdoclet] (XDocletMain.start                   47  ) Running <ojbrepository/>
  +[ojbdoclet] Generating ojb repository descriptor (build/resources//repository_user.xml)
  +[ojbdoclet] Type test.Project
  +[ojbdoclet] Processed 5 types
  +[ojbdoclet] Processed 5 types
  +[ojbdoclet] (XDocletMain.start                   47  ) Running <torqueschema/>
  +[ojbdoclet] Generating torque schema (build/resources//project-schema.xml)
  +[ojbdoclet] Processed 5 types
  +
  +setup-db:
  +
  +check-use-classpath:
  +
  +check-run-only-on-schema-change:
  +
  +sql-check:
  +
  +sql:
  +     [echo] +------------------------------------------+
  +     [echo] |                                          |
  +     [echo] | Generating SQL for YOUR Torque project!  |
  +     [echo] | Woo hoo!                                 |
  +     [echo] |                                          |
  +     [echo] +------------------------------------------+
  +
  +sql-classpath:
  +[torque-sql] Using contextProperties file:
  +             /home/steve/projects/productmanager/build.properties
  +[torque-sql] Using classpath
  +[torque-sql] Generating to file
  +             /home/steve/projects/productmanager/build/resources/report.productmanager.sql.generation
  +[torque-sql] Parsing file: 'ojbcore-schema.xml'
  +[torque-sql] (transform.DTDResolver               128 ) Resolver: used database.dtd from
  +             org.apache.torque.engine.database.transform package
  +[torque-sql] Parsing file: 'project-schema.xml'
  +[torque-sql] (transform.DTDResolver               140 ) Resolver: used
  +             http://jakarta.apache.org/turbine/dtd/database.dtd
  +
  +sql-template:
  +
  +create-db-check:
  +
  +create-db:
  +[torque-data-model] Using classpath
  +[torque-data-model] Generating to file
  +                    /home/steve/projects/productmanager/build/resources/create-db.sql
  +[torque-data-model] Parsing file: 'ojbcore-schema.xml'
  +[torque-data-model] (transform.DTDResolver               128 ) Resolver: used database.dtd
from
  +                    org.apache.torque.engine.database.transform package
  +[torque-data-model] Parsing file: 'project-schema.xml'
  +[torque-data-model] (transform.DTDResolver               140 ) Resolver: used
  +                    http://jakarta.apache.org/turbine/dtd/database.dtd
  +     [echo]
  +     [echo]       Executing the create-db.sql script ...
  +     [echo]
  +      [sql] Executing file:
  +            /home/steve/projects/productmanager/build/resources/create-db.sql
  +      [sql] 2 of 2 SQL statements executed successfully
  +
  +insert-sql:
  +[torque-sql-exec] Our new url -> jdbc:mysql://localhost/productmanager
  +[torque-sql-exec] Executing file:
  +                  /home/steve/projects/productmanager/build/resources/project-schema.sql
  +[torque-sql-exec] Executing file:
  +                  /home/steve/projects/productmanager/build/resources/ojbcore-schema.sql
  +[torque-sql-exec] 50 of 50 SQL statements executed successfully
  +
  +BUILD SUCCESSFUL]]></source>
  +                <p>
  +                    That was it. You now have your database setup properly. Go on, have
a look:
  +                </p>
  +                <source><![CDATA[
  +mysql -u steve productmanager
  +
  +mysql> show tables;
  +]]></source>
  +                <p>
  +                    There, all tables for your project, as well as the tables required
for some
  +                    OJB functionality which we also used in the above process (you can
recognize
  +                    them by their names which start with <code>ojb_</code>).
  +                </p>
  +            </section>
           </section>
  +
           <anchor id="runtime-configuration-files"/>
           <section>
               <title>The runtime configuration files</title>
  @@ -339,6 +580,7 @@
                   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>
  @@ -349,6 +591,7 @@
                       in them, though.
                   </p>
               </section>
  +
               <section>
                   <title>Configuring the database connection</title>
                   <p>
  @@ -359,6 +602,7 @@
                       setup this file for you and place it in the <code>build/resources</code>
directory.
                   </p>
               </section>
  +
               <section>
                   <title>Configuring the repository</title>
                   <p>
  @@ -374,7 +618,97 @@
                       repository metadata and the database schema are generated.
                   </p>
               </section>
  +
  +            <section>
  +                <title>Sample project</title>
  +                <p>
  +                    Actually, there is not much to do here. For our simple sample application
  +                    the default properties of OJB work just fine, so we leave <code>OJB.properties</code>
  +                    and <code>OJB-logging.properties</code> untouched.
  +                </p>
  +                <p>
  +                    Also, the build file generated the connection descriptor for us, and
we were using the
  +                    XDoclet OJB module and Torque to generate the repository metadata and
database for us.
  +                    For instance, the processed connection descriptor (file
  +                    <code>build/resources/repository_database.xml</code>) looks
like this:
  +                </p>
  +                <source><![CDATA[
  +<jdbc-connection-descriptor
  +    jcd-alias="default"
  +    default-connection="true"
  +    platform="MySQL"
  +    jdbc-level="3.0"
  +    driver="com.mysql.jdbc.Driver"
  +    protocol="jdbc"
  +    subprotocol="mysql"
  +    dbalias="//localhost/productmanager"
  +    username="root"
  +    password=""
  +    eager-release="false"
  +    batch-mode="false"
  +    useAutoCommit="1"
  +    ignoreAutoCommitExceptions="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="21"
  +        validationQuery="" />
  +    <sequence-manager className="org.apache.ojb.broker.util.sequence.SequenceManagerHighLowImpl">
  +        <attribute attribute-name="grabSize" attribute-value="20"/>
  +        <attribute attribute-name="autoNaming" attribute-value="true"/>
  +        <attribute attribute-name="globalSequenceId" attribute-value="false"/>
  +        <attribute attribute-name="globalSequenceStart" attribute-value="10000"/>
  +    </sequence-manager>
  +</jdbc-connection-descriptor>
  +]]></source>
  +                <p>
  +                    If you're curious as to what this stuff means, check this
  +                    <link href="site:jdbc-connection-descriptor">reference guide</link>.
  +                </p>
  +                <p>
  +                    The repository metadata (file <code>build/resources/repository_user.xml</code>)
  +                    starts like:
  +                </p>
  +                <source><![CDATA[
  +<class-descriptor
  +    class="sample.Product"
  +    table="Product"
  +>
  +    <field-descriptor
  +        name="name"
  +        column="name"
  +        jdbc-type="VARCHAR"
  +        length="32"
  +    >
  +    </field-descriptor>
  +    <field-descriptor
  +        name="price"
  +        column="price"
  +        jdbc-type="FLOAT"
  +    >
  +    </field-descriptor>
  +    <field-descriptor
  +        name="stock"
  +        column="stock"
  +        jdbc-type="INTEGER"
  +    >
  +    </field-descriptor>
  +    <field-descriptor
  +        name="id"
  +        column="id"
  +        jdbc-type="INTEGER"
  +        primarykey="true"
  +    >
  +    </field-descriptor>
  +</class-descriptor>
  +...
  +]]></source>
  +            </section>
           </section>
  +
           <section>
               <title>Learning More</title>
               <p>
  
  
  

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