JDCO Relativity Up and Running
Java Data Cache Objects
JDCO Relativity™
Up and Running
Prototyping and Developing Database Applications
without Programming
For Database Designers, Business/Data Analysts, DBAs
and Application Developers
Howard Hyde
Updated 2007.07.11
Table of Contents
(Don’t Skip the) Introduction
1.1Who This Document (and Product) is For and Why
1.2What is JDCO?
1.3What is Relativity™?
1.4What does JDCO do?
1.5What does ‘Without Programming’ mean?
2Installation and Setup
2.1Database, Webserver and Browser
2.2Any Database You Want, as Long as It’s Oracle
2.2.1Oracle Installation
2.2.2Oracle configuration and development
2.2.3JDCO – Oracle version compatibility
2.3Web/Application Server
2.3.1Java Installation
2.3.2Tomcat Installation
2.3.3JDBC Installation
2.3.4Installing and Configuring JDCO Relativity
2.4Client Application Web Browser
2.5Application Security
2.5.1User Authentication and Password Protection
2.5.2The Memory Realm and tomcat-users.xml
2.5.3Basic and Form-based authentication
2.5.4Security configuration in web.xml
2.5.5SSL and Encryption
2.6Summary and Conclusion
2.6.1Ready to Develop
2.6.2Ready to Deploy
3Schema Browser / Prototype Generator: Basic Out-of-the-Box Features
3.1Defining a Sample Database Application
3.1.1Business Domain
3.1.2Data Model
3.1.3SQL DDL
3.2Default Application Modules
3.3Search, List, Add/Edit, Save: The Data Maintenance Cycle
3.3.1Introducing the Seach and List forms
3.3.2The Edit Form
4Painless Application Customization
4.1Defining Table Usages via database Views: ‘VW_<Table Name>’
4.2Read-only Report Views: ‘R$_*’
5Advanced Application Customization Techniques
5.1Shadow Tables, API Views and Instead-of-Triggers
6Fine-grained Application Customization with jdco-app-config.xml
6.1Application configuration
6.2Database Connection: <dbConnection>
6.3Default Read-Write Mode
6.4Application Modules: <DTableGroupDef>
6.5Data Table Usages: <DTableDef>
6.6A complete jdco-app-config.xml listing
(Don’t Skip the)Introduction
This introduction contains important technical and philosophical background information which is essential to getting the most out of the product. It is highly recommended that the reader pay close attention.
1.1Who This Document (and Product) is For and Why
This document is targeted at anyone with a need to analyze business processes, casually browse relational databases, prototype applications or or build full-featured enterprise information systems. This includes application architects, business analysts, data analysts, database designers, DBAs, programmer/developers and technical managers.
JDCO Relativity is a powerful tool for navigating through relational data, trying out different designs, giving and soliciting feedback from application stakeholders, and demonstrating the functionality of an application; all of this with a very light technical learning curve.
This document explains how to get the most from JDCO short of writing code. The underlying philosophy of JDCO is that the common infrastructure of database applications --- connectivity, query retrieval, persistence, referential integrity, concurrency / contention management, transaction management etc., and even certain design pattern-driven functionality --- are universal to any database and do not depend on the specific business or other subject being represented. Therefore a proper database application development framework should provide support for these features out of the box without the need to write custom compiled programs. The only reasons for writing code should be to implement highly specific, non-generic features, or to extend the product’s functionality in general.
The document is not only for non-coders, however. Techies who are interested in extending or revising the functionality of the reference implementation user interface, will need to understand the content of this volume prior to embarking upon programming to the JDCO API, which is treated in a separate document.
1.2What is JDCO?
Here is the concise definition of JDCO:
JDCO is a database application middleware technology: an object/relational translation tool, data persistence engine and application development framework.
A parse of the acronym will yield a more in-depth explanation of what JDCO is:
- Java: The product is implemented in the Java programming language, with the benefits of cross-platform independence, rich object-oriented development platform, high performance and large, dedicated developer community that comes with that.
- Data: The product is about managing data; presenting information to an application user, managing the relationships among different data items, and executing the retrieval and persistence of data from and to the permanent store; the relational database management system (RDBMS)[1].
- Cache: JDCO creates a buffer between the client application and the database, in order to minimize redundant database queries, maintain some session state information between requests, and manage concurrency, contention, business rules and other application mechanisms.
- Objects: JDCO presents a holistic, business-level, object-oriented interface to data which is ultimately retrieved from and persisted to a decomposed, atomized, non-redundant relational form in the database. It shields the developer from complex and tendious tasks of maintaining unique and foreign key relationships, writing SQL statements, managing database connections and binding parameters to SQL connection drivers.
There are several database persistence frameworks and technologies on the Java market now. JDCO is unique in the degree to which it leverages the power of the relational database and SQL to represent the business classes, enforce business rules, facilitate application functionality and reduce the need for custom coding.
JDCO is not a database administration or query tool or a low-level record browser. Its purpose is to interpret designed relational structures and to present an interactive business use case transactional interface. Note the term ‘designed’. JDCO is not interested in staging tables or tables without primary keys. It is used with tables that have been constructed with an organic, validated, consistent relational information system in mind.
Again and again, the supremacy of Design (with clean DDL[2]) will be emphasized, with explanations of what good design is.
1.3What is Relativity™?
Relativity is simply the JDCO class library, being used out of the box to browse relational databases, without writing any Java code. It is JDCO in this role that this document is all about. Once you customize your application, you can call it anything you want.
1.4What does JDCO do?
In a nutshell, JDCO does the repetitive, tedious and complex work inherent in a multi-tier application that needs to move, transform and transmit data structures and content around, so that the analyst or developer can concentrate on the business case and design. JDCO interprets relational database features such as check constraints, primary and unique keys, foreign key references, and composite key structures in order to present the most logical user interface implied by the design. To list a few examples:
- Numeric Primary Key column values are typically hidden from the user and populated behind the scenes.
- Foreign key references are presented as drop-down list boxes, filtered by check constraints and other runtime contextual information, showing a descriptive value to the user while returning the key value internally.
- Queries which would return a number of rows exceeding a threshold are prevented from thrashing the database and overwhelming the user interface; JDCO detects large result sets and allows the user to ‘pick a page’ of b through n of x total rows.
- …and much more, easily modifiable and configurable without programming.
1.5What does ‘Without Programming’ mean?
The concept of developing database applications without programming refers to JDCO’s ability to shield the developer from the need write custom, compiled procedural or object-oriented code. It does not mean that no technical knowledge is necessary.
Knowledge of industry-standard (and/or Oracle) SQL is essential to going beyond mere browsing. Clean SQL DDL for the creation and fine-tuning of relational data objects, and well-designed queries encapsulated in views which provide alternate presentations of business objects, will carry the developer a long way toward robust, full-featured applications. Knowledge of (X)HTML, Cascading Stylesheets (CSS) and Javascript all come into the mix.
But the developer does not need to be concerned with writing case-by-case SQL DML (insert, update, delete), runtime referential integrity, surrogate key generation, transaction management, concurrency/contention or a host of other technical issues; JDCO handles all of these transparently behind the scenes.
Again, the developer’s first job is to get the design right. From there, JDCO database applications unfold with ease.
2Installation and Setup
This chapter summarizes the tasks required to get JDCO running in its standard, web application configuration.
2.1Database, Webserver and Browser
The reference implementationarchitecture for a JDCO/Relativity application is comprised of 3 tiers:
- Database, a.k.a. RDBMS[3]
- Web/application server
- (Thin) Client web browser
Each of these tiers will be described in detail in the sections that follow.
2.2Any Database You Want, as Long as It’s Oracle
JDCO is currently configured only to work with the Oracle (8i, 9i, 10g) relational database management system (RDBMS). In the future, it may be ported to other platforms, such as MS SQL Server, MySQL, IBM DB2 etc.
Oracle licensing is FREE for development and tryout purposes. Although Oracle is typically associated with large, multi-million dollar systems, a little attention to the right licensing of the right edition can go a long way toward containing costs to the order of a few thousand dollars.
Go to the Oracle Technology Network at to download the database software.
2.2.1Oracle Installation
For development and tryout purposes, especially if you are not a trained Oracle DBA, the best option is to run the Oracle installer, choose the Standard Edition (not Enterprise), specify the system passwords you’ll want to use with your database and otherwise accept the default settings, including the standard starter database.
2.2.2Oracle configuration and development
JDCO is not an Oracle development tool; it is not an interface for creating users/schemas, tables, columns, keys, views, indexes etc. For that you need a development and adminstrative tool (or at the very least, the time-honored, traditional command-line interface tool that we all love to hate, SQL*Plus).
Oracle comes with web-based administration tools, which it will present to you during the installation process. You’ll probably want to use a third-party tool such asT.O.A.D. (Tool for Oracle Application Developers) by Quest Software.This one is very popular among developers and DBAs. There are several editions, including a Free version (available from third-party websites; find it by searching on Google: ‘Oracle Free Toad’ or go to
Another popular tool for Oracle is the Embarcadero suite, including Rapid SQL, optimized for development/programming, and DBArtisan, optimized for administration. See details.
Many other resources are available for explaining how to install, configure and use Oracle. The essential points for our present purposes are:
- Verify that you can start and stop the Oracle database and listener. On Windows, this is done via the Services control panel, under Administrative Tools.
- Verify that you can connect to your Oracle schema/user accounts, such as SYS, SYSTEM, and any DBA or other accounts that you create. A typical account-creation script would look something like:
createuser bigdba identifiedby bigdba
defaulttablespace users
temporarytablespace temp
quotaunlimitedon users;
grantconnect,resource,dbato bigdba;
createuser dev identifiedby dev
defaulttablespace users
temporarytablespace temp
quotaunlimitedon users;
grantconnect,resourceto dev;
- Be familiar with the Transparent Network Substrate Names file which Oracle uses to resolve network requests for connections to the database. The file is NETWORK\ADMIN\tnsnames.ora.
2.2.3JDCO – Oracle version compatibility
JDCO has been tested with Oracle 9i and 10g. The only difference which has been noticed as significant to JDCO is the DROPPED column in the system view DBA_TABLES, introduced in version 10. Oracle 10g tracks tables even after they are dropped (their very structure and definition removed), using system-generated names like ‘BIN$zFL+Nxj+QUuVQ3bPZLHJ/g==$0’. Since we do not wish to see dropped tables, when querying the 10g metadata JDCO adds the clause ‘WHERE DROPPED = ‘NO’ to its SQL statement.
JDCO recognizes the Oracle version and handles this issue for you without any intervention or customization.
2.3Web/Application Server
JDCO has been developed and tested using the Apache/Jakarta Tomcat webserver. It is intended to be J2EE compatible and therefore should work on any compliant web/application server, such as JBoss, Bea Weblogic, IBM Websphere, or Oracle Application Server. For information and product downloads, see the following:
- Tomcat:
- JBoss:
- Oracle Application Server:
- IBM Websphere:
- BEA Weblogic:
Again, to keep things simple, if you are not an experienced system administrator, it is best to use the simplest configuration. Keep that in mind in the following sub-sections.
2.3.1Java Installation
Tomcat requires and is dependent upon a separate installation of Java. My recommendation for beginners is to go to and download the latest production (non-Beta) build, including the SDK (not only the JRE[4]). Install it in a simple location such as C:\java\j2sdk1.4.2_05 and be prepared to specify this location to the Tomcat installer.
2.3.2Tomcat Installation
Follow the installation instructions that come with Tomcat (or your other choice of web/application server). Be certain to specify to Tomcat the Java directory that you created in the previous step. The default IP port for Tomcat is 8080, but I usually change this to 8088. Remember your adminstrative password; You can find and edit it in the configuration file conf/tomcat-users.xml.
After installation is complete, verify that you can start and stop the service. In Windows, this is done with the Services control panel.
2.3.3JDBC Installation
In order for Tomcat and JDCO to work with Oracle, the JDBC (Java database connectivity) driver classes must be available to Tomcat. To install these, simply copy the file classes12.jar from the Oracle jdbc/lib directory to Tomcat’s shared/lib directory (make sure you bounce (restart) Tomcat before attempting to use it).
2.3.4Installing and Configuring JDCO Relativity
The final step in setting up your JDCO Relativity framework is to install JDCO in the webserver deployment directory. Unzip the file Relativity.zip into the Tomcat directory under /webapps. Tomcat will automatically make this application available the next time it refreshes, using the directory name (Relativity) as the application name and end of the URL.
Web / servlet applications are frequently deployed as web archive (.war) files. JDCO / Relativity should NOT be deployed in this manner, as the running product itself needs to write to files within the directory structure.
2.4Client Application Web Browser
There is no client installation required apart from a standard internet browser such as Microsoft Internet Explorer ( Netscape Navigator ( or Mozilla Firefox ( In this way, JDCO applications may be deployed for public access as well as secure, private use.
Since JDCO makes liberal use of Javascript, Cascading Style Sheets (CSS) and cookies (client-side browser files containing persistent session state information), it is required to have these features enabled and recommended to keep up to date with recent (bug-free) production versions of browsers (they’re free after all! C’mon, people!).
To see and begin browsing your JDCO / Relativity application, point your browser to the URL constructed as follows:
- name or ip address>:<port no>/<application name>
For example:
If your webserver is hosted on the same computer as you are browsing from, the localhost server name or default ip address should work:
If you need to use Secure Socket Layer (SSL) in order to encrypt and make secure all communication between the browser and the web server, the URL will be modified. This subject is treated in the next section.
2.5Application Security
You may not want to permit anyone and everyone to access your web application, especially if it is deployed on a public network such as the internet; you may wish to implement password protection such that only identified and authenticated users may browse your pages. You might want to permit some users access to certain pages but not to others. Furthermore, to provide additional security, you may wish to encrypt the communication between the browser and the webserver, so that no one ‘sniffing’ or intercepting the network bitstream can know the content of the data being transferred back and forth; this is especially important if the information is of a sensitive nature, such as social security numbers, bank account and/or credit card numbers, etc.
Your web/application server documentation and other sources can explain these topics in more depth. We will give you just enough explantation in the sub-sections below to point you in the right direction.
Here is a summary checklist:
- Define users and roles in tomcat-users.xml
- Un-comment the Realm specification in server.xml
- (Optional) If using Form-based authentication, create the HTML login and login error form documents.
- Add the <security-constraint> element and its sub-elements to the web.xml file.
- (Optional) Enable the SSL port in server.xml and add the <transport-guarantee>CONFIDENTIAL</transport-guarantee> element to web.xml.
2.5.1User Authentication and Password Protection
With User Authentication, you ask users to identify and validate themselves prior to permitting them access to a requested resource identified by a URL. Tomcat uses the concept of the Realm for managing user, roles (groups) and passwords. There are a few different implementations of the Realm concept; the most robust stores user account and password information in a relational database, separate from the Tomcat installation. The easiest, quick-and-dirty solution with which to get started, is the Memory realm.
2.5.2The Memory Realm and tomcat-users.xml
To use the memory realm, you must un-comment (or enter) the line in Tomcat’s /conf/server.xml file: