1.3. JDO
Prev | Chapter 1. Kodo Sample Code | Next

## 1.3. JDO

### 1.3.1. Using Application Identity

The files for this sample are located in the `samples/jdo/appid` directory of the Kodo installation. This sample shows how to use JDO application identity. The `GovernmentForm` class uses a static inner class as its application identity class. The `Main` class is a simple JDO application that allows you to create and manipulate persistent GovernmentForm instances.

### 1.3.2. Customizing Logging

The files for this sample are located in the `samples/jdo/logging` directory of the Kodo installation. This sample shows how to plug a custom logging strategy into Kodo. The `Main` class implements custom logging and has a `main` method demonstrating how to set your custom log as the system default.

### 1.3.3. Custom Sequence Factory

The files for this sample are located in the `samples/jdo/seqfactory` directory of the Kodo installation. This sample shows how to define a custom JDO sequence factory and use it for certain classes.

### 1.3.4. Using Externalization to Persist Second Class Objects

The files for this sample are located in the `samples/jdo/externalization` directory of the Kodo installation. This sample demonstrates how to persist field types that aren't directly supported by JDO using Kodo's externalization framework.

The `ExternalizationFields` class is a persistence-capable class with fields of various types, none of which are recognized by JDO. The JDO metadata for `ExternalizationFields` uses Kodo's "externalizer" and "factory" metadata extensions to name methods that can be used to transform each field into a supported type, and then reconstruct it from its external form. Even complex external forms are supported; the `ExternalizationFields.pair` field externalizes to a list of persistence-capable objects.

The `ExternalizationFieldsMain` class is a driver to demonstrate that `ExternalizationFields` instances persist correctly.

### 1.3.5. Custom Mappings

The files for this sample are located in the `samples/jdo/ormapping` directory of the Kodo installation. This sample demonstrates custom field and class mapping.

- IsMaleHandler is a custom value handler that transforms a boolean field into 'M' or 'F' characters in the database. If shows how to create transformation value handlers.

- PointHandler is a custom value handler for java.awt.Point. It demonstrates how to create a multi-column custom value handlers for complex data.

- XMLStrategy is a custom field strategy that simulates a field that maps to a non-standard column type, and that may require non-standard operations to store and retrieve data.

- StoredProcClassStrategy is a custom class strategy that simulates using stored procedures to access persistent data.

The CustomFields class is a persistence-capable class that uses each of the custom field mappings above. The StoredProc class is a persistence-capable class that uses the StoredProcClassStrategy. The CustomFieldsMain and StoredProcMain classes are simple driver programs for each of these types.

Note that creating custom class mappings requires a license for the Enterprise Edition. Custom field and value mappings work with the Standard Edition.

Also, make sure to browse the "externalization" sample directory. Kodo includes an externalization feature that can be used to persist many unsupported field types without having to create a custom mapping.

### 1.3.6. Custom Proxies

The files for this sample are located in the `samples/jdo/proxies` directory of the Kodo installation. This sample demonstrates custom second class object proxies for mutable persistent fields not directly supported by Kodo.

- `CustomSet` is a custom extension of `java.util.Set` with some extra methods.

- `CustomStringContainer` is a mutable object that holds an internal string. We use this object as a second class object, not a first class object.

The `CustomProxies` class is a persistence-capable class that uses each of the custom proxies above. `CustomProxiesMain` is a simple driver program for showing that the custom proxies work.

### 1.3.7. Example of full-text searching in JDO

The files for this sample are located in the `samples/jdo/textindex` directory of the Kodo installation. This sample demonstrates how full-text indexing might be implemented in JDO. Most relational databases cannot optimize contains queries for large text fields, meaning that any substring query will result in a full table scan (which can be extremely slow for tables with many rows).

The `AbstractIndexable` class implements `javax.jdo.InstanceCallbacks` which will cause the textual content of the implementing persistent class to be split into individual "word" tokens, and stored in a related table. Since this happens whenever an instance of the class is stored, the index is always up to date. The `Indexer` class is a utility that assists in building queries that act on the indexed field.

The `TextIndexMain` class is a driver to demonstrate a simple text indexing application.

### 1.3.8. Horizontal Mappings

This sample demonstrates how to use horizontal mappings in JDO to implement the common pattern of individual tables that track the creation data and last modification date. This is accomplished through the `LastModified` superclass that contains a `lastModificationDate` and `creationDate` field that is automatically updated from the `jdoPreStore` method.

The `package.jdo` file specifies that the `LastModified` class use a horizontal mapping, which means that each of the fields will then be declared in the subclasses: `Widget`, `WidgetOrder`, `WidgetOrderItem`.

### 1.3.9. Sample Human Resources Model

The files for this sample are located in the `samples/jdo/models/humres` directory of the Kodo installation. This sample demonstrates the JDO mapping of an example "Human Resources" schema. The following concepts are illustrated in this sample:

- Mixed Application Identity and Datastore Identity

- Named Query execution

- Value Mappings

- One to One Mappings

- One to Many Mappings (with and without inverses)

### 1.3.10. Sample School Schedule Model

