001: /**
002: * Copyright (C) 2006 NetMind Consulting Bt.
003: *
004: * This library is free software; you can redistribute it and/or
005: * modify it under the terms of the GNU Lesser General Public
006: * License as published by the Free Software Foundation; either
007: * version 3 of the License, or (at your option) any later version.
008: *
009: * This library is distributed in the hope that it will be useful,
010: * but WITHOUT ANY WARRANTY; without even the implied warranty of
011: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012: * Lesser General Public License for more details.
013: *
014: * You should have received a copy of the GNU Lesser General Public
015: * License along with this library; if not, write to the Free Software
016: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
017: */package hu.netmind.persistence;
018:
019: import java.util.Map;
020: import java.sql.Connection;
021: import java.util.List;
022: import hu.netmind.persistence.parser.QueryStatement;
023:
024: /**
025: * All database implementations must adhere to this specification.
026: * To support a specific database, the abstract methods of this class must be
027: * implemented and the class added to the database factory (source).<br>
028: * The following issues must be handled by implementation:
029: * <ul>
030: * <li>Implementation may provide run-time optimalization of database
031: * configuration, indexes, tablespaces as long as it keeps all data
032: * intact and available as before.</li>
033: * </ul>
034: * @author Brautigam Robert
035: * @version Revision: $Revision$
036: */
037: public interface DatabaseImplementation {
038: /**
039: * Releases all resources held by the database implementation.
040: * @param source The connection source which can be used to communicate
041: * for the last time with the database server. Allocated connections should
042: * not be closed, the caller will handle that.
043: */
044: void release(ConnectionSource source);
045:
046: /**
047: * Modifies an object already in database with given fields.
048: * @param tableName The table to save attributes to.
049: * @param id The id of object to save (All object entries have an id).
050: * @param attributes The attributes in form of name:value pairs.
051: */
052: DatabaseStatistics save(Connection connection, String tableName,
053: Map keys, Map attributes);
054:
055: /**
056: * Insert an object into the database.
057: * @param tableName The table to save attributes to.
058: * @param attributes The attributes in form of name:value pairs.
059: */
060: DatabaseStatistics insert(Connection connection, String tableName,
061: Map attributes);
062:
063: /**
064: * Remove an entry from database.
065: * @param tableName The table to remove object from.
066: * @param attributes The attributes which identify the object.
067: * Equality is assumed with each attribute and it's value.
068: */
069: DatabaseStatistics remove(Connection connection, String tableName,
070: Map attributes);
071:
072: /**
073: * Ensure that table exists in database. It is the responsibility of
074: * the implementation to ensure that the named table with given
075: * parameters exists. If the table exists, but is not defined
076: * as in 'attributeTypes', the implementation <strong>must</strong>
077: * retain all common attributes during the re-structuring of that
078: * table. Of course, if no common attributes exist, the implementation
079: * is free to drop the table and recreate it.<br>
080: * In every database, the field named 'persistence_id' is the primary
081: * key if it exists, or no primary key if the attributeTypes do not
082: * contain it.<br>
083: * All columns will be indexed by default.
084: * @param tableName The table to check.
085: * @param attributeTypes The attribute names together with which
086: * java class they should hold.
087: * @param create If true, create table physically, if false, only
088: * update internal representations, but do not create table.
089: */
090: DatabaseStatistics ensureTable(Connection connection,
091: String tableName, Map attributeTypes,
092: List keyAttributeNames, boolean create);
093:
094: /**
095: * Select objects from database as ordered list of attribute maps.
096: * @param connection The connection to use.
097: * @param stmt The query statement.
098: * @param limits The limits of the result. (Offset, maximum result count)
099: * @param result The result object. It will be filled with data.
100: */
101: DatabaseStatistics search(Connection connection,
102: QueryStatement stmt, Limits limits, SearchResult result);
103: }
|