/*
 * TypeDriver.java
 * 
 * (C) 28.02.2005 Markus Schaber, Logi-Track ag, CH 8001 Zuerich
 * 
 * $Id: $
 */
package org.postgresql.types;

import org.postgresql.PGConnection;

import java.sql.SQLException;

public interface TypeDriver {

    /**
     * Return all classes that are known to be supported at compile-time.
     */
    public Class[] getSupportedClasses();

    /** Return all sql types that are known to be supported. */
    public String[] getSupportedTypes();

    /** Test whether we support the SQL type. */
    public boolean supports(String type);

    /**
     * Test whether we support the following class.
     * 
     * This must return true for all classes that are in getSupportedClasses. It
     * is also allowed to return true for other classes it knows to write, for
     * example third-party subclasses that are not known at compile time.
     */
    public boolean supports(Class klass);

    /** Which SQL type do we produce for this object 
     * Note that this mapping is not 1:1, a single SQL type may correspond
     * to a cuple of java types. 
     */
    public String objectType(Object data) throws SQLException;

    /** Do we support creation of binary representation? 
     * @returns true on instances of TypeBinaryWriter
     */
    public boolean supportsBinaryWrite();

    /** Do we support creation of text representation?  
     * @returns true on instances of TypeTextWriter
     */
    public boolean supportsTextWrite();

    /** Do we support parsing of binary representation?  
     * @returns true on instances of TypeBinaryReader
     */
    public boolean supportsBinaryReading();

    /** Do we support parsing of text representation?  
     * @returns true on instances of TypeTextReader
     */
    public boolean supportsTextReading();

    /**
     * Initialize the TypeDriver for a new connection.
     * 
     * This method may do read-only queries on the database. It allows the
     * driver to make adoptions for different protocols, server versions or
     * installed data types. An example for this is PostGIS, where older
     * versions do not support binary representation on the server side.
     * 
     * XXX: Should we only use java.sql.Connection here?
     * 
     * @returns the TypeDriver instance, which may be the same as the input
     *          parameter if no adoption is made.
     */
    public TypeDriver forConnection(PGConnection conn) throws SQLException;
}