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

Constructors:

Command_bb( )
~Command_bb( )

Methods:

post( )	posts a copy of the Command entry argument on the blackboard
erase( )	locates and erases the Command object on the blackboard with the same label as the calling argument
replace( )	replaces the blackboard Command object with the same label as the first calling argument with a copy of the second argument
search( )	searches for a Command object on the blackboard with the same label as the first argument and executes it using any calling arguments in the first argument as additional calling arguments to the located Command object
lock_entry( )	no-op
str( )	gets the blackboard name
test_driver( )	runs the test driver

Description

The command blackboard stores entries of function pointers and their associated calling arguments. The entries are Command objects which are indexed on the blackboard by their string label (each entry must have a unique label). This abstraction allows the event polling mechanism to call an arbitrary function each pass through the polling loop, then generate an event if the return value of the function indicates that it should do so. Complicated algorithms can be run as part of the polling process in this way.

Like other blackboards, the search method attempts to locate an entry on the blackboard with the same label as the Command object passed into the method. If a match is found, the execute method of the located Command object is called (if the search condition Command object has any calling arguments of its own, they are passed to the execute method of the located Command object as additional calling arguments for that object).

If the execute method returns true, the located Command object is cloned and pushed onto the vector supplied as the second argument. If the execute method returns false, nothing is added to the results vector. The search method returns the size of the results vector in any case.

Derived from

Blackboard

Example

  
    #include <vector>
    #include <string>
    #include <iostream>
    #include "command.h"
    #include "command_bb.h"
  
    using namespace std;
  
    // The following function demonstrates a global function to be
    // placed on the Command Blackboard by an OAPI client. This simple
    // example dumps its arguments to cout, then returns true.
    bool foo(vector<string>& args)
    {
       for (int i = 0; i < args.size(); i++) cout << args[i] << endl;
       return(true);
    }
  
    // The following driver posts a command on the Command Blackboard,
    // then does a search for it which results in its execution.
    int main(int argc, char* argv[])
    {
       string     label("Foo Command"); // give the command a name
       string     arg("/tmp");          // a command argument
       Command*   com;
  
       com = new Command(label, foo);   // create new Command that points
                                        // to foo()
       com->add_arg(arg);               // add a single calling argument
  
       Command_bb com_bb;
       com_bb.post(com);                // post Command on blackboard
       delete com;                      // no longer needed
  
       com = new Command(label);        // create Command for search
       vector<string> results;          // results vector
  
                                        // search returns size of results
                                        // vector
       if (com_bb.search(com, results)) { 
           cout << "Command execution returns true." << endl;
           delete results[0];           // delete search result
       } else {
           cout << "Command not found or returned false." << endl;
       }
  
       delete com;                      // no longer needed
       return(0);
    }
  

See Also:

• Command
• "OPUS API Blackboard and Support Classes Design Document"

Command_bb::Command_bb - The Command_bb constructor.

Synopsis

Command_bb::Command_bb()

Description

This method constructs a Command_bb object.

Exceptions Thrown

none

Command_bb::~Command_bb - The Command_bb destructor.

Synopsis

Command_bb::~Command_bb()

Description

This method destroys the object. Each Command object on the blackboard is deleted, so care should be taken to prevent the object from going out of scope until it is no longer needed.

Exceptions Thrown

none

Command_bb::post - Post a copy of a Command object on the blackboard.

Synopsis

void Command_bb::post(
                      const Entry* e) // I - Command object to post

Description

A copy of the Command object is constructed and posted to the blackboard. If a Command object already exists on the blackboard with the same Com_label value, posting fails and 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 Command; Type.arg points to the calling argument
Already<Entry*>	- if Command with same Com_label already exists; Already.arg points to the calling argument

Example

  
    bool foo(vector<string>&);
    Command_bb cbb;
    string label("COMMAND1");
    Command* com = new Command(label, foo);
    cbb->post(com);
    delete com;
  

Command_bb::erase - Remove a Command entry from the blackboard.

Synopsis

void Command_bb::erase(
                       const Entry* e)      // I - pointer to a Command
                                            //     object with a label
                                            //     matching the one to
                                            //     delete

Description

A search is made of the blackboard for a Command object with a Com_label value identical to the calling argument's. If found, the blackboard entry is deleted. If no match is found, 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 Command; Type.arg points to the calling argument
No_entry<Entry*>	- if no match to the argument's Com_label is found; No_entry.arg points to the calling argument

