HiRISE

HiRISE.HiPlan.HiCat
Class Observation_Record_Broker

java.lang.Object
  extended by HiRISE.HiPlan.HiCat.Observation_Record_Broker

public class Observation_Record_Broker
extends Object

A mechanism for interacting with a HiRISE database to select and update HiRISE observation records.

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.

Database Access

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.

Version:
2.23
Author:
Christian Schaller - UA/PIRL
See Also:
Observation_Record

Field Summary
static String DEFAULT_CATALOG
          Default name for the database catalog that contains the observation parameter and CCD parameter tables.
static String ID
          Class identification name with source code version and date.
 
Constructor Summary
Observation_Record_Broker(Database database)
          Creates an observation record broker with the specified database.
Observation_Record_Broker(Database database, String catalog)
          Creates an observation record broker with the specified database and named database catalog.
 
Method Summary
 String getCatalog()
          Gets the database catalog this broker uses for its transactions.
 Database getDatabase()
          Gets the database currently being used by this broker to conduct transactions.
 String makeTableReference(String table)
          Generates a table reference for the indicated table using this broker's catalog.
 Observation_Record select(String id)
          Retrieves an observation record from this brokers's database.
 void setCatalog(String catalog)
          Sets the database catalog this broker will use for its transactions.
 void setDatabase(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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ID

public static final String ID
Class identification name with source code version and date.

See Also:
Constant Field Values

DEFAULT_CATALOG

public static final String DEFAULT_CATALOG
Default name for the database catalog that contains the observation parameter and CCD parameter tables.

See Also:
Constant Field Values
Constructor Detail

Observation_Record_Broker

public Observation_Record_Broker(Database database,
                                 String catalog)
Creates an observation record broker with the specified database and named database catalog.

Parameters:
database - the database with which this broker conducts operations.
catalog - the catalog that holds the observation parameter tables.

Observation_Record_Broker

public Observation_Record_Broker(Database database)
Creates an observation record broker with the specified database. The DEFAULT_CATALOG is used for operations.

Parameters:
database - the database with which this broker conducts operations.
Method Detail

getDatabase

public Database getDatabase()
Gets the database currently being used by this broker to conduct transactions.

Returns:
the database currently used for transactions.

setDatabase

public void setDatabase(Database database)
Sets the database to be used by this broker for all future transactions. Setting the database has no effect on the database catalog; it may be necessary to change that as well, via the setCatalog(String) method.

Parameters:
database - the database to use for future transactions.

getCatalog

public String getCatalog()
Gets the database catalog this broker uses for its transactions. This catalog must contain the observation table (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.

Returns:
the database catalog this broker uses.

setCatalog

public void setCatalog(String catalog)
Sets the database catalog this broker will use for its transactions. This catalog must contain the observation table (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.

Parameters:
catalog - the database catalog to use for transactions; if null, DEFAULT_CATALOG will be used instead.

select

public Observation_Record select(String id)
                          throws Database_Exception
Retrieves an observation record from this brokers's database. The record is identified by a unique id, which is the observation ID for the observation.

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.

Parameters:
id - the unique identifier for the observation record.
Returns:
an observation record containing the parameters for the observation identified by the id. If no record exists for the id, null is returned.
Throws:
Database_Exception - if there is a problem with database access.

updateObservationParameters

public int updateObservationParameters(Observation_Record observation)
                                throws Database_Exception
Updates the observation parameters in this broker's database for a given observation record. This method should be used when it is inappropriate to update the individual CCD parameters. For example, when an observation command file is generated and its pathname must be logged in the system, this method should be used, since the CCD parameters are not affected.

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.

Parameters:
observation - the observation record that contains the parameters for the observation to be updated.
Returns:
the number of records updated, which should be 0 or 1.
Throws:
Database_Exception - if there is a problem with database access.

update

public int update(Observation_Record observation)
           throws Database_Exception
Updates the parameters in this broker's database for a given observation record. If the record does not already exist, it is updated via an INSERT operation. If the record already exists, an UPDATE operation is used instead.

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.

Parameters:
observation - the observation record that contains the parameters for the observation to be updated.
Returns:
the total number of records updated, which should equal 1 + the number of CCDs used in the observation.
Throws:
Database_Exception - if there is a problem with database access.

makeTableReference

public String makeTableReference(String table)
                          throws Database_Exception
Generates a table reference for the indicated table using this broker's catalog.

Parameters:
table - the table for which a table reference will be generated.
Returns:
the table reference
Throws:
Database_Exception - if a table reference cannot be generated.
See Also:
Database.Table_Reference(String,String), getCatalog()

HiRISE

Copyright (C) Arizona Board of Regents on behalf of the Planetary Image Research Laboratory, Lunar and Planetary Laboratory at the University of Arizona