/*

  * Copyright 2003-2004 The Apache Software Foundation.

  * 

  * Licensed under the Apache License, Version 2.0 (the "License");

  * you may not use this file except in compliance with the License.

  * You may obtain a copy of the License at

  * 

  *      http://www.apache.org/licenses/LICENSE-2.0

  * 

  * Unless required by applicable law or agreed to in writing, software

  * distributed under the License is distributed on an "AS IS" BASIS,

  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

  * See the License for the specific language governing permissions and

  * limitations under the License.

  */

 package org.apache.commons.mapper;

 import java.util.Collection;

 /**

  * A Mapper is responsible for mapping domain objects to a persistent data store.

  * By removing this functionality from the domain objects, the backend

  * datastore implementation is allowed to change without affecting any domain 

  * objects.  Examples of Mapper implementations include JdbcMapper, EjbMapper, 

  * and JdoMapper which store data using their respective technologies.

  * <p>

  * Additionally, Mappers decouple your application from the underlying mapping 

  * technology.  You might use JdbcMappers for a small website and then migrate 

  * to EjbMappers as the site grows without your application code changing.

  * <p>

  * Mapper implementations should not use instance variables to maintain state 

  * because they will be run in a multi-threaded environment.  The MapperFactory 

  * will return the same instance of a Mapper every time it's requested.  Mappers 

  * should use local method variables and method parameters to maintain thread 

  * safety.

  * <p>

  * Mapper is equivalent to the concept of a data access object (DAO).

  * 

  * @see MapperFactory

  */

 public interface Mapper {

     /**

      * Create the given object in a persistent data store.  The 

      * Mapper should document what type of Object is expected.

      * @return Object the created object's unique id.

      * @throws MapperException

      * @throws UnsupportedOperationException if this mapper doesn't support this 

      * method.

      */

     Object create(Object object) throws MapperException;

     /**

      * Find the given Object based on its unique identifier.  This could be a primary 

      * key for relational database backends or an ID field in an XML file for XML 

      * implementations.  The Mapper should document what type of object is 

      * expected and what type it returns.

      * @param id An Object that represents a unique ID or a container for 

      * composite key values.

      * @return Object a single object with the given id or null if none found

      * @throws MapperException

      * @throws UnsupportedOperationException if this mapper doesn't support this 

      * method.

      */

     Object findByUniqueId(Object id) throws MapperException;

     /**

      * Remove an object from the data store.

      * @throws MapperException

      * @throws UnsupportedOperationException if this mapper doesn't support this 

      * method.

      */

     void delete(Object object) throws MapperException;

     /**

      * Update the given object in the data store.

      * @throws MapperException

      * @throws UnsupportedOperationException if this mapper doesn't support this 

      * method.

      */

     void update(Object object) throws MapperException;

     /**

      * Returns a Collection of all objects for the given mapper.

      * @throws MapperException

      * @throws UnsupportedOperationException if this mapper doesn't support this 

      * method.

      */

     Collection findAllObjects() throws MapperException;

 }