Example

   
    Command_bb cbb;
    string label("COMMAND1");
    Command* com = new Command(label);     // create new Command with label
                                           // matching the one to delete
  
    try {
       cbb.erase(com);                     // attempt to erase it
    }
    catch(No_entry<Entry*>) {              // no such command
       cout << label << " was not found.";
    }
    delete com;                            // no longer needed
  

Command_bb::replace - Replace a Command object on the blackboard with another.

Synopsis

void Command_bb::replace(
                         const Entry* old_ent, // I - Command object with
                                               //     the same Com_label
                                               //     as the one to be
                                               //     replaced
                         const Entry* new_ent) // I - Replacement Command
                                               //     object

Description

An attempt is made to erase the Command object with the same Com_label as the first argument from the blackboard. If successful, a copy of the second argument is posted.

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 Command; Type.arg points to the calling argument
No_entry<Entry*>	- if no match to the argument's Com_label is found; No_entry.arg points to the calling argument
Bad_val<Entry*>	- if argument is null; Bad_val.arg points to the calling argument
Type<Entry*>	- if argument is not of type Command; Type.arg points to the calling argument
Already<Entry*>	- if Command with same Com_label already exists; Already.arg points to the calling argument

Example

  
    bool foo(vector<string>&);
    Command_bb cbb;
    Command* old_com = new Command(old_label); // create new Command with
                                               // label matching the one
                                               // to delete
    Command* new_com = new Command(new_label,  // create replacement
                                   foo);       // Command
  
    try {
       cbb.replace(old_com, new_com);          // erase old; post new
    }
    catch(...) {
       cout << "Replacement failed." << endl;
    }
    delete old_com;                            // no longer needed
    delete new_com;                            // no longer needed
    

Command_bb::search - Search for and execute a Command on the blackboard.

Synopsis

int Command_bb::search(
                       const Entry* e,          // I   - a Command object
                                                //       with the same
                                                //       Com_label as
                                                //       the search target
                       vector<Entry*>& results) // I/O - results vector
                       const

Description

A search for a Command object with the same Com_label as the first argument is made on the blackboard. If a match is found, the execute method of the located Command object is called (if the search condition Command object has any calling arguments of its own, they are passed to the execute method of the located Command object as additional calling arguments for that object).

If the execute method returns true, the located Command object is cloned and pushed onto the vector supplied as the second argument. If the execute method returns false, nothing is added to the results vector.

Returns

    The size of the results vector just prior to returning.

Exceptions Thrown

[any exceptions thrown by the Command function]

Bad_val<Entry*>	- if argument is null; Bad_val.arg points to the calling argument
Type<Entry*>	- if first argument is not of type Command; Type.arg points to the calling argument
No_entry<Entry*>	- if Command not found on Command Blackboard; No_entry.arg points to the calling argument

Example

  
    Command_bb cbb;
    string label("COMMAND1");
    Command* com = new Command(label);         // create new Command with
                                               // label we are looking for
  
    vector<Entry*> results;                    // results vector
    try {
       if(cbb.search(com, results)) {
          cout << "Command execution returns"
             " true." << endl;
          delete results[0];                   // delete result
       }
    }
    catch(...) {
       cout << "Search failed." << endl;
    }
    delete com;                                // no longer needed
  

Command_bb::lock_entry - none

Synopsis

Opus_lock* Command_bb::lock_entry(
                                  const Entry* e)

Description

Creates a Null_lock object off the heap and returns a pointer to it. The client should delete the object when it is no longer needed.

Returns

    A pointer to a Null_lock object allocated off the heap.

Exceptions Thrown

none

Command_bb::str - Get the blackboard name.

Synopsis

string Command_bb::str() const

Description

This method returns a string describing the blackboard.

Returns

    string containing the blackboard name

Exceptions Thrown

none

Example

  
    Command_bb cbb;
    cout << "About to post command on " << cbb.str() << endl;
  

Command_bb::test_driver - Test the blackboard implementation.

Synopsis

bool Command_bb::test_driver()

Description

This method exercises the blackboard 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

  
    Command_bb cbb;
    cout << "Running the Command Blackboard test driver." << endl;
    if (cbb.test_driver()) cout << "Pass." << endl;
    else                   cout << "Fail." << endl;
    

For more information, contact opushelp@stsci.edu

Last modified: 25 April 2000