All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class PREDATOR.Connection 

java.lang.Object
   |
   +----PREDATOR.Connection
public class Connection
extends Object
The main interface for a Java applet or application to maintain a client connection with a PREDATOR server. It provides methods to connect and disconnect, and to process queries and callbacks. A Connection object is thread-safe in that many threads can use it simultanously with no possibility of race conditions or blocking threads.
An object of this class must be maintained for each client session with the PREDATOR server. The standard way to use this class is:
  1. Create this object.
  2. Create a ServerSite object, which will identify the location of the PREDATOR server.
  3. Call the open(ServerSite) method of this class.
  4. Run queries (see below).
  5. Close the connection via a call to the close() method of class.
To run a query, first create a Query object. Then call processQuery(Query) and get the ResultObject it returns. Then, using the instanceof operator, determine if the result is a UnformattedResult or a RecordStreamResult object. If desired, make callbacks for "full values" of callback objects. Then, end the query (freeing up server resources) by calling endQuery().

A database server error may arise if the queries sent are inappropriate. To check if the server has noted an error, use the isError() function. If an error has occurred, the actual error (which provides messages and stack information) can be obtained via a call to getError(). Applications should check for errors at the following times:

  1. After calls to Connection.open(ServerSite S)
  2. After calls to Connection.endQuery() (or Connection.processQuery(Query Q, true)).
  3. After calls to Connection.close()

See Also:
ServerSite, Query, QueryResult, RecordStreamResult, UnformattedResult

Variable Index

o ADTs
The ADT table
o clientId
The client identification number
o errorBuffer
The buffer which holds server errors.
o errorReader
The thread which asynchronously reads off the error stream
o FORMATTED_RESULTS_SENTINEL
The byte which prefixes all formatted query results
o InitString
The string which tells the server to start a new client session
o primary
The primary socket connection; used for sending queries and reading results
o queryInProcess
True if a query is in process
o secondary
The secondary socket connection; used for reading asynchronous errors
o SERVER_SETUP_STRING
The string the server sends over in response to the InitString
o SHOREXactIdSize
The size of a SHORE transaction ID (in bytes)
o site
The PREDATOR site to which this client is connected
o xactId
The binary transaction ID of the current query

Constructor Index

o Connection()

Method Index

o close()
Closes the connection to the PREDATOR server.
o endQuery()
Ends the last query to be processed.
o getCallbackObjectURL(DataObject, ADT, ADTMetaInfo)
Returns a URL to a callback object.
o getError()
If an error exists, returns the error and clears the error buffer.
o isError()
Checks to see if there is a pending server error.
o isOpen()
Determines if this connection is open.
o open(ServerSite)
Opens a new connection to a PREDATOR server.
o processQuery(Query, boolean)
Processes a query, returning its associated result object.
o queryInProcess()
Determines if a query is currently in process, i.e., processQuery() has been called, but not endQuery().

Variables

o InitString 
 protected static final String InitString
The string which tells the server to start a new client session

o SERVER_SETUP_STRING 
 protected static final String SERVER_SETUP_STRING
The string the server sends over in response to the InitString

o primary 
 protected SocketConnection primary
The primary socket connection; used for sending queries and reading results

o secondary 
 protected SocketConnection secondary
The secondary socket connection; used for reading asynchronous errors

o site 
 protected ServerSite site
The PREDATOR site to which this client is connected

o clientId 
 protected int clientId
The client identification number

o ADTs 
 protected ADT ADTs[]
The ADT table

o queryInProcess 
 protected boolean queryInProcess
True if a query is in process

o FORMATTED_RESULTS_SENTINEL 
 protected static final byte FORMATTED_RESULTS_SENTINEL
The byte which prefixes all formatted query results

o xactId 
 protected byte xactId[]
The binary transaction ID of the current query

o SHOREXactIdSize 
 protected static final int SHOREXactIdSize
The size of a SHORE transaction ID (in bytes)

