This class is available for the OPUS Blackboard API. The initial OPUS 2.0 release is described here
Constructors:
File_osf_bb( ) | construct given directory containing the OSF files |
~File_osf_bb( ) |
Methods:
post( ) | creates an OSF file |
erase( ) | deletes an OSF file |
replace( ) | renames an OSF file |
search( ) | searches for matching OSF files |
lock_entry( ) | places a lock on an OSF file |
str( ) | gets the blackboard name |
get_bb_dir( ) | gets the directory in which the OSF files are stored |
new_osf( ) | creates a new File_osf object |
test_driver( ) | runs the test driver |
Description
This implementation of an Osf_bb object stores its entries, File_osf objects, as files in the directory specified by the environment variable OPUS_OBSERVATIONS_DIR. The file name contains all of the information-- the files themselves are empty. In general, clients of the OAPI do not instantiate objects of this class directly.
Derived from
Example
#include <iostream> #include "file_osf_bb.h" #include "file_osf.h" #include "dataset.h" #include "data_id.h" #include "time_stamp.h" #include "opus_lock.h" using namespace std; // The following example uses the File OSF Blackboard to find // an OSF on disk, then delete it. int main(int argc, char* argv[]) { File_osf_bb* obb = new File_osf_bb("/home/opus/sci_osfs/"); Osf* fosf = obb->new_osf(); // padded except // for time stamp fosf->search_fill_all(); // place search characters // in all fields Dataset* dat = new Dataset("N12345678"); // set DATASET field fosf->set_field(dat); delete dat; Data_id* did = new Data_id("SCI"); // set DATA_ID field fosf->set_field(did); delete did; vector<Entry*> res; if (obb->search(fosf, res)) { // search for OSF Opus_lock* lck = 0; try { // attempt lock on OSF lck = obb->lock_entry(res[0]); obb->erase(res[0]); // delete it cout << "Deleted OSF: " << fosf->str() << endl; } catch(...) { cout << "Failed to delete OSF: " << res[0]->str() << endl; } delete lck; // release & delete delete res[0]; } else { cout << "Could not find OSF: " << fosf->str() << endl; } delete fosf; delete obb; return(0); }
See Also:
File_osf_bb::File_osf_bb - The File_osf_bb constructor.
Synopsis
File_osf_bb::File_osf_bb( const string& dir) // I - directory containing // the OSF files
Description
The constructor verifies that the directory specified in the calling argument exists.
Exceptions Thrown
Io_error<int> | - if indicated directory does not exist; Io_error.arg contains the value of errno |
Example
File_osf_bb* obb = new File_osf_bb("/home/opus/sci_osfs/");
File_osf_bb::~File_osf_bb - The File_osf_bb destructor.
Synopsis
File_osf_bb::~File_osf_bb()
Description
This method destroys the object.
Exceptions Thrown
File_osf_bb::post - Create an OSF file.
Synopsis
void File_osf_bb::post( const Entry* ce) // I - File_osf object to // create file from
Description
This method creates a new file based on the File_osf object in the blackboard directory. If an OSF file with the same Time_stamp and Dataset fields already exists, an exception is thrown.
Exceptions Thrown
Bad_val<Entry*> | - if argument is null; Bad_val.arg points to the calling argument |
Type<Entry*> | - if argument is not of type File_osf; Type.arg points to the calling argument |
Already<Entry*> | - if the OSF file already exists; Already.arg points to the calling argument |
Io_error<int> | - if a file creation error occurs; Io_error.arg contains the value of errno |
Example
File_osf_bb* obb = new File_osf_bb("/home/opus/sci_osfs/"); Osf* fosf = obb->new_osf(); // padded except for time stamp Dataset* dat = new Dataset("N12345678"); // set DATASET fosf->set_field(dat); delete dat; Data_id* did = new Data_id("SCI"); // set DATA_ID fosf->set_field(did); delete did; try { obb->post(fosf); // place OSF on file system } catch(Already<Entry*>) { cout << "OSF already exists!" << endl; } delete fosf; delete obb;
File_osf_bb::erase - Delete an OSF file.
Synopsis
void File_osf_bb::erase( const Entry* ce) // I - File_osf object to delete
Description
The OSF file named in the argument is deleted from the blackboard directory. If multiple matches to the OSF are found or no match exists, exceptions are thrown. No attempt is made to lock the object being deleted; the caller is responsible for obtaining a lock prior to making this call.
Exceptions Thrown
Bad_val<Entry*> | - if the argument is null; Bad_val.arg points to the calling argument |
Type<Entry*> | - if argument is not of type File_osf; Type.arg points to the calling argument |
Bad_val<Entry*> | - if first argument is null; Bad_val.arg points to the first argument |
Type<Entry*> | - if first argument is not of type File_osf; Type.arg points to the first argument |
Io_error<const char*> | - if the file search fails; Io_error.arg contains the error message |
Ambiguous<vector<Entry*>*> | - if more than one OSF file is found on disk; Ambiguous.arg points to a vector allocated off the heap containing all matching entries, each allocated off the heap |
Io_error<int> | - if the delete operation fails; Io_error.arg contains the value of errno |
No_entry<Entry*> | - if no OSF file is found; No_entry.arg points to the calling argument |
Example
File_osf_bb* obb = new File_osf_bb("/home/opus/sci_osfs/"); Osf* fosf = obb->new_osf(); // padded except // for time stamp fosf->search_fill_all(); // place search characters // in all fields Dataset* dat = new Dataset("N12345678"); // set DATASET field fosf->set_field(dat); delete dat; Data_id* did = new Data_id("SCI"); // set DATA_ID field fosf->set_field(did); delete did; vector<Entry*> res; if (obb->search(fosf, res)) { // search for OSF Opus_lock* lck = 0; try { // attempt lock on OSF lck = obb->lock_entry(res[0]); obb->erase(res[0]); // delete it delete lck; // release & delete cout << "Deleted OSF: " << fosf->str() << endl; } catch(...) { cout << "Failed to delete OSF: " << res[0]->str() << endl; } delete res[0]; } else { cout << "Could not find OSF: " << fosf->str() << endl; } delete fosf; delete obb;
File_osf_bb::replace - Rename an OSF file.
Synopsis
void File_osf_bb::replace( const Entry* old_ent, // I - OSF file to replace const Entry* new_ent) // I - Replacement OSF // file
Description
This method replaces the OSF file named in the first argument with the OSF file named in the second argument. No attempt is made to lock the object being replaced; the caller is responsible for obtaining a lock prior to making this call.
Exceptions Thrown
Bad_val<int> | - if either argument is null; Bad_val.arg indicates the bad argument (0 or 1) |
Type<const Entry*> | - if either argument is not of type File_osf; Type.arg points to the bad argument |
Io_error<const char*> | - if the file rename attempt fails; Io_error.arg contains the error message |
Example
File_osf_bb* obb = new File_osf_bb("/home/opus/sci_osfs/"); Osf* fosf = obb->new_osf(); // padded except for time stamp fosf->search_fill_all(); // place search characters in // all fields Dataset* dat = new Dataset("N12345678"); // set DATASET fosf->set_field(dat); delete dat; Data_id* did = new Data_id("SCI"); // set DATA_ID fosf->set_field(did); delete did; vector<Entry*> res; if (obb->search(fosf, res)) { // search for OSF Entry* nosf = res[0]->clone(); did = new Data_id("ARC"); // create new DATA_ID nosf->set_field(did); delete did; obb->replace(res[0], nosf); // replace original OSF delete res[0]; delete nosf; } delete fosf; delete obb;
File_osf_bb::search - Search for an OSF file on the blackboard.
Synopsis
int File_osf_bb::search( const Entry* ce, // I - the OSF file to // look for vector<Entry*>& res) // I - results vector const
Description
A search of the blackboard is made for the file named in the File_osf object argument. Any matches are placed in new File_osf objects which are pushed on the vector argument. The client should delete these entries when they are no longer needed as they are allocated off the heap.
Returns
The size of the vector argument after the search is made and matchingentries have been pushed on the vector argument.
Exceptions Thrown
Bad_val<Entry*> | - if first argument is null; Bad_val.arg points to the first argument |
Type<Entry*> | - if first argument is not of type File_osf; Type.arg points to the first argument |
Io_error<const char*> | - if the file search fails; Io_error.arg contains the error message |
Example
File_osf_bb* obb = new File_osf_bb("/home/opus/sci_osfs/"); Osf* fosf = obb->new_osf(); // padded except for // time stamp fosf->search_fill_all(); // place search characters in // all fields Dataset* dat = new Dataset("N12345678"); // replace DATASET in OSF fosf->set_field(dat); delete dat; Data_id* did = new Data_id("SCI"); // replace DATA_ID in OSF fosf->set_field(did); delete did; vector<Entry*> res; if (obb->search(fosf, res)) { // search for OSF obb->erase(res[0]); // delete it delete res[0]; } delete fosf; delete obb;
File_osf_bb::new_osf - Create a new File_osf object.
Synopsis
Osf* File_osf_bb::new_osf() const Osf* File_osf_bb::new_osf( const char* fname) // I - OSF file name const
Description
A new File_osf object is constructed off the heap and returned to the caller. If an argument is provided, it should contain a valid OSF file name. If no argument is provided, the new object will contain a Time_stamp field initialized with the current time; all other fields will contain padding. The client should delete the new object when it is no longer needed.
Returns
A pointer to the new File_osf object.
Exceptions Thrown
Bad_val<string> | - if the file name fails to parse; Bad_val.arg contains a copy of the calling argument |
Example
File_osf_bb* obb = new File_osf_bb("/home/opus/sci_osfs/"); Osf* fos = obb->new_osf();
File_osf_bb::lock_entry - Create a lock file for the indicated OSF file.
Synopsis
Opus_lock* File_osf_bb::lock_entry( const Entry* ce) // I - OSF file to lock
Description
This method attempts to create a lock file for the indicated OSF file. If the OSF is locked already, an exception is thrown. If multiple matches to the OSF file are found, or no match exists, exceptions are thrown. The returned Opus_lock object is allocated off the heap, and should be deleted by the client when it is no longer needed.
Returns
A new Opus_lock object for the OSF file.
Exceptions Thrown
Bad_val<Entry*> | - if argument is null; Bad_val.arg points to the calling argument |
Type<Entry*> | - if argument is not of type File_osf; Type.arg points to the calling argument |
Locked<string> | - if the target file is locked already; Locked.arg contains the target name |
Io_error<int> | - if an IO error occurs during the lock attempt; Io_error.arg contains the value of errno |
Bad_val<string> | - if the stretch cannot be resolved; Bad_val.arg contains the stretched file name |
Bad_val<vector<string>> | - if the calling arguments are incorrect; Bad_val.arg is a vector containing the calling arguments |
Io_error<int> | - if the disk space check fails; Io_error.arg contains the value of errno |
Bad_val<vector<string>> | - if calling arguments are incorrect; Bad_val.arg is a vector containing the calling arguments |
Exec<int> | - if the subprocess spawn attempt fails; Exec.arg contains the return status from the spawn attemp |
Bad_val<string> | - if the string does not appear to be a directory specification or invalid characters are present; Bad_val.arg contains the calling argument |
Io_error<int> | - if a problem occurs determining the current working directory; Io_error.arg contains the value of errno |
Bad_val<string> | - if the string contains invalid characters; Bad_val.arg contains the calling argument |
Bad_val<string> | - if the extension prefix is not present or invalid characters are present; Bad_val.arg contains the calling argument |
Bad_val<string> | - if dangle prefix is not present or invalid characters are present; Bad_val.arg contains the calling argument |
Io_error<int> | - if an IO error occurs creation of the lock directory; Io_error.arg contains the value of errno |
Example
File_osf_bb* obb = new File_osf_bb("/home/opus/sci_osfs/"); Osf* fosf = obb->new_osf(); // padded except // for time stamp fosf->search_fill_all(); // place search characters // in all fields Dataset* dat = new Dataset("N12345678"); // set DATASET field fosf->set_field(dat); delete dat; Data_id* did = new Data_id("SCI"); // set DATA_ID field fosf->set_field(did); delete did; vector<Entry*> res; if (obb->search(fosf, res)) { // search for OSF Opus_lock* lck = 0; try { // attempt lock on OSF lck = obb->lock_entry(res[0]); obb->erase(res[0]); // delete it delete lck; // release & delete cout << "Deleted OSF: " << fosf->str() << endl; } catch(...) { cout << "Failed to delete OSF: " << res[0]->str() << endl; } delete res[0]; } else { cout << "Could not find OSF: " << fosf->str() << endl; } delete fosf; delete obb;
File_osf_bb::str - Get the blackboard name.
Synopsis
string File_osf_bb::str() const
Description
This method returns a string describing the blackboard.
Returns
string containing the blackboard name, "File_osf_bb".
Exceptions Thrown
Example
File_osf_bb* obb = new File_osf_bb("/home/opus/sci_osfs/"); cout << "OSF implementation in use is " << obb->str() << endl;
File_osf_bb::get_bb_dir - Get the blackboard location on the file system.
Synopsis
string File_osf_bb::get_bb_dir() const
Description
This method returns the directory in which the blackboard is stored.
Returns
string containing the blackboard location
Exceptions Thrown
File_osf_bb::test_driver - Test the blackboard implementation.
Synopsis
bool File_osf_bb::test_driver()
Description
This method exercises the object's methods. Diagnostic output is sent to cerr. If all of the tests pass, this method returns true. Otherwise, it returns false. All exceptions generated during the test are caught and reported.
Returns
true - if all tests pass;false - if one or more of the tests fail
Exceptions Thrown
Example
File_osf_bb* obb = new File_osf_bb("/home/opus/sci_osfs/"); cout << "Running the File OSF Blackboard test driver." << endl; if (obb.test_driver()) cout << "Pass." << endl; else cout << "Fail." << endl;
Copyright © 1997-2000 The Association of Universities for
Research in Astronomy, Inc. All Rights Reserved.
For more information, contact opushelp@stsci.edu
Last modified: 25 April 2000