commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject cvs commit: jakarta-commons-sandbox/mapper/xdocs index.xml
Date Tue, 09 Sep 2003 00:51:39 GMT
dgraham     2003/09/08 17:51:39

  Modified:    mapper/xdocs index.xml
  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 @@
  -  <title>Mapper: Data Mapping Abstraction Component</title>
  +  <title>Data Mapping Abstraction Component</title>
     <author email="">David Graham</author>
  @@ -11,7 +11,7 @@
   <section name="Mapper: Data Mapping Abstraction Component">
  -<section name="Rationale">
  +<section name="Purpose">
   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
   to be an API allowing pluggable mapper objects of varying implementations.
  +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.
  +<section name="Interaction With Other Packages">
  +    <p>Commons Mapper relies on the standard JDK 1.2 (or later) APIs.</p>
  +<section name="Example Usage">
  +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.
  -All mappers must implement the <code>Mapper</code> interface.
  -<code>MapperFactory</code> is the main object in the framework.  It allows
  -to lookup <code>Mapper</code> implementations without them knowing the underlying
  +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.
  -    // 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);
  @@ -70,13 +110,50 @@
  -<section name="Interaction With Other Packages">
  +<section name="JDBC Utilities">
  -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:
  +	<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>
  +<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>

View raw message