001: /*
002: * $Header: /export/home/cvsroot/MyPersonalizerRepository/MyPersonalizer/Subsystems/Kernel/Sources/es/udc/mypersonalizer/kernel/model/repository/sql/storers/PropertyStorageStrategy.java,v 1.1.1.1 2004/03/25 12:08:36 fbellas Exp $
003: * $Revision: 1.1.1.1 $
004: * $Date: 2004/03/25 12:08:36 $
005: *
006: * =============================================================================
007: *
008: * Copyright (c) 2003, The MyPersonalizer Development Group
009: * (http://www.tic.udc.es/~fbellas/mypersonalizer/index.html) at
010: * University Of A Coruna
011: * All rights reserved.
012: *
013: * Redistribution and use in source and binary forms, with or without
014: * modification, are permitted provided that the following conditions are met:
015: *
016: * - Redistributions of source code must retain the above copyright notice,
017: * this list of conditions and the following disclaimer.
018: *
019: * - Redistributions in binary form must reproduce the above copyright notice,
020: * this list of conditions and the following disclaimer in the documentation
021: * and/or other materials provided with the distribution.
022: *
023: * - Neither the name of the University Of A Coruna nor the names of its
024: * contributors may be used to endorse or promote products derived from
025: * this software without specific prior written permission.
026: *
027: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
028: * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
029: * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
030: * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
031: * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
032: * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
033: * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
034: * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
035: * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
036: * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
037: * POSSIBILITY OF SUCH DAMAGE.
038: *
039: */
040:
041: package es.udc.mypersonalizer.kernel.model.repository.sql.storers;
042:
043: import java.util.Map;
044: import java.util.List;
045: import java.sql.Connection;
046:
047: import es.udc.mypersonalizer.kernel.model.metainfo.MetaService;
048: import es.udc.mypersonalizer.kernel.model.properties.Property;
049: import es.udc.mypersonalizer.kernel.util.exceptions.DuplicateInstanceException;
050: import es.udc.mypersonalizer.kernel.util.exceptions.InstanceNotFoundException;
051: import es.udc.mypersonalizer.kernel.util.exceptions.InternalErrorException;
052:
053: /**
054: * This interface specifies a strategy ("strategy" desing pattern) to access
055: * and maniputate properties on the database. A property is identified by a
056: * <code>Map</code>, mapping <code>String</code>s to <code>Object</code>s.
057: * The <code>String</code>s make up the key, and the <code>Object</code>s
058: * are their values. This feature allows to use strings or numbers as values
059: * for key fields. If fact, the values of the keys can only be one of the
060: * following ones: java.lang.Byte, java.lang.Short, java.lang.Integer,
061: * java.lang.Float, java.lang.Double and java.lang.String. No check will
062: * be done.
063: * <p>
064: * A "storer" class will retrieve the policy to be used by means of
065: * <code>PropertyStorageStrategyRegistrySingleton</code>, and will delegate
066: * on it in order to access or manipulate the corresponding property.
067: *
068: * @author Fernando Bellas
069: * @since 1.0
070: */
071: public interface PropertyStorageStrategy {
072:
073: /**
074: * Extracts a property identified by its key from the database.
075: *
076: * @param connection the connection to the database
077: * @param key the map with the key columns and their corresponding values
078: * @return the <code>Property</code> extracted from the result set
079: * @throws InternalErrorException if a failure is detected.
080: * @throws IntanceNotFoundException if the property identified by the key does
081: * not exist
082: */
083: Property findProperty(Connection connection, Map key)
084: throws InternalErrorException, InstanceNotFoundException;
085:
086: /**
087: * Extracts a property range by using the key fields.
088: *
089: * @param connection the connection to the database
090: * @param keys the key columns as a list of <code>String</code>s
091: * @param offset the number of initial properties to be skipped. This
092: * parameter must be greather or equals than 0
093: * @param size the number of properties to be extracted
094: * @return the property range as a map of (<code>Map, Property</code>).
095: * The map contains the key fields and their values for each
096: * property. If the map size is less than the parameter "size"
097: * that means that there are no more properties to read.
098: * @throws InternalErrorException if a failure is detected.
099: */
100: Map findPropertiesByRange(Connection connection, List keys,
101: int offset, int size) throws InternalErrorException;
102:
103: /**
104: * Updates a property identified by its key from the database.
105: *
106: * @param connection the connection to the database
107: * @param key the map with the key columns and their corresponding values
108: * @param property the property to be updated
109: * @throws InternalErrorException if a failure is detected.
110: * @throws InstanceNotFoundException if the property identified by the key does
111: * not exist
112: */
113: void updateProperty(Connection connection, Map key,
114: Property property) throws InternalErrorException,
115: InstanceNotFoundException;
116:
117: /**
118: * Adds a property identified by its key from the database.
119: *
120: * @param connection the connection to the database
121: * @param key the map with the key columns and their corresponding values
122: * @param property the property to be inserted
123: * @throws InternalErrorException if a failure is detected.
124: * @throws DuplicateInstanceException if there already existed a property with
125: * such a key
126: */
127: void addProperty(Connection connection, Map key, Property property)
128: throws InternalErrorException, DuplicateInstanceException;
129:
130: /**
131: * Removes the property identified by a given key from the database.
132: *
133: * @param connection the connection to the database
134: * @param key the map with the key columns and their corresponding values
135: * @throws InternalErrorException if a failure is detected.
136: * @throws InstanceNotFoundException if the property identified by the key does
137: * not exist
138: */
139: void removeProperty(Connection connection, Map key)
140: throws InternalErrorException, InstanceNotFoundException;
141:
142: /**
143: * Sets the metainformation needed for the strategy to work.
144: * @param metainfo the Meatinformation needed.
145: */
146: void setMetainfo(MetaService metainfo);
147: }
|