You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by dg...@apache.org on 2003/09/09 02:51:39 UTC
cvs commit: jakarta-commons-sandbox/mapper/xdocs index.xml
dgraham 2003/09/08 17:51:39
Modified: mapper/xdocs index.xml
Log:
Added more info and examples.
Revision Changes Path
1.2 +89 -12 jakarta-commons-sandbox/mapper/xdocs/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/mapper/xdocs/index.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- index.xml 8 Sep 2003 04:37:27 -0000 1.1
+++ index.xml 9 Sep 2003 00:51:39 -0000 1.2
@@ -3,7 +3,7 @@
<document>
<properties>
- <title>Mapper: Data Mapping Abstraction Component</title>
+ <title>Data Mapping Abstraction Component</title>
<author email="dgraham@apache.org">David Graham</author>
</properties>
@@ -11,7 +11,7 @@
<section name="Mapper: Data Mapping Abstraction Component">
-<section name="Rationale">
+<section name="Purpose">
<p>
Most Java applications must store data to a data store whether it's XML files or
@@ -47,22 +47,62 @@
Commons Mapper is <strong>not</strong> a data mapping implementation. It is meant
to be an API allowing pluggable mapper objects of varying implementations.
</p>
+<p>
+The package also contains well factored JDBC helper classes that reduce the burden
+of using JDBC as a data mapping tool. This functionality could be placed in a
+different package if needed.
+</p>
+
+</section>
+
+<section name="Interaction With Other Packages">
+ <p>Commons Mapper relies on the standard JDK 1.2 (or later) APIs.</p>
+</section>
+
+<section name="Example Usage">
+<p>
+Commons Mapper is based on the idea of groups of mappers and a
+<code><a href="apidocs/org/apache/commons/mapper/MapperFactory.html">MapperFactory</a></code>.
+Mappers are responsible for persisting one kind
+of Object to a data store. MapperFactory is responsible for dynamically loading
+and initializing Mappers for the client code. Typically, a .properties file is
+used to map domain class names to mapper implementation class names and passed to
+a new MapperFactory instance.
+</p>
<p>
-All mappers must implement the <code>Mapper</code> interface.
-<code>MapperFactory</code> is the main object in the framework. It allows clients
-to lookup <code>Mapper</code> implementations without them knowing the underlying
-type.
+All mappers must implement the <code><a href="apidocs/org/apache/commons/mapper/Mapper.html">Mapper</a></code>
+interface. The majority of mapping work can be accomplished through the methods in this
+interface with specialized methods added to specific Mappers as needed.
</p>
<pre>
- // Setup MapperFactory (this is best done in a .properties file).
+ // 1. Setup MapperFactory (this is best done with a .properties file).
// The keys in the file are fully qualified class names of objects to
// persist. The values are the fully qualified class names of the Mapper
- // objects.
+ // objects.
+
+ // Note: The keys can actually be anything you want; however, by using
+ // fully qualified class names, you can use the Object.class shortcut
+ // notation to lookup Mappers with MapperFactory.getMapper() as shown in
+ // step 3.
+
Map mappers = new HashMap();
mappers.add("com.yourcorp.Person", "com.yourcorp.PersonMapper");
MapperFactory factory = new MapperFactory(mappers);
+
+ // 2. Add a factory listener that will initialize Mapper instances as
+ // they are created. This allows you to initialize any number of Mapper
+ // types without subclassing MapperFactory and using an ugly if/else
+ // statement.
+
+ MapperFactoryListener listener =
+ new JdbcMapperFactoryListener(dataSource);
+ factory.addMapperFactoryListener(listener);
+ // 3. Persist object with a dynamically loaded Mapper implementation.
+ // The factory will return a com.yourcorp.PersonMapper object
+ // (which was defined in the Map) to do the persistence.
+
Person p = new Person("Joe", "User");
Mapper m = factory.getMapper(Person.class);
m.create(p);
@@ -70,13 +110,50 @@
</section>
-
-<section name="Interaction With Other Packages">
-
+<section name="JDBC Utilities">
<p>
-Commons Mapper relies on the standard JDK 1.2 (or later) APIs.
+The other component in Commons Mapper is a set of JDBC helper classes and interfaces.
+Using these classes has several advantages:
</p>
+<ul>
+ <li>
+ No possibility for resource leaks. Correct JDBC coding isn't difficult but
+ it is time-consuming and tedious. This often leads to connection leaks that may
+ be difficult to track down.
+ </li>
+ <li>
+ Cleaner, clearer persistence code. The amount of code needed to persist objects
+ in a database is drastically reduced. The remaining code clearly expresses your
+ intention without being cluttered with resource cleanup.
+ </li>
+</ul>
+</section>
+<section name="JDBC Example">
+ <p>
+ This code could be part of a JdbcPersonMapper class that you write
+ to perist Person objects in your application.
+ </p>
+ <pre>
+ // Define a ResultSetProcessor instance to create Person objects
+ private static final ResultSetProcessor makePerson =
+ new ResultSetRowProcessor() {
+ public Object processRow(ResultSet rs) {
+ Person p = new Person();
+ p.setFirstName(rs.getString("firstName"));
+ // set other properties from ResultSet...
+
+ return p;
+ }
+ };
+
+ // Implement findAllObjects from the Mapper interface with a one
+ // line call to a JdbcHelper instance. No connections, statements,
+ // or cleanup required!
+ public Collection findAllObjects() {
+ return this.helper.executeQuery(this.getQuery("person.findAll"), makePerson);
+ }
+ </pre>
</section>