Framework properties

Several properties can be defined in the configuration:

• The property setting is stack traces must be presented in the case of exceptions encounteed in the framework
• Several properties for Python scripts
• The name which should be shown in the GUI window of the framework
• The maximum number of lines of the Logger
• A file which will be used to write the logs
• The log level specifying which message levels will be logged by the Logger
• Allow publish Services and request-response Services to accept to have more than once provider at the same time
• Configure how event service datas are handled before notified subscribers
• Simplify debugging Groovy or Python scripts
• Show the applications versions
• Allow the framework to "fail" rather than logging an error when the configuration is incorrect at startup
• Specify the paths for the user-defined module types
• Specify the paths for the native libraries
• Allow to include portions of the XML documents using the xInclude mechanism
• Allow to specify how the services invocations are performed
• Define how complex datas are considered as changed by default
• Allow to specify the number of background Threads to use in the services invocation
• Any user-defined global configuration properties which can be used in all other configuration files
• Specify how classes are loaded if the configuration is an entry in a zip file or jar file
• Use a recorder engine which will record all invocations and notifications in the framework

Note that application-specific framework properties are set in the application properties configuration file.

GUI window and logger area

The GUI window shows a logger area which presents various logs and errors which can appear during the framework execution:
.

Note that the following command-line arguments allow to configure if the window ill appear or be iconified:

• "noGUI": true if the Framework Window should not be shown
• "minimizeGUI": true if the Framework Window should be iconified

For example:

      java -jar protoframework.jar config=filelist.xml minimizeGUI      

Name of the GUI window

The windowTitle and fullWindowTitle properties specify the name which must be shown in the GUI window.

• The windowTitle property will append the title to the default GUI window name
• The fullWindowTitle property will replace the title

For example:

      <files>
         <file url="applications.xml" />
         <file url="services.xml" />
         <file url="types.xml" />
         <property key="windowTitle" value="Sample 1" />
      </files>

has the following result on the GUI window:

      <files>
         <file url="applications.xml" />
         <file url="services.xml" />
         <file url="types.xml" />
         <property key="fullWindowTitle" value="Sample 1" />
      </files>

has the following result on the GUI window:

Position of the GUI window

The consolePosition property allow to specify he position of the GUI window. The format is <x position;>;<y position;. For example:

      <files>
         <file url="applications.xml" />
         <file url="services.xml" />
         <file url="types.xml" />
         <property key="consolePosition" value="500;500" />
      </files>

Logger size

The logMaximumLines property specifies the maximum number of lines of the Logger.

Log File

The logFile property specifies a file which will be used to write the logs.

Stack traces configuration

The logStackTraces property can be set to specify that stack traces must be presented in the case of exceptions encountered in the framework. By default only the name of the exception will be shown in the Logger.

Print stack trace

The printStackTrace property allows to print the errors stackTrace on the console.

Log level

The logLevel property specifies which message levels will be logged by the Logger. The supported values are^[1]

The values are not case sensitive

:

• "OFF": will speciify that no logs will be shown
• "FINE" (500): the log level for warnings
• "FINER" (400): the log level for warnings
• "CONFIG" (700): the log level for warnings
• "INFO" (800): the log level for warnings
• "WARNING" (900): the log level for warnings
• "SEVERE" (1000): the default log level

For example:

      // will be logged by default, except if the log level is set to "OFF"
      Logging.error("the error");

      // will only be logged if the log level is set at least to "WARNING"
      Logging.error("the error", Level.WARNING);

      // will only be logged if the log level is set at least to "INFO"
      Logging.info("the error", Level.INFO);

FailFast configuration

The failFast property can be set to specify that the framework must throw an exception in the following cases rather than log an error:

• The configuration of a module is "fatally" incorrect. This is the case if the module instance can not be found, or if one of its specified entry points do not exist
• An address used in the network configuration is already bound

The default behavior is false (an error will be logged in these cases).

For example:

      <files>
      ...
         <property key="failFast" value="true" />
      </files>

Configure how event services datas are handled

