[OPUS]

File_entry - An entry object that is used on the files blackboard.


Availability:

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

Constructors:
File_entry( )
~File_entry( )

Methods:
clone( ) returns a copy of this object
str( ) overrides the base class implementation to format the output as a file name
operator==( ) overrides the base class implementation, adding wildcard support
assign( ) parses file names into fields
contains_wildcard( ) checks the File_entry for wildcards

Data Members:


 static const char FILE_ACTION_INDICATOR; // FILE_ACTION indicator

 static const std::string FILE_NAME_TOKEN;     // substitution token for
                                          // FILE_ACTION commands

 static const std::string IGNORE;         // signals FILE_ACTION command
                                          // return status is ignored

 static const char DIFF_WILDCARD;         // field apply-differences
                                          // wildcard character

 static const Field::PAD FILES_PADC;  // field pad character

 static const int DIRECTORY_IDENT;    // unique field ID's

 static const int ROOTNAME_IDENT;

 static const int EXTENSION_IDENT;

 static const int DANGLE_IDENT;

Description

File_entries are abstractions of files in the file system, itself abstracted as the files blackboard. They contain the following fields: Directory, Rootname, Extension, and Dangle. For example, the file specification below is parsed to produce the indicated fields in a File_entry object:

       /home/opus/data/lz_1234567890.pod_done
 

^ ^^ ^^ ^^ ^ | || || || | -------------------------------------- | | | | | | | | Directory Rootname | Dangle Extension

OPUS file polling applications (which poll the files blackboard) have the option of specifying a command (a FILE_ACTION) to be executed once a file event completes normally. The action is triggered when one of the event File_entry fields is updated with the status "FILE_SUCCESS" in a call to Opus_env::close_event. At this point, the indicated command is executed and errors are reported to the process log file (if requested).

Derived from

Entry

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:


File_entry::File_entry - The File_entry constructor.

Synopsis


File_entry::File_entry()

File_entry::File_entry(
                       const string& fname) // I - file name to assign from

File_entry::File_entry(
                       const char* fname) // I - file name to assign from

File_entry::File_entry(
                       const File_entry& e) // I - File_entry to
                                            //     initialize from

Description

The constructor creates each of the Field objects (Directory, Rootname, Extension, and Dangle), and if a file name argument is supplied, assigns it to the object. The indicated file need not exist (nor will it be created by this method) on the file system.

Exceptions Thrown

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

Example

  
    File_entry* new_file = new File_entry("temp.txt"); 
  


File_entry::~File_entry - The File_entry destructor.

Synopsis


File_entry::~File_entry()

Description

This method destroys the object.

Exceptions Thrown

none


File_entry::clone - Create a copy of this object.

Synopsis


Entry* File_entry::clone() const

Description

A new File_entry object is created off the heap and initialized with the contents of this object, then returned to the caller. The client should delete the new object when it is no longer needed.

Returns

    A pointer to the new File_entry object initialized with this object.

Exceptions Thrown

none


File_entry::str - Get the file name stored in the object.

Synopsis


string File_entry::str() const

Description

The base class implementation is overridden by this method in order to remove the padding from each of the fields prior to concatenation.

Returns

    string containing the full file specification

Exceptions Thrown

none

Example

  
    Files_bb fbb;
    File_entry* cond = new File_entry("*.log"); // create search mask
  
    cout << "Search on " << cond->str() << " found:" << endl;
    vector<Entry*> res;
    if (fbb.search(cond, res)) {
       for (int i = 0; i < res.size(); i++) {
          cout << res[i]->str() << endl;        // output file names
          delete res[i];                        // delete result
       }
    } else {
       cout << "[no files found]" << endl;
    }
    delete cond;                                // delete condition
  


File_entry::assign - Parse file name and assign to each of the object's fields.

Synopsis


void File_entry::assign(
                        const string& fname) // I - file name to parse

Description

This method parses the input file name into Directory, Rootname, Extension, and Dangle fields. If the path is not absolute, the file name is resolved in terms of the current working directory absolute path.

Exceptions Thrown

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

Example

  
    File_entry file_ent;
    file_ent.assign("/home/opus/process.log");
  


File_entry::operator== - Compare File_entry objects for equality

Synopsis


bool File_entry::operator==(
                            const Entry* e) // I - object to compare to
                            const

Description

This method overrides the base class implementation (which simply calls operator== for each field) to support wildcarding of fields. Two File_entry objects are equal if the non-wildcarded portions of each are identical.

*** Note that a pointer to the object with which the comparison is to be made is required, not a reference.

Returns

    true  - if the File_entry objects are identical

false - if the File_entry objects differ

Exceptions Thrown

Type<Entry*> - if the argument is not of type File_entry; Type.arg points to the calling argument


File_entry::contains_wildcard - Indicate whether the object contains wildcard characters

Synopsis


bool File_entry::contains_wildcard() const

Description

True is returned if the object contains characters in Os_specific::FILE_SINGLE_CHAR_WILDCARD or Os_specific::FILE_MULTI_CHAR_WILDCARD.

Returns

    true  - if one or more wildcard characters are present;

false - if no wildcard characters are present

Exceptions Thrown

none


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