DataMapper 1.0

Bobby Woolf, 07/01/2000

The DataMapper is a tool to convert formatted stream data into Java domain objects and vice versa. It is commonly used to read records from a file into Java as objects, and to write similar objects back out to a new file. It is designed to allow developers to easily describe the mappings between the data format and the object model, and will then use those mappings to do all of work.

The DataMapper facilitates exchanging data with legacy applications that do not support newer data transfer technologies like Java object serialization, Corba, and XML. The data is often transferred between applications via a messaging system such as MQSeries from IBM or another that implements the Java Message Service API.

• Contents
• *** Downloading ***
• Installation
• Getting Started
• Documentation
• Extending the DataMapper
• License

Contents of the Release

Installation

To install the DataMapper:

1. Unzip the datamapper.zip file.
2. Add dm.jar to the CLASSPATH. For example: set classpath=%classpath%;INSTALL_DIR\lib\dm.jar
3. To test the DataMapper, run JUnit on the DataMapperTestCase class. All of the tests should pass OK. For example: java junit.swingui.LoadingTestRunner bw.dm.test.DataMapperTestCase

Getting Started

To get started with using the DataMapper, read the cookbook. It walks through the major features of the DataMapper and the considerations for which ones to use when. Also look at the *Example files in the bw.dm.test package, also included in the examples directory.

Documentation

Extending the DataMapper

The DataMapper is designed to be highly extensible. It is pattern dense, so to understand its implementation, it helps to be familiar with the patterns in Design Patterns: Elements of Reusable Object-Oriented Software by Gamma, Helm, Johnson, and Vlissides.

There are numerous aspects of the DataMapper one might wish to extend. The meat of the DataMapper is implemented in bw.dm.impl; these classes aren't really ment to be used directly, but are public so that they can easily be subclassed.

Extensions clients frequently make to the DataMapper include:

• Custom implementations of bw.util.TypeConverter to handle their own simple objects.
• Custom implementations of bw.dm.ExceptionHandler and bw.dm.ExceptionLog to handle exceptions.
• Custom implementations of bw.dm.CompositeFieldFormat and bw.dm.impl.ProtocolAdapter/bw.dm.impl.FieldFormatAdapter to handle new types of storage objects.
• Custom extensions of bw.dm.impl.LeafFieldFormatDescription to handle new ways to read a field. The destire to handle CSV files lead to a new LeafFieldFormatDescription subclass that became QuotedFieldFormatDescription.
• Custom bw.dm.builders.FormatMapBuilder subclasses that make it easier to use all of the other new stuff.

In short, describing the DataMapper's design, implementation, patterns, and how to extend it would require a whole new set of documentation that hasn't been writen yet. In the meantime, this information can be inferred from the Javadocs, by reverse engineering the code into a design/UML tool, and by browsing the code.