By default event Services datas are handled in a background Thread by each subscriber when the notification is effective. It means that if the same event service is sent multiple times in rapid succession with different values for its datas, it is possible that the values seen by the subscribers will appear to always have the last value^[2]

This is because the effective notification will happen "some time in the future" after the provider has performed its invocation, which means the values can have already been updated when the notification is really applied

.

To avoid this it is possible to specify that datas are copied to an intermediary repository for each invocation before the notification Thread is called, ensuring that the datas will appear with their effective values even if the invocation has been performed multiple times in rapid succession. The name of the boolean property is eventServicesCopyDatas.

For example:

      <files>
      ...
         <property key="eventServicesCopyDatas" value="true" />
      </files>

Accepting multiple providers

By default only event Services allow to have multiple providers at the same time.

However it is possible to configure the framework to allow publish Services and request-response Services to accept to have more than once provider at the same time. The name of the boolean property is acceptMultipleProviders.

For example:

      <files>
      ...
         <property key="acceptMultipleProviders" value="true" />
      </files>

Auto attaching providers

By default if there is more than one provider to a service only those which are explicitly declared as attached to the service are providers of this service.

However it is possible to configure the framework to allow by default as many providers to a service as desired without having to declare it for each provider configuration. The name of the boolean property is autoAttachProviders.

For example:

      <files>
      ...
         <property key="autoAttachProviders" value="true" />
      </files>

Debugging scripts

The debugScripts property can be set to simplify debugging Groovy or Python scripts.

For example:

      <files>
      ...
         <property key="debugScripts" value="true" />
      </files>

Python configuration properties

The global framework properties have several properties which are used for Python modules:

• The path of the Python executable to execute Python scripts
• The default Python version to execute Python scripts
• The behavior of Python scripts when encountering Deprecation or Future warnings
• The default port size for commmunicating with Python scripts
• Show the python command-line when Python processes are started
• Set the default values for the waitAtStart and waitAtInit properties for Python modules
• Set if enumerations should be sent by default with their state names rather than an int

Native libraries

The libPath element allows to declare where to find the native libraries used with java modules. For example:

      <files>
         <file url="applications.xml" />
         <file url="services.xml" />
         <file url="types.xml" />
         <file url="properties.xml" />
         <libPath url="my/lib" />
      </files>

Applications versions

The showLibVersion property can be set to show the version of the applications jar files on the logger. Note that a library version for an application will only be shown on the logger if the Manifest of the Application jar file has the Version manifest property.

For example, if "appli1" has the following Manifest:

      Version: 12.1

This will show in the logger:

XInclude support

The supportXInclude property allows to include portions of the XML documents using the xInclude mechanism. It help to define only once an XML structure (such as the interfaces of a module) and reuse them in several configurations.

For example:

      <files>
         <file url="applications.xml" />
         <file url="services.xml" />
         <file url="types.xml" />
         <file url="properties.xml" />
         <property key="supportXInclude" value="true" />
      </files>

Default behavior to detect changes for complex datas

The defaultChangeBehavior allows to specify how complex datas are considered as changed by default. There are two modes:

• changed specifies that the full graph of a complex datas is taken into account to detected if the data has changed
• unchanged specifies that normally a complex data is always considered as changed

The changed value is used by default.

For example:

      <files>
         <file url="applications.xml" />
         <file url="services.xml" />
         <file url="types.xml" />
         <property key="defaultChangeBehavior" value="unchanged" />
      </files>

Service invocation properties

Three properties allow to customize the way services are invoked:

• The serviceInvocationMode property allows to specify if the services will be invoked in a background Thread managed by an ExecutorService^[3]
  Using a Thread Pool
  or in the same Thread as the caller
• The serviceInvocationDomain property allows to specify if there will be one separate Thread pool for each module or one unique pool for all the Framework, shared by all modules
• The servicesExecutorPool property allows to specify the number of Threads used in the pool

Note that by default:

• The serviceInvocationMode is executorService, which means that a Thread pool will be used
• The servicesExecutorPool is 1, which means that only one Thread will be used
• The serviceInvocationDomain is module, which means that there will be one pool for each module

