public class Observation_Record_Broker
extends java.lang.Object
The record broker conducts transactions with the database on behalf of a third-party used, such as HiCommand or the HOGG. HiRISE observation data are complex entities, requiring up to 15 records in two different tables, the records linked together by a database-assigned identifcation number. The broker removes from the user the burdern of managing these entities.
The observation parameters are stored in the Planned_Observations
table.
The CCD parameters are stored in the Planned_CCD_Parameters
table.
The user is free to manage connections to the database if desired, but the broker is able to do so otherwise, opening and closing the connections as needed. This strategy allows the user to pick the most efficient method for making connections. For numerous, frequent transactions, such as with the HiCommand, the user may wish to manage the connections. For infrequent connections, such with the HOGG, it may be best to let the broker open and close the connection itself. No configuration for this behavior is required. If the database connection was made before the broker's query methods were invoked, the broker does not attempt to manage it. If the connection was not already established prior to the invocation, the broker opens it before performing the update and closes it down again after.
All operations via the broker require at least SELECT permission on
both tables (Planned_Observations and
Planned_CCD_Parameters). Some operations, notably the update(Observation_Record)
and updateObservationParameters(Observation_Record)
methods, require
UPDATE permission on the observation parameters table. The former
method also requires INSERT permission on both tables and
DELETE permission on the CCD parameters table.
Observation_Record
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
DEFAULT_CATALOG
Default name for the database catalog that contains the observation
parameter and CCD parameter tables.
|
static java.lang.String |
ID
Class identification name with source code version and date.
|
Constructor and Description |
---|
Observation_Record_Broker(PIRL.Database.Database database)
Creates an observation record broker with the specified database.
|
Observation_Record_Broker(PIRL.Database.Database database,
java.lang.String catalog)
Creates an observation record broker with the specified database and named
database catalog.
|
Modifier and Type | Method and Description |
---|---|
java.lang.String |
getCatalog()
Gets the database catalog this broker uses for its transactions.
|
PIRL.Database.Database |
getDatabase()
Gets the database currently being used by this broker to conduct
transactions.
|
java.lang.String |
makeTableReference(java.lang.String table)
Generates a table reference for the indicated table using this broker's
catalog.
|
Observation_Record |
select(java.lang.String id)
Retrieves an observation record from this brokers's database.
|
void |
setCatalog(java.lang.String catalog)
Sets the database catalog this broker will use for its transactions.
|
void |
setDatabase(PIRL.Database.Database database)
Sets the database to be used by this broker for all future transactions.
|
int |
update(Observation_Record observation)
Updates the parameters in this broker's database for a given observation
record.
|
int |
updateObservationParameters(Observation_Record observation)
Updates the observation parameters in this broker's database for a given
observation record.
|
public static final java.lang.String ID
public static final java.lang.String DEFAULT_CATALOG
public Observation_Record_Broker(PIRL.Database.Database database, java.lang.String catalog)
database
- the database with which this broker conducts operations.catalog
- the catalog that holds the observation parameter tables.public Observation_Record_Broker(PIRL.Database.Database database)
DEFAULT_CATALOG
is used for operations.database
- the database with which this broker conducts operations.public PIRL.Database.Database getDatabase()
public void setDatabase(PIRL.Database.Database database)
setCatalog(String)
method.database
- the database to use for future transactions.public java.lang.String getCatalog()
Planned_Observations
) and the
CCD parameters table (CCD_Fields.PLANNED_CCD_PARAMETERS_TABLE
Planned_CCD_Parameters). If it does not, the broker's transaction methods
will fail.public void setCatalog(java.lang.String catalog)
Planned_Observations
) and the
CCD parameters table (CCD_Fields.PLANNED_CCD_PARAMETERS_TABLE
Planned_CCD_Parameters). If it does not, the broker's transaction methods
will fail.catalog
- the database catalog to use for transactions; if
null, DEFAULT_CATALOG
will be used instead.public Observation_Record select(java.lang.String id) throws PIRL.Database.Database_Exception
An operator must have SELECT permissions on the observation and CCD parameters tables. Without this permission, this method will fail.
If the database does not already have an open connection, a connection will be opened for this transaction, after which the connection will be closed. If the database already has an open connection, that connection will be used and the broker will not manage the connection.
id
- the unique identifier for the observation record.PIRL.Database.Database_Exception
- if there is a problem with database access.public int updateObservationParameters(Observation_Record observation) throws PIRL.Database.Database_Exception
This method uses a strict UPDATE operation; it does not do an INSERT if the record to be updated does not already exist. In this case, this method will return 0; it will not throw an exception.
An operator must have UPDATE permission on the observation parameters table. Without this permission, this method will fail.
If the database does not already have an open connection, a connection will be opened for this transaction, after which the connection will be closed. If the database already has an open connection, that connection will be used and the broker will not manage the connection.
observation
- the observation record that contains the
parameters for the observation to be updated.PIRL.Database.Database_Exception
- if there is a problem with database access.public int update(Observation_Record observation) throws PIRL.Database.Database_Exception
The CCD parameters are handled differently. To simplify operations and eliminate a need for the user to keep track of which CCDs were active (and therefore had records in the CCD parameters table) prior to and following the update, all CCD parameters for the observation in question are simply removed entirely from the database via a DELETE operation. The new parameters are then added via an INSERT operation.
An operator must have UPDATE and INSERT permission on the observation parameters table. The operator must also have INSERT and DELETE permission on the CCD parameters table. Without these permissions, this method will fail.
The return value equals the number of observation records updated, which should be 1, plus the number of CCD records updated, which should equal the number of active CCDs for the observation.
If the database does not already have an open connection, a connection will be opened for this transaction, after which the connection will be closed. If the database already has an open connection, that connection will be used and the broker will not manage the connection.
observation
- the observation record that contains the parameters for
the observation to be updated.PIRL.Database.Database_Exception
- if there is a problem with database access.public java.lang.String makeTableReference(java.lang.String table) throws PIRL.Database.Database_Exception
table
- the table for which a table reference will be generated.PIRL.Database.Database_Exception
- if a table reference cannot be generated.Database.Table_Reference(String,String)
,
getCatalog()
Copyright \ (C) Arizona Board of Regents on behalf of the \ Planetary Image Research Laboratory, Lunar and \ Planetary Laboratory at the University of Arizona