You are viewing a plain text version of this content. The canonical link for it is here.
Posted to general@db.apache.org by rh...@apache.org on 2012/12/19 19:20:28 UTC
svn commit: r843115 [8/44] - in /websites/production/db/content/derby: ./
binaries/ blogs/ blogs/images/ dev/ docs/ images/ integrate/
integrate/plugin_help/ integrate/plugin_help/images/ logo/ manuals/ papers/
papers/DerbyTut/ releases/ skin/ skin/css...
Added: websites/production/db/content/derby/integrate/DerbyTomcat5512JPetStor.html
==============================================================================
--- websites/production/db/content/derby/integrate/DerbyTomcat5512JPetStor.html (added)
+++ websites/production/db/content/derby/integrate/DerbyTomcat5512JPetStor.html Wed Dec 19 18:20:21 2012
@@ -0,0 +1,771 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta content="Apache Forrest" name="Generator">
+<meta name="Forrest-version" content="0.8">
+<meta name="Forrest-skin-name" content="pelt">
+<title>Embedding Apache Derby in Tomcat and creating an iBATIS JPetStore Demo</title>
+<link type="text/css" href="../skin/basic.css" rel="stylesheet">
+<link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet">
+<link media="print" type="text/css" href="../skin/print.css" rel="stylesheet">
+<link type="text/css" href="../skin/profile.css" rel="stylesheet">
+<script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script>
+<link rel="shortcut icon" href="../">
+</head>
+<body onload="init()">
+<script type="text/javascript">ndeSetTextSize();</script>
+<div id="top">
+<!--+
+ |breadtrail
+ +-->
+<div class="breadtrail">
+<a href="http://www.apache.org/">apache</a> > <a href="http://db.apache.org/">db</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+<!--+
+ |header
+ +-->
+<div class="header">
+<!--+
+ |start group logo
+ +-->
+<div class="grouplogo">
+<a href="http://db.apache.org/derby"><img class="logoImage" alt="Apache Derby" src="../images/derby-logo-web.png" title="Derby is a zero-admin Java RDBMS"></a>
+</div>
+<!--+
+ |end group logo
+ +-->
+<!--+
+ |start Project Logo
+ +-->
+<div class="projectlogoA1">
+<a href="http://db.apache.org"><img class="logoImage" alt="Apache DB Project" src="../images/db-logo-white.png" title="Apache DB creates and maintains database solutions."></a>
+</div>
+<!--+
+ |end Project Logo
+ +-->
+<!--+
+ |start Tabs
+ +-->
+<ul id="tabs">
+<li>
+<a class="unselected" href="../index.html">Home</a>
+</li>
+<li>
+<a class="unselected" href="../quick_start.html">Quick Start</a>
+</li>
+<li>
+<a class="unselected" href="../derby_downloads.html">Download</a>
+</li>
+<li>
+<a class="unselected" href="../derby_comm.html">Community</a>
+</li>
+<li>
+<a class="unselected" href="../manuals/index.html">Documentation</a>
+</li>
+<li class="current">
+<a class="selected" href="../blogs/index.html">Resources</a>
+</li>
+</ul>
+<!--+
+ |end Tabs
+ +-->
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<!--+
+ |start Subtabs
+ +-->
+<div id="level2tabs"></div>
+<!--+
+ |end Endtabs
+ +-->
+<script type="text/javascript"><!--
+document.write("Last Published: " + document.lastModified);
+// --></script>
+</div>
+<!--+
+ |breadtrail
+ +-->
+<div class="breadtrail">
+
+
+ </div>
+<!--+
+ |start Menu, mainarea
+ +-->
+<!--+
+ |start Menu
+ +-->
+<div id="menu">
+<div onclick="SwitchMenu('menu_1.1', '../skin/')" id="menu_1.1Title" class="menutitle">Blogs and Articles About Derby</div>
+<div id="menu_1.1" class="menuitemgroup">
+<div class="menuitem">
+<a href="../blogs/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../blogs/index.html#blogs">Blogs</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3', '../skin/')" id="menu_1.1.3Title" class="menutitle">Articles</div>
+<div id="menu_1.1.3" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.1.3.1', '../skin/')" id="menu_1.1.3.1Title" class="menutitle">Tutorials, Tips and Tuning</div>
+<div id="menu_1.1.3.1" class="menuitemgroup">
+<div class="menuitem">
+<a href="../blogs/index.html#getstarted">Getting Started</a>
+</div>
+<div class="menuitem">
+<a href="../blogs/index.html#features">Features, Hints and Tips</a>
+</div>
+<div class="menuitem">
+<a href="../blogs/index.html#security">Security</a>
+</div>
+<div class="menuitem">
+<a href="../blogs/index.html#performance">Performance and Tuning</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.2', '../skin/')" id="menu_1.1.3.2Title" class="menutitle">Tools and Migration</div>
+<div id="menu_1.1.3.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../blogs/index.html#tools">Tools</a>
+</div>
+<div class="menuitem">
+<a href="../blogs/index.html#migration">Migration</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.3', '../skin/')" id="menu_1.1.3.3Title" class="menutitle">Applications</div>
+<div id="menu_1.1.3.3" class="menuitemgroup">
+<div class="menuitem">
+<a href="../blogs/index.html#client">Client</a>
+</div>
+<div class="menuitem">
+<a href="../blogs/index.html#middletier">Middle Tier</a>
+</div>
+<div class="menuitem">
+<a href="../blogs/index.html#persistence">Persistence</a>
+</div>
+<div class="menuitem">
+<a href="../blogs/index.html#scalability">Scalability and Failover</a>
+</div>
+</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.2', '../skin/')" id="menu_1.2Title" class="menutitle">Integration With Other Products</div>
+<div id="menu_1.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../integrate/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../integrate/index.html#uses">What works with Derby?</a>
+</div>
+<div class="menuitem">
+<a href="../integrate/index.html#products">Product Writeups</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.3', '../skin/')" id="menu_1.3Title" class="menutitle">Eclipse Plug-ins</div>
+<div id="menu_1.3" class="menuitemgroup">
+<div class="menuitem">
+<a href="../integrate/derby_plugin_info.html">Info</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.4', '../skin/')" id="menu_1.4Title" class="menutitle">Papers and Presentations</div>
+<div id="menu_1.4" class="menuitemgroup">
+<div class="menuitem">
+<a href="../papers/index.html">Overview</a>
+</div>
+<div onclick="SwitchMenu('menu_1.4.2', '../skin/')" id="menu_1.4.2Title" class="menutitle">Derby Engine</div>
+<div id="menu_1.4.2" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.4.2.1', '../skin/')" id="menu_1.4.2.1Title" class="menutitle">Javadoc</div>
+<div id="menu_1.4.2.1" class="menuitemgroup">
+<div class="menuitem">
+<a href="http://db.apache.org/derby/javadoc/engine">Engine</a>
+</div>
+<div class="menuitem">
+<a href="http://db.apache.org/derby/javadoc/language">Language</a>
+</div>
+<div class="menuitem">
+<a href="http://db.apache.org/derby/javadoc/tools">Tools</a>
+</div>
+<div class="menuitem">
+<a href="http://db.apache.org/derby/javadoc/publishedapi">API</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../papers/derby_arch.html">Architecture</a>
+</div>
+<div class="menuitem">
+<a href="../papers/btree_package.html">BTree</a>
+</div>
+<div class="menuitem">
+<a href="../papers/pageformats.html">Disk Page Format</a>
+</div>
+<div class="menuitem">
+<a href="../papers/derby_htw.html">How Things Work</a>
+</div>
+<div class="menuitem">
+<a href="../papers/Intersect-design.html">Intersect & Except</a>
+</div>
+<div class="menuitem">
+<a href="../papers/JDBCImplementation.html">JDBC</a>
+</div>
+<div class="menuitem">
+<a href="../papers/logformats.html">Log Format</a>
+</div>
+<div class="menuitem">
+<a href="../papers/recovery.html">Logging & Recovery</a>
+</div>
+<div class="menuitem">
+<a href="../papers/optimizer.html">Optimizer</a>
+</div>
+<div class="menuitem">
+<a href="http://db.apache.org/derby/javadoc/engine/org/apache/derby/iapi/types/package-summary.html#package_description">Type System</a>
+</div>
+<div class="menuitem">
+<a href="../papers/versionupgrade.html">Versioning</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.4.3', '../skin/')" id="menu_1.4.3Title" class="menutitle">Derby Network Client</div>
+<div id="menu_1.4.3" class="menuitemgroup">
+<div class="menuitem">
+<a href="../papers/DerbyClientSpec.html">Functional Spec</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.4.4', '../skin/')" id="menu_1.4.4Title" class="menutitle">Derby Tutorial</div>
+<div id="menu_1.4.4" class="menuitemgroup">
+<div class="menuitem">
+<a href="../papers/DerbyTut/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../papers/DerbyTut/install_software.html">Step 1: Install Software</a>
+</div>
+<div class="menuitem">
+<a href="../papers/DerbyTut/ij_intro.html">Step 2: ij Basics</a>
+</div>
+<div class="menuitem">
+<a href="../papers/DerbyTut/embedded_intro.html">Step 3: Embedded Derby</a>
+</div>
+<div class="menuitem">
+<a href="../papers/DerbyTut/ns_intro.html">Step 4: Derby Network Server</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.4.5', '../skin/')" id="menu_1.4.5Title" class="menutitle">Presentations</div>
+<div id="menu_1.4.5" class="menuitemgroup">
+<div class="menuitem">
+<a href="../papers/ApacheCon.html">ApacheCon</a>
+</div>
+<div class="menuitem">
+<a href="../papers/MiscPresentations.html#Victorian+Java+User+Group">Victorian JUG 2008</a>
+</div>
+<div class="menuitem">
+<a href="../papers/MiscPresentations.html#OSCON+2005">OSCON 2005</a>
+</div>
+<div class="menuitem">
+<a href="../papers/MiscPresentations.html#Colorado+Software+Summit+2004">Colorado 2004</a>
+</div>
+</div>
+</div>
+<!--+
+ |start Search
+ +-->
+<div class="searchbox">
+<hr>
+<form action="http://www.google.com/search" method="get">
+<input value="db.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="18" name="q" id="query" type="text" value="Search the site with google">
+ <input name="Search" value="Search" type="submit">
+</form>
+</div>
+<!--+
+ |end search
+ +-->
+<div id="credit"></div>
+<div id="roundbottom">
+<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
+<!--+
+ |alternative credits
+ +-->
+<div id="credit2"></div>
+</div>
+<!--+
+ |end Menu
+ +-->
+<!--+
+ |start content
+ +-->
+<div id="content">
+<div class="trail">Font size:
+ <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
+ <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+ <input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
+</div>
+<h1>Embedding Apache Derby in Tomcat and creating an iBATIS JPetStore Demo</h1>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#Why+Derby">Why Derby</a>
+</li>
+<li>
+<a href="#The+Software+Components">The Software Components</a>
+</li>
+<li>
+<a href="#Typographic+Conventions+Used">Typographic Conventions Used</a>
+</li>
+<li>
+<a href="#Required+Software+%2F+Downloads">Required Software / Downloads</a>
+</li>
+<li>
+<a href="#Setup+of+Application+with+the+Datasource+in+the+Global+Context%3A">Setup of Application with the Datasource in the Global Context:</a>
+</li>
+<li>
+<a href="#Alternate+Setup%3A+Datasource+in+the+Application+Context">Alternate Setup: Datasource in the Application Context</a>
+</li>
+<li>
+<a href="#Database+Creation+Instructions+%28optional%29">Database Creation Instructions (optional)</a>
+</li>
+<li>
+<a href="#General+Integration+Notes">General Integration Notes</a>
+</li>
+<li>
+<a href="#Tomcat+Integration+Notes">Tomcat Integration Notes</a>
+</li>
+<li>
+<a href="#iBATIS+Integration+Notes">iBATIS Integration Notes</a>
+</li>
+<li>
+<a href="#Rlinks">Links Section</a>
+</li>
+</ul>
+</div>
+
+<p>This is the third in a series of articles that detail creating a demonstration web application using a Derby database running in different server environments. This article details how to create the demo on the Apache Tomcat Server. See the links in the <a href="#Rlinks">Related Articles</a> section below to access the other articles.</p>
+
+
+<div class="note">
+<div class="label">Note</div>
+<div class="content"> As of this writing (Oct 2005), Tomcat 5.5.12 has just been declared a "stable release" and is used for this demonstration. Version 5.5.12 bundles the DBCP libraries needed to establish the datasource connection pool used by the system. If you will be using an older version of Tomcat you will need to add this component as described on the <em>JDBC Datasources</em> page for your release. You may also need to address other version differences. This deployment was not tested on other Tomcat versions.</div>
+</div>
+
+
+<p>
+ This article shows the steps required to embed Derby in a Tomcat version 5.5.12 Server and then deploy a copy of the iBATIS JPetStore application that utilizes a Derby database. The implementation accesses the Derby database via a JNDI registered datasource and hence the same application code and Derby database can be used unchanged to create the demo in different environments. Details are provided for registering the datasource as either a Tomcat server-wide (Global) JNDI resource or a per-application (context specific) JNDI resource.</p>
+
+<a name="N1001D"></a><a name="Why+Derby"></a>
+<h2 class="boxed">Why Derby</h2>
+<div class="section">
+<p>
+Most J2EE applications use a JDBC-compliant database to store data. Arguably, one of the more time consuming tasks when deploying such an web application is the database setup. These steps often involve compiling DBMS code (if the database system is not already installed) then creating and populating the physical database itself. Since Derby is implemented entirely in JAVA these steps can be avoided. Simply put, Derby is easy add to a Tomcat Server environment and reduces the complexity of deploying applications that use a database.</p>
+<p>
+Installation of the Derby DBMS is as simple as copying a 2 Mb jarfile to a known location. Like any other general use component the Derby jarfile is added to the Tomcat common shared library directory. Setup of the physical database and application data can be as easy as copying the fully initialized physical database to a location on the Server machine then configuring datasource to access it. The following instructions demonstrate the ease with which this can be accomplished using Tomcat version 5.5.12.
+</p>
+</div>
+ <!-- MISC TEXT:
+The web application used for the demonstration is the freely distributable iBATIS JpetStore application.
+ -->
+
+<a name="N1002C"></a><a name="The+Software+Components"></a>
+<h2 class="boxed">The Software Components</h2>
+<div class="section">
+<p>Derby is an open source, java relational database freely available from the Apache Software Foundation (ASF). It is well suited for use with Java applications that require data persistence and is ideally suited for use in a Server environment like Tomcat. Derby can be used in one of two configurations, embedded in a java application or used with Network Server and run as a separate DBMS process. When embedded in an application like Tomcat that provides network communication services there is usually no need to run the Network Server.</p>
+<p>
+Tomcat is a widely used, open source web application server freely available from ASF. Initially designed as a servlet/JSP container Tomcat now bundles many additional components that provide J2EE Server capabilities to the system. Tomcat development is managed as a subproject of the Apache Jakarta project.</p>
+<p>
+JPetStore is a rewritten Pet Store application based on Sun's J2EE Pet Store. It was originally designed to compare the .NET and J2EE architectures. It is now the official example application for the iBATIS Data Mapper framework. iBATIS greatly simplifies the coding of Java and .NET applications that access data from a relational database like Derby. iBATIS, like the other software used in this implementation is an open source product freely available from ASF.</p>
+</div>
+
+<a name="N1003C"></a><a name="Typographic+Conventions+Used"></a>
+<h2 class="boxed">Typographic Conventions Used</h2>
+<div class="section">
+<p> The following codes in curly braces will be used to represent installation dependant information as described below:</p>
+<dl>
+
+<dt>{Tomcat_Home}</dt>
+
+<dd> The installation directory for the Tomcat server (a.k.a. <span class="codefrag">CATALINA_HOME</span>).</dd>
+
+<dt>{machine-name}</dt>
+
+<dd> the hostname of the machine on which the server and application are installed.</dd>
+
+<dt>{Derby_System_Home}</dt>
+
+<dd> the directory containing the <span class="codefrag">derby.log</span> file. This is the default output directory for Derby and should be the same as {Tomcat_Home}. The JPetStoreDB database will be located in the <span class="codefrag">{Derby_System_Home}\Databases</span> subdirectory. </dd>
+
+<dt>{Derby_Jars}</dt>
+
+<dd> The location of the derby jarfiles. In this installation the location will be the Tomcat common shared library directory: <span class="codefrag">{Tomcat_Home}/common/lib</span>
+
+</dd>
+
+</dl>
+</div>
+
+<a name="N1006D"></a><a name="Required+Software+%2F+Downloads"></a>
+<h2 class="boxed">Required Software / Downloads</h2>
+<div class="section">
+<ul>
+
+<li>If necessary, install a functional J2SE Java Developers Kit (JDK). Tomcat 5.5.12 requires JDK 5.0 by default. If you will be using an JDK please see the Tomcat documentation for setup information. The JDK 'bin' directory should be included in your PATH.</li>
+
+<li> If necessary, Download and install <a class="external" href="http://tomcat.apache.org/download-55.cgi#5.5.12">Tomcat v 5.5.12</a>. </li>
+
+<li>Download the <a href="../binaries/DerbyJPetStore4Tomcat.zip">DerbyJPetStore4Tomcat.zip</a> file (4.8 Mb) associated with this article. Move the file to the directory {Tomcat_Home}/work.</li>
+
+</ul>
+</div>
+
+<a name="N10088"></a><a name="Setup+of+Application+with+the+Datasource+in+the+Global+Context%3A"></a>
+<h2 class="boxed">Setup of Application with the Datasource in the Global Context:</h2>
+<div class="section">
+<p>The initial steps below walk you through moving the files contained in the DerbyJPetStore4Tomcat.zip file to the locations required to support the deployment instructions that follow. Note that the zipfile contains not only the application system but also the DBMS and the initialized database. No database activity is required other than placing the files in the proper directories. Assuming you have a functioning Tomcat 5.5.12 system already everything you need to create the demo is found in the zipfile associated with this article.</p>
+<p>Subsequent steps show you how to define the JPetStoreDB datasource connection pool in the Global Naming Context. When defined in this way the datasource can be utilized by any application running on the server. Once the datasource required by the application is defined the JPetStore application is deployed and you have a functioning web application. The step-by-step instructions are:</p>
+<ul>
+
+<li>
+
+<strong>Stop Tomcat: </strong>Shutdown Tomcat if it is running.</li>
+
+<li>
+
+<strong>Extract the database zipfile and deployment files: </strong> Unzip the files from DerbyJPetStore4Tomcat.zip into the directory {Tomcat_Home}/work then "install" Derby as follows:
+ <ul>
+
+<li>
+
+<strong>Install the Derby DBMS system:</strong> Move the derby.jar file to the Tomcat 'common' directory {Tomcat_Home}/common/lib.</li>
+
+<li>
+
+<strong>Setup the JPetstore database: </strong>Unzip the database from the DerbyJPetStoreDB.zip file and move the Databases directory tree to {Tomcat_Home}. </li>
+
+</ul>
+
+</li>
+
+<li>
+
+<strong>Define the Global Datasource: </strong>A Global datasource is defined in the server XML configuration file <span class="codefrag">{Tomcat_Home}/conf/server.xml</span>. Save a copy of the current server configuration file then add the following definition to <span class="codefrag">{Tomcat_Home}/conf/server.xml</span>. The location of the definition must be in the Global Naming Resources section of the file. For simplicity locate the end of section marker <span class="codefrag"></GlobalNamingResources></span> and add the following lines just above it: <pre class="code">
+ <!-- Global Datasource for Derby JPetStoreDB database -->
+ <Resource name="jdbc/JPetStoreDB"
+ type="javax.sql.DataSource" auth="Container"
+ description="Derby database for JPetStoreApp"
+ maxActive="100" maxIdle="30" maxWait="10000"
+ username="" password=""
+ driverClassName="org.apache.derby.jdbc.EmbeddedDriver"
+ url="jdbc:derby:Databases/JPetStoreDB"/>
+ </pre>
+
+</li>
+
+<li>
+
+<strong>Start Tomcat and the manager console:</strong> Start Tomcat and open the Manager application in a browser (URL for default installation: http://{machine-name}:8080/manager/html). Supply a valid username and password to access the <span class="codefrag">Tomcat Web Application Manager </span> screen.</li>
+
+<li>
+
+<strong>Deploy the JPetStore application: </strong> Scroll past the application list to the section labeled: <span class="codefrag">
+Deploy directory or WAR file located on server </span> (see Figure 1). Enter the following information:<pre class="code">
+ Context Path (optional): /JPetStoreApp
+ XML Configuration file URL: work/JPetStoreAppGbl.xml
+ WAR or Directory URL: work/JPetStoreApp.war
+ </pre>
+
+<div class="note">
+<div class="label">Figure 1: Tomcat Manager Deployment Screen</div>
+<div class="content">
+
+<img alt="TomcatDeploy" src="../images/TomcatDeploy.gif">
+</div>
+</div>
+ Click the <span class="codefrag">Deploy</span> button to deploy and start the application. Check in the message section for the confirmation of a successful deployment: <span class="codefrag">OK - Deployed application at context path /JPetStoreApp</span>.
+
+ </li>
+
+<li>
+
+<strong>Test the application:</strong> In the <span class="codefrag">Applications</span> list section, click on the application name in the <span class="codefrag">Path</span> column or open the application from a new window with the URL: <span class="codefrag">http://{machine-name}:8080/JPetStoreApp</span>
+
+</li>
+
+</ul>
+</div>
+
+
+<a name="N100F9"></a><a name="Alternate+Setup%3A+Datasource+in+the+Application+Context"></a>
+<h2 class="boxed">Alternate Setup: Datasource in the Application Context</h2>
+<div class="section">
+<p>The datasource connection pool used by the JPetStore application can be defined in the Global context as show above or in the Application context outlined here. Either context will support connections between iBATIS and Derby. The difference between the two setups is whether or not another application deployed to this Tomcat server will be able to access the datasource. When the datasource is defined in the Global context other applications can also connect to the pool by linking to the Global datasource using a copy of the <span class="codefrag">Resource-link</span> definition found in the <span class="codefrag">JPetStoreAppGbl.xml</span> file used in the deployment above. This is the configuration that should be used if, say, a Petstore accounting or reporting application will be deployed in a separate secured context that is available to a limited number of users.
+ </p>
+<p>When setting up a connection pool in the application context all the information about the datasource is provided in the application XML configuration file. Compare this to the Global datasource setup where the definition is in the server XML configuration file <span class="codefrag">server.xml</span> rather than the application XML configuration file. The contents of these two files are all that differs in the following set of steps for recreating the demo using an application context datasource. </p>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">The steps below assume you have performed the previous steps and already have the JPetStore files extracted and the derby.jar and Derby database copied to the proper locations.</div>
+</div>
+<ul>
+
+<li>
+
+<strong>Stop Tomcat: </strong>Shutdown Tomcat if it is running.</li>
+
+<li>
+
+<strong>Replace the server.xml file: </strong>Restore the copy of the original server.xml saved previously or delete the Datasource definitions lines added to the <span class="codefrag">GlobalNamingResources</span> section. No changes to the server.xml file are needed in this configuration.</li>
+
+<li>Extract the database zipfile and deployment files: <em>Already done</em>
+
+<ul>
+
+<li>Install the Derby DBMS system: <em>Already done</em>
+
+</li>
+
+<li>Setup the JPetstore database: <em>Already done</em>
+
+</li>
+
+</ul>
+
+</li>
+
+<li>
+
+<strong>Start Tomcat and the manager console:</strong> Start Tomcat and open the Manager application in a browser (URL for default installation: <span class="codefrag">http://{machine-name}:8080/manager/html</span>). Supply a valid username and password to access the <span class="codefrag">Tomcat Web Application Manager</span> screen.</li>
+
+<li>
+
+<strong>Undeploy the JPetStore application: </strong>The application deployed above is not functional and recorded errors to the logfile when it attempted to start. Click the <span class="codefrag">Undeploy</span> for JPetStoreApp in the application list</li>
+
+<li>
+
+<strong>Deploy the JPetStoreA application: </strong> Scroll past the application list to the section labeled: <span class="codefrag">
+Deploy directory or WAR file located on server</span> (refer to Figure 1). Enter the following information:<pre class="code">
+ Context Path (optional): /JPetStoreAppA
+ XML Configuration file URL: work/JPetStoreAppCntxt.xml
+ WAR or Directory URL: work/JPetStoreApp.war
+ </pre>
+ Click the <span class="codefrag">Deploy</span> button to deploy and start the application. Check in the message section for the confirmation of a successful deployment: <span class="codefrag">OK - Deployed application at context path /JPetStoreAppA</span>.
+ </li>
+
+<li>
+
+<strong>Test the application:</strong> In the <span class="codefrag">Applications</span> list section, click on the application name in the <span class="codefrag">Path</span> column or open the application from a new window with the URL: <span class="codefrag">http://{machine-name}:8080/JPetStoreAppA</span>
+
+</li>
+
+</ul>
+</div>
+
+<a name="N10170"></a><a name="Database+Creation+Instructions+%28optional%29"></a>
+<h2 class="boxed">Database Creation Instructions (optional)</h2>
+<div class="section">
+<p>The following steps show how to build the Derby database from scratch. This is similar to the build procedure required when deploying applications using most other DBMS system except a separate database creation step is not required. Two files (*.sql) are supplied in the zipfile to perform the schema build and data inserts. To use this procedure you will need to download a complete set of Derby jarfiles in order to obtain the IJ scripting tool used in the following commands. The IJ tool is used to process the SQL commands in the provided scripts. The IJ tool is contained in the derbytools.jar file. Place derbytools.jar in the {Derby_Jars} directory. For simplicity the examples below place all necessary files in the same directory and specify as much a possible (including the command to create the database) on the command line.</p>
+<ul>
+
+<li>Copy the following SQL script files to the <span class="codefrag">{Derby_System_Home}\Databases</span> subdirectory where you will build the database: <span class="codefrag">,jpetstore-derby-schema.sql, jpetstore-derby-dataload.sql</span>. Issue the following command to create the database, tables and indexes:
+ <pre class="code">
+ java -cp {Derby_Jars}/derby.jar:{Derby_Jars}/derbytools.jar \
+ -Dderby.system.home={Derby_System_Home}\Databases \
+ -Dij.database=jdbc:derby:JPetStoreDB;create=true \
+ org.apache.derby.tools.ij jpetstore-derby-schema.sql
+ </pre>
+
+</li>
+
+<li>Now load the data into the tables using the following command:
+ <div class="note">
+<div class="label">Note</div>
+<div class="content">If you are performing the build on a Windows based OS change the classpath separator between the jarfile names for a colon (:) to a semicolon (;) in the following commands:
+ e.g. java -cp {Derby_Jars}/derby.jar;{Derby_Jars}/derbytools.jar...</div>
+</div>
+
+<pre class="code">
+ java -cp {Derby_Jars}/derby.jar:{Derby_Jars}/derbytools.jar \
+ -Dderby.system.home={Derby_System_Home}\Databases \
+ -Dij.database=jdbc:derby:JPetStoreDB \
+ org.apache.derby.tools.ij jpetstore-derby-dataload.sql
+ </pre>
+
+</li>
+
+</ul>
+<p>You now have a fully populated database to use with the JPetStore application.</p>
+</div>
+ <!-- Integration Notes Section -->
+
+<a name="N10199"></a><a name="General+Integration+Notes"></a>
+<h2 class="boxed">General Integration Notes</h2>
+<div class="section">
+<p>
+J2EE Servers use multiple classloaders (aka hierarchies) to provide the isolation necessary to run many applications at once. This Derby-JPetStore integration uses a Server defined datasource to avoid problems that can occur when Derby is used in an environment that has multiple classloaders. Derby is written in Java and all its classes must be loaded by the same classloader. When using a J2EE Server this can be assured by defining Derby datasources at the server level. This is particularly important when using Derby in it's embedded configuration. When using a database or other datasource in a J2EE environment it is also a good design practice to access them via a J2EE resource managed by the server.
+ </p>
+<p>
+ The zipfile provided contains a fully initialized database to demonstrate that a Derby database built and populated on one platform (in this case Windows) can be transferred to different platforms and work fine. Try copying the database and derby jarfiles to different platforms and you will see that the system works without modification. The text files included in the zipfile will not do well in an EBCDIC architecture but the Derby engine and supplied database will work fine. If you want to build the database from scratch you can use the SQL files supplied in the archive. See the 'Optional Database Setup Instructions' section for how to use the IJ tools to build and populate the database.</p>
+</div>
+
+
+<a name="N101A6"></a><a name="Tomcat+Integration+Notes"></a>
+<h2 class="boxed">Tomcat Integration Notes</h2>
+<div class="section">
+<p>Tomcat is designed so that new java components (a.k.a. shared libraries) can be easily added to the system. This is accomplished by adding the jarfiles containing the components to the $CATALINA_HOME/common/lib directory.
+ Derby is designed to be used in just this manner. The Derby manuals refer to this as embedding. Embedding makes Derby just another component available to the applications deployed on Tomcat. Adding the derby.jar file to the common shared libraries directory makes the Derby engine, not just the JDBC driver, available. No separate steps are required to install, configure or start the Derby engine.</p>
+<p>The default Session Manager (<span class="codefrag">org.apache.catalina.session.StandardManager</span>) created for each application context (a.k.a. web application) enables <a class="external" href="http://tomcat.apache.org/tomcat-5.5-doc/config/manager.html#Restart Persistence">Restart persistence</a>. This feature is disabled in the JPetStore XML configuration files to avoid the problem where the JNDI context <span class="codefrag">java:comp</span> is not accessible when the iBATIS Dao Transaction Pool is restarted. This problem is typified by startup messages in the <span class="codefrag">catalina.log</span> file containing the following error text: </p>
+<pre class="code">org.apache.catalina.session.StandardManager start
+SEVERE: Exception loading sessions from persistent storage
+java.lang.ExceptionInInitializerError
+ at com.ibatis.jpetstore.service.CatalogService.<nit>(CatalogService.java:23)
+ <em>--- rest of trace removed --</em>
+ Caused by: java.lang.RuntimeException:
+ Could not initialize DaoConfig.
+ Cause: com.ibatis.dao.client.DaoException:
+ Error while configuring DaoManager.
+ Cause: com.ibatis.sqlmap.client.SqlMapException:
+ There was an error while building the SqlMap instance.
+ <em> -- messages removed --</em>
+ --- Cause: com.ibatis.sqlmap.client.SqlMapException:
+ There was an error configuring JndiDataSourceDaoTransactionPool.
+ Cause: javax.naming.NameNotFoundException:
+ Name java:comp is not bound in this Context </pre>
+<div class="note">
+<div class="label">Disabling Restart Persistence</div>
+<div class="content">The following line in the application XML configuration file sets the persistence file to an empty string and disables Restart Persistence for the application: <span class="codefrag"> <Manager pathname=""/> </span>
+</div>
+</div>
+</div>
+
+<a name="N101D0"></a><a name="iBATIS+Integration+Notes"></a>
+<h2 class="boxed">iBATIS Integration Notes</h2>
+<div class="section">
+<p>If you wish to build your own iBATIS JPetstore war file like the one supplied in the zipfile file you will need to download the JPetStore application source code (see the 'Related Links' section) and make the following modifications to the source files before performing a build as described in the JPetStore build instructions: </p>
+<ul>
+
+<li>
+ Edit the <span class="codefrag">sql-map-config.xml</span> file and replace the existing TransactionManager definition section with the this section that specifies a JNDI lookup should be performed to obtain the datasource to use:
+ <pre class="code">
+ <transactionManager type="JDBC" >
+ <dataSource type="JNDI">
+ <property name="DBJndiContext" value="jdbc/JPetStoreDB"/>
+ </dataSource>
+ </transactionManager>
+ </pre>
+
+</li>
+
+<li>Edit the <span class="codefrag">web.xml</span> file and replace the existing resource-ref definition with the following:
+ <pre class="code">
+ <resource-ref>
+ <description>JPetStore DataSource</description>
+ <res-ref-name>jdbc/JPetStoreDB</res-ref-name>
+ <res-type>javax.sql.DataSource</res-type>
+ <res-auth>Container</res-auth>
+ <res-sharing-scope>Shareable</res-sharing-scope>
+ </resource-ref>
+ </pre>
+
+</li>
+
+</ul>
+</div>
+ <!-- RELATED LINKS SECTION -->
+
+<a name="N101F3"></a><a name="Rlinks"></a>
+<h2 class="boxed">Links Section</h2>
+<div class="section">
+<p>Required Downloads to perform this deployment: </p>
+<ul>
+
+<li>
+
+<a href="../binaries/DerbyJPetStore4Tomcat.zip">DerbyJPetStore4Tomcat.zip</a>
+
+</li>
+
+<li>
+
+<a class="external" href="http://tomcat.apache.org/download-55.cgi#5.5.12">Tomcat v 5.5.12</a>
+
+</li>
+
+</ul>
+<p>Download links for software used in creating this deployment:</p>
+<ul>
+
+<li>
+
+<a href="http://db.apache.org/derby/releases/release-10.0.2.1.html">Apache Derby version 10.0.2.1</a> [Note: the *-bin archives contain the documentation as well as Derby].
+ </li>
+
+<li>
+
+<a class="external" href="http://prdownloads.sourceforge.net/ibatisjpetstore/iBATIS_JPetStore-4.0.5.zip?download">iBATIS JPetStore version 4.0.5</a>
+
+</li>
+
+</ul>
+<p>Learn more:</p>
+<ul>
+
+<li> The <a href="http://db.apache.org/derby/index.html">Apache Derby Project</a> homepage.
+ </li>
+
+<li> The <a class="external" href="http://ibatis.apache.org">Apache iBATIS Project</a> homepage.
+ </li>
+
+<li>The <a class="external" href="http://tomcat.apache.org">Apache Tomcat Project</a> homepage
+ </li>
+
+<li> The developerWorks Derby / IBM Cloudscape <a class="external" href="http://www.ibm.com/developerworks/views/db2/libraryview.jsp?product_by=IBM+Cloudscape">Technical Library</a>
+</li>
+
+<li>Apache Derby <a href="http://db.apache.org/derby/papers/">White Papers</a>
+</li>
+
+</ul>
+<p>Related articles:</p>
+<ul>
+
+<li>The Derby difference: <a class="external" href="http://www.ibm.com/developerworks/db2/library/techarticle/dm-0509bradbury/">Using Derby with J2EE Servers</a>
+
+</li>
+
+<li>Derby WebSphere deployment of JPetStore <a href="JPetStoreWebSphere.html">Using Derby with WebSphere to implement iBATIS JPetStore</a>
+
+</li>
+
+<li>Derby Geronimo deployment of JPetStore <a href="JPetStoreGeronimo.html">Using Derby with Geronimo to implement iBATIS JPetStore</a>
+
+</li>
+
+</ul>
+<p>
+ Stan Bradbury wrote these instructions.
+ Please post any questions about them
+ to <a href="../derby_mail.html">derby-user@db.apache.org</a>.
+ </p>
+</div>
+
+</div>
+<!--+
+ |end content
+ +-->
+<div class="clearboth"> </div>
+</div>
+<div id="footer">
+<!--+
+ |start bottomstrip
+ +-->
+<div class="lastmodified">
+<script type="text/javascript"><!--
+document.write("Last Published: " + document.lastModified);
+// --></script>
+</div>
+<div class="copyright">
+ Copyright ©
+ 2004-2012 Apache Software Foundation</div>
+<div id="feedback">
+ Send feedback about the website to:
+ <a id="feedbackto" href="mailto:derby-user@db.apache.org?subject=Feedback%C2%A0integrate/DerbyTomcat5512JPetStor.html">derby-user@db.apache.org</a>
+</div>
+<!--+
+ |end bottomstrip
+ +-->
+</div>
+</body>
+</html>
Added: websites/production/db/content/derby/integrate/JPOX_Derby.html
==============================================================================
--- websites/production/db/content/derby/integrate/JPOX_Derby.html (added)
+++ websites/production/db/content/derby/integrate/JPOX_Derby.html Wed Dec 19 18:20:21 2012
@@ -0,0 +1,1317 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta content="Apache Forrest" name="Generator">
+<meta name="Forrest-version" content="0.8">
+<meta name="Forrest-skin-name" content="pelt">
+<title>Using JPOX JDO with Derby</title>
+<link type="text/css" href="../skin/basic.css" rel="stylesheet">
+<link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet">
+<link media="print" type="text/css" href="../skin/print.css" rel="stylesheet">
+<link type="text/css" href="../skin/profile.css" rel="stylesheet">
+<script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script>
+<link rel="shortcut icon" href="../">
+</head>
+<body onload="init()">
+<script type="text/javascript">ndeSetTextSize();</script>
+<div id="top">
+<!--+
+ |breadtrail
+ +-->
+<div class="breadtrail">
+<a href="http://www.apache.org/">apache</a> > <a href="http://db.apache.org/">db</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+<!--+
+ |header
+ +-->
+<div class="header">
+<!--+
+ |start group logo
+ +-->
+<div class="grouplogo">
+<a href="http://db.apache.org/derby"><img class="logoImage" alt="Apache Derby" src="../images/derby-logo-web.png" title="Derby is a zero-admin Java RDBMS"></a>
+</div>
+<!--+
+ |end group logo
+ +-->
+<!--+
+ |start Project Logo
+ +-->
+<div class="projectlogoA1">
+<a href="http://db.apache.org"><img class="logoImage" alt="Apache DB Project" src="../images/db-logo-white.png" title="Apache DB creates and maintains database solutions."></a>
+</div>
+<!--+
+ |end Project Logo
+ +-->
+<!--+
+ |start Tabs
+ +-->
+<ul id="tabs">
+<li>
+<a class="unselected" href="../index.html">Home</a>
+</li>
+<li>
+<a class="unselected" href="../quick_start.html">Quick Start</a>
+</li>
+<li>
+<a class="unselected" href="../derby_downloads.html">Download</a>
+</li>
+<li>
+<a class="unselected" href="../derby_comm.html">Community</a>
+</li>
+<li>
+<a class="unselected" href="../manuals/index.html">Documentation</a>
+</li>
+<li class="current">
+<a class="selected" href="../blogs/index.html">Resources</a>
+</li>
+</ul>
+<!--+
+ |end Tabs
+ +-->
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<!--+
+ |start Subtabs
+ +-->
+<div id="level2tabs"></div>
+<!--+
+ |end Endtabs
+ +-->
+<script type="text/javascript"><!--
+document.write("Last Published: " + document.lastModified);
+// --></script>
+</div>
+<!--+
+ |breadtrail
+ +-->
+<div class="breadtrail">
+
+
+ </div>
+<!--+
+ |start Menu, mainarea
+ +-->
+<!--+
+ |start Menu
+ +-->
+<div id="menu">
+<div onclick="SwitchMenu('menu_1.1', '../skin/')" id="menu_1.1Title" class="menutitle">Blogs and Articles About Derby</div>
+<div id="menu_1.1" class="menuitemgroup">
+<div class="menuitem">
+<a href="../blogs/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../blogs/index.html#blogs">Blogs</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3', '../skin/')" id="menu_1.1.3Title" class="menutitle">Articles</div>
+<div id="menu_1.1.3" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.1.3.1', '../skin/')" id="menu_1.1.3.1Title" class="menutitle">Tutorials, Tips and Tuning</div>
+<div id="menu_1.1.3.1" class="menuitemgroup">
+<div class="menuitem">
+<a href="../blogs/index.html#getstarted">Getting Started</a>
+</div>
+<div class="menuitem">
+<a href="../blogs/index.html#features">Features, Hints and Tips</a>
+</div>
+<div class="menuitem">
+<a href="../blogs/index.html#security">Security</a>
+</div>
+<div class="menuitem">
+<a href="../blogs/index.html#performance">Performance and Tuning</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.2', '../skin/')" id="menu_1.1.3.2Title" class="menutitle">Tools and Migration</div>
+<div id="menu_1.1.3.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../blogs/index.html#tools">Tools</a>
+</div>
+<div class="menuitem">
+<a href="../blogs/index.html#migration">Migration</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.3', '../skin/')" id="menu_1.1.3.3Title" class="menutitle">Applications</div>
+<div id="menu_1.1.3.3" class="menuitemgroup">
+<div class="menuitem">
+<a href="../blogs/index.html#client">Client</a>
+</div>
+<div class="menuitem">
+<a href="../blogs/index.html#middletier">Middle Tier</a>
+</div>
+<div class="menuitem">
+<a href="../blogs/index.html#persistence">Persistence</a>
+</div>
+<div class="menuitem">
+<a href="../blogs/index.html#scalability">Scalability and Failover</a>
+</div>
+</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.2', '../skin/')" id="menu_1.2Title" class="menutitle">Integration With Other Products</div>
+<div id="menu_1.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../integrate/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../integrate/index.html#uses">What works with Derby?</a>
+</div>
+<div class="menuitem">
+<a href="../integrate/index.html#products">Product Writeups</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.3', '../skin/')" id="menu_1.3Title" class="menutitle">Eclipse Plug-ins</div>
+<div id="menu_1.3" class="menuitemgroup">
+<div class="menuitem">
+<a href="../integrate/derby_plugin_info.html">Info</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.4', '../skin/')" id="menu_1.4Title" class="menutitle">Papers and Presentations</div>
+<div id="menu_1.4" class="menuitemgroup">
+<div class="menuitem">
+<a href="../papers/index.html">Overview</a>
+</div>
+<div onclick="SwitchMenu('menu_1.4.2', '../skin/')" id="menu_1.4.2Title" class="menutitle">Derby Engine</div>
+<div id="menu_1.4.2" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.4.2.1', '../skin/')" id="menu_1.4.2.1Title" class="menutitle">Javadoc</div>
+<div id="menu_1.4.2.1" class="menuitemgroup">
+<div class="menuitem">
+<a href="http://db.apache.org/derby/javadoc/engine">Engine</a>
+</div>
+<div class="menuitem">
+<a href="http://db.apache.org/derby/javadoc/language">Language</a>
+</div>
+<div class="menuitem">
+<a href="http://db.apache.org/derby/javadoc/tools">Tools</a>
+</div>
+<div class="menuitem">
+<a href="http://db.apache.org/derby/javadoc/publishedapi">API</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../papers/derby_arch.html">Architecture</a>
+</div>
+<div class="menuitem">
+<a href="../papers/btree_package.html">BTree</a>
+</div>
+<div class="menuitem">
+<a href="../papers/pageformats.html">Disk Page Format</a>
+</div>
+<div class="menuitem">
+<a href="../papers/derby_htw.html">How Things Work</a>
+</div>
+<div class="menuitem">
+<a href="../papers/Intersect-design.html">Intersect & Except</a>
+</div>
+<div class="menuitem">
+<a href="../papers/JDBCImplementation.html">JDBC</a>
+</div>
+<div class="menuitem">
+<a href="../papers/logformats.html">Log Format</a>
+</div>
+<div class="menuitem">
+<a href="../papers/recovery.html">Logging & Recovery</a>
+</div>
+<div class="menuitem">
+<a href="../papers/optimizer.html">Optimizer</a>
+</div>
+<div class="menuitem">
+<a href="http://db.apache.org/derby/javadoc/engine/org/apache/derby/iapi/types/package-summary.html#package_description">Type System</a>
+</div>
+<div class="menuitem">
+<a href="../papers/versionupgrade.html">Versioning</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.4.3', '../skin/')" id="menu_1.4.3Title" class="menutitle">Derby Network Client</div>
+<div id="menu_1.4.3" class="menuitemgroup">
+<div class="menuitem">
+<a href="../papers/DerbyClientSpec.html">Functional Spec</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.4.4', '../skin/')" id="menu_1.4.4Title" class="menutitle">Derby Tutorial</div>
+<div id="menu_1.4.4" class="menuitemgroup">
+<div class="menuitem">
+<a href="../papers/DerbyTut/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../papers/DerbyTut/install_software.html">Step 1: Install Software</a>
+</div>
+<div class="menuitem">
+<a href="../papers/DerbyTut/ij_intro.html">Step 2: ij Basics</a>
+</div>
+<div class="menuitem">
+<a href="../papers/DerbyTut/embedded_intro.html">Step 3: Embedded Derby</a>
+</div>
+<div class="menuitem">
+<a href="../papers/DerbyTut/ns_intro.html">Step 4: Derby Network Server</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.4.5', '../skin/')" id="menu_1.4.5Title" class="menutitle">Presentations</div>
+<div id="menu_1.4.5" class="menuitemgroup">
+<div class="menuitem">
+<a href="../papers/ApacheCon.html">ApacheCon</a>
+</div>
+<div class="menuitem">
+<a href="../papers/MiscPresentations.html#Victorian+Java+User+Group">Victorian JUG 2008</a>
+</div>
+<div class="menuitem">
+<a href="../papers/MiscPresentations.html#OSCON+2005">OSCON 2005</a>
+</div>
+<div class="menuitem">
+<a href="../papers/MiscPresentations.html#Colorado+Software+Summit+2004">Colorado 2004</a>
+</div>
+</div>
+</div>
+<!--+
+ |start Search
+ +-->
+<div class="searchbox">
+<hr>
+<form action="http://www.google.com/search" method="get">
+<input value="db.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="18" name="q" id="query" type="text" value="Search the site with google">
+ <input name="Search" value="Search" type="submit">
+</form>
+</div>
+<!--+
+ |end search
+ +-->
+<div id="credit"></div>
+<div id="roundbottom">
+<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
+<!--+
+ |alternative credits
+ +-->
+<div id="credit2"></div>
+</div>
+<!--+
+ |end Menu
+ +-->
+<!--+
+ |start content
+ +-->
+<div id="content">
+<div class="trail">Font size:
+ <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
+ <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+ <input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
+</div>
+<h1>Using JPOX JDO with Derby</h1>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#Overview">Overview</a>
+</li>
+<li>
+<a href="#Step+1.+Prerequisites">Step 1. Prerequisites</a>
+</li>
+<li>
+<a href="#Step+2.+Download+sample+code+and+configuration+files">Step 2. Download sample code and configuration files</a>
+</li>
+<li>
+<a href="#Step+3.+Examine%2FCreate+the+Database+schema">Step 3. Examine/Create the Database schema</a>
+</li>
+<li>
+<a href="#Step+4.+Write+the+classes+used+to+persist+the+data">Step 4. Write the classes used to persist the data</a>
+</li>
+<li>
+<a href="#Step+5.++Create+the+JDO+meta-data+mapping+file">Step 5. Create the JDO meta-data mapping file</a>
+</li>
+<li>
+<a href="#Step+6.+Create+a+log4j.properties+file+to+be+used+by+JPOX">Step 6. Create a log4j.properties file to be used by JPOX</a>
+</li>
+<li>
+<a href="#Step+7.+Enhancing+the+JPOX+classes">Step 7. Enhancing the JPOX classes</a>
+</li>
+<li>
+<a href="#Step+8.+Code+the+class+which+makes+the+JPOX+JDO+queries">Step 8. Code the class which makes the JPOX JDO queries</a>
+</li>
+<li>
+<a href="#Step+9.+Code+the+application+class+which+calls+the+business+logic+class">Step 9. Code the application class which calls the business logic class</a>
+</li>
+<li>
+<a href="#Step+10.+Compile+all+classes%2C+enhance+the+persistence+capable+ones+and+run+the+application">Step 10. Compile all classes, enhance the persistence capable ones and run the application</a>
+</li>
+<li>
+<a href="#Resources+and+Acknowledgements">Resources and Acknowledgements</a>
+</li>
+</ul>
+</div>
+
+
+<a name="N1000D"></a><a name="Overview"></a>
+<h2 class="boxed">Overview</h2>
+<div class="section">
+<p>
+This paper gives a concrete example of using JPOX JDO to persist and retrieve
+data to and from Apache Derby. Java Data Objects (JDO) is a specification for
+persisting Java objects. JPOX JDO 1.1 is the reference implementation for the
+JDO 2.0 specification. The JDO 2.0 API is provided by the Apache JDO project
+and is required to run JPOX JDO 1.1. The JDO 2.0 API conforms to the JDO 2.0
+specification.
+</p>
+<p>Apache Derby, a subproject of the Apache DB project, is a standards compliant database, written and implemented entirely in Java. </p>
+<p>The steps below show how to use the bottom-up approach to designing an
+application which persists Derby data using JPOX Java Data Objects. The
+bottom-up approach means the database schema has already been defined. We
+will need to provide an object to relational mapping file and the Java
+classes (objects) which will be made persistence capable.
+(The alternate approach, called top-down, is to define the Java classes
+and then generate the database schema based on the mapping file between
+database and object classes.)
+</p>
+<p>
+The section, <em>Download sample code and configuration files</em>, contains a
+zip file which includes a populated Derby database and SQL to create the
+database schema (if desired), Java source files, the JPOX JDO meta-data file
+and the application classes to issue the JPOX queries. This is not a detailed
+explanation of either JPOX or Derby, but should be used as a "cookbook" on how
+to use the two together.
+</p>
+</div>
+
+
+<a name="N10023"></a><a name="Step+1.+Prerequisites"></a>
+<h2 class="boxed">Step 1. Prerequisites</h2>
+<div class="section">
+<p>
+The following software needs to be downloaded and installed prior to using the
+source files provided in the download zip file, <span class="codefrag">jpox_derby.zip</span>.
+</p>
+<table class="ForrestTable" cellspacing="1" cellpadding="4">
+
+<tr>
+
+<th colspan="1" rowspan="1">Software</th>
+<th colspan="1" rowspan="1">Minimum Release Level Required</th>
+<th colspan="1" rowspan="1">Release Used in this Example</th>
+<th colspan="1" rowspan="1">Download Location</th>
+
+</tr>
+
+<tr>
+
+<td colspan="1" rowspan="1">Java JDK or SDK</td>
+<td colspan="1" rowspan="1">1.4.2</td>
+<td colspan="1" rowspan="1">1.4.2</td>
+<td colspan="1" rowspan="1">Sun or IBM</td>
+
+</tr>
+
+<tr>
+
+<td colspan="1" rowspan="1">Apache Derby</td>
+<td colspan="1" rowspan="1">10.1</td>
+<td colspan="1" rowspan="1">10.1.2</td>
+<td colspan="1" rowspan="1"><a href="http://db.apache.org/derby/derby_downloads.html">Apache Derby</a></td>
+
+</tr>
+
+<tr>
+
+<td colspan="1" rowspan="1">Apache JDO</td>
+<td colspan="1" rowspan="1">2.0-snapshot7.jar</td>
+<td colspan="1" rowspan="1">2.0-rc1</td>
+<td colspan="1" rowspan="1"><a href="http://db.apache.org/jdo/releases/release-2.0-rc1.cgi">Apache JDO, 2.0 RC1</a></td>
+
+</tr>
+
+<tr>
+
+<td colspan="1" rowspan="1">JPOX JDO "Core"</td>
+<td colspan="1" rowspan="1">1.1.0-beta 5</td>
+<td colspan="1" rowspan="1">1.1.0-rc-1</td>
+<td colspan="1" rowspan="1">JPOX "core" <a class="external" href="http://www.jpox.org/docs/download.html">jpox.org</a></td>
+
+</tr>
+
+<tr>
+
+<td colspan="1" rowspan="1">JPOX JDO Enhancer</td>
+<td colspan="1" rowspan="1">1.1.0-beta 5</td>
+<td colspan="1" rowspan="1">1.1.0-rc-1</td>
+<td colspan="1" rowspan="1">JPOX Enhancer <a class="external" href="http://www.jpox.org/docs/download.html">jpox.org</a></td>
+
+</tr>
+
+<tr>
+
+<td colspan="1" rowspan="1">Apache Jakarta Byte Code Engineering Library (BCEL)</td>
+<td colspan="1" rowspan="1">5.1</td>
+<td colspan="1" rowspan="1">5.1</td>
+<td colspan="1" rowspan="1"><a class="external" href="http://jakarta.apache.org/site/downloads/downloads_bcel.cgi/">BCEL</a>(Used by JPOX during the enhancement of the Java classes.)</td>
+
+</tr>
+
+<tr>
+
+<td colspan="1" rowspan="1">Apache Log4j</td>
+<td colspan="1" rowspan="1">1.2.8</td>
+<td colspan="1" rowspan="1">1.2.12</td>
+<td colspan="1" rowspan="1"><a class="external" href="http://logging.apache.org/site/binindex.cgi">Apache Log4j</a></td>
+
+</tr>
+
+</table>
+</div>
+
+
+<a name="N100F9"></a><a name="Step+2.+Download+sample+code+and+configuration+files"></a>
+<h2 class="boxed">Step 2. Download sample code and configuration files</h2>
+<div class="section">
+<p>
+This paper will list each step required to get the sample application up and running, including partial code listings. However, to get the most
+out of this paper download the file, <a href="../binaries/jpox_derby.zip">jpox_derby.zip</a> to follow along with each step or to view the entire source and configuration files.
+</p>
+<p>
+After downloading the <span class="codefrag">jpox_derby.zip</span> file unzip it to a
+convenient directory. The examples that follow assume it was unzipped
+to the C:/ directory on a windows machine.
+</p>
+</div>
+
+
+<a name="N1010D"></a><a name="Step+3.+Examine%2FCreate+the+Database+schema"></a>
+<h2 class="boxed">Step 3. Examine/Create the Database schema</h2>
+<div class="section">
+<p>
+As mentioned above, using the bottom-up approach means we need to
+define our database schema first. The schema shown below consists of five tables for a simple airlines reservation system. The data directory
+contained in the zip file contains the airlinesDB already populated
+with these tables and data. However, if you would like to run the SQL
+at a later time to create the database, the airlinesDB.sql file contained
+in the zip file can be used to do so.
+</p>
+<p>
+<strong>SQL for Derby database tables</strong>
+</p>
+<p class="code-block">CREATE TABLE APP.CITIES
+(
+CITY_ID INTEGER NOT NULL CONSTRAINT cities_pk PRIMARY KEY,
+CITY_NAME VARCHAR(24) NOT NULL,
+COUNTRY VARCHAR(26) NOT NULL,
+AIRPORT CHAR(3),
+LANGUAGE VARCHAR(16),
+COUNTRY_ISO_CODE CHAR(2)
+);
+
+CREATE TABLE APP.FLIGHTS
+(
+FLIGHT_ID CHAR(6) NOT NULL,
+SEGMENT_NUMBER INTEGER NOT NULL,
+ORIG_AIRPORT CHAR(3),
+DEPART_TIME TIME,
+DEST_AIRPORT CHAR(3),
+ARRIVE_TIME TIME,
+MEAL CHAR(1) CONSTRAINT MEAL_CONSTRAINT
+CHECK (meal IN ('B', 'L', 'D', 'S')),
+FLYING_TIME DOUBLE PRECISION,
+MILES INTEGER,
+AIRCRAFT VARCHAR(6),
+DEPART_DATE DATE,
+CONSTRAINT FLIGHTS_PK Primary Key (FLIGHT_ID)
+);
+
+CREATE INDEX DESTINDEX ON APP.FLIGHTS (DEST_AIRPORT) ;
+
+CREATE INDEX ORIGINDEX ON APP.FLIGHTS (ORIG_AIRPORT) ;
+
+CREATE TABLE APP.USERS
+(
+FIRSTNAME VARCHAR(40) NOT NULL,
+LASTNAME VARCHAR (40) NOT NULL,
+USERNAME VARCHAR(20) NOT NULL CONSTRAINT username_pk PRIMARY KEY,
+PASSWORD VARCHAR(20) NOT NULL,
+PASSWORD_VERIFY VARCHAR(20),
+EMAIL VARCHAR(30) NOT NULL
+);
+
+CREATE TABLE APP.USER_CREDIT_CARD
+(
+ID INT NOT NULL GENERATED ALWAYS AS IDENTITY CONSTRAINT user_cc_pk PRIMARY KEY,
+USERNAME varchar(20) NOT NULL,
+LASTNAME varchar(40),
+CREDIT_CARD_TYPE varchar(15) NOT NULL,
+CREDIT_CARD_NUMBER varchar(20) NOT NULL,
+CREDIT_CARD_DISPLAY varchar(25) NOT NULL
+);
+
+ALTER TABLE APP.USER_CREDIT_CARD ADD CONSTRAINT USERNAME_FK
+Foreign Key (username) REFERENCES APP.USERS (username);
+
+CREATE TABLE APP.FLIGHTHISTORY
+(
+ID INT NOT NULL GENERATED ALWAYS AS IDENTITY CONSTRAINT user_fh_pk PRIMARY KEY,
+USERNAME VARCHAR(20) NOT NULL,
+FLIGHT_ID CHAR(6) NOT NULL,
+ORIG_AIRPORT CHAR(3) NOT NULL,
+DEST_AIRPORT CHAR(3) NOT NULL,
+MILES INTEGER,
+AIRCRAFT VARCHAR(6),
+DEPARTURE_DATE VARCHAR(25),
+CREDIT_CARD_TYPE varchar(15) NOT NULL,
+CREDIT_CARD_DISPLAY varchar(25) NOT NULL
+);
+
+ALTER TABLE APP.FLIGHTHISTORY ADD CONSTRAINT USERNAME_FH_FK
+Foreign Key (username) REFERENCES APP.USERS (username);
+</p>
+</div>
+
+
+<a name="N1011F"></a><a name="Step+4.+Write+the+classes+used+to+persist+the+data"></a>
+<h2 class="boxed">Step 4. Write the classes used to persist the data</h2>
+<div class="section">
+<p>
+Once you have created the database schema you will need to code one class for
+each corresponding database table you want to persist using JPOX. The Java
+class needs to consist of setters and getters with a default constructor to
+match the database table.
+</p>
+<p>
+Here's the class that corresponds to the APP.CITIES table above. The only
+constraint on the Java class to be persisted is it must have a default
+constructor, which can be private if you want it to be. The source code for all five java classes that correspond to the database schema shown above is in
+<span class="codefrag">jpox_derby.zip</span>.
+</p>
+<p>
+<strong>Partial listing of CityBean.Java</strong>
+</p>
+<p class="code-block">
+public class CityBean {
+
+ private int cityId;
+
+ private String cityName;
+
+ private String country;
+
+ private String airport;
+
+ private String language;
+
+ private String countryCode;
+
+ public CityBean() {
+ cityId = 0;
+ cityName = "";
+ country = "";
+ airport = "";
+ language = "";
+ countryCode = "";
+ }
+
+ public CityBean(int city_id, String city, String ctry, String air) {
+ cityId = city_id;
+ cityName = city;
+ country = ctry;
+ airport = air;
+ }
+
+ public CityBean(int cityId, String cityName, String country,
+ String airport, String language, String countryCode) {
+ this.cityId = cityId;
+ this.cityName = cityName;
+ this.country = country;
+ this.airport = airport;
+ this.language = language;
+ this.countryCode = countryCode;
+ }
+
+ public String getAirport() {
+ return airport;
+ }
+
+ public void setAirport(String airport) {
+ this.airport = airport;
+ }
+
+ // create getters and setters for all other member variables
+
+ ...
+
+}
+</p>
+</div>
+
+
+<a name="N10137"></a><a name="Step+5.++Create+the+JDO+meta-data+mapping+file"></a>
+<h2 class="boxed">Step 5. Create the JDO meta-data mapping file</h2>
+<div class="section">
+<p>
+By convention this file is usually referred to as <span class="codefrag">package.jdo</span>.
+Take a look at the partial listing of the <span class="codefrag">package.jdo</span> file I am using to map
+the Derby database tables to the Java classes. (The full package.jdo is available in the download.)
+</p>
+<p>
+<strong>Partial listing of package.jdo</strong>
+</p>
+<p class="code-block">
+
+<?xml version="1.0"?>
+<!DOCTYPE jdo PUBLIC "-//Sun Microsystems, Inc.//DTD Java Data Objects
+Metadata 2.0//EN" "http://java.sun.com/dtd/jdo_2_0.dtd">
+ <jdo>
+ <package name="org.apache.derby.demo.beans.view">
+ <class name="CityBean" identity-type="application" table="CITIES">
+ <field name="cityId" primary-key="true">
+ <column name="CITY_ID" jdbc-type="INTEGER"/>
+ </field>
+ <field name="cityName">
+ <column name="CITY_NAME" length="24" jdbc-type="VARCHAR"/>
+ </field>
+ <field name="country">
+ <column name="COUNTRY" length="26" jdbc-type="VARCHAR"></column>
+ </field>
+ <field name="airport">
+ <column name="AIRPORT" length="3" jdbc-type="CHAR" allows-null="">
+ </column>
+ </field>
+ <field name="language">
+ <column name="LANGUAGE" length="16" jdbc-type="VARCHAR" allows-null="">
+ </column>
+ </field>
+ <field name="countryCode">
+ <column name="COUNTRY_ISO_CODE" length="2" jdbc-type="CHAR" allows-null="">
+ </column>
+ </field>
+ </class>
+ <class name="FlightsBean" identity-type="application" table="FLIGHTS">
+ <field name="flightId" primary-key="true">
+
+ ...
+
+ <class name="FlightHistoryBean" identity-type="application"
+ table="FLIGHTHISTORY" detachable="true">
+ <field name="id" primary-key="true" value-strategy="autoassign">
+ <column name="id" jdbc-type="INTEGER"/>
+ </field>
+
+ ...
+
+ </class>
+ </package>
+ <package name="org.apache.derby.demo.beans.model">
+ <class name="UserBean" identity-type="application" table="USERS"
+ detachable="true">
+
+ ...
+
+ <class name="UserCreditCardBean" identity-type="application"
+ table="USER_CREDIT_CARD">
+
+ ...
+
+ </class>
+ </package>
+ </jdo>
+</p>
+<p>
+The package name refers to the package of the Java class, the class
+to the Java Class and the table attribute in the class element is the
+name of the database table. Some of the interesting things to note
+are the use of primary keys and the autoassign attribute for the
+FlightHistoryBean (FlightHistory table). Here is the section showing
+the FlightHistoryBean to FlightHistory table mapping:
+</p>
+<p class="code-block">
+ <class name="FlightHistoryBean" identity-type="application"
+ table="FLIGHTHISTORY" detachable="true">
+ <field name="id" primary-key="true" value-strategy="autoassign">
+ <column name="id" jdbc-type="INTEGER"/>
+ </field>
+</p>
+<p>
+Referring back to the first part of the create table statement of the FlightHistory table above:
+</p>
+<p class="code-block">
+CREATE TABLE APP.FLIGHTHISTORY
+(
+id int not null generated always as identity constraint user_fh_pk primary key,
+USERNAME VARCHAR(20) NOT NULL,
+...
+</p>
+<p>
+notice how the id column is the primary key which is generated as an identity
+column. To map this to the persistence class the value-strategy must be
+autoassign.
+</p>
+<p>
+This meta-data file, <span class="codefrag">package.jdo</span>, needs to be at a level in the
+source tree that includes all classes it references. For instance, the
+<span class="codefrag">package.jdo</span> below references classes in the <span class="codefrag">org.apache.derby.demo.beans.view</span> and <span class="codefrag">org.apache.derby.demo.beans.model</span>
+packages, so the <span class="codefrag">package.jdo</span> file would need to be at the level
+of <span class="codefrag">org.apache.derby.demo.beans</span> to ensure that it can have
+access to the <span class="codefrag">view</span> and <span class="codefrag">model</span> packages below the
+beans package.
+</p>
+<p>
+For this reason I just put my <span class="codefrag">package.jdo</span> at the top level of all
+of the packages I'm using.
+</p>
+</div>
+
+
+<a name="N10181"></a><a name="Step+6.+Create+a+log4j.properties+file+to+be+used+by+JPOX"></a>
+<h2 class="boxed">Step 6. Create a log4j.properties file to be used by JPOX</h2>
+<div class="section">
+<p>
+JPOX uses Apache Log4j to report output and errors. Therefore a
+<span class="codefrag">log4j.properties</span> file is required. A sample one is shown below which includes JPOX specific categories. The file to be used for the JPOX output is called jpox.log. Check this log for messages if you have problems during enhancement or runtime.
+</p>
+<p>
+<strong>log4j.properties file required by JPOX</strong>
+</p>
+<p class="code-block">
+# Define the destination and format of our logging
+log4j.appender.A1=org.apache.log4j.FileAppender
+log4j.appender.A1.File=jpox.log
+log4j.appender.A1.layout=org.apache.log4j.PatternLayout
+log4j.appender.A1.layout.ConversionPattern=%d{HH:mm:ss,SSS} (%t) %-5p [%c] - %m%n
+
+# JPOX Categories
+log4j.category.JPOX.JDO=INFO, A1
+log4j.category.JPOX.Cache=INFO, A1
+log4j.category.JPOX.MetaData=INFO, A1
+log4j.category.JPOX.General=INFO, A1
+log4j.category.JPOX.Utility=INFO, A1
+log4j.category.JPOX.Transaction=INFO, A1
+log4j.category.JPOX.RDBMS=DEBUG, A1
+
+log4j.category.JPOX.Enhancer=INFO, A1
+log4j.category.JPOX.SchemaTool=INFO, A1
+</p>
+</div>
+
+<a name="N10195"></a><a name="Step+7.+Enhancing+the+JPOX+classes"></a>
+<h2 class="boxed">Step 7. Enhancing the JPOX classes</h2>
+<div class="section">
+<p>
+After all of the Java classes representating the objects corresponding
+to the database tables have been written, they first need to be
+compiled and then they need to be "enhanced", which makes them
+persistence-capabable. JPOX provides a helper class to do this for you which is contained in the jar file <span class="codefrag">jpox-enhancer-*.jar.</span> and is called <span class="codefrag">org.jpox.enhancer.JPOXEnhancer</span>.
+</p>
+<p>
+We'll defer the compilation and enhancement step until we are ready
+to configure our environment after we've coded the business logic
+class and application class.
+</p>
+</div>
+
+
+<a name="N101A7"></a><a name="Step+8.+Code+the+class+which+makes+the+JPOX+JDO+queries"></a>
+<h2 class="boxed">Step 8. Code the class which makes the JPOX JDO queries</h2>
+<div class="section">
+<p>
+Here is the class that contains the business logic specific to our trivialized
+airlines reservation application. Also shown is a properties file that is read upon startup to set some JPOX and JDO properties. Although these properties
+are required to configure JPOX appropriately to work with Derby, they can be set
+from within the application, versus using a properties file as I've done here. The complete source for this class is available in the download.
+</p>
+<p>
+<strong>Partial listing of JPoxJDO.java containing the JPOX queries</strong>
+</p>
+<p class="code-block">
+package org.apache.derby.demo.persistence;
+
+import javax.jdo.JDOHelper;
+import javax.jdo.PersistenceManager;
+import javax.jdo.PersistenceManagerFactory;
+import javax.jdo.Query;
+import javax.jdo.Transaction;
+
+...
+
+public class JPoxJDO {
+
+ private static final String JPOX_CONFIG = "jpox.properties";
+ private static Properties prop;
+ private boolean isInitialized = false;
+ private PersistenceManager pm;
+
+ public JPoxJDO() {
+ if (isInitialized) {
+ return;
+ }
+ else {
+ initialize();
+ }
+
+ }
+
+ private void initialize() {
+
+ System.out.println("JpoxJDO, initialize called");
+ getDatasourceProps();
+ pm = createPersistenceManager();
+ isInitialized = true;
+ return;
+ }
+
+ // load all of the various JPOX properties from a properties file
+
+ private void getDatasourceProps() {
+ InputStream is = this.getClass().getResourceAsStream(JPOX_CONFIG);
+
+ prop = new Properties();
+ try {
+ prop.load(is);
+ } catch (IOException exception) {
+ throw new RuntimeException("jpox.properties not found.",
+ exception);
+ }
+ }
+
+ // create the PersistenceManager using the JDO Helper class
+ // the persistencemanage is used for all JPOX transactions
+
+ private static PersistenceManager createPersistenceManager() {
+
+ PersistenceManagerFactory pmf = JDOHelper
+ .getPersistenceManagerFactory(prop);
+
+ return pmf.getPersistenceManager();
+
+ }
+
+ // close the persistence manager.
+
+ public void shutdown() {
+ if (pm != null) {
+ pm.close();
+ }
+
+ }
+
+ // If the username is in the APP.USERS table retrieve
+ // the database row, which in JPOX is the class UserBean
+
+ public UserBean getUserPassword(String userName) {
+
+ UserBean userBean;
+
+ Transaction txn = pm.currentTransaction();
+ try {
+ txn.begin();
+ // this represents the equivalent of the SQL query:
+ // select username, password from APP.USERS where username = ?
+ Query query = pm.newQuery(UserBean.class, "userName == username");
+ query.declareParameters("String username");
+ query.setUnique(true);
+ userBean = (UserBean) query.execute(userName.trim());
+ pm.retrieve(userBean);
+ if (userBean == null) {
+ userBean = new UserBean();
+ }
+ txn.commit();
+ } finally {
+ if (txn.isActive()) {
+ txn.rollback();
+ }
+ }
+ return userBean;
+ }
+
+ // Insert a row into the APP.USERS table by first creating a
+ // UserBean, then using JPOX to persist the UserBean to Derby.
+
+ public int insertUser(String firstName, String lastName, String userName,
+ String email, String password) {
+
+ ...
+
+
+ // insert a row into the UserCreditCard table by first
+ // creating a UserCreditCardBean and then using JPOX
+ // to persist the data
+
+ public int insertUserCreditCard(String lastname, String userName,
+ String creditCardType, String creditCardNum, String creditCardDisplay) {
+
+ int success = 0;
+ UserCreditCardBean userCCBean = new UserCreditCardBean(lastname.trim(),
+ userName.trim(), creditCardType.trim(), creditCardNum.trim(),
+ creditCardDisplay.trim());
+
+ Transaction txn = pm.currentTransaction();
+ try {
+ txn.begin();
+ pm.makePersistent(userCCBean);
+ txn.commit();
+ success = 1;
+ } finally {
+ if (txn.isActive()) {
+ txn.rollback();
+ success = 0;
+ }
+ }
+ return success;
+ }
+
+ // query for the Destination Airports of a City based on
+ // the Origin Airport of a flight
+ // return the data in the form of the JPOX enhanced class,
+ // CityBean
+
+ public CityBean[] destAirports(String origAirport) {
+
+ ...
+
+ // query for all Cities in the APP.CITIES table
+ // returning an Array of CityBeans
+
+ public CityBean[] cityList() {
+
+ ...
+
+ // return an array of FlightsBean which include a specific
+ // ORIG_AIRPORT and DEST_AIRPORT
+
+ public FlightsBean[] origDestFlightList(String origAirport,
+ String destAirport, Date startDate) {
+
+ ...
+
+ // return the rows in the FlightHistory table based on the Username
+ // in the form of an array of FlightHistoryBeans
+
+ public FlightHistoryBean[] fetchFlightHistory(String userName) {
+
+ ...
+
+ // insert into the UserFlightHistory table by creating
+ // the FlightHistoryBean and persisting it to Derby
+
+ public int insertUserFlightHistory(String userName, FlightsBean flightsBean,
+ String creditCardType, String creditCardDisplay) {
+
+ ...
+}
+</p>
+<p>
+Notice the use of the <span class="codefrag">javax.jdo.Query and javax.jdo.Transaction</span>
+classes to create the queries and transactions used by JPOX.
+</p>
+<p>
+Here is the properties file, <span class="codefrag">jpox.properties</span>, used by the <span class="codefrag">JPoxJDO.java</span>
+class to set properties for JDO and JPOX. The Derby JDBC Embedded Driver is used for the JDBC Driver and the Derby Connection URL points to the
+relative path to the <span class="codefrag">airlinesDB</span> database under the data directory.
+</p>
+<p>
+<strong>Properties file to set the JPOX properties</strong>
+</p>
+<p class="code-block">
+javax.jdo.PersistenceManagerFactoryClass=org.jpox.PersistenceManagerFactoryImpl
+org.jpox.autoCreateSchema=false
+org.jpox.validateTables=false
+org.jpox.validateConstraints=false
+javax.jdo.option.NontransactionalRead=true
+javax.jdo.option.ConnectionDriverName=org.apache.derby.jdbc.EmbeddedDriver
+javax.jdo.option.ConnectionURL=jdbc:derby:data/airlinesDB
+javax.jdo.option.ConnectionUserName=APP
+javax.jdo.option.ConnectionPassword=mine
+</p>
+<p>
+Prior to running the sample application below make sure the <span class="codefrag">jpox.properties</span> file is in the directory where the <span class="codefrag">JPoxJDO</span> class is since the <span class="codefrag">jpox.properties</span> file
+is read at run time to initialize the <span class="codefrag">JPoxJDO</span> class.
+</p>
+</div>
+
+
+<a name="N101E1"></a><a name="Step+9.+Code+the+application+class+which+calls+the+business+logic+class"></a>
+<h2 class="boxed">Step 9. Code the application class which calls the business logic class</h2>
+<div class="section">
+<p>
+The <span class="codefrag">DerbyJPox.java</span> class calls the methods of the <span class="codefrag">JPoxJDO.java</span> class as you might in a sample application.
+</p>
+<p>
+<strong>Partial Listing of DerbyJPox.java application class</strong>
+</p>
+<p class="code-block">
+package org.apache.derby.demo.application;
+
+public class DerbyJPox {
+
+ public static void main(String[] args) {
+ JPoxJDO jpoxJDO = new JPoxJDO();
+ UserBean userBean = jpoxJDO.getUserPassword("apacheu");
+
+ ...
+
+ // Note, the user table has a primary key on username ... this insert
+ // will only work once.
+
+ int success = jpoxJDO.insertUser("Susan", "Cline", "slc",
+ "slc@mycomp.org", "mypass");
+ ...
+
+ CityBean[] cityBeans = jpoxJDO.destAirports("ATH");
+ ...
+
+ FlightsBean flightsBean = new FlightsBean("AA1134", 1, "ATH", new Time(0), "AMS",
+ new Time(1), "B", 12.00, "1200", "B747", new Date());
+ int success2 = jpoxJDO.insertUserFlightHistory("slc", flightsBean,
+ "visa", "4728-xxxx-xxxx-xxxx-4567");
+ ...
+
+ FlightHistoryBean[] flightHistoryBeans = jpoxJDO.fetchFlightHistory("slc");
+ ...
+ jpoxJDO.shutdown();
+ ...
+ }
+}
+
+</p>
+</div>
+
+
+<a name="N101F8"></a><a name="Step+10.+Compile+all+classes%2C+enhance+the+persistence+capable+ones+and+run+the+application"></a>
+<h2 class="boxed">Step 10. Compile all classes, enhance the persistence capable ones and run the application</h2>
+<div class="section">
+<p>
+The instructions below show how to compile all classes and enhance the persistence-capable classes assuming the download file, <span class="codefrag">jpox_derby.zip</span> was unzipped to the C:/ directory on a windows machine.
+</p>
+<p>
+
+<strong>Directory structure after unzipping <span class="codefrag">jpox_derby.zip</span></strong>
+</p>
+<p class="code-block">
+C:\JPOX_Derby
+|
++ --- data
+| |
+| + --- airlinesDB.sql
+| + --- airlinesDB
+|
++ --- src (the java source files)
+| |
+| + --- package.jdo
+| + --- log4j.properties
+| + --- org
+| |
+| + --- apache
+| |
+| + --- derby
+| |
+| + --- demo
+| |
+| + --- application
+| | |
+| | + --- DerbyJPox.java
+| | |
+| + --- beans
+| | |
+| | + --- model
+| | | |
+| | | + --- UserBean.java
+| | | + --- UserCreditCardBean.java
+| | |
+| | + --- view
+| | | |
+| | | + --- CityBean.java
+| | | + --- FlightHistoryBean.java
+| | | + --- FlightsBean.java
+| | |
+| + --- persistence
+| | |
+| | + --- JPoxJDO.java
+| | + --- jpox.properties
+|
+|
+|
+</p>
+<p>
+To make this example more straightforward, complete the following steps before proceeding to the next step.
+</p>
+<ul>
+
+<li>Create a <span class="codefrag">lib</span> and a <span class="codefrag">bin</span> directory under the <span class="codefrag">\JPOX_Derby</span> directory.</li>
+
+<li>Copy these six jar files to the <span class="codefrag">lib</span> directory.
+<ul>
+
+<li>bcel-5.1.jar</li>
+
+<li>derby.jar</li>
+
+<li>jdo2-api-2.0-rc1.jar</li>
+
+<li>jpox-1.1.0-rc-1.jar</li>
+
+<li>jpox-enhancer-1.1.0-rc-1.jar</li>
+
+<li>log4j-1.2.12.jar</li>
+
+</ul>
+
+</li>
+
+<li>
+Copy the <span class="codefrag">log4j.properties</span> file that is in the <span class="codefrag">\JPOX_Derby\</span><strong>src</strong> directory to the <span class="codefrag">\JPOX_Derby\</span><strong>bin</strong> directory.
+</li>
+
+<li>
+Copy the <span class="codefrag">package.jdo</span> file that is in the <span class="codefrag">\JPOX_Derby\</span><strong>src</strong> directory to the <span class="codefrag">\JPOX_Derby\</span><strong>bin</strong> directory.
+</li>
+
+</ul>
+<p>Referring to the above directory structure as an example, first compile the classes that we will later make persistence capable. The compiled
+classes need to go into the bin directory you just created. </p>
+<p>
+<strong>Note:</strong> In all of these examples make sure there are no spaces in the value for the classpath specified by the <span class="codefrag">-cp</span> flag in the <span class="codefrag">java</span> command. The spaces have been added for readability.</p>
+<p>
+
+<strong>Compiling the Java Data Objects</strong>
+
+</p>
+<p class="code-block">
+C:\JPOX_Derby>javac -d bin src\org\apache\derby\demo\beans\model\*.java
+src\org\apache\derby\demo\beans\view\*.java
+</p>
+<p>
+<strong>Enhancing these classes using the JPOXEnhancer class</strong>
+</p>
+<p class="code-block">
+
+C:\JPOX_Derby>java -Dlog4j.configuration=file:src\log4j.properties -cp
+lib\bcel-5.1.jar;lib\jpox-enhancer-1.1.0-rc-1.jar;lib\jpox-1.1.0-rc-1.jar;
+lib\jdo2-api-2.0-rc1.jar;lib\log4j-1.2.12.jar;bin
+org.jpox.enhancer.JPOXEnhancer src\package.jdo
+
+</p>
+<p>
+<strong>The output from enhancing these five classes</strong>
+</p>
+<p class="code-block">
+JPOX Enhancer (version 1.1.0-rc-1) : Enhancement of classes
+
+ENHANCED (PersistenceCapable) : org.apache.derby.demo.beans.view.CityBean
+ENHANCED (PersistenceCapable) : org.apache.derby.demo.beans.view.FlightsBean
+ENHANCED (PersistenceCapable) : org.apache.derby.demo.beans.view.FlightHistoryBe
+an
+ENHANCED (PersistenceCapable) : org.apache.derby.demo.beans.model.UserBean
+ENHANCED (PersistenceCapable) : org.apache.derby.demo.beans.model.UserCreditCard
+Bean
+</p>
+<p>Next, we'll compile both the business logic class, <span class="codefrag">org.apache.derby.demo.persistence.JPoxJDO</span> and the application class, <span class="codefrag">org.apache.derby.demo.application.DerbyJPox</span>. When compiling these two classes do not recompile the classes you just enhanced. Doing so, will "remove" the enhancement and cause the application to fail at runtime.
+</p>
+<p>
+
+<strong>Compiling the business logic and application class</strong>
+
+</p>
+<p class="code-block">
+C:\JPOX_Derby>javac -d bin -cp lib\jdo2-api-2.0-rc1.jar;lib\jpox-1.1.0-rc-1.jar;
+bin src\org\apache\derby\demo\persistence\*.java
+src\org\apache\derby\demo\application\*.java
+</p>
+<p>
+We need to do one last step prior to running the application class.
+Copy the <span class="codefrag">jpox.properties</span> file from the <span class="codefrag">C:\JPOX_Derby\</span><strong>src</strong><span class="codefrag">\org\apache\derby\demo\persistence</span> directory
+to the <span class="codefrag">C:\JPOX_Derby\</span><strong>bin</strong><span class="codefrag">\org\apache\derby\demo\persistence</span> directory.
+</p>
+<p>Now we're ready to run the sample application. Use the command below to run the <span class="codefrag">DerbyJPox.java</span> class.</p>
+<p>
+
+<strong>Run the application class, <span class="codefrag">DerbyJPox</span></strong>
+
+</p>
+<p class="code-block">
+C:\JPOX_Derby>java -cp lib\jdo2-api-2.0-rc1.jar;lib\jpox-1.1.0-rc-1.jar;
+lib\derby.jar;lib\log4j-1.2.12.jar;bin
+org.apache.derby.demo.application.DerbyJPox
+</p>
+<p>The output from running the application class, DerbyJPox.java is shown below.</p>
+<p>
+
+<strong>Output from DerbyJPox</strong>
+
+</p>
+<p class="code-block">
+JpoxJDO, initialize called
+Issuing JPOX queries against the Derby DB, airlinesDB
+***********************************************************
+Query 1: The UserBean corresponding to the username apacheu is:
+firstname: apache lastname: user email: apacheu@mycompany.com
+***********************************************************
+Insert 1: Create a new user by calling JPoxJDO.insertUser(
+"Susan", "Cline", "slc", "slc@mycomp.org", "mypass")
+Successfully inserted the user 'slc' into the database.
+***********************************************************
+Query 2: Find the destination cities of flights from Athens.
+Dest City: Amsterdam
+Dest City: Cairo
+Dest City: Istanbul
+Dest City: Lagos
+Dest City: London
+Dest City: Paris
+***********************************************************
+Insert 2: Create a FlightsHistoryBean by calling
+JPoxJDO.insertUserFlightHistory
+("slc", myFlightsBean, "visa", "4728-xxxx-xxxx-xxxx-4567")
+Successfully inserted a row into the FlightHistory table.
+***********************************************************
+Query 3: Select the row from the FlightHistory table based on username slc
+by calling JPoxJDO.fetchFlightHistory("slc")
+Flight: AA1134 Orig Airport: ATH Dest: AMS Credit Crd: 4728-xxxx-xxxx-xxxx-4567
+***********************************************************
+Shutting down JPOX persistence manager.
+***********************************************************
+</p>
+</div>
+
+
+<a name="N102CA"></a><a name="Resources+and+Acknowledgements"></a>
+<h2 class="boxed">Resources and Acknowledgements</h2>
+<div class="section">
+<p>
+The <a href="http://db.apache.org/derby/">Derby</a> web site and <a class="external" href="http://wiki.apache.org/db-derby/">wiki</a> are the best sources of information about Derby.
+</p>
+<p>For in-depth information about JPOX see the <a class="external" href="http://www.jpox.org/index.jsp">JPOX</a> web site.
+
+Apache JDO provides the JD0 2.0 API which is available from the <a href="http://db.apache.org/jdo">Apache JDO</a> web site. JPOX JDO provides the reference implementation of the JDO 2.0 specification via the JPOX JDO 1.1 release. </p>
+<p>The <a class="external" href="http://www.jpox.org/docs/1_1/tutorials/tutorial.html">JPOX 1.1 Tutorial</a> is vital to get up to speed with JPOX JDO.
+</p>
+<p>Many thanks to <strong>Michelle Caisse</strong> and <strong>Craig Russell</strong> of the Apache JDO project in helping me with my "newbie" questions on configuring JPOX with Derby and general JDO questions.</p>
+<p>Susan Cline wrote this paper and would appreciate any feedback
+in the form of suggestions, corrections or questions about it by posting to the
+<a class="external" href="mailto:derby-user@db.apache.org">derby-user</a> mailing list.
+</p>
+</div>
+
+
+<p>
+<em>Last updated: March 8, 2006</em>
+</p>
+
+
+</div>
+<!--+
+ |end content
+ +-->
+<div class="clearboth"> </div>
+</div>
+<div id="footer">
+<!--+
+ |start bottomstrip
+ +-->
+<div class="lastmodified">
+<script type="text/javascript"><!--
+document.write("Last Published: " + document.lastModified);
+// --></script>
+</div>
+<div class="copyright">
+ Copyright ©
+ 2004-2012 Apache Software Foundation</div>
+<div id="feedback">
+ Send feedback about the website to:
+ <a id="feedbackto" href="mailto:derby-user@db.apache.org?subject=Feedback%C2%A0integrate/JPOX_Derby.html">derby-user@db.apache.org</a>
+</div>
+<!--+
+ |end bottomstrip
+ +-->
+</div>
+</body>
+</html>