Of course if serviceInvocationMode is blocking, the two other propeties are not used.

Service invocation mode

The serviceInvocationMode property allows to specify how the services invocation will be performed:

• By default, or if the property has the executorService value, the framework will perform the invocation in a background Thread
• If the property has the blocking value, the framework will perform the invocation in the same Thread as the caller

For example:

      <files>
         <file url="applications.xml" />
         <file url="services.xml" />
         <file url="types.xml" />
         <property key="serviceInvocationMode" value="blocking" />
      </files>

Service invocation domain

The serviceInvocationDomain property allows to specify the on which domain the service executor pool will work:

• By default, or if the property has the module value, the framework will create one separate ExecutorService for each module
• If the property has the global value, the framework will create only one ExecutorService for all the modules

For example:

      <files>
         <file url="applications.xml" />
         <file url="services.xml" />
         <file url="types.xml" />
         <property key="serviceInvocationDomain" value="global" />
      </files>

Services executor pool

The servicesExecutorPool property allows to specify the number of Threads which will be used in the background Threads pool if the framework perform the services invocation in a background Thread. By default there is only one Thread in the pool. Of course this property is not useful if the invocations are blocking (performed in the same Thread as the caller).

For example:

      <files>
         <file url="applications.xml" />
         <file url="services.xml" />
         <file url="types.xml" />
         <property key="serviceInvocationMode" value="executorService" />
         <property key="servicesExecutorPool" value="5" />
      </files>

Loading a configuration which is an entry in a zip or jar file

The allowNestedClassLoaders property specify how the modules will be loaded if the filelist configuration is an entry in a jar file or zip file:

• By default a standard URLClassLoader will be used
• If the property value is true, a special URLClassLoader which is able to loa Jar files nested in jar files will be used. This will only be used through if the filelist configuration is a jar of zip file entry

Note that by default the standard Java ClassLoaders are not able to load classes which are defined in jar files nested inside zip or jar files.

Example

Suppose for example the following zip file containing the configuration:

      zipfile.zip
      - filelist.xml
      - applications.xml
      - services.xml
      - types.xml
         - EmbeddedLibraries.jar

With the following content for the filelist.xml file:

      <files>
         <file url="applications.xml" />
         <file url="services.xml" />
         <file url="types.xml" />
         <property key="allowNestedClassLoaders" value="true" />
      </files>

We can do:

      java -jar protoFramework.jar config=jar:file:/zipfile.zip!/filelist.xml

Use Global ClassLoaders

The useGlobalClassLoaders will specify that if the configuration is specified as an entry of a jar file, the jar file will be automatically added to the general ClassLoader.

Example

Suppose for example the following jar file containing the configuration:

      MyConfig.jar
         - META-INF
            - MANIFEST-MF
         - filelist.xml
         - applications.xml
         - services.xml
         - types.xml
         - org
            - samples
            - Module.class

With the following content for the filelist.xml file:

      <files>
         <file url="applications.xml" />
         <file url="services.xml" />
         <file url="types.xml" />
         <property key="useGlobalClassLoaders" value="true" />
      </files>

We can do:

      java -jar protoFramework.jar config=jar:file:/MyConfig.jar!/filelist.xml

Log debug messages

The debugLog property can be used to help with debugging. It specifies a file which will be used so as the module can log messages. For example:

      <files>
         <file url="applications.xml" />
         <file url="services.xml" />
         <file url="types.xml" />
         <property key="debugLog" value="myFile.log" />
      </files>

The following method can be used by modules to log messages to both the console and this log file:

      DebugBuffer.println(message);

The file will be automatically flushed when the framework is shutdown.

Recorder engine

The eventLogger element allows to use a recorder engine which will record all invocations and notifications in the framework.

The attributes of the element are:

• The url attribute declares the jar file of the library which will be used to perform the record
• The scenario attribute declares the file to use to serialize the record
• The autoStart attribute is an optional attribute specifying if the record must begin as soon as the framework starts

