Skip to content

Commit

Permalink
Do not speak of classpath properties but of application properties
Browse files Browse the repository at this point in the history
  • Loading branch information
Martijn Dirkse committed Aug 8, 2024
1 parent f5dc84e commit 6339853
Show file tree
Hide file tree
Showing 3 changed files with 9 additions and 9 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,9 @@ The bottom layer shows the operating system of your server. On top of that you n

Inside the Frank!Framework layer, you also see the word "classes". This is a relic of the past. In the past the Frank!Framework often hosted only one Frank config and the distinction between the Frank!Framework and that Frank config was blurred. A trace of this practice remains now within the Frank!Runner. With the Frank!Runner, you can put common XML and property files in a folder ``classes`` that is a brother of the ``configurations`` and ``tests`` folders. You can also put a Frank config there if you want, although this is considered bad practice. For the application server there is no distinction between the Frank!Framework and the ``classes`` folder, which is why these are grouped within the same layer.

The shown stack is relevant for Frank developers because it influences the way properties can be used. When the application server is started, it gets property definitions from the operating system and from command-line arguments (system properties). The application server then boots the Frank!Framework. During this process, classpath properties are read from the deployed Frank!Framework and the extra data added there (i.e. your ``classes`` folder). The Configurations layer defines configuration properties, which are just the properties you define within your Frank config.
The shown stack is relevant for Frank developers because it influences the way properties can be used. When the application server is started, it gets property definitions from the operating system and from command-line arguments (system properties). The application server then boots the Frank!Framework. During this process, application properties are read from the deployed Frank!Framework and the extra data added there (i.e. your ``classes`` folder). The Configurations layer defines configuration properties, which are just the properties you define within your Frank config.

A few properties can only be defined as system properties. An example is property ``log.dir``, the directory in which the Frank!Framework should store log files. When it is defined as classpath property, it will not work: the value is not applied by the Frank!Framework to store log information, but references to it in Frank configurations do produce the configured value. There are also properties that only work as system property or classpath property, but not as configuration property. See subsection :ref:`propertiesFramework` for more examples. This limitation can only apply to properties that are interpreted by the Frank!Framework. Other properties (e.g. ``my.hello`` in subsection :ref:`propertiesReference`) can be freely defined as configuration properties, classpath properties or system properties.
A few properties can only be defined as system properties. An example is property ``log.dir``, the directory in which the Frank!Framework should store log files. When it is defined as application property, it will not work: the value is not applied by the Frank!Framework to store log information, but references to it in Frank configurations do produce the configured value. There are also properties that only work as system property or application property, but not as configuration property. See subsection :ref:`propertiesFramework` for more examples. This limitation can only apply to properties that are interpreted by the Frank!Framework. Other properties (e.g. ``my.hello`` in subsection :ref:`propertiesReference`) can be freely defined as configuration properties, application properties or system properties.

The Frank!Framework detects the type of application server used to host it. This information appears in property ``application.server.type``. The following table shows for each application server the resulting value of ``application.server.type``:

Expand Down
6 changes: 3 additions & 3 deletions docs/source/advancedDevelopment/properties/framework.rst
Original file line number Diff line number Diff line change
Expand Up @@ -26,10 +26,10 @@ otap.stage
Has the same meaning as ``dtap.stage``, exists for backward compatibility.

configurations.names
The value should be a comma-separated list of all configurations. For example, if a Frank contains the classpath configuration and a configuration ``MyConfig``, then the value of this property should be ``${instance.name},MyConfig``. Only works as system property or classpath property, unless nested configurations are used. Nested configurations are beyond the scope of this manual at the moment.
The value should be a comma-separated list of all configurations. For example, if a Frank contains the application configuration (loaded into the application server along with the Frank!Framework) and a configuration ``MyConfig``, then the value of this property should be ``${instance.name},MyConfig``. Only works as system property or application property, unless nested configurations are used. Nested configurations are beyond the scope of this manual at the moment.

configurations.MyConfig.classLoaderType
If there is a configuration ``MyConfig``, then this property defines how configuration ``MyConfig`` is read. For example, ``DirectoryClassLoader`` indicates that ``MyConfig`` is stored on the local file system of the server. Configurations can also be stored in the database; then this property has another value. This property should exist for every configuration. ``MyConfig`` should be replaced with the configuration name to get the property name. This property only works as a system property or a classpath property, unless nested configurations are used. Nested configurations are beyond the scope of this manual.
If there is a configuration ``MyConfig``, then this property defines how configuration ``MyConfig`` is read. For example, ``DirectoryClassLoader`` indicates that ``MyConfig`` is stored on the local file system of the server. Configurations can also be stored in the database; then this property has another value. This property should exist for every configuration. ``MyConfig`` should be replaced with the configuration name to get the property name. This property only works as a system property or an application property, unless nested configurations are used. Nested configurations are beyond the scope of this manual.

