db-ojb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bri...@apache.org
Subject cvs commit: db-ojb/xdocs getting-started.xml
Date Thu, 27 Nov 2003 17:01:27 GMT
brianm      2003/11/27 09:01:27

  Modified:    xdocs    getting-started.xml
  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$ -->
       <author email="brian@skife.org">Brian McCallister</author>
       <title>ObJectRelationalBridge - Getting Started</title>
   <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 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 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 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>
  -<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 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 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
  +            Ant documentation.
  +        </p>
  +        <p>
  +            Next download the latest <a href="http://db.apache.org/builds/ojb/">source
  +            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>
  +            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
  +            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
  +            most projects. For example configurations you can look in the <code>profiles</code>
  +            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
  +        </p>
  +        <p>
  +            The repository metadata files  are located in the 
  +            <code>src/resources/</code> directory. The <code>repository_user.xml</code>
  +            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>

To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org

View raw message