OPUS API Class: File_osf

File_osf_bb - A file name-based implementation of an Osf_bb object.

Availability:

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

Osf_bb

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:

Osf_bb
File_osf
"OPUS API Blackboard and Support Classes Design Document"

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

none

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 matching

entries 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

none

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

none

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

none

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;

OPUS API index · STScI Home Page · Search · Topics · Index

For more information, contact opushelp@stsci.edu

Last modified: 25 April 2000

File_osf_bb( )	construct given directory containing the OSF files
~File_osf_bb( )

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

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

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

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