java.lang.Object
- com.mckoi.database.jdbc.RemoteDatabaseInterface

All Implemented Interfaces:

DatabaseInterface, ProtocolConstants

Direct Known Subclasses:

StreamDatabaseInterface
```
abstract class RemoteDatabaseInterface
extends java.lang.Object
implements DatabaseInterface, ProtocolConstants
```
An abstract implementation of DatabaseInterface that retrieves information from a remote server host. The actual implementation of the communication protocol is left to the derived classes.

Nested Class Summary

Nested Classes
Modifier and Type	Class	Description
`private class`	`RemoteDatabaseInterface.ConnectionThread`	The connection thread that can dispatch commands concurrently through the in/out pipe.
`(package private) static class`	`RemoteDatabaseInterface.MByteArrayOutputStream`	A ByteArrayOutputStream that allows us access to the underlying byte[] array.
`(package private) static class`	`RemoteDatabaseInterface.ServerCommand`	Represents the data in a command from the server.

Field Summary

Fields
Modifier and Type	Field	Description
`private RemoteDatabaseInterface.ConnectionThread`	`connection_thread`	The thread that dispatches commands to the server.
`private DatabaseCallBack`	`database_call_back`	A DatabaseCallBack implementation that is notified of all events that are received from the database.

Fields inherited from interface com.mckoi.database.jdbc.ProtocolConstants
ACKNOWLEDGEMENT, AUTHENTICATION_ERROR, CLOSE, DATABASE_EVENT, DISPOSE_RESULT, DISPOSE_STREAMABLE_OBJECT, EXCEPTION, FAILED, PING, PUSH_STREAMABLE_OBJECT_PART, QUERY, RESULT_SECTION, SERVER_REQUEST, STREAMABLE_OBJECT_SECTION, SUCCESS, USER_AUTHENTICATION_FAILED, USER_AUTHENTICATION_PASSED

Constructor Summary

Constructors
Constructor Description

RemoteDatabaseInterface()

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method	Description
`(package private) abstract void`	`closeConnection()`	Closes the connection.
`void`	`dispose()`	Called when the connection is disposed.
`void`	`disposeResult(int result_id)`	Disposes of a result of a query on the server.
`void`	`disposeStreamableObject(int result_id, long streamable_object_id)`	Disposes a streamable object channel with the given identifier.
`QueryResponse`	`execQuery(SQLQuery sql)`	Executes the query and returns a QueryResponse object that describes the result of the query.
`ResultPart`	`getResultPart(int result_id, int start_row, int count_rows)`	Returns a part of a result set.
`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.
`private static void`	`logException(java.lang.Throwable e)`	Writes the exception to the JDBC log stream.
`boolean`	`login(java.lang.String default_schema, java.lang.String user, java.lang.String password, DatabaseCallBack call_back)`	Attempts to log in to the database as the given username with the given password.
`(package private) abstract byte[]`	`nextCommandFromServer(int timeout)`	Blocks until the next command is received from the server.
`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.
`(package private) abstract void`	`writeCommandToServer(byte[] command, int offset, int length)`	Writes the given command to the server.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - connection_thread
```
private RemoteDatabaseInterface.ConnectionThread connection_thread
```
    The thread that dispatches commands to the server. This is created and started after the 'login' method is called. This can handle concurrent queries through the protocol pipe.
  - database_call_back
```
private DatabaseCallBack database_call_back
```
    A DatabaseCallBack implementation that is notified of all events that are received from the database.
- Constructor Detail
  - RemoteDatabaseInterface
```
RemoteDatabaseInterface()
```
- Method Detail
  - logException
```
private static void logException(java.lang.Throwable e)
```
    Writes the exception to the JDBC log stream.
  - writeCommandToServer
```
abstract void writeCommandToServer(byte[] command,
                                   int offset,
                                   int length)
                            throws java.io.IOException
```
    Writes the given command to the server. The way the command is written is totally network layer dependent.
    
    Throws:
    
    java.io.IOException
  - nextCommandFromServer
```
abstract byte[] nextCommandFromServer(int timeout)
                               throws java.io.IOException
```
    Blocks until the next command is received from the server. The way this is implemented is network layer dependant.
    
    Throws:
    
    java.io.IOException
  - closeConnection
```
abstract void closeConnection()
                       throws java.io.IOException
```
    Closes the connection.
    
    Throws:
    
    java.io.IOException
  - login
```
public boolean login(java.lang.String default_schema,
                     java.lang.String user,
                     java.lang.String password,
                     DatabaseCallBack call_back)
              throws java.sql.SQLException
```
    Description copied from interface: DatabaseInterface
    
    Attempts to log in to the database as the given username with the given password. Only one user may be authenticated per connection. This must be called before the other methods are used.
    A DatabaseCallBack implementation must be given here that is notified of all events from the database. Events are only received if the login was successful.
    
    Specified by:
    
    login in interface DatabaseInterface
    
    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 sql)
                        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 start_row,
                                int count_rows)
                         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
  - dispose
```
public void dispose()
             throws java.sql.SQLException
```
    Description copied from interface: DatabaseInterface
    
    Called when the connection is disposed. This will terminate the connection if there is any connection to terminate.
    
    Specified by:
    
    dispose in interface DatabaseInterface
    
    Throws:
    
    java.sql.SQLException

Class RemoteDatabaseInterface

Nested Class Summary

Field Summary

Fields inherited from interface com.mckoi.database.jdbc.ProtocolConstants

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

connection_thread

database_call_back

Constructor Detail

RemoteDatabaseInterface

Method Detail

logException

writeCommandToServer

nextCommandFromServer

closeConnection

login

pushStreamableObjectPart

execQuery

getResultPart

disposeResult

getStreamableObjectPart

disposeStreamableObject

dispose