org.opencastproject.db.DBSession Maven / Gradle / Ivy
/*
* Licensed to The Apereo Foundation under one or more contributor license
* agreements. See the NOTICE file distributed with this work for additional
* information regarding copyright ownership.
*
*
* The Apereo Foundation licenses this file to you under the Educational
* Community License, Version 2.0 (the "License"); you may not use this file
* except in compliance with the License. You may obtain a copy of the License
* at:
*
* http://opensource.org/licenses/ecl2.txt
*
* 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 org.opencastproject.db;
import org.opencastproject.util.function.ThrowingConsumer;
import org.opencastproject.util.function.ThrowingFunction;
import java.util.function.Consumer;
import java.util.function.Function;
import javax.persistence.EntityManager;
/**
* DBSession implements common DB query execution handlers.
*/
public interface DBSession extends AutoCloseable {
/**
* Execute given function without opening a new transaction. It should be assumed that the EntityManager was newly
* created.
*
* @param fn Function to execute.
*/
void exec(Consumer fn);
/**
* Execute given function that can throw a checked exception without opening a new transaction. It should be assumed
* that the EntityManager was newly created.
*
* @param fn Function to execute.
* @param Exception type that could be thrown by fn.
* @throws E Exception thrown by fn.
*/
void execChecked(ThrowingConsumer fn) throws E;
/**
* Execute given function without opening a new transaction. It should be assumed that the EntityManager was newly
* created. The return value of given function is returned.
*
* @param fn Function to execute.
* @return Object fn has returned.
* @param Return type of fn.
*/
T exec(Function fn);
/**
* Execute given function that can throw a checked exception without opening a new transaction. It should be assumed
* that the EntityManager was newly created. The return value of given function is returned.
*
* @param fn Function to execute.
* @return Object fn has returned.
* @param Return type of fn.
* @param Exception type that could be thrown by fn.
* @throws E Exception thrown by fn.
*/
T execChecked(ThrowingFunction fn) throws E;
/**
* Execute given function within a transaction. There can only be a single transaction per DBSession object. It should
* be assumed that the EntityManager and transaction are reused if this method is executed again. Further, should be
* assumed that fn could be executed multiple times if the transaction fails and should be retried.
*
* @param fn Function to execute.
*/
void execTx(Consumer fn);
/**
* Execute given function that can throw a checked exception within a transaction. There can only be a single
* transaction per DBSession object. It should be assumed that the EntityManager and transaction are reused if this
* method is executed again. Further, should be assumed that fn could be executed multiple times if the transaction
* fails and should be retried.
*
* @param fn Function to execute.
* @param Exception type that could be thrown by fn.
* @throws E Exception thrown by fn.
*/
void execTxChecked(ThrowingConsumer fn) throws E;
/**
* Execute given function within a transaction. There can only be a single transaction per DBSession object. It should
* be assumed that the EntityManager and transaction are reused if this method is executed again. Further, should be
* assumed that fn could be executed multiple times if the transaction fails and should be retried.
*
* @param maxTransactionRetries Maximal number of times fn can be executed again in case of transaction errors.
* @param fn Function to execute.
*/
void execTx(int maxTransactionRetries, Consumer fn);
/**
* Execute given function that can throw a checked exception within a transaction. There can only be a single
* transaction per DBSession object. It should be assumed that the EntityManager and transaction are reused if this
* method is executed again. Further, should be assumed that fn could be executed multiple times if the transaction
* fails and should be retried.
*
* @param maxTransactionRetries Maximal number of times fn can be executed again in case of transaction errors.
* @param fn Function to execute.
* @param Exception type that could be thrown by fn.
* @throws E Exception thrown by fn.
*/
void execTxChecked(int maxTransactionRetries, ThrowingConsumer fn) throws E;
/**
* Execute given function within a transaction. There can only be a single transaction per DBSession object. It should
* be assumed that the EntityManager and transaction are reused if this method is executed again. Further, should be
* assumed that fn could be executed multiple times if the transaction fails and should be retried. The return value
* of given function is returned.
*
* @param fn Function to execute.
* @return Object fn has returned.
* @param Return type of fn.
*/
T execTx(Function fn);
/**
* Execute given function that can throw a checked exception within a transaction. There can only be a single
* transaction per DBSession object. It should be assumed that the EntityManager and transaction are reused if this
* method is executed again. Further, should be assumed that fn could be executed multiple times if the transaction
* fails and should be retried. The return value of given function is returned.
*
* @param fn Function to execute.
* @return Object fn has returned.
* @param Return type of fn.
* @param Exception type that could be thrown by fn.
* @throws E Exception thrown by fn.
*/
T execTxChecked(ThrowingFunction fn) throws E;
/**
* Execute given function within a transaction. There can only be a single transaction per DBSession object. It should
* be assumed that the EntityManager and transaction are reused if this method is executed again. Further, should be
* assumed that fn could be executed multiple times if the transaction fails and should be retried. The return value
* of given function is returned.
*
* @param maxTransactionRetries Maximal number of times fn can be executed again in case of transaction errors.
* @param fn Function to execute.
* @return Object fn has returned.
* @param Return type of fn.
*/
T execTx(int maxTransactionRetries, Function fn);
/**
* Execute given function that can throw a checked exception within a transaction. There can only be a single
* transaction per DBSession object. It should be assumed that the EntityManager and transaction are reused if this
* method is executed again. Further, should be assumed that fn could be executed multiple times if the transaction
* fails and should be retried. The return value of given function is returned.
*
* @param maxTransactionRetries Maximal number of times fn can be executed again in case of transaction errors.
* @param fn Function to execute.
* @return Object fn has returned.
* @param Return type of fn.
* @param Exception type that could be thrown by fn.
* @throws E Exception thrown by fn.
*/
T execTxChecked(int maxTransactionRetries, ThrowingFunction fn) throws E;
/**
* Closes this DBSession and cleans up related objects.
*/
void close();
}