[OPUS]

Files_bb - A blackboard object that is an interface to the file system.


Availability:

This class is available for the OPUS Blackboard API. The initial OPUS 2.0 release is described here

Constructors:
Files_bb( )
~Files_bb( )

Methods:
post( ) creates a new file
erase( ) deletes a file
replace( ) renames a file
search( ) searches for a file and returns any matches
lock_entry( ) locks a file
str( ) gets the blackboard name
new_file_entry( ) creates a new File_entry object
test_driver( ) runs the test driver

Description

The files blackboard is a blackboard interface to the file system. The entries used by this blackboard, File_entry objects, are file specifications.

Derived from

Blackboard

Example

  
    #include <iostream>
    #include <vector>
    #include "files_bb.h"
    #include "entry.h"
    #include "file_entry.h"
  
    using namespace std;
  
    // The following example uses the Files Blackboard to search for
    // a wildcarded file name.
    int main(int argc, char* argv[])
    {
       Files_bb fbb;
       File_entry* f_ent = new File_entry("temp.*"); // create File_entry
                                                     // file mask
  
       vector<Entry*> results;                       // results vector
       if (fbb.search(f_ent, results)) {             // files located
          for (int i = 0; i < results.size(); i++) {
             cout << "Found file " << f_ent->str() << endl;
             delete results[i];                      // delete result entry
          }
       } else {
          cout << "No files matching " << f_ent->str()
               << " found." << endl;
       }
       delete f_ent;                                 // delete mask
       return(0);
    }
  

See Also:


Files_bb::Files_bb - The Files_bb constructor.

Synopsis


Files_bb::Files_bb()

Description

This method constructs an instance of the files blackboard.

Exceptions Thrown

none


Files_bb::~Files_bb - The Files_bb destructor.

Synopsis


Files_bb::~Files_bb()

Description

This method destroys the object.

Exceptions Thrown

none


Files_bb::post - Create a new, empty file on the file system.

Synopsis


void Files_bb::post(
                    const Entry* e) // I - File_entry object containing
                                    //     the file to create

Description

Given a File_entry object argument containing a file name, this method creates that file on disk. Wildcards are not permitted in any of the File_entry object's fields.

Exceptions Thrown

Bad_val<Entry*> - if argument is null or contains wildcard characters; Bad_val.arg points to the calling argument
Type<Entry*> - if the argument is not of type File_entry; Type.arg points to the calling argument
Io_error<int> - if file creation fails; Io_error.arg contains the value of errno

Example

  
    Files_bb fbb;
    string fname("temp.txt");                  // file name to create
    File_entry* f_ent = new File_entry(fname); // create new File_entry
                                               // with file name
  
    fbb.post(f_ent);                           // create file
    delete f_ent;                              // no longer needed
  


Files_bb::erase - Delete the file specified by the File_entry object.

Synopsis


void Files_bb::erase(
                     const Entry* e)  // I - File_entry object specifying
                                      //     the file to delete

Description

The File_entry object can contain wildcards in which case all matches are deleted. If no matching file is found, an exception is thrown.

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_entry; Type.arg points to the first argument
Io_error<string> - if the search attempt fails; Io_error.arg contains the error message
Severe<void*> - if the search results cannot be parsed; Severe.arg points to null
Bad_val<Entry*> - if argument is null; Bad_val.arg points to the calling argument
Type<Entry*> - if argument is not of type File_entry; Type.arg points to the calling argument
No_entry<Entry*> - if no matching file is found on disk; No_entry.arg points to the calling argument

Example

  
    Files_bb fbb;
    File_entry* f_ent = new File_entry("temp.txt"); // file to delete
  
    fbb.erase(f_ent);                               // delete file
    delete f_ent;                                   // no longer needed
  


Files_bb::replace - Rename a file.

Synopsis


void Files_bb::replace(
                       const Entry* old_ent, // I - old file name
                       const Entry* new_ent) // I - new file name

Description

This method renames the file specified by the first argument to the file name specified by the second argument. Wildcards are not permitted in either of the File_entry objects.

Exceptions Thrown