The files for this sample are located in the `samples/jdo/models/school` directory of the Kodo installation. This sample demonstrates different JDO inheritance strategies for the same object model. The following concepts are illustrated in this sample:

- Flat Inheritance Mappings

- State Image Version Indicator

- Vertical Inheritance Mappings

- Horizontal Inheritance Mappings

- Value Mappings

- Many to Many Mappings

The `samples/models/school` directory contains the following interfaces that represent the abstract data model:

- Address

- HomeAddress (extends Address)

- WorkAddress (extends Address)

- Person

- Parent (extends Person)

- Student (extends Person)

- Employee (extends Person)

- Teacher (extends Employee)

- Admin (extends Employee)

- Staff (extends Employee)

- Course

- ScheduledClass

Each of the `flat`, `vertical`, and `horizontal` subdirectories contain implementations of the object model that are identical except for name, and that their inheritance mapping in the `package.jdo` file uses the type of the directory's corresponding name.

### 1.3.11. JMX Management

This sample shows how to use the Kodo JMX Management features. In order to see an example of runtime management:

In order to see an example of remote management:

- Open two console windows, and ensure in each that your `CLASSPATH` has all of the jars distributed with Kodo, and that your execution path is configured for the Kodo tools. If you need additional help with this step, see the installation directions at Chapter 2, Kodo Installation.

- In the first console window, ensure that the Kodo distribution root directory is in your `CLASSPATH`

- Ensure that an appropriate `jdo.properties` is in a directory in your `CLASSPATH` or in the root level of a jar in your `CLASSPATH`, or in a `META-INF` directory in your `CLASSPATH`.

- Change to the `samples/management` directory

- Compile the class file by running: `javac *.java`

- Enhance the data classes by running: `jdoc package.jdo`

- Update the database schema and generate mappings by running: `mappingtool package.jdo`

- Seed the database by running: `java samples.management.SeedDatabase`

- Add the following line to your properties file:

  `kodo.ManagementConfiguration: local-mgmt`

- Start the sample program which will bring up Kodo's management console upon initialization. `java samples.management.ManagementSampleMain`

The Kodo ProfilingAgent also has a JMX MBean. You can see an example of remote profiling if you turn on the ProfilingAgent by making the following setting in your properties file:

- `kodo.ManagementConfiguration: local-mgmt-prof`

A fetch group `g` has been pre-configured in the `package.jdo` file. You can turn on the usage of that fetch group in the example by adding the following setting to your properties file:

- `kodo.FetchGroups: g`

Note that the Kodo PersistenceManagerFactory DataCache also has a JMX MBean. You can see an example of DataCache management if you turn on the data cache by adding the following settings to your properties file:

- `kodo.DataCache: true`

- `kodo.RemoteCommitProvider: sjvm`

Kodo's management and profiling tools can be used in a wide range of modes and environments. For example, by setting the `kodo.ManagementConfiguration` setting to `profiling-gui`, you can use the profiling tool exclusively. You can have Kodo connect and integrate with your existing JMX configuration such as provided by your application server or products such as `MX4J`. For further details on configuring Kodo management and profiling tools, see Chapter 12, Management and Monitoring.

To extend Kodo's monitoring abilities to your own code, you can use `TimeWatch`. An example of how to use the TimeWatch can be found in `QueryThread.java`. A TimeWatch allows for monitoring of named code blocks.

### 1.3.12. XML Store Manager

This sample shows how to use the Kodo XML Store Manager AbstractStoreManager implementation.

For more information on implementing your own custom store manager, please see the XML Store Manager Javadoc (package kodo.xmlstore), and the source code in `src/kodo/xmlstore` under your Kodo installation.

| Note
The AbstractStoreManager requires a Kodo Enterprise Edition license.

In order to see an example of the XML Store Manager:

- Ensure that the Kodo distribution root directory is in your `CLASSPATH`. This is done automatically if you set up your environment as described in the README.

- Ensure that the sample `xmlstore.properties` is in a directory in your `CLASSPATH` or in the root level of a jar in your `CLASSPATH`. Enter your Kodo license key into the sample `xmlstore.properties` as the value of the `kodo.LicenseKey` property.

- Ensure that your `CLASSPATH` has all of the jars distributed with Kodo. This is done automatically if you set up your environment as described in the README.

- `javac *.java`

- `jdoc -p xmlstore.properties package.jdo`

- Note that there is no need to run `mappingtool` for custom store managers.

- `java samples.jdo.xmlstore.SeedDatabase`

- Note the XML data in the selected data directory as specified by your `kodo.ConnectionURL`.

### 1.3.13. Using JDO with Java Server Pages (jsp)

The files for this sample are located in the `samples/jdo/jsp` directory of the Kodo installation. This sample creates a simple Petshop web application to demonstrate using JDO with JSPs. Run ant on the included `build.xml` file and follow the instructions ant displays.

### 1.3.14. JDO Enterprise Java Beans 2.x Facade

The files for this sample are located in the `samples/jdo/ejb` directory of the Kodo installation. This sample demonstrates how to use JDO with 2.x EJBs. It includes session beans that use JDO instead of EJB 2.x entity beans.

Prev | Up | Next
1.2. JPA | Home | Appendix 1. JPA Resources