Documentation/Modules/IModule

Interface IModule: Guidelines for Writing Modules

All Modules in OpenOpal must implement the Interface IModule. The interface contains a set of methods. The purpose and the functionality of these methods is described in the following sections.

It is essential for a correct program execution to ensure that the guidelines are exactly followed by the Module programmers.

Method Options getOptions()

1. Functionality
   • returns the current Options.
   • ensure that cloned Options are returned!
2. Objectives
   • returning a clone of the Options ensures that changing Options outside the Module has no impact.
3. Sample Code

public Options getOptions() {
  return (Options) options.clone();
}

Method void setOptions(Options o)

1. Functionality
   • sets the Options for a Module
   • ensure that Options are cloned before they are set!
2. Objectives
   • setting a clone of the Options ensures that changing Options outside the Module has no impact.
3. Sample Code

public void setOptions(Options o) {
  options = (Options) o.clone();
}

Method String check()

1. Functionality
   • check, if this Module is set up correctly, e.g.
     • are the Options correct?
     • are all required Connections of the Module available (e.g. an optimization algorithm may require one connection to a problem)
     • do the settings (e.g. Options) agree with the properties of connected Modules?
   • checking requires several steps:
     1. if the Module is connected to other Modules, it should first
        • call check() of the connected Modules and
        • return a message, if any connected Module’s check is unsuccessful (i.e. a non-empty string is returned)
     2. if checking the connected Modules was successful, the Module should check itself and return a non-empty string if checking fails
2. Properties
   • checks are usually fast
3. Return Value
   • empty string “” if successful, else a message
4. Sample Code for Optimization:

public String check(){ 
 
  s = "";

  // 1. check connected modules
  for (Object o: evaluables) { 
     String so=((IModule)o).check(); 
     if (so.length > 0){ 
      s += “checking connected module with ID “ + 
         (IModule o).getID() + “ failed with message: \\n” + so;
     }
  } 
  if (s.length > 0){ 
      return “checking connected modules failed: \\n” + s; 

  // 2. check this module, return String if not successful 
  if (opt.verbose > 3)
      s+= "Option verbose must be between 0 and 3, but is set to " + opt.verbose + "\\n";
  // …

  return s; 
} 

Method String init(long SystemTime)

( ToDo: This does not work System time [milli sec] is too long to guaranty that no conflict. )

1. Functionality
   • initialize Modules such that executing optimizations or learning processes is possible
   • Initialization requires several steps:
     1. check if the argument (SystemTime) has changed compared to the time of the last check (see also example below). If the argument has not changed, the system has not changed and a new initialization is not necessary. Thus, return the message of the previous check and do no further checking.
     2. If the Module is connected to other Modules, it should first
        • call the init() of the connected Modules and
        • return a message, if any connected Module fails to initialize
     3. If the initialization of the connected Modules is successful, it should then get the properties of the connected Modules
        • return a message, if any connected Module fails to return properties
     4. Initialize itself and return a string if initialization fails
2. Objectives
   • initialization should never lead to exceptions
   • It must not call check()!
3. Properties
   • the init() method is the only method of IModule that may require CPU time (e.g. for loading a large data source). Thus the SystemTime as argument to this method should help avoiding unnecessary initializations.
4. Advanced Features
   • the Module should check if initialization is necessary. Typically initialization is necessary when
     • the Options of the Module are changed
     • the connections of the Module changed
     • the properties of the connected Modules changed
   • if nothing changed, it should not initialize in order to save computer resources
5. Return Value
   • empty string “” if successful, else a message
6. Sample Code for Optimization:

public string init(long init_id){ 

  s = ""; 
  if (this.init_id == init_id){
      return [the message of the last initialization]; 

  this.init_id = init_id; 

  for (Object o: evaluables) {
     String so=((IModule)o).init(init_id); 
     if (so.length > 0){ 
      s += “initializing connected module with ID “ + 
         (IModule o).getID() + “ failed with message: \\n” + so;
     }
  } 
  if (s.length > 0){ 
      return “initializing connected modules failed: \\n” + s; 

  // initialize this module, return String if not successful 
  // …

  return s; 
} 

Method int getID()

1. Functionality
   • gets the ID for this module
2. Objectives
   • the ID is important for debugging, e.g. Modules can identify to which other Modules they are connected

Method void setID(int id)

1. Functionality
   • sets the ID for this Module.
2. Objectives
   • IDs should be set at the time of instantiation and should not be modified.
   • the ID is important for debugging, e.g. Modules can identify to which other Modules they are connected

Method String getInfo()

1. Functionality
   • Returns a String in HTML or plain text, describing the module
   • A Module such as an optimization algorithm should return the problem properties when it this Module is called.
2. Objectives
   • get information about Module properties for checking or debugging user settings

Summary

1. properties of a Module should only change when the Method init() is called.
   • this guarantees that Modules do not change while they are checked!

Open Items

• 'path handling for files','The path handling of openopal:

files that are eg. written by the protocoller are placed in the source directory of the code. Instead the should be a working directory (e.g. the one where one calls openopal from). In addition, the file browsing dialog should remember the working directory (of the previous call).'

• 'Thead save','Methods like evaluate() or init() are currently not thread save.

Multiple (optimization) algorithms may call these methods.

One solution to this is to synchronize critical methods. ','Methods like evaluate() or init() are currently not thread save. Multiple (optimization) algorithms may call these methods.