org.fluentjdbc.DatabaseTable Maven / Gradle / Ivy

Go to download
package org.fluentjdbc;

import javax.annotation.CheckReturnValue;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import javax.annotation.ParametersAreNonnullByDefault;
import java.util.Collection;
import java.util.List;
import java.util.UUID;
import java.util.stream.Stream;

import static org.fluentjdbc.DatabaseStatement.parameterString;

/**
 * Provides a starting point for for fluent-jdbc with explicit Connection management
 * 
 *
 * Example
 *  * DatabaseTable table = new DatabaseTableImpl("database_table_test_table");
 * Object id = table.insert()
 *     .setPrimaryKey("id", null)
 *     .setField("code", 1002)
 *     .setField("name", "insertTest")
 *     .execute(connection);
 *
 * List<Long> result = table.where("name", "insertTest").orderBy("code").listLongs(connection, "code");
 * table.where("id", id).setField("name", updatedName).execute(connection);
 * table.where("id", id).delete(connection);
 * 
 *
 * @see DatabaseTableImpl
 * @see DatabaseTableWithTimestamps
 */
@ParametersAreNonnullByDefault
public interface DatabaseTable extends DatabaseQueryable {

    /**
     * If you haven't called {@link #orderBy}, the results of {@link DatabaseListableQueryBuilder#list}
     * will be unpredictable. Call unordered() if you are okay with this.
     */
    @CheckReturnValue
    DatabaseTableQueryBuilder unordered();

    /**
     * Adds an order by clause to the query. Needed in order to list results
     * in a predictable order.
     */
    @CheckReturnValue
    DatabaseTableQueryBuilder orderBy(String orderByClause);

    @CheckReturnValue
    DatabaseTableAlias alias(String alias);

    @CheckReturnValue
    String getTableName();

    /**
     * Creates a {@link DatabaseSaveBuilder} which creates a INSERT or UPDATE
     * statement, depending on whether the row already exists in the database. If idValue is null,
     * {@link DatabaseSaveBuilder} will attempt to use the table's autogeneration of primary keys
     * if there is no row with matching unique keys
     */
    @CheckReturnValue
    DatabaseSaveBuilder newSaveBuilder(String idColumn, @Nullable Long idValue);

    /**
     * Creates a {@link DatabaseSaveBuilder} which creates a INSERT or UPDATE
     * statement, depending on whether the row already exists in the database. Throws exception if idValue is null
     */
    @CheckReturnValue
    DatabaseSaveBuilder newSaveBuilderWithString(String idColumn, String idValue);

    /**
     * Use instead of {@link #newSaveBuilder} if the database driver does not
     * support RETURN_GENERATED_KEYS
     */
    @CheckReturnValue
    DatabaseSaveBuilder newSaveBuilderNoGeneratedKeys(String idColumn, @Nullable Long idValue);

    /**
     * Creates a {@link DatabaseSaveBuilder} which creates a INSERT or UPDATE
     * statement, depending on whether the row already exists in the database.
     * Generates UUID.randomUUID if idValue is null and row with matching unique keys does not already exist
     */
    @CheckReturnValue
    DatabaseSaveBuilder newSaveBuilderWithUUID(String fieldName, @Nullable UUID uuid);

    /**
     * Creates a {@link DatabaseInsertBuilder} object to fluently generate a INSERT ... statement
     */
    @CheckReturnValue
    DatabaseInsertBuilder insert();

    /**
     * Creates a {@link DatabaseUpdateBuilder} object to fluently generate a UPDATE ... statement
     */
    @CheckReturnValue
    DatabaseUpdateBuilder update();

    /**
     * Executes DELETE FROM tableName
     */
    DatabaseDeleteBuilder delete();

    /**
     * Creates a {@link DatabaseBulkInsertBuilder} object to fluently generate a INSERT ... statement
     * for a list of objects. Example:
     *
     *      *     public void saveAll(List<TagType> tagTypes, Connection connection) {
     *         tagTypesTable.bulkInsert(tagTypes)
     *             .setField("name", TagType::getName)
     *             .generatePrimaryKeys("id", TagType::setId)
     *             .execute(connection);
     *     }
     * 
     *
     */
    @CheckReturnValue