001: /*
002: * Copyright (c) 2001 The Open For Business Project - www.ofbiz.org
003: *
004: * Permission is hereby granted, free of charge, to any person obtaining a
005: * copy of this software and associated documentation files (the "Software"),
006: * to deal in the Software without restriction, including without limitation
007: * the rights to use, copy, modify, merge, publish, distribute, sublicense,
008: * and/or sell copies of the Software, and to permit persons to whom the
009: * Software is furnished to do so, subject to the following conditions:
010: *
011: * The above copyright notice and this permission notice shall be included
012: * in all copies or substantial portions of the Software.
013: *
014: * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
015: * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
016: * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
017: * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
018: * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
019: * OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
020: * THE USE OR OTHER DEALINGS IN THE SOFTWARE.
021: */
022:
023: package org.ofbiz.entity.datasource;
024:
025: import java.util.Collection;
026: import java.util.List;
027: import java.util.Map;
028: import java.util.Set;
029:
030: import org.ofbiz.entity.GenericEntityException;
031: import org.ofbiz.entity.GenericPK;
032: import org.ofbiz.entity.GenericValue;
033: import org.ofbiz.entity.condition.EntityCondition;
034: import org.ofbiz.entity.model.ModelEntity;
035: import org.ofbiz.entity.model.ModelRelation;
036: import org.ofbiz.entity.util.EntityFindOptions;
037: import org.ofbiz.entity.util.EntityListIterator;
038:
039: /**
040: * Generic Entity Helper Class
041: *
042: *@author <a href="mailto:jonesde@ofbiz.org">David E. Jones</a>
043: *@author <a href='mailto:chris_maurer@altavista.com'>Chris Maurer</a>
044: *@version $ revision: $
045: *@since 1.0
046: */
047: public interface GenericHelper {
048:
049: /** Gets the name of the server configuration that corresponds to this helper
050: *@return server configuration name
051: */
052: public String getHelperName();
053:
054: /** Creates a Entity in the form of a GenericValue and write it to the database
055: *@return GenericValue instance containing the new instance
056: */
057: public GenericValue create(GenericValue value)
058: throws GenericEntityException;
059:
060: /** Find a Generic Entity by its Primary Key
061: *@param primaryKey The primary key to find by.
062: *@return The GenericValue corresponding to the primaryKey
063: */
064: public GenericValue findByPrimaryKey(GenericPK primaryKey)
065: throws GenericEntityException;
066:
067: /** Find a Generic Entity by its Primary Key and only returns the values requested by the passed keys (names)
068: *@param primaryKey The primary key to find by.
069: *@param keys The keys, or names, of the values to retrieve; only these values will be retrieved
070: *@return The GenericValue corresponding to the primaryKey
071: */
072: public GenericValue findByPrimaryKeyPartial(GenericPK primaryKey,
073: Set keys) throws GenericEntityException;
074:
075: /** Find a number of Generic Value objects by their Primary Keys, all at once
076: *@param primaryKeys A List of primary keys to find by.
077: *@return List of GenericValue objects corresponding to the passed primaryKey objects
078: */
079: public List findAllByPrimaryKeys(List primaryKeys)
080: throws GenericEntityException;
081:
082: /** Remove a Generic Entity corresponding to the primaryKey
083: *@param primaryKey The primary key of the entity to remove.
084: *@return int representing number of rows effected by this operation
085: */
086: public int removeByPrimaryKey(GenericPK primaryKey)
087: throws GenericEntityException;
088:
089: /** Finds Generic Entity records by all of the specified fields (ie: combined using AND)
090: *@param modelEntity The ModelEntity of the Entity as defined in the entity XML file
091: *@param fields The fields of the named entity to query by with their corresponging values
092: *@param orderBy The fields of the named entity to order the query by;
093: * optionally add a " ASC" for ascending or " DESC" for descending
094: *@return List of GenericValue instances that match the query
095: */
096: public List findByAnd(ModelEntity modelEntity, Map fields,
097: List orderBy) throws GenericEntityException;
098:
099: /** Finds Generic Entity records by all of the specified fields (ie: combined using OR)
100: *@param modelEntity The ModelEntity of the Entity as defined in the entity XML file
101: *@param fields The fields of the named entity to query by with their corresponging values
102: *@param orderBy The fields of the named entity to order the query by;
103: * optionally add a " ASC" for ascending or " DESC" for descending
104: *@return List of GenericValue instances that match the query
105: */
106: public List findByOr(ModelEntity modelEntity, Map fields,
107: List orderBy) throws GenericEntityException;
108:
109: /** Finds GenericValues by the conditions specified in the EntityCondition object, the the EntityCondition javadoc for more details.
110: *@param modelEntity The ModelEntity of the Entity as defined in the entity XML file
111: *@param entityCondition The EntityCondition object that specifies how to constrain this query
112: *@param fieldsToSelect The fields of the named entity to get from the database; if empty or null all fields will be retreived
113: *@param orderBy The fields of the named entity to order the query by; optionally add a " ASC" for ascending or " DESC" for descending
114: *@return List of GenericValue objects representing the result
115: */
116: public List findByCondition(ModelEntity modelEntity,
117: EntityCondition entityCondition, Collection fieldsToSelect,
118: List orderBy) throws GenericEntityException;
119:
120: public List findByMultiRelation(GenericValue value,
121: ModelRelation modelRelationOne, ModelEntity modelEntityOne,
122: ModelRelation modelRelationTwo, ModelEntity modelEntityTwo,
123: List orderBy) throws GenericEntityException;
124:
125: /** Finds GenericValues by the conditions specified in the EntityCondition object, the the EntityCondition javadoc for more details.
126: *@param modelEntity The ModelEntity of the Entity as defined in the entity XML file
127: *@param whereEntityCondition The EntityCondition object that specifies how to constrain this query before any groupings are done (if this is a view entity with group-by aliases)
128: *@param havingEntityCondition The EntityCondition object that specifies how to constrain this query after any groupings are done (if this is a view entity with group-by aliases)
129: *@param fieldsToSelect The fields of the named entity to get from the database; if empty or null all fields will be retreived
130: *@param orderBy The fields of the named entity to order the query by; optionally add a " ASC" for ascending or " DESC" for descending
131: *@param findOptions An instance of EntityFindOptions that specifies advanced query options. See the EntityFindOptions JavaDoc for more details.
132: *@return EntityListIterator representing the result of the query: NOTE THAT THIS MUST BE CLOSED WHEN YOU ARE
133: * DONE WITH IT, AND DON'T LEAVE IT OPEN TOO LONG BEACUSE IT WILL MAINTAIN A DATABASE CONNECTION.
134: */
135: public EntityListIterator findListIteratorByCondition(
136: ModelEntity modelEntity,
137: EntityCondition whereEntityCondition,
138: EntityCondition havingEntityCondition,
139: Collection fieldsToSelect, List orderBy,
140: EntityFindOptions findOptions)
141: throws GenericEntityException;
142:
143: public long findCountByCondition(ModelEntity modelEntity,
144: EntityCondition whereEntityCondition,
145: EntityCondition havingEntityCondition)
146: throws GenericEntityException;
147:
148: /** Removes/deletes Generic Entity records found by all of the specified fields (ie: combined using AND)
149: *@param modelEntity The ModelEntity of the Entity as defined in the entity XML file
150: *@param fields The fields of the named entity to query by with their corresponging values
151: *@return int representing number of rows effected by this operation
152: */
153: public int removeByAnd(ModelEntity modelEntity, Map fields)
154: throws GenericEntityException;
155:
156: /** Store the Entity from the GenericValue to the persistent store
157: *@param value GenericValue instance containing the entity
158: *@return int representing number of rows effected by this operation
159: */
160: public int store(GenericValue value) throws GenericEntityException;
161:
162: /** Store the Entities from the List GenericValue instances to the persistent store.
163: * This is different than the normal store method in that the store method only does
164: * an update, while the storeAll method checks to see if each entity exists, then
165: * either does an insert or an update as appropriate.
166: * These updates all happen in one transaction, so they will either all succeed or all fail,
167: * if the data source supports transactions. This is just like to othersToStore feature
168: * of the GenericEntity on a create or store.
169: *@param values List of GenericValue instances containing the entities to store
170: *@return int representing number of rows effected by this operation
171: */
172: public int storeAll(List values) throws GenericEntityException;
173:
174: /** Remove the Entities from the List from the persistent store.
175: * <br>The List contains GenericEntity objects, can be either GenericPK or GenericValue.
176: * <br>If a certain entity contains a complete primary key, the entity in the datasource corresponding
177: * to that primary key will be removed, this is like a removeByPrimary Key.
178: * <br>On the other hand, if a certain entity is an incomplete or non primary key,
179: * if will behave like the removeByAnd method.
180: * <br>These updates all happen in one transaction, so they will either all succeed or all fail,
181: * if the data source supports transactions.
182: *@param dummyPKs List of GenericEntity instances containing the entities or by and fields to remove
183: *@return int representing number of rows effected by this operation
184: */
185: public int removeAll(List dummyPKs) throws GenericEntityException;
186:
187: /** Check the datasource to make sure the entity definitions are correct, optionally adding missing entities or fields on the server
188: *@param modelEntities Map of entityName names and ModelEntity values
189: *@param messages List to put any result messages in
190: *@param addMissing Flag indicating whether or not to add missing entities and fields on the server
191: */
192: public void checkDataSource(Map modelEntities, List messages,
193: boolean addMissing) throws GenericEntityException;
194: }
|