Bad_val<Entry*> - if argument(s) is null or wildcard characters are present; Bad_val points to the bad argument
Type<Entry*> - if argument(s) is not of type File_entry; Type.arg points to the bad argument
Io_error<int> - if rename attempt fails; Io_error.arg contains the value of errno

Example

  
    Files_bb fbb;
    File_entry* old_file = new File_entry("old_file"); // old file name
    File_entry* new_file = new File_entry("new_file"); // new file name
  
    try {
       fbb.replace(old_file, new_file);                // rename file
    }
    catch(...) {
       cout << "File rename failed." << endl;
    }
  
    delete old_file;                                   // no longer needed
    delete new_file;                                   // no longer needed
  


Files_bb::search - Search for a match or matches to a file name.

Synopsis


int Files_bb::search(
                     const Entry* e,      // I - File_entry object specifying
                                          //     the file to search for
                     vector<Entry*>& res) // I - results vector
                     const

Description

This method conducts a search for the file name (can contain wildcards) specified by the first argument. Any matches are pushed onto the vector supplied in the second argument. The matching entries are allocated off the heap and should be deleted by the client when they are no longer needed.

Returns

    The size of the supplied vector after the search is made and any

matching entries have been pushed onto the vector.

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_entry; Type.arg points to the first argument
Io_error<string> - if the search attempt fails; Io_error.arg contains the error message
Severe<void*> - if the search results cannot be parsed; Severe.arg points to null

Example

  
    Files_bb fbb;
    File_entry f_ent = new File_entry("temp.*"); // create File_entry
                                                 // file mask
  
    vector<Entry*> results;                      // results vector
    if (fbb.search(f_ent, results)) {
       for (int i = 0; i < results.size(); i++) {
          cout << "Found file " << f_ent->str() << endl;
          delete results[i];                     // delete result entry
       }
    }
    delete f_ent;                                // no longer needed
  


File_bb::new_file_entry - Create a new File_entry object.

Synopsis


File_entry* Files_bb::new_file_entry() const

File_entry* Files_bb::new_file_entry(
                                     const string& fname) // I - file name
                                     const

File_entry* Files_bb::new_file_entry(
                                     const char* fname) // I - file name
                                     const

Description

A new File_entry object is constructed off the heap and initialized by the supplied file name argument (if present). The client should delete the object when it is no longer needed.

Returns

    A pointer to the new File_entry object initialized by the calling

argument (if supplied).

Exceptions Thrown

none

Example

  
    Files_bb fbb;
    File_entry* f_ent = fbb.new_file_entry("/tmp/temp.txt");
  


Files_bb::lock_entry - Place a lock on the indicated file.

Synopsis


Opus_lock* Files_bb::lock_entry(
                                const Entry* ce) // I - file to lock

Description

This method attempts to create a lock file for the indicated file. Wildcards are not permitted in the argument. If the file is locked already, an exception is thrown. If multiple matches to the 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

    Pointer to a new Opus_lock object for the file.

Exceptions Thrown

Bad_val<Entry*> - if argument is null or contains wildcard chars; Bad_val.ard points to the calling argument
Type<Entry*> - if argument is not of type File_entry; 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

  
    Files_bb fbb;
    File_entry* f_ent = new File_entry("temp.txt"); // file to delete
  
    try {
       Opus_lock* lck = fbb.lock_entry(f_ent);
       fbb.erase(f_ent);                            // delete file
       delete lck;                                  // release & delete
    }
    catch(...) {
       cout << "Failed to get file lock - file not erased." << endl;
    }
    delete f_ent;                                   // no longer needed
  
  


Files_bb::str - Get the blackboard name.

Synopsis


string Files_bb::str() const

Description

This method returns a string describing the blackboard.

Returns

    string containing the blackboard name, "Files_bb".

Exceptions Thrown

none

Example

  
    Files_bb fbb;
    cout << "The files blackboard name is " << fbb.str() << endl;
  


Files_bb::test_driver - Test the blackboard implementation.

Synopsis


bool Files_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

  
    Files_bb fbb;
    cout << "Running the Files Blackboard test driver." << endl;
    if (fbb.test_driver()) cout << "Pass." << endl;
    else                    cout << "Fail." << endl;
  

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

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