// Licensed to the Apache Software Foundation (ASF) under one

// or more contributor license agreements. See the NOTICE file

// distributed with this work for additional information

// regarding copyright ownership. The ASF licenses this file

// to you under the Apache License, Version 2.0 (the

// "License"); you may not use this file except in compliance

// 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 com.cloud.utils.db;

import java.io.Serializable;

import java.util.List;

import java.util.Map;

import javax.naming.ConfigurationException;

import com.cloud.utils.Pair;

/**

* 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);

// Finds one unique VO using uuid

T findByUuid(String uuid);

// Finds one unique VO using uuid including removed entities

T findByUuidIncludingRemoved(String uuid);

/**

* @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);

/**

* @return

*/

Class<T> getEntityBeanType();

public int getRegionId();

/**

* @param sc

* @param filter

* @return

*/

Pair<List<T>, Integer> searchAndCount(SearchCriteria<T> sc, Filter filter);

}