// Copyright 2012 Citrix Systems, Inc. Licensed under the
// Apache License, Version 2.0 (the "License"); you may not use this
// file except in compliance with the License. Citrix Systems, Inc.
// reserves all rights not expressly granted by 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.
//
// Automatically generated by addcopyright.py at 04/03/2012
package com.cloud.utils.db;
import java.io.Serializable;
import java.util.List;
import java.util.Map;
import javax.naming.ConfigurationException;
/**
* a uniform method for persisting and finding db entities.
**/
public interface GenericDao<T, ID extends Serializable> {
/**
*/
static final String REMOVED_COLUMN = "cloud_removed";
static final String REMOVED = "removed";
/**
* This column can be used if the table wants to track creation time.
*/
static final String CREATED_COLUMN = "created";
/**
*/
static final String XID_COLUMN = "xid";
/**
* Look for an entity bean using the database id. Does not lock the row.
* @param id database unique id for the entity bean.
* @return entity bean.
**/
T findById(ID id);
T findByIdIncludingRemoved(ID id);
T findById(ID id, boolean fresh);
/**
* @return VO object ready to be used for update. It won't have any fields filled in.
*/
T createForUpdate();
SearchBuilder<T> createSearchBuilder();
<K> GenericSearchBuilder<T, K> createSearchBuilder(Class<K> clazz);
T createForUpdate(ID id);
/**
* Returns a SearchCriteria object that can be used to build search conditions.
*
* @return SearchCriteria
*/
SearchCriteria<T> createSearchCriteria();
/**
* lock the rows that matched the search criteria and filter. This method needs
* to be called within a transaction.
*
* @param sc SearchCriteria containing the different search conditions
* @param filter Filter containing limits etc
* @param exclusive exclusive or share lock
* @return List<T> list of entity beans
*/
List<T> lockRows(SearchCriteria<T> sc, Filter filter, boolean exclusive);
/**
* lock 1 of the return set. This method needs to be run within a
* transaction or else it's useless.
* @param sc
* @param exclusive
* @return T if found and locked. null if not.
*/
T lockOneRandomRow(SearchCriteria<T> sc, boolean exclusive);
/**
* Find and lock the row for update.
* @param id id
* @param exclusive is this a read share lock or exclusive lock?
* @return T
*/
T lockRow(ID id, Boolean exclusive);
/**
* Acquires a database wide lock on the id of the entity. This ensures
* that only one is being used. The timeout is the configured default.
*
* @param id id of the entity to acquire an lock on.
* @return object if acquired; null if not. If null, you need to call findById to see if it is actually not found.
*/
T acquireInLockTable(ID id);
/**
* Acquires a database wide lock on the id of the entity. This ensures
* that only one is being used. The timeout is the configured default.
*
* @param id id of the entity to acquire an lock on.
* @param seconds time to wait for the lock.
* @return entity if the lock is acquired; null if not.
*/
T acquireInLockTable(ID id, int seconds);
/**
* releases the lock acquired in the acquire method call.
* @param id id of the entity to release the lock on.
* @return true if it is released. false if not or not found.
*/
boolean releaseFromLockTable(final ID id);
boolean update(ID id, T entity);
/**
* Look for all active rows.
* @return list of entity beans.
*/
List<T> listAll();
/**
* Look for all active rows.
* @param filter filter to limit the results
* @return list of entity beans.
*/
List<T> listAll(Filter filter);
/**
* Search for the entity beans
* @param sc
* @param filter
* @return list of entity beans.
*/
List<T> search(SearchCriteria<T> sc, Filter filter);
/**
* Search for the entity beans using the sql SQL_CACHE option
* @param sc
* @param filter
* @param enable_query_cache
* @return list of entity beans.
*/
List<T> search(SearchCriteria<T> sc, Filter filter, final boolean enable_query_cache);
List<T> searchIncludingRemoved(SearchCriteria<T> sc, final Filter filter, final Boolean lock, final boolean cache);
List<T> searchIncludingRemoved(SearchCriteria<T> sc, final Filter filter, final Boolean lock, final boolean cache, final boolean enable_query_cache);
/**
* Customized search with SearchCritiria
* @param sc
* @param filter
* @return list of entity beans.
*/
public <M> List<M> customSearchIncludingRemoved(SearchCriteria<M> sc, Filter filter);
/**
* Retrieves the entire table.
* @return collection of entity beans.
**/
List<T> listAllIncludingRemoved();
/**
* Retrieves the entire table.
* @param filter filter to limit the returns.
* @return collection of entity beans.
**/
List<T> listAllIncludingRemoved(Filter filter);
/**
* Persist the entity bean. The id field of the entity is updated with
* the new id.
* @param entity the bean to persist.
* @return The persisted version of the object. A null is returned if
* there's no primary key specified in the VO object.
**/
T persist(T entity);
/**
* remove the entity bean. This will call delete automatically if
* the entity bean does not have a removed field.
* @param id
* @return true if removed.
*/
boolean remove(ID id);
/**
* Remove based on the search criteria. This will delete if the VO object
* does not have a REMOVED column.
* @param sc search criteria to match
* @return rows removed.
*/
int remove(SearchCriteria<T> sc);
/**
* Expunge actually delete the row even if it's REMOVED.
* @param id
* @return true if removed.
*/
boolean expunge(ID id);
/**
* remove the entity bean specified by the search criteria
* @param sc
* @return number of rows deleted
*/
int expunge(final SearchCriteria<T> sc);
/**
* expunge the removed rows.
*/
void expunge();
public <K> K getNextInSequence(Class<K> clazz, String name);
/**
* Configure.
* @param name name of the dao.
* @param params params if any are specified.
* @return true if config is good. false if not.
*/
boolean configure(String name, Map<String, Object> params) throws ConfigurationException;
<M> List<M> customSearch(SearchCriteria<M> sc, Filter filter);
boolean lockInLockTable(String id);
boolean lockInLockTable(String id, int seconds);
boolean unlockFromLockTable(String id);
public <K> K getRandomlyIncreasingNextInSequence(Class<K> clazz, String name);
<K> SearchCriteria2 createSearchCriteria2(Class<K> resultType);
SearchCriteria2 createSearchCriteria2();
public T findOneBy(final SearchCriteria<T> sc);
}