o errorReader 
 protected ErrorReader errorReader
The thread which asynchronously reads off the error stream

o errorBuffer 
 protected ServerErrorBuffer errorBuffer
The buffer which holds server errors. This object is shared between the main thread and the error reader thread.

Constructors

o Connection 
 public Connection()

Methods

o isOpen 
 public boolean isOpen()
Determines if this connection is open.

Returns:
true if the connection is open, false otherwise.
o queryInProcess 
 public boolean queryInProcess()
Determines if a query is currently in process, i.e., processQuery() has been called, but not endQuery().

Returns:
true if a query is in process
o open 
 public synchronized void open(ServerSite Site) throws CannotConnectException, ConnectionAlreadyOpenException
Opens a new connection to a PREDATOR server.

Parameters:
Site - The site to which the connection should be made
Throws: CannotConnectException
if the connection cannot be opened
Throws: ConnectionAlreadyOpenException
if the connection is already open
o close 
 public synchronized void close() throws UnterminatedQueryException, NoOpenConnectionException, InterruptedException
Closes the connection to the PREDATOR server.

Throws: NoOpenConnectionException
if no connection is open
Throws: UnterminatedQueryException
if the previous query was not ended using endQuery()
Throws: InterruptedException
if this thread is interrupted while closing the connection
See Also:
endQuery
o processQuery 
 public synchronized QueryResult processQuery(Query Q,
                                              boolean endQuery) throws NoOpenConnectionException, UnterminatedQueryException
Processes a query, returning its associated result object. After this function is called, any number of callbacks can be made for data objects (assuming the result was a RecordStreamResult object). If the endQuery parameter is set to false, the query will not be ended automatically after the results are read. In this case, the endQuery() function must be called before a new query can be processed. Note that while records are still being transferred through a RecordStreamResult, the query has not ended. Only after the last record is read will the query be automatically ended.

Parameters:
Query - The query to process
enwQuery - If this parameter is false, the transaction will not be automatically ended after the result is obtained; otherwise, it will.
Returns:
The result of the query; this can be either an UnformattedResult or a RecordStream result.
Throws: NoOpenConnectionException
if no connection is open
Throws: UnterminatedQueryException
if the previous query was not ended using endQuery()
See Also:
endQuery, RecordStreamResult, UnformattedResult
o endQuery 
 public synchronized void endQuery() throws NoOpenConnectionException, NoQueryRunningException, InterruptedException
Ends the last query to be processed. This function must be called before a new query is processed. It is highly advisable to call this function as soon as possible, because it terminates the query's transaction at the server, freeing up system resources for other clients. This function will block until the query can be properly ended.

Throws: NoOpenConnectionException
if no connection is open
Throws: NoQueryRunningException
if no query has been processed or the last query was ended
Throws: InterruptedException
If the current thread is interrupted while blocking waiting to end the query
o getCallbackObjectURL 
 public URL getCallbackObjectURL(DataObject Object,
                                 ADT TypeADT,
                                 ADTMetaInfo MetaInfo) throws NoOpenConnectionException
Returns a URL to a callback object.

Parameters:
Object - The CallbackObject for which a URL is desired
TypeADT - The ADT associated with the object. This can be obtained by the getTypeADT() method of the attribute corresponding to this object. The attribute is available from the schema of the record from which the object was obtained.
MetaInfo - The meta-information associated with the object. This can be obtained by the getMetaInfo() method of the attribute corresponding to this object. The attribute is available from the schema of the record from which the object was obtained.
Throws: NoOpenConnectionException
if no connection is open
See Also:
getSchema, getAttribute, getMetaInfo, getTypeADT
o isError 
 public boolean isError()
Checks to see if there is a pending server error.

Returns:
true if the server has registered an error, false otherwise
o getError 
 public ServerError getError()
If an error exists, returns the error and clears the error buffer. If none exists, returns null.

Returns:
The server error 
All Packages  Class Hierarchy  This Package  Previous  Next  Index