001/* 
002 * JKNIV, whinstone one contract to access your database.
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.whinstone.commands;
021
022import net.sf.jkniv.exception.HandleableException;
023import net.sf.jkniv.sqlegance.Sql;
024import net.sf.jkniv.sqlegance.SqlType;
025import net.sf.jkniv.sqlegance.builder.RepositoryConfig;
026import net.sf.jkniv.whinstone.Queryable;
027import net.sf.jkniv.whinstone.ResultRow;
028
029/**
030 * A command handler to keep the life-cycle to be executed
031 * the {@link Queryable} and {@link Command} for a repository. 
032 * 
033 * @author Alisson Gomes
034 * @since 0.6.0
035 */
036public interface CommandHandler
037{
038    /**
039     * Configure the life-cycle with a {@link Queryable}
040     * @param queryable query name and yours parameters
041     * @return a reference to this object.
042     */
043    CommandHandler with(Queryable queryable);
044
045    /**
046     * Configure the life-cycle with a {@link Sql} 
047     * @param sql Dynamic SQL
048     * @return a reference to this object.
049     */
050    CommandHandler with(Sql sql);
051    
052    /**
053     * Configure the life-cycle with a custom result parser rows of query.
054     * @param customResultRow customized result row to parser
055     * @return a reference to this object.
056     */
057    CommandHandler with(ResultRow<?, ?> customResultRow);
058
059    /**
060     * Configure the life-cycle with the handler exception
061     * @param handlerException rules to handler the all exceptions
062     * @return a reference to this object.
063     */
064    CommandHandler with(HandleableException handlerException);
065
066    /**
067     * Retrieve the command implementation for the 
068     * Repository like: Update, Select, Batch etc
069     * @return the specific implementation for the command.
070     */
071    Command asCommand();
072    
073    /**
074     * Invoke all pre callback methods configured 
075     * for the parameters of {@link Queryable}
076     * @return a reference to this object.
077     */
078    CommandHandler preCallback();
079
080    /**
081     * Invoke all post callback methods configured 
082     * for the parameters of {@link Queryable}
083     * @return a reference to this object.
084     */
085    CommandHandler postCallback();
086
087    /**
088     * Invoke all post callback methods, configured to be
089     * executed after a successful commit, for the 
090     * parameters of {@link Queryable}.
091     * @return a reference to this object.
092     */
093    CommandHandler postCommit();
094
095    /**
096     * Invoke all post callback methods, configured to be
097     * executed after a failure, for the parameters of 
098     * {@link Queryable}.
099     * @return a reference to this object.
100     */
101    CommandHandler postException();
102    
103    /**
104     * Execute the database command
105     * @param <T> Generic type of return, example: rows affected by a command or list of objects.
106     * @return the result of the command execution
107     */
108    <T> T run();
109    
110    /**
111     * If the command isn't the SQL type expected an illegal argument exception is throw.
112     * @param expected type of SQL expected
113     * @return a reference to this object.
114     * @throws IllegalArgumentException if {@link Sql} isn't the expected {@code SqlType}
115     */
116    CommandHandler checkSqlType(SqlType expected);
117}