001package io.ebean;
002
003import java.sql.ResultSet;
004import java.sql.SQLException;
005
006/**
007 * Builds RawSql instances from a SQL string and column mappings.
008 * <p>
009 * Note that RawSql can also be defined in ebean-orm.xml files and be used as a
010 * named query.
011 * </p>
012 *
013 * @see RawSql
014 */
015public interface RawSqlBuilder {
016
017  /**
018   * Create and return a RawSql object based on the resultSet and list of properties the columns in
019   * the resultSet map to.
020   * <p>
021   * The properties listed in the propertyNames must be in the same order as the columns in the
022   * resultSet.
023   */
024  static RawSql resultSet(ResultSet resultSet, String... propertyNames) {
025    return XServiceProvider.rawSql().resultSet(resultSet, propertyNames);
026  }
027
028  /**
029   * Create and return a SqlRow based on the resultSet with dbTrueValue and binaryOptimizedUUID options.
030   */
031  static SqlRow sqlRow(ResultSet resultSet, final String dbTrueValue, boolean binaryOptimizedUUID) throws SQLException {
032    return XServiceProvider.rawSql().sqlRow(resultSet, dbTrueValue, binaryOptimizedUUID);
033  }
034
035  /**
036   * Return an unparsed RawSqlBuilder. Unlike a parsed one this query can not be
037   * modified - so no additional WHERE or HAVING expressions can be added to
038   * this query.
039   */
040  static RawSqlBuilder unparsed(String sql) {
041    return XServiceProvider.rawSql().unparsed(sql);
042  }
043
044  /**
045   * Return a RawSqlBuilder parsing the sql.
046   * <p>
047   * The sql statement will be parsed so that Ebean can determine where it can
048   * insert additional WHERE or HAVING expressions.
049   * </p>
050   * <p>
051   * Additionally the selected columns are parsed to determine the column
052   * ordering. This also means additional checks can be made with the column
053   * mapping - specifically we can check that all columns are mapped and that
054   * correct column names are entered into the mapping.
055   * </p>
056   */
057  static RawSqlBuilder parse(String sql) {
058    return XServiceProvider.rawSql().parsed(sql);
059  }
060
061  /**
062   * Set the mapping of a DB Column to a bean property.
063   * <p>
064   * For Unparsed SQL the columnMapping MUST be defined in the same order that
065   * the columns appear in the SQL statement.
066   * </p>
067   *
068   * @param dbColumn     the DB column that we are mapping to a bean property
069   * @param propertyName the bean property that we are mapping the DB column to.
070   */
071  RawSqlBuilder columnMapping(String dbColumn, String propertyName);
072
073  /**
074   * Ignore this DB column. It is not mapped to any bean property.
075   */
076  RawSqlBuilder columnMappingIgnore(String dbColumn);
077
078  /**
079   * Modify any column mappings with the given table alias to have the path prefix.
080   * <p>
081   * For example modify all mappings with table alias "c" to have the path prefix "customer".
082   * </p>
083   * <p>
084   * For the "Root type" you don't need to specify a tableAliasMapping.
085   * </p>
086   */
087  RawSqlBuilder tableAliasMapping(String tableAlias, String path);
088
089  /**
090   * Create the immutable RawSql object. Do this after all the column mapping
091   * has been defined.
092   */
093  RawSql create();
094
095}