001/* 
002 * JKNIV, SQLegance keeping queries maintainable.
003 * 
004 * Copyright (C) 2017, the original author or authors.
005 *
006 * This library is free software; you can redistribute it and/or
007 * modify it under the terms of the GNU Lesser General Public
008 * License as published by the Free Software Foundation; either
009 * version 2.1 of the License.
010 * 
011 * This library is distributed in the hope that it will be useful,
012 * but WITHOUT ANY WARRANTY; without even the implied warranty of
013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014 * Lesser General Public License for more details.
015 * 
016 * You should have received a copy of the GNU Lesser General Public
017 * License along with this library; if not, write to the Free Software Foundation, Inc., 
018 * 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
019 */
020package net.sf.jkniv.sqlegance.dialect;
021
022import net.sf.jkniv.reflect.beans.PropertyAccess;
023import net.sf.jkniv.sqlegance.params.ParamMarkType;
024
025/**
026 * Represents a SQL syntax from a specific database.
027 * 
028 * The implementations provider correct syntax to execute a paging query, that limits the number
029 * of rows returned and SQL to count of total records.
030 * 
031 * <p><b>Note:</b> The implementation MUST BE state-less and thread-safe because one instance parse all queries from one
032 * {@code Repository}.
033 * 
034 * @author Alisson Gomes 
035 * @since 0.6.0
036 */
037public interface SqlDialect
038{
039    /**
040     * Dialect name
041     * @return the dialect name
042     */
043    String name();
044    
045    /**
046     * verify if dialect instance supports {@code feature} specified
047     * @param feature to check
048     * @return {@code true} when the dialect supports, {@code false} otherwise
049     */
050    boolean supportsFeature(SqlFeatureSupport feature);
051    
052    /**
053     * verify if dialect supports a specific {@link ParamMarkType}
054     * @param paramParse parameter mark type
055     * @return {@code true} when the parse type is supported, {@code false} otherwise
056     */
057    boolean supportsParmMark(ParamMarkType paramParse);
058    
059    /**
060     * Override a SQL ANSI feature
061     * @param sqlFeature override a {@link SqlFeature} supports.
062     * @return the previous value associated with key {@code sqlFeature}
063     */
064    SqlFeature addFeature(SqlFeature sqlFeature);
065    
066    /**
067     * Return the limit of elements in an {@code INPUT} parameter the database supports.
068     *
069     * @return the limit of parameters from statement, default is a big number {@code Integer.MAX_VALUE}
070     */
071    int getMaxOfParameters();
072    
073    /**
074     * Max number of parameters supported by JDBC driver
075     * @param max maximum value of parameter in the query
076     */
077    void setMaxOfParameters(int max);
078    
079    /**
080     * The template to mount the {@code COUNT} SQL
081     * @return a string template, like that:
082     * {@code select count(1) from (%1$s) _alias_internal_table_} 
083     */
084    String getSqlPatternCount();
085    
086    /**
087     * The template to mount the SQL paginated, using LIMIT and OFFSET 
088     * clauses according the specific database
089     * @return a string template, like that:
090     *  {@code %1$s LIMIT %2$s, %3$s}
091     */
092    String getSqlPatternPaging();
093    
094    /**
095     * Build a paginate query accordingly data base dialect
096     * @param sqlText final SQL with parameters to bind
097     * @param offset number from first row from query result
098     * @param max maximum number of rows from query result.
099     * @return paginate query for specific data base dialect
100     */
101    String buildQueryPaging(final String sqlText, int offset, int max);
102    
103    /**
104     * Build a paginate query accordingly data base dialect
105     * @param sqlText final SQL with parameters to bind
106     * @param offset number from first row from query result
107     * @param max maximum number of rows from query result.
108     * @param bookmark a page selected marked the reader's place
109     * @return paginate query for specific data base dialect
110     */
111    String buildQueryPaging(final String sqlText, int offset, int max, String bookmark);
112    
113    /**
114     * Build a paginate query to count the total of records from {@code sqlText}
115     * @param sqlText original SQL to discover the total of records
116     * @return query that count the total of records from {@code sqlText}
117     */
118    String buildQueryCount(final String sqlText);
119 
120    /**
121     * The access name for {@code id} field, the identifier from an entity
122     * @return the property access, default access values are: {@code id}, {@code getId}, {@code setId}
123     */
124    PropertyAccess getAccessId();
125
126    /**
127     * The access name for {@code revision} field, a revision number from an entity
128     * @return the property access, default access values are: {@code rev}, {@code getRev}, {@code setRev}
129     */
130    PropertyAccess getAccessRevision();
131}