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 br...@apache.org on 2003/11/27 18:01:27 UTC
cvs commit: db-ojb/xdocs getting-started.xml
brianm 2003/11/27 09:01:27
Modified: xdocs getting-started.xml
Log:
Reworked to be based around the ojb-blank ant task
Revision Changes Path
1.2 +71 -181 db-ojb/xdocs/getting-started.xml
Index: getting-started.xml
===================================================================
RCS file: /home/cvs/db-ojb/xdocs/getting-started.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- getting-started.xml 27 Nov 2003 13:08:25 -0000 1.1
+++ getting-started.xml 27 Nov 2003 17:01:27 -0000 1.2
@@ -1,192 +1,82 @@
<?xml version="1.0"?>
<!-- @version $Id$ -->
<document>
-
<properties>
<author email="brian@skife.org">Brian McCallister</author>
<title>ObJectRelationalBridge - Getting Started</title>
</properties>
-
<body>
-
<section name="Getting Started with OJB">
-<subsection name="Introduction">
- <p>
- This document is designed to help you get started with OJB for the first
- time. It is a cookbook type set of instructions designed to get you get
- OJB installed, and able to work on the other various tutorials.
- </p>
- <p>
- This tutorial will:
- <ol>
- <li>Install OJB</li>
- <li>Set up a database to test against</li>
- <li>Set up a basic project using OJB</li>
- <li>Configure a PostgreSQL database for use with OJB</li>
- </ol>
- </p>
- <p>
- This tutorial presumes you are comfortable configuring your relational
- database of choice, including adding databases and users, and
- configuring access controls at the database level (ie, you can create a
- database and user and give the user permission to access and change the
- database over a JDBC connection).
- </p>
-</subsection>
-<subsection name="Setting Up the Database">
- <p>
- The easiest way to get started is just to use the included HSQLDB
- embedded database. As people usually have a different database in mind
- this section will describe setting up a PostgreSQL database.
- </p>
- <p>
- Getting started, it is convenient to use the standard names that OJB likes to use for
- testing. So, create a database named <code>OJB</code> and a user with
- read/write access to that database named <code>oleg</code>. In
- PostgreSQL I prefer to name the database lower-case
- <code>ojb</code> as it makes the command line psql tools easier to use.
- Your mileage may vary.
- </p>
-</subsection>
-<subsection name="Installing and Building OJB">
- <p>
- Using the source installation provides a great deal of flexibility when
- working with OJB, and is the better path to take while learning the
- tool.
- </p>
- <p>
- Download the most recent source distribution, or retrieve it from CVS
- and unpack it to a chosen directory. Building OJB will require
- retrieving several additional libraries which are not redistributable by
- Jakarta directly. These are specified in the <a
- href="deployment.html">deployment</a> instructions. Retrieve the needed
- libraries and install them in <code>lib/</code> directory. As mentioned,
- make sure to include the JDBC driver for the database you are using.
- </p>
- <p>
- Now, run <code>ant jar</code> in your installation directory to build
- OJB. If you experience build errors that a class is not found, you have
- missed a required library. Check again to make sure you have downloaded
- and added the needed jars to the <code>lib/</code> directory. The
- package name of the missing class should give you a good clue as to what
- library you need.
- </p>
-</subsection>
-<subsection name="Accessing Your Database">
- <p>
- Now that you know you can build the actual OJB library, lets make sure
- it works with your database.
- </p>
- <p>
- Edit the <code>build.properties</code> file and uncomment the line for
- the database you are using. For this example we will use PostgreSQL, so
- we will uncomment the linefor PostgreSQL: <code>profile=postgresql</code>
- and comment the line for HSQL: <code>#profile=hsqldb</code>. You will
- uncomment the profile you need for your specific database.
- </p>
- <p>
- Look for your database's entry in the <code>profiles/</code> directory,
- <code>postgresql.profile</code> for our PostgreSQL example, and open it
- in your text editor. Make any needed changes (such as specifying a
- password if you have your database set to require one) to the
- configuration and save the profile.
- </p>
- <p>
- Now that the raw information needed to access your database is entered,
- go back to the installation directory for OJB and run
- <code>ant junit</code> and sit back. This will construct all of the
- needed tables for OJB, as well as tables for unit testing OJB. It will
- then happily run all of the various unit tests for you.
- </p>
- <p>
- Assuming the build succeeded, take a look at your database and look at
- the various tables. Pay particular note to the system tables described
- in the <a href="platforms.html">platforms</a> documentation. You will
- need these tables in the database for your application as well.
- </p>
-</subsection>
-</section>
-
-<section name="Your Project">
-<subsection name="Preparing the Database">
- <p>
- Once again we will begin by preparing the database. One option is to
- change the database profile to point directly at your project database
- and run the ant task to build the database. While this will generated
- the needed OJB tables, it will also clutter your database with a score
- or so ugly unit test tables.
- </p>
- <p>
- Assuming you tested against the same type of database you intend to run
- against, the DDL for the required tables already exists, though. You can
- use this DDL to generate the OJB tables in your database. The core
- tables required by OJB will have their DDL in the
- <code>target/src/sql/ojbcore-schema.sql</code> sql script. You can use
- it directly to generate the required tables in your project's database.
- </p>
- <p>
- OJB uses <a href="http://db.apache.org/torque">Torque</a> to generate
- the JUnit tables. An excellent way to generate the OJB tables, instead
- of using the DDL generated for the tests, is to generate your schema via
- Torque as well, and include the schema definitions from the JUnit tests
- in your schema definition. This is, however, beyond the scope of this
- tutorial. Torque does have an excellent set of tutorials that can make
- this task very simple though. The schema definition for OJB is in the
- <code>src/schema/ojbcore-schema.xml</code> file. Just drop this file
- into your own Torque schema directory and you are good to go, the OJB
- schema will be built right alongside your own.
- </p>
-</subsection>
-<subsection name="OJB Deployment">
- <p>
- Detailed deployment information is available in the <a
- href="deployment.html">deployment</a> documentation, including examples
- of deployment to various J2EE containers. This tutorial
- merely steps through the minimum to get a project up and running in a
- freestanding applications.
- </p>
- <p>
- OJB requires a number of configuration files to function correctly.
- All of these configuration files can be loaded directly off of the
- classpath, however so you just need ot get the onto your runtime
- classpath.
- </p>
- <p>
- The required files are:
- <ul>
- <li>OJB.properties</li>
- <li>repository*.xml</li>
- </ul>
- It is easiest to just copy the files from the test run to your project
- and edit them to your needs. The test files can be found in the
- <code>target/test/ojb/</code> directory. Copy these to a place directly
- on your classpath - or better, to a place where your build process can
- copy them to your runtime classpath.
- </p>
- <p>
- Open up the repository.xml file. It is basically a skeleton that
- includes the other repository-*.xml files. The default layout works
- fairly well - use repository-user.xml for your mappings,
- repository-database.xml for the database connection information, etc.
- You can safely comment out or remove the junit, jdo, and ejb sections
- however for this. If you intend to use that functionality yourself, go
- ahead and add it back in after you have a stronger understanding of what
- it does. For now, we just need the core functionality. make sure to
- leave the internal reference in - it contains the mappings
- for OJB's internally used tables.
- </p>
- <p>
- In addition to the configuration information, you will need the ojb jar
- library, and its required libraries. An up to date list of these is kept
- on the
- <a href="deployment.html#Additional jar archives">
- Deployment</a> page. Copy these jar files to your runtime classpath as
- well as the db-ojb-*.jar.
- </p>
- <p>
- You are now ready to begin using OJB!
- </p>
-</subsection>
+ <subsection name="Building OJB">
+ <p>
+ First, ensure that you have <a href="http://ant.apache.org">Ant</a> installed and have the
+ <code>ANT_HOME</code> and <code>JAVA_HOME</code>
+ environment variables set so that you can build OJB. Setting these up is described in
+ Ant documentation.
+ </p>
+ <p>
+ Next download the latest <a href="http://db.apache.org/builds/ojb/">source distribution</a>.
+ 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.
+ </p>
+ <p>
+ Unpack the source distribution and retrieve the additional
+ <a href="http://db.apache.org/ojb/deployment.html#Additional%20jar%20archives">
+ required libaries</a>. Place these jar files in the <code>lib</code> directory
+ of the OJB distribution.
+ </p>
+ <p>
+ Change to the OJB installation directory and run <code>ant ojb-blank</code>. This will
+ build OJB and an additional jar file containing a rudimentary project which uses OJB. After
+ the build finishes you will find the <code>ojb-blank.jar</code> library in the
+ <code>dist</code> directory.
+ </p>
+ </subsection>
+ <subsection name="Your Project">
+ <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>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 <code>repository_database.xml</code> 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>
+ The ojb-blank project also includes the <a href="http://db.apache.org/torque/">Torque</a>
+ schema for OJB's required tables. You do not need to use Torque to build your database, but
+ it can also be used generate the DDL for you to modify an existing database. The OJB tables
+ are required for specific options, such as clustered locking and OJB managed sequences. More
+ information on these tables is available <a href="platforms.html">platform documentation</a>
+ </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.
+ </p>
+ </subsection>
+ <subsection name="Learning More">
+ <p>
+ The next step is to go through the <a href="user-docs.html">tutorials</a> for the things
+ you need to do. The
+ <a href="">Mapping Tutorial</a> in particular is required to learn how to map
+ your objects to relational tables.
+ </p>
+ </subsection>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org