07. Persistence Syntax
In contrast to heavy and complex XML or JSON structures, the AREG Framework employs a lightweight approach, utilizing simple Key-Value pairs known as Properties, to read and store data in files. To facilitate this functionality, the AREG Framework includes an integrated text parser, referred to as the persistence module. This module plays a crucial role in parsing configuration files and instantiating objects based on the extracted data. By leveraging this simple text parsing capability, the AREG Framework provides a streamlined and efficient solution for handling configuration files and data persistence.
The parser used in the AREG Framework follows a set of valid symbols and syntax rules. Here are the key elements to understand:
- The prototype for saving key-value pairs in configuration files is
<property key> = <property value>. - Comments should begin with the
#symbol, followed by a space:"# ". - The assignment of a value to a key can optionally end with a
;symbol. - White spaces and tabs are considered valid and are ignored by the parser.
Here is an example showcasing valid key-value pairs, with both lines considered acceptable:
# Example of setting scopes, one line ending with a ';' symbol and the other without
scope.myapp.scope_one = DEBUG | SCOPE; # Ends with a ';' symbol
scope.myapp.scope_two = WARN | SCOPE # Does not end with a ';' symbolThe Property Key used in the persistence object follows a structured syntax consisting of four fields: a mandatory section and property, and optional module and position. The syntax of the key is as follows: section.property[.module][.position]. To be considered valid, a Property Key must include at least the section and property fields. The keys should be unique within the file to ensure proper identification and retrieval of data.
For example, in the log.init file, the log scope elements utilize the keyword scope as the section, along with the names of the modules serving as the properties. This structured approach enables efficient organization and retrieval of data within the configuration file.
Properties in the AREG Framework can accommodate any value. The value of a property is defined after the = symbol and extends until it encounters either the ; symbol, a comment starting with # , or the end of the line (\n).
When developers need to save a list of values, such as a list of files, it is recommended to use the : symbol instead of the ; symbol. For example, consider the following configuration snippet that saves a list of locations:
location.files = ./config/:~/config/:/usr/bin/; # List of locationsIn this case, the location.files property contains a list of file paths separated by :.
Here are some valid examples of key-value pairs commonly used in configuration files:
a) The following key-value pairs consist of keys that include the section, property, and module fields:
log.layout.enter = %d: [ %t %x.%z: Enter --> ]%n
log.layout.message = %d: [ %t %p >>> ] %m%n
log.layout.exit = %d: [ %t %x.%z: Exit <-- ]%nIn this example, the keys log.layout.enter, log.layout.message, and log.layout.exit each have distinct meanings and are associated with the log section and layout property.
b) The following key-value pairs belong to the same section, but have different interpretations:
scope.* = DEBUG | SCOPE # All applications log all messages
scope.mcrouter.* = NOTSET # Exception: mcrouter application does not log any messages
scope.myapp.service_* = ERROR # In the myapp application, the "service_" scopes only log errors without scope
scope.*.areg_* = NOTSET ; # In all applications, the "areg_" scopes do not log messagesIn this example, the keys scope.*, scope.mcrouter.*, scope.myapp.service_*, and scope.*.areg_* define different logging behaviors for various scopes within the scope section.
These examples illustrate the flexibility and structure of key-value pairs within configuration files, allowing for precise configuration and customization of application settings.