configurations.autoDatabaseClassLoader
If this property is false (the default), only configurations mentioned in ``configurations.names`` can be uploaded to the database and only if their ``configurations.<config name>.classLoaderType`` property is ``DatabaseClassLoader``. This requires you to set a lot of properties. If you do not need this strict control for uploading configurations, then set this property to true. You can then upload any configuration to the database. The only exceptions are the configs mentioned in ``configurations.names`` in this case.
Expand All @@ -56,7 +56,7 @@ configurations.directory.autoLoad
When you use the Frank!Runner, this property is ``false``. Nevertheless you do not have to specify property ``configurations.names``, because the Frank!Runner sets this property for you.

jdbc.migrator.active
Can be "true" or "false" (the default). When true, database initialization is switched on. The default behavior is to do this with Liquibase, see https://www.liquibase.org/. With Liquibase, the file ``DatabaseChangelog.xml`` is executed. This property behaves differently as a system property or classpath property on the one hand, or as a configuration property on the other hand. See section :ref:`advancedDevelopmentDatabase` for details.
Can be "true" or "false" (the default). When true, database initialization is switched on. The default behavior is to do this with Liquibase, see https://www.liquibase.org/. With Liquibase, the file ``DatabaseChangelog.xml`` is executed. This property behaves differently as a system property or application property on the one hand, or as a configuration property on the other hand. See section :ref:`advancedDevelopmentDatabase` for details.

log.dir
The directory to which the Frank!Framework writes its log files. Only works as system property. Usually it is not necessary to set this property because the Frank!Framework can automatically choose a suitable directory.
Expand Down
8 changes: 4 additions & 4 deletions docs/source/advancedDevelopment/properties/initialization.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,20 @@
How Properties Are Set
======================

In subsection :ref:`propertiesDeploymentEnvironment`, the characteristics of the deployment environment of a Frank config were explained. The Frank!Framework can be deployed on different types of application servers. The Frank!Framework detects the type of application server and automatically sets the property ``application.server.type``. System administrators can configure the properties ``dtap.stage`` and ``dtap.side`` as system properties, for example by setting Java properties as explained in subsection :ref:`propertiesReference`. A consequence of the boot process of the Frank!Framework was explained, namely the difference between system properties, classpath properties and configuration properties (three levels). It was said that some properties can only be supplied as system properties (most basic level), while some others can only be supplied as system properties or classpath properties (the most basic level or the next level, but not as configuration properties). For most properties however, it does not matter how they are configured.
In subsection :ref:`propertiesDeploymentEnvironment`, the characteristics of the deployment environment of a Frank config were explained. The Frank!Framework can be deployed on different types of application servers. The Frank!Framework detects the type of application server and automatically sets the property ``application.server.type``. System administrators can configure the properties ``dtap.stage`` and ``dtap.side`` as system properties, for example by setting Java properties as explained in subsection :ref:`propertiesReference`. A consequence of the boot process of the Frank!Framework was explained, namely the difference between system properties, application properties and configuration properties (three levels). It was said that some properties can only be supplied as system properties (most basic level), while some others can only be supplied as system properties or application properties (the most basic level or the next level, but not as configuration properties). For most properties however, it does not matter how they are configured.

Precedence Order
----------------

Each Frank config has its own set of properties. Next to these configuration properties, properties set within the deployment environment are applied, namely classpath properties and system properties. There is a precedence order between these three property sources. For each configuration, the order of precedence is as follows:
Each Frank config has its own set of properties. Next to these configuration properties, properties set within the deployment environment are applied, namely application properties and system properties. There is a precedence order between these three property sources. For each configuration, the order of precedence is as follows:

#. System properties.
#. Configuration properties.
#. Classpath properties.
#. Application properties.

As a consequence, the system administrator can override configuration properties by setting them as system properties. You tried this at the end of subsection :ref:`propertiesReference`.

As said before, it is possible to put a Frank config in the ``classes`` folder of a Frank application, although this is considered bad practice. This Frank config only uses the classpath properties and the system properties, the system properties taking precedence.
As said before, it is possible to put a Frank config in the ``classes`` folder of a Frank application, although this is considered bad practice. This Frank config only uses the application properties and the system properties, the system properties taking precedence.

Property files
--------------
Expand Down

0 comments on commit 6339853

Please sign in to comment.