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 the Modules is connected to other Modules, it should first
        • call check() of the connected Modules and
        • return a message, if any connected Modules’s check is unsuccessful (i.e. a non-empty string is returned).
     2. if checking the connected Modules was successful, the Modules 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 index)

Currently the index is not used!

1. Functionality
   • initialize Modules such that executing optimizations or learning processes is possible.
   • Initialization requires several steps:
     1. check if the argument (index) 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 Modules is connected to other Modules, it should first
        • call the init() of the connected Modules and
        • return a message, if any connected Modules 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 Modules 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 this method should not be called too often.
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; 
} 

Summary

Properties of a Module should only change when the Method init() is called. This guarantees that Modules do not change while they are checked or other Modules are running!

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
   • 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