/*
 * Copyright (c) 2012, Codename One and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Codename One designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *  
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 * 
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 * 
 * Please contact Codename One through http://www.codenameone.com/ if you 
 * need additional information or have any questions.
 */
package com.codename1.db;

import com.codename1.ui.Display;
import java.io.IOException;

/**
 * <p>Allows access to SQLite specifically connecting to a database and executing sql queries on the data.
 * There is more thorough coverage of the {@link com.codename1.db Database API here}.</p>
 * 
 * <p>The Database class abstracts the underlying SQLite of the device if 
 * available.<br>
 * 
 * Notice that this might not be supported on all platforms in which case the {@code Database} will be null.</p>
 * 
 * <p>SQLite should be used for very large data handling, for small storage 
 * refer to {@link com.codename1.io.Storage} which is more portable.</p>
 * 
 * <p>The sample code below presents a Database Explorer tool that allows executing arbitrary SQL and 
 * viewing the tabular results:</p>
 * <script src="https://gist.github.com/codenameone/282b02c20e7bd067f1f0.js"></script>
 * <img src="https://www.codenameone.com/img/developer-guide/sql-table.png" alt="Querying the temp demo generated by the SQLDemo application">
 * <img src="https://www.codenameone.com/img/developer-guide/sql-entry.png" alt="Issuing a query">
 * 
 * @author Chen
 */
public abstract class Database {
    
    /**
     * Opens a database or create one if not exists
     * 
     * @param databaseName the name of the database
     * @return Database Object or null if not supported on the platform
     * 
     * @throws IOException if database cannot be created
     */
    public static Database openOrCreate(String databaseName) throws IOException{
        return Display.getInstance().openOrCreate(databaseName);
    }
        
    /**
     * Indicates weather a database exists
     * 
     * <p><strong>NOTE:</strong> Not supported in the  Javascript port.  Will always return false.</p>
     * 
     * @param databaseName the name of the database
     * @return true if database exists
     */
    public static boolean exists(String databaseName){
        return Display.getInstance().exists(databaseName);
    }
    
    /**
     * Deletes database
     * 
     * <p><strong>NOTE:</strong> This method is not supported in the  Javascript port.  Will silently fail.</p>
     * 
     * @param databaseName the name of the database
     * @throws IOException if database cannot be deleted
     */
    public static void delete(String databaseName) throws IOException{
        Display.getInstance().delete(databaseName);
    }
    
    /**
     * Returns the file path of the Database if exists and if supported on 
     * the platform.
     * 
     * <p><strong>NOTE:</strong> This method will return null in the Javascript port.</p>
     * @return the file path of the database
     */
    public static String getDatabasePath(String databaseName){
        return Display.getInstance().getDatabasePath(databaseName);    
    }
    
    /**
     * Starts a transaction
     * 
     * <p><strong>NOTE:</strong> Not supported in Javascript port.  This method will do nothing when running in Javascript.</p>
     * @throws IOException if database is not opened
     */
    public abstract void beginTransaction() throws IOException;
    
    /**
     * Commits current transaction
     * 
     * <p><strong>NOTE:</strong> Not supported in Javascript port.   This method will do nothing when running in Javascript.</p>
     * 
     * @throws IOException if database is not opened or transaction was not started
     */
    public abstract void commitTransaction() throws IOException;
    
    /**
     * Rolls back current transaction 
     * 
     * <p><strong>NOTE:</strong> Not supported in Javascript port.   This method will do nothing when running in Javascript.</p>
     * 
     * @throws IOException if database is not opened or transaction was not started
     */
    public abstract void rollbackTransaction() throws IOException;
    
    /**
     * Closes the database
     * 
     * @throws IOException 
     */
    public abstract void close() throws IOException;
    
    /**
     * Execute an update query.
     * Used for INSERT, UPDATE, DELETE and similar sql statements.
     * 
     * @param sql the sql to execute
     * 
     * @throws IOException 
     */
    public abstract void execute(String sql) throws IOException;

    /**
     * Execute an update query with params.
     * Used for INSERT, UPDATE, DELETE and similar sql statements.
     * The sql can be constructed with '?' and the params will be binded to the
     * query
     * 
     * @param sql the sql to execute
     * @param params to bind to the query where the '?' exists
     * 
     * @throws IOException 
     */
    public abstract void execute(String sql, String [] params) throws IOException;
    
    /**
     * Execute an update query with params.
     * Used for INSERT, UPDATE, DELETE and similar sql statements.
     * The sql can be constructed with '?' and the params will be binded to the
     * query
     * 
     * @param sql the sql to execute
     * @param params to bind to the query where the '?' exists, supported object 
     * types are String, byte[], Double, Long and null
     * 
     * @throws IOException 
     */
    public void execute(String sql, Object... params) throws IOException{
        if ( params == null) {
            execute(sql);
        } else {
            //throw new RuntimeException("not implemented");
            int len = params.length;
            String[] strParams = new String[len];
            for ( int i=0; i<len; i++) {
                if (params[i] instanceof byte[]) {
                    throw new RuntimeException("Blobs aren't supported on this platform");
                }
                if (params[i] == null) {
                    strParams[i] = null;
                } else {
                    strParams[i] = params[i].toString();
                }
            }
            execute(sql, strParams);
        }
        
    }
    
    
    /**
     * This method should be called with SELECT type statements that return 
     * row set.  
     * 
     * @param sql the sql to execute
     * @param params to bind to the query where the '?' exists
     * @return a cursor to iterate over the results
     * 
     * @throws IOException 
     */
    public abstract Cursor executeQuery(String sql, String [] params) throws IOException;
    
    /**
     * This method should be called with SELECT type statements that return 
     * row set it accepts object with params.
     * 
     * @param sql the sql to execute
     * @param params to bind to the query where the '?' exists, supported object 
     * types are String, byte[], Double, Long and null
     * @return a cursor to iterate over the results
     * 
     * @throws IOException 
     */
    public Cursor executeQuery(String sql, Object... params) throws IOException{
        if ( params == null || params.length == 0) {
            return executeQuery(sql);
        } else {
            int len = params.length;
            String[] strParams = new String[len];
            for ( int i=0; i<len; i++) {
                if (params[i] instanceof byte[]) {
                    throw new RuntimeException("Blobs aren't supported on this platform");
                }
                if (params[i] == null) {
                    strParams[i] = null;
                } else {
                    strParams[i] = params[i].toString();
                }
            }
            return executeQuery(sql, strParams);
        }
    }
    
    /**
     * This method should be called with SELECT type statements that return 
     * row set.  
     * 
     * @param sql the sql to execute
     * @return a cursor to iterate over the results
     * 
     * @throws IOException 
     */
    public abstract Cursor executeQuery(String sql) throws IOException;
    
}