For example:

      <files>
         <file url="applications.xml" />
         <file url="services.xml" />
         <file url="types.xml" />
         <eventLogger url="perfoLogger.jar" scenario="logged.xml"/>
      </files>

User-defined module types

The customFactories property allows to specify the paths for the user-defined module types, which allow to define your own kind of modules and refer to them in the applications configuration. For example, you could define specific module types to handle Simulink modules, or other kinds of modules linked to any other framework or library.

For example:

      <files>
         <file url="applications.xml" />
         <file url="services.xml" />
         <file url="types.xml" />
         <file url="properties.xml" />
         <property key="customFactories" value="myPythonFactory.jar;simulinkFactory.jar" />
      </files>

User-defined global configuration properties

A global property is declared by the confProperty element. This element has two mandatory attributes:

• key: the name of the variable
• value: the value of the variable
• allowSetByLauncher: allow to set the value of the variable through the launcher arguments

These properties can be used in all other configuration files by using the "${variable_name}" construct.

For example:

      <files>
         <file url="applications.xml" />
         <file url="services.xml" />
         <file url="types.xml" />
         <confProperty key="myPath" value="D:/my/directory/"
      </files>

For example, we can use this property in the properties configuration file:

      <properties>
         <application name="appli1" >
            <module name="module1" >
               <moduleProperty key="theGraphicPath" value="${myPath}/graphic.xml" />
            </module>
         </application>
      </properties>

Setting user-defined property values through the launcher arguments

It is possible to specify that a user-defined property value can be set through the launcher arguments by setting the true value to the allowSetByLauncher attribute. In that case:

• The value attribute specifies the value which will be used to set the user-defined property if the launcher does not define this value
• Else the value will be set by the launcher

For example:

      <files>
         <file url="applications.xml" />
         <file url="services.xml" />
         <file url="types.xml" />
         <confProperty key="myPath" value="D:/my/directory/" allowSetByLauncher="true" />
      </files>

If we start the framework by:

      java -jar protoframework.jar config=filelist.xml

The myPath value will have the D:/my/directory/ value.

But if we start the framework by:

      java -jar protoframework.jar config=filelist.xml myPath=D:/the/other/directory

The myPath value will have the D:/the/other/directory value.

Environment properties configuration properties

A system environment variable is declared by the env element. This element can have two attributes:

• key: (mandatory) the name of the system environment variable
• default: (optional) the default value of the variable if the environment variable does not exist

These properties can be used in all other configuration files by using the "${global key}" construct.

For example:

      <files>
         <env key="APPLIS" />
      ...
         <file url="config/${APPLIS}" />
      </files>

It is also possible to set the value for an environment variable, with the setenv element. This element can have these attributes:

• key: (mandatory) the name of the system environment variable
• value: (mandatory) the value of the variable
• overwrite: (optional) true if it is allowed to overwrite the current value of the environment variable if it already exists

For example:

      <files>
         <setenv key="APPLIS" value="applications.xml" />
      </files>

Showing the values of properties

The echo element allows to show the value of an environment variable or a confProperty^[4]

Or the fact that the variable does not exist

.

• If the attribute type has the value "env", it shows the value of an environment variable. It can be a variable set in the system before the start of the framework or a variable set through the setenv element
• If the attribute type has the value "confProperty", it shows the value of a confProperty declaration

For example:

      <files>
         <env key="APPLIS" />
         <confProperty key="theProperty" value="theValue" />
         <file url="${APPLIS}" />
         <file url="services.xml" />
         <file url="types.xml" />
         <echo type="env" key="APPLIS" />
         <echo type="confProperty" key="theProperty" />
      </files>

Example

      <files>
         <file url="applications.xml" />
         <file url="services.xml" />
         <file url="types.xml" />
         <property key="logStackTraces" value="true" />
         <property key="logMaximumLines" value="200" />
         <property key="logFile" value="myFile.log" />
         <property key="acceptMultipleProviders" value="true" />
         <property key="pythonRuntime" value="C:/Program Files (x86)/Python24/python.exe" />
         <property key="showLibVersion" value="true" />
      </files>