![[OPUS]](opus.gif)
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
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
Files_bb::~Files_bb - The Files_bb destructor.
Synopsis
Files_bb::~Files_bb()
Description
This method destroys the object.
Exceptions Thrown
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
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
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
Example
Files_bb fbb;
cout << "Running the Files Blackboard test driver." << endl;
if (fbb.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