Class AbstractJDBCDatabaseInterface

  • All Implemented Interfaces:
    DatabaseInterface
    Direct Known Subclasses:
    InternalJDBCHelper.InternalDatabaseInterface, JDBCDatabaseInterface

    public abstract class AbstractJDBCDatabaseInterface
    extends java.lang.Object
    implements DatabaseInterface
    An abstract implementation of JDBCDatabaseInterface that provides a connection between a single DatabaseConnection and a DatabaseInterface implementation.

    This receives database commands from the JDBC layer and dispatches the queries to the database system. It also manages ResultSet maps for query results.

    This implementation does not handle authentication (login) / construction of the DatabaseConnection object, or disposing of the connection.

    This implementation ignores the AUTO-COMMIT flag when a query is executed. To implement AUTO-COMMIT, you should 'commit' after a command is executed.

    SYNCHRONIZATION: This interface is NOT thread-safe. To make a thread-safe implementation use the LockingMechanism.

    See JDBCDatabaseInterface for a standard server-side implementation of this class.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.util.HashMap blob_id_map
      Mantains a mapping from streamable object id for a particular object that is currently being uploaded to the server.
      private Database database
      The Databas object that represents the context of this database interface.
      private DatabaseConnection database_connection
      The database connection transaction.
      private boolean disposed
      Set to true when this database interface is disposed.
      private java.util.HashMap result_set_map
      The mapping that maps from result id number to Table object that this JDBC connection is currently maintaining.
      private SQLQueryExecutor sql_executor
      The SQL parser object for this interface.
      private int unique_result_id
      This is incremented every time a result set is added to the map.
      private User user
      Access to information regarding the user logged in on this connection.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private int addResultSet​(AbstractJDBCDatabaseInterface.ResultSetInfo result)
      Adds this result set to the list of result sets being handled through this processor.
      protected void checkNotDisposed()
      Checks if the interface is disposed, and if it is generates a friendly SQLException informing the user of this.
      protected void clearResultSetMap()
      Clears the contents of the result set map.
      DebugLogger Debug()
      Returns a DebugLogger object that can be used to log debug messages against.
      void disposeResult​(int result_id)
      Disposes of a result of a query on the server.
      private void disposeResultSet​(int result_id)
      Disposes of the result set with the given result_id.
      void disposeStreamableObject​(int result_id, long streamable_object_id)
      Disposes a streamable object channel with the given identifier.
      QueryResponse execQuery​(SQLQuery query)
      Executes the query and returns a QueryResponse object that describes the result of the query.
      void finalize()
      Clean up if this object is GC'd.
      private Ref flushLargeObjectRefFromCache​(long streamable_object_id)
      Removes the large object reference from the HashMap for the given streamable object id from the HashMap.
      protected Database getDatabase()
      Returns the Database that is the context of this interface.
      protected DatabaseConnection getDatabaseConnection()
      Returns the DatabaseConnection objcet for this connection.
      private Ref getLargeObjectRefFor​(long streamable_object_id)
      Returns a reference object that handles the given streamable object id in this database interface.
      private Ref getLargeObjectRefFor​(long streamable_object_id, byte type, long object_length)
      Returns a reference implementation object that handles an object that is either currently being pushed onto the server from the client, or is being used to reference a large object in an SQLQuery.
      ResultPart getResultPart​(int result_id, int row_number, int row_count)
      Returns a part of a result set.
      private AbstractJDBCDatabaseInterface.ResultSetInfo getResultSet​(int result_id)
      Gets the result set with the given result_id.
      StreamableObjectPart getStreamableObjectPart​(int result_id, long streamable_object_id, long offset, int len)
      Returns a section of a large binary or character stream in a result set.
      protected User getUser()
      Returns the User object for this connection.
      protected java.sql.SQLException handleExecuteThrowable​(java.lang.Throwable e, SQLQuery query)
      Wraps a Throwable thrown by the execution of a query in DatabaseConnection with an SQLException and puts the appropriate error messages to the debug log.
      protected void init​(User user, DatabaseConnection connection)
      Initializes this database interface with a User and DatabaseConnection object.
      protected void internalDispose()
      Disposes all resources associated with this object.
      void pushStreamableObjectPart​(byte type, long object_id, long object_length, byte[] buf, long offset, int length)
      Pushes a part of a streamable object from the client onto the server.
      • Methods inherited from class java.lang.Object

        clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • database

        private Database database
        The Databas object that represents the context of this database interface.
      • result_set_map

        private java.util.HashMap result_set_map
        The mapping that maps from result id number to Table object that this JDBC connection is currently maintaining.

        NOTE: All Table objects are now valid over a database shutdown + init.

      • unique_result_id

        private int unique_result_id
        This is incremented every time a result set is added to the map. This way, we always have a unique key on hand.
      • user

        private User user
        Access to information regarding the user logged in on this connection. If no user is logged in, this is left as 'null'. We can also use this to retreive the Database object the user is logged into.
      • database_connection

        private DatabaseConnection database_connection
        The database connection transaction.
      • sql_executor

        private SQLQueryExecutor sql_executor
        The SQL parser object for this interface. When a statement is being parsed, this object is sychronized.
      • blob_id_map

        private java.util.HashMap blob_id_map
        Mantains a mapping from streamable object id for a particular object that is currently being uploaded to the server. This maps streamable_object_id to blob id reference.
      • disposed

        private boolean disposed
        Set to true when this database interface is disposed.
    • Constructor Detail

      • AbstractJDBCDatabaseInterface

        public AbstractJDBCDatabaseInterface​(Database database)
        Sets up the database interface.
    • Method Detail

      • init

        protected final void init​(User user,
                                  DatabaseConnection connection)
        Initializes this database interface with a User and DatabaseConnection object. This would typically be called from inside an authentication method, or from 'login'. This must be set before the object can be used.
      • getDatabase

        protected final Database getDatabase()
        Returns the Database that is the context of this interface.
      • getUser

        protected final User getUser()
        Returns the User object for this connection.
      • Debug

        public final DebugLogger Debug()
        Returns a DebugLogger object that can be used to log debug messages against.
      • getDatabaseConnection

        protected final DatabaseConnection getDatabaseConnection()
        Returns the DatabaseConnection objcet for this connection.
      • addResultSet

        private int addResultSet​(AbstractJDBCDatabaseInterface.ResultSetInfo result)
        Adds this result set to the list of result sets being handled through this processor. Returns a number that unique identifies this result set.
      • disposeResultSet

        private void disposeResultSet​(int result_id)
        Disposes of the result set with the given result_id. After this has been called, the GC should garbage the table.
      • clearResultSetMap

        protected final void clearResultSetMap()
        Clears the contents of the result set map. This removes all result_id ResultSetInfo maps.
      • handleExecuteThrowable

        protected final java.sql.SQLException handleExecuteThrowable​(java.lang.Throwable e,
                                                                     SQLQuery query)
        Wraps a Throwable thrown by the execution of a query in DatabaseConnection with an SQLException and puts the appropriate error messages to the debug log.
      • getLargeObjectRefFor

        private Ref getLargeObjectRefFor​(long streamable_object_id,
                                         byte type,
                                         long object_length)
        Returns a reference implementation object that handles an object that is either currently being pushed onto the server from the client, or is being used to reference a large object in an SQLQuery.
      • getLargeObjectRefFor

        private Ref getLargeObjectRefFor​(long streamable_object_id)
                                  throws java.sql.SQLException
        Returns a reference object that handles the given streamable object id in this database interface. Unlike the other 'getLargeObjectRefFor method, this will not create a new handle if it has not already been formed before by this connection. If the large object ref is not found an exception is generated.
        Throws:
        java.sql.SQLException
      • flushLargeObjectRefFromCache

        private Ref flushLargeObjectRefFromCache​(long streamable_object_id)
                                          throws java.sql.SQLException
        Removes the large object reference from the HashMap for the given streamable object id from the HashMap. This allows the Ref to finalize if the VM does not maintain any other pointers to it, and therefore clean up the resources in the store.
        Throws:
        java.sql.SQLException
      • internalDispose

        protected final void internalDispose()
        Disposes all resources associated with this object. This clears the ResultSet map, and NULLs all references to help the garbage collector. This method would normally be called from implementations of the 'dispose' method.
      • checkNotDisposed

        protected final void checkNotDisposed()
                                       throws java.sql.SQLException
        Checks if the interface is disposed, and if it is generates a friendly SQLException informing the user of this.
        Throws:
        java.sql.SQLException
      • pushStreamableObjectPart

        public void pushStreamableObjectPart​(byte type,
                                             long object_id,
                                             long object_length,
                                             byte[] buf,
                                             long offset,
                                             int length)
                                      throws java.sql.SQLException
        Description copied from interface: DatabaseInterface
        Pushes a part of a streamable object from the client onto the server. The server stores the large object for use with a future query. For example, a sequence of with a query with large objects may operate as follows;

         1) Push 100 MB object (id = 104)
         2) execQuery with query that contains a streamable object with id 104
         

        Note that the client may push any part of a streamable object onto the server, however the streamable object must have been completely pushed for the query to execute correctly. For example, an 100 MB byte array may be pushed onto the server in blocks of 64K (in 1,600 separate blocks).

        Specified by:
        pushStreamableObjectPart in interface DatabaseInterface
        Parameters:
        type - the StreamableObject type (1 = byte array, 2 = char array)
        object_id - the identifier of the StreamableObject for future queries.
        object_length - the total length of the StreamableObject.
        buf - the byte[] array representing the block of information being sent.
        offset - the offset into of the object of this block.
        length - the length of the block being pushed.
        Throws:
        java.sql.SQLException
      • execQuery

        public QueryResponse execQuery​(SQLQuery query)
                                throws java.sql.SQLException
        Description copied from interface: DatabaseInterface
        Executes the query and returns a QueryResponse object that describes the result of the query. The QueryResponse object describes the number of rows, describes the columns, etc. This method will block until the query has completed. The QueryResponse can be used to obtain the 'result id' variable that is used in subsequent queries to the engine to retrieve the actual result of the query.
        Specified by:
        execQuery in interface DatabaseInterface
        Throws:
        java.sql.SQLException
      • getResultPart

        public ResultPart getResultPart​(int result_id,
                                        int row_number,
                                        int row_count)
                                 throws java.sql.SQLException
        Description copied from interface: DatabaseInterface
        Returns a part of a result set. The result set part is referenced via the 'result id' found in the QueryResponse. This is used to read parts of the query once it has been found via 'execQuery'.

        The returned List object contains the result requested.

        If the result contains any StreamableObject objects, then the server allocates a channel to the object via the 'getStreamableObjectPart' and the identifier of the StreamableObject. The channel may only be disposed if the 'disposeStreamableObject' method is called.

        Specified by:
        getResultPart in interface DatabaseInterface
        Throws:
        java.sql.SQLException
      • disposeResult

        public void disposeResult​(int result_id)
                           throws java.sql.SQLException
        Description copied from interface: DatabaseInterface
        Disposes of a result of a query on the server. This frees up server side resources allocated to a query. This should be called when the ResultSet of a query closes. We should try and use this method as soon as possible because it frees locks on tables and allows deleted rows to be reclaimed.
        Specified by:
        disposeResult in interface DatabaseInterface
        Throws:
        java.sql.SQLException
      • getStreamableObjectPart

        public StreamableObjectPart getStreamableObjectPart​(int result_id,
                                                            long streamable_object_id,
                                                            long offset,
                                                            int len)
                                                     throws java.sql.SQLException
        Description copied from interface: DatabaseInterface
        Returns a section of a large binary or character stream in a result set. This is used to stream large values over the connection. For example, if a row contained a multi megabyte object and the client is only interested in the first few characters and the last few characters of the stream. This would require only a few queries to the database and the multi- megabyte object would not need to be downloaded to the client in its entirety.
        Specified by:
        getStreamableObjectPart in interface DatabaseInterface
        Throws:
        java.sql.SQLException
      • disposeStreamableObject

        public void disposeStreamableObject​(int result_id,
                                            long streamable_object_id)
                                     throws java.sql.SQLException
        Description copied from interface: DatabaseInterface
        Disposes a streamable object channel with the given identifier. This should be called to free any resources on the server associated with the object. It should be called as soon as possible because it frees locks on the tables and allows deleted rows to be reclaimed.
        Specified by:
        disposeStreamableObject in interface DatabaseInterface
        Throws:
        java.sql.SQLException
      • finalize

        public void finalize()
                      throws java.lang.Throwable
        Clean up if this object is GC'd.
        Overrides:
        finalize in class java.lang.Object
        Throws:
        java.lang.Throwable