@@TITLE: WireHose Database Setup@@

WireHose Developer Center
WireHose Developer Center
NewsProductsDownloadDevelopersAbout Us

WireHose Database Setup

Contents

Introduction

The WireHose frameworks are designed to work with any database supported by WebObjects, and offer several features to make cross-database development and deployment easier. WireHose comes with support for building and running applications with FrontBase, OpenBase and Oracle, and it's easy to add support for other databases.

WireHose can replace the database adaptor and connection dictionary on the fly when each EOModel is loaded. This allows you to switch between multiple databases by specifying a different adaptor dictionary on the command line when launching your application, as, for example, during development versus deployment.

For improved performance, WireHose fetchers use custom SQL which may be incompatible with some databases. Use of this SQL can be controlled by several defaults. In general, any database which supports subselects should work properly with WireHose, though databases that support SQL set operators such as INTERSECT and EXCEPT (or MINUS) will perform better.

All WireHose-specific entity attributes are defined by a handful of attribute prototypes. Using prototypes allows you to change the definition of every WireHose attribute in a single place.

Versions of WebObjects prior to 5.0 provided a method for automatically generating primary keys which were 12-byte NSData objects. This was convenient because it did not require a round-trip to the database to allocate new primary keys. WHEnterpriseObject provides this capability for WebObjects 5.2, and will encode entity information into the primary key generated.

Changing the adaptor dictionary

Each EOModel in a WebObjects application contains information in its index.eomodeld file called the "connection dictionary", which tells WebObjects which database on which host to connect to, which JDBC driver to use, etc.

WireHose can replace the database adaptor and connection dictionary on the fly when each EOModel is loaded. This allows you to switch between multiple databases by specifying a different adaptor dictionary on the command line when launching your application, as, for example, during development versus deployment.

An adaptor dictionary file is a property list with two keys, "adaptorName" and "connectionDictionary". There are adaptor dictionaries for FrontBase, OpenBase and Oracle located in the WireHoseExtras/DatabaseSetup directory.

Here's a sample adaptor dictionary:

{
    adaptorName = JDBC; 
    connectionDictionary = {
        URL = "jdbc:FrontBase://localhost/wirehose/user=wirehose";
        driver = "jdbc.FrontBase.FBJDriver";
        plugin = "";
        username = "";
        password = "";
    }; 
}

If you name your adaptor dictionary "adaptorDict.plist" and add it to your application's Bundle Resources in the Application Server target, the WireHose frameworks will find it and use it automatically. Otherwise, you can use the WHAdaptorDict property to specify the name of the adaptor dictionary to use at runtime. You can specify either the name of an adaptor dictionary in your application's Bundle Resources, or the full pathname to the desired file.

SQL properties

For improved performance, WireHose fetchers use custom SQL which may be incompatible with some databases. In general, any database which supports subselects should work properly with WireHose, though databases that support SQL set operators such as INTERSECT and EXCEPT (or MINUS) will perform better.

The custom SQL generated is controlled by several defaults (see Properties for more information about setting defaults):

WHSQLIntersectOperator
SQL operator to use when constructing queries. Defaults to "INTERSECT". If set to "false" or "NO", then an alternative syntax is used which does not require INTERSECT functionality.
WHSQLExceptOperator
SQL operator to use when constructing queries. Defaults to "EXCEPT". For Oracle, you would set this to "MINUS". If set to "false" or "NO", then an alternative syntax is used which does not require EXCEPT functionality. This default is ignored if WHSQLIntersectOperator is set to "false" or "NO".
WHSQLTimestampFormat
Format to be applied to timestamps when constructing queries. Defaults to "default". There are two convenience values:
  • "default" specifies "''yyyy-MM-dd HH:mm:ss zzz''"
  • "oracle" specifies "'TO_DATE'(''yyyy-MM-dd hh:mm:ssaa'', '''YYYY/MM/DD HH:MI:SSAM''')"

See NSTimestampFormatter and java.text.SimpleDateFormat for possible formats.

Setting attribute prototypes

All WireHose-specific entity attributes are defined by a handful of attribute prototypes. Using prototypes allows you to change the definition of every WireHose entity in a single place, no matter which EOModel or framework they reside in (including the WireHoseBase EOModel in the WireHoseBase framework).

See Apple's Using EOModeler documentation for details about creating prototype definitions.

Default prototype definitions for FrontBase, OpenBase and Oracle are provided in frameworks which were installed in your /Library/Frameworks folder. The Project Builder projects for these are in WireHoseExtras/SampleCode.

To define your own prototypes, create a new WebObjects Framework project, and add a new EOModel to the Application Server target. Create one entity named "EOJDBCPrototypes", and define prototypes as shown in the table below.

Then build and install your prototypes framework. Adding this framework to any WireHose application will cause WebObjects to use your prototype definitions instead of the ones defined in the WireHoseBase framework. To use a prototypes framework in a command-line tool, make sure there is entry in your classpath which points to the prototypes framework directory as there won't be a jar file to point to, e.g., "...:/Library/MyPrototypes.framework:..."

Prototype NameSample DefinitionValue ClassComments
whBinaryIDBYTE(16)NSDataUsed as primary key for all WHTag entities. You can safely define this as an integer. See "Using binary primary keys" for more information.
whBooleanCHAR(1)StringUsed for all boolean attributes such as isIndexed and shouldShowName. See "Working with boolean attributes" for more information.
whIntegerINTNSNumber (i)Used for integer attributes such as importance.
whIntegerIDINTNSNumber (i)Used as primary key for all WireHose entities, except for WHTag. You can safely define this as a binary. See "Using binary primary keys" for more information.
whLongTextCLOBNSStringUsed for storing large amounts of text, usually in a to-one related object. See WHLongTextResource for more information.
whSecondsINTNSNumber (i)Used for attributes such as cacheExpires.
whString255CHAR(255)NSStringUsed for attributes such as name or componentName. You may prefer to define this as a VARCHAR.
whString64CHAR(64)NSStringUsed primarily for attributes such as entityName. You may prefer to define this as a VARCHAR.
whString32CHAR(32)NSStringUsed for attributes such as login, password, affiliate and areaName. You may prefer to define this as a VARCHAR.
whTimestampTIMESTAMPNSGregorianDateUsed for all dateAdded attributes, as well as dateLastLogin.

Working with boolean attributes

Some WireHose attributes are boolean, e.g., isIndexed in WHIndexable, or shouldShowName in WHChannel. There is no standard way to store booleans in a database; some support BOOLEAN columns, while others may store a "Y" or "N" in a CHAR(1) column, or a zero or one in an INTEGER. WHEnterpriseObject provides several utility methods which make it easy to deal with varying definitions for boolean attributes in a transparent fashion.

Your eomodel should define boolean columns as an attribute of type BOOLEAN, INTEGER or CHAR(1), depending on what's appropriate for your database. The WireHoseBase eomodel defines a "whBoolean" prototype which you can use to modify the definition for all boolean attributes in a single place.

WHEnterpriseObject's storedBooleanValueForKey and takeStoredBooleanValueForKey methods translate between a Java primitive boolean and the type ultimately required by the database adaptor, and will call the indexed and setIndexed methods to obtain or set the value. A NULL value in the database is translated as false.

See the WHEnterpriseObject documentation for more information about working with boolean attributes.

Using other databases

The WireHose frameworks are designed to be as database independent as possible. For improved performance, WireHose fetchers use custom SQL which may be incompatible with some databases. In general, any database which supports subselects should work properly with WireHose, though databases that support SQL set operators such as INTERSECT and EXCEPT (or MINUS) will perform better.

Create the database

Here's one way to accomplish this task:

  • Make a copy of the WireHoseBase.eomodeld somewhere on your hard drive. This file is located in the Resources directory of the WireHoseBase framework, which was installed into /Library/Frameworks.
  • Open the copy in EOModeler.
  • Use Model -> Set Adaptor Info... to set the URL, plugin and driver information as needed for your database.
  • In the "Table Mode" view, select all entities which have a non-blank entry in the Table column. For entities which share the same table (such as the WHChannelTag table), make sure each table is selected only once.
  • Click the "Generate SQL" button and cross your fingers. Depending on your database and adaptor, everything may work fine the first try. If not, you may need to edit the generated SQL in a text editor and execute it manually.

Create an adaptor dictionary

See Changing the adaptor dictionary for instructions.

Create a prototypes framework

See Setting attribute prototypes for more information. Create a new WebObjects Framework project and add the EOModel containing your prototype definitions to the Application Server target.

Before you build and launch your application, be sure that you have added the correct prototypes framework for your database to the Application Server target.

Launching the sample applications

When launching WireHose applications you'll also need to tell the WireHose frameworks to use your adaptor dictionary by using this extra command-line default:

-WHAdaptorDict /path/to/YourAdaptorDict.plist

In addition, you may need to use one or more properties to control the custom SQL WireHose generates. See SQL properties for more information.

Copyright ©2000-2008 Gary Teter. All rights reserved. WireHose and the eyeball-and-arrows logo are trademarks of Gary Teter.