001 /*
002 * Copyright 2003-2004 The Apache Software Foundation.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017 package org.apache.commons.mapper;
018
019 import java.util.Collection;
020
021 /**
022 * A Mapper is responsible for mapping domain objects to a persistent data store.
023 * By removing this functionality from the domain objects, the backend
024 * datastore implementation is allowed to change without affecting any domain
025 * objects. Examples of Mapper implementations include JdbcMapper, EjbMapper,
026 * and JdoMapper which store data using their respective technologies.
027 * <p>
028 * Additionally, Mappers decouple your application from the underlying mapping
029 * technology. You might use JdbcMappers for a small website and then migrate
030 * to EjbMappers as the site grows without your application code changing.
031 * <p>
032 * Mapper implementations should not use instance variables to maintain state
033 * because they will be run in a multi-threaded environment. The MapperFactory
034 * will return the same instance of a Mapper every time it's requested. Mappers
035 * should use local method variables and method parameters to maintain thread
036 * safety.
037 * <p>
038 * Mapper is equivalent to the concept of a data access object (DAO).
039 *
040 * @see MapperFactory
041 */
042 public interface Mapper {
043
044 /**
045 * Create the given object in a persistent data store. The
046 * Mapper should document what type of Object is expected.
047 * @return Object the created object's unique id.
048 * @throws MapperException
049 * @throws UnsupportedOperationException if this mapper doesn't support this
050 * method.
051 */
052 Object create(Object object) throws MapperException;
053
054 /**
055 * Find the given Object based on its unique identifier. This could be a primary
056 * key for relational database backends or an ID field in an XML file for XML
057 * implementations. The Mapper should document what type of object is
058 * expected and what type it returns.
059 * @param id An Object that represents a unique ID or a container for
060 * composite key values.
061 * @return Object a single object with the given id or null if none found
062 * @throws MapperException
063 * @throws UnsupportedOperationException if this mapper doesn't support this
064 * method.
065 */
066 Object findByUniqueId(Object id) throws MapperException;
067
068 /**
069 * Remove an object from the data store.
070 * @throws MapperException
071 * @throws UnsupportedOperationException if this mapper doesn't support this
072 * method.
073 */
074 void delete(Object object) throws MapperException;
075
076 /**
077 * Update the given object in the data store.
078 * @throws MapperException
079 * @throws UnsupportedOperationException if this mapper doesn't support this
080 * method.
081 */
082 void update(Object object) throws MapperException;
083
084 /**
085 * Returns a Collection of all objects for the given mapper.
086 * @throws MapperException
087 * @throws UnsupportedOperationException if this mapper doesn't support this
088 * method.
089 */
090 Collection findAllObjects() throws MapperException;
091
092 }