Documentation/Modules/IModule

Interface IModule

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.

Furthermore, the Modules must have a class Options that comprises all user settings as simple types (boolean, long, double, String) or vectors/arrays of those types. The options are automatically read using Java Reflection API.

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

Method Options getOptions()

1. Functionality
   • returns the current Options class.
   • 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 Modules has no impact.
3. Sample Code

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

Method String check()

1. Functionality
   • check, if this Modules is set up correctly, i.e. checks if
     • the Options are correct?
     • all required Connections of the Modules are available (e.g. an optimization algorithm may require one connection to a problem)
     • the settings (e.g. Options) agree with the properties of connected Modules?
   • checking requires several steps:
     1. if theModules is connected to other Modules, it should first
        • call check() of the connected Modules and
        • return a message, if any connectedModules’s check is unsuccessful (i.e. a non-empty string is returned)
     2. if checking the connected Modules was successful, theModules 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 theModules is connected to other Modules, it should first
        • call the init() of the connected Modules and
        • return a message, if any connectedModules 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 connectedModules 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
   • theModules should check if initialization is necessary. Typically initialization is necessary when
     • the Options of theModules are changed
     • the connections of theModules 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 thisModules.
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
   • AModules such as an optimization algorithm should return the problem properties when it thisModules is called.
2. Objectives
   • get information aboutModules properties for checking or debugging user settings

Summary

1. properties of aModules 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.