ART#106 - What is config path and configuration layering?



Now that the basics on components and nucleus are clear, we can get into a bit of detail for configuration files..

Configuration Path (or config-path)
Lately we have been reading about this term, but we are not exactly sure what it is. 
A configuration path is a path in your ATG module, where nucleus searches for configuration files to create components.
This is generally "config" folder in your ATG module (if you use default settings for setting up your ATG module in Eclipse).
When you create a new ATG module in eclipse, it asks you for a location and name for config path. By default, it is set-up as "config".
You can change it later in the file "MANIFEST.MF" in "META-INF" folder of your ATG module (see below screenshot). 




We will discuss setting up ATG module in later sections, when we start with ATG-setup on windows machine.

Property File Formats
The properties file written for ATG must conform to a format recognizable by java.util.Properties. As discussed earlier, there is a specific format in which properties files must be written for Java/ATG to understand them.
NOTE: nucleus specific properties are prefixed by a $ sign. (for example; $scope=global or $class=com.mypackage.Person)

Setting Properties
Properties can be set using "=" sign or ":" sign. For example:-
Name=Stephen
Age:20
Also, array/collection properties can be set in comma separated format. For example, a java class defines a property 
ArrayList<String> carsList;
.... more java code follows...
In this case, the value of list carsList can be set using configuration files in comma-separated format as:-
carsList=Honda,Skoda,Mercedes
Or, if we wish to write these in multiple lines, we can do this by adding "\" at the end of each line as follows:-
carsList=\
        Honda,\
        Skoda,\
        Mercedes
NOTE: white-spaces are ignored in the beginning and end of a line. Also, in below case, white-spaces are ignored.
name=Stephen
and
name = Stephen
are treated in the same way. (white-space before and after "=" is ignored. Same would be the case, if we use ":" in place of "=")
Similar to how collection/array properties are set in configuration files, we can also set properties which implement the "Map" interface. For a map property specified in java file:-
Map carMap;
The values can be set as
carMap=\
        honda=affordable,\
        skoda=costly,\
        mercedes=in-my-dreams
The above block initializes the "carMap" map, with above key-value pairs.

A component can also refer to another component depending on scope (we will discuss scopes in later sections).
For example, there is a component "/atg/commerce/Weather" which needs to be used (and referenced) by our "Person" component. As discussed earlier, "Weather" component's configuration file must be placed in config-path, inside the folder structure <ATG_CONFIG_PATH>/atg/commerce/Weather.properties.




In this case, Person.java should look like:-
public class Person {
  String name;
  int age;
  Weather weather;

  public Person () {
    System.out.println ("constructing Person");
  }
  public String getName () { return name; }
  public void setName (String name) {
    System.out.println ("setting name to " + name);
    this.name = name;
  }
  public int getAge () { return age; }
  public void setAge (int age) {
    System.out.println ("setting age to " + age);
    this.age = age;
  }
  public Weather getWeather () { return weather; }
  public void setWeather (Weather weather) {
    System.out.println ("setting weather to " + weather.getCurrentWeather());
    this.weather = weather;
  }
}

And the configuration file (Person.properties) would look like below. Please note the "weather" property. It contains the full path of the Weather component.


$class=Person
name=Stephen
age=20
weather=/atg/commerce/Weather

NOTE: Nucleus does not limit the nesting of components. For example, component1 can refer to component2, and component2 can refer to component3 and so on. We should however, avoid circular references. For example component1 refers to component2 and component2 refers to component1 would lead to circular reference and might lead to a deadlock.


Special Characters
Some special characters are treated specially, below are the details:-

Character
Description
!
#
If placed at the beginning of a line, comments out the line.
\n
Newline character
\r
Carriage return
\t
Tab
\\
Inserts a backslash character. For example:
path=c:\\docs\\doc1
\u
Prefixes a UNICODE character—for example, \u002c.

Configuration Layering
This is one of the most important topics without which customization in ATG is simply not possible. There might be cases when 
1. We want to change the property-values of some OOTB components 
OR 
2. Our ATG application is running for different environments, and we want some specific properties to be different for each environment (for example, a property which stores a file path, might have different values on different environments)
OR
3. We need to add some properties to out-of-the-box component (Extending a component).
In these cases configuration layering comes into play.

There are a lot of ATG OOTB modules which start-up when the ATG server starts. Each module has its own config-path and its own set of configuration files and components.

For cases 1 and 2, we create a configuration file with the same name as OOTB component and place it at the same location in OUR config-path.

For example, let us assume the component "Weather" exists OOTB at location /atg/commerce/Weather, with following properties:-


$class=com.mypackage.Weather
currentWeather=sunny

In order to change its property "currentWeather", we need to create a configuration file Weather.properties (same name as OOTB file) at location <ATG_CONFIG_PATH>/atg/commerce/, and change the property currentWeather as "rainy" (see below).



For case#3, we will discuss the details in further section viz. "Extending OOTB Components".

Below are some guidelines for configuration layering:-

  • Properties are appended in layered configuration files automatically. In above example, the (assumed) OOTB component "Weather" had two properties viz. "$class" and "currentWeather". Since we needed to change only "currentWeather", we mentioned only this property in the configuration file. Previous properties (in this case "$class") were appended automatically.
  • For array/collection properties, the previous value is overridden on using "=" operator. If we want to append more values in a particular collection/array property, "+=" operator is used.
  • Nucleus properties like $class and $scope are just like any other properties and can be overridden.
Now let us understand some technical details on component and their scopes.

Back



Next





12 comments:

  1. Hi Monis, my name is Carlos, i have a question on this specific topic, let's use the same components you describe above, (Person and Weather) but instead of have a single reference to Weather component on Person class I would like to manage an Array or Collection of weather components (ex. ArrayList mWeathers) so how can i set its values on the Person .properties file?

    would it be something like this?

    mWeathers=\
    /atg/commerce/weather/snowy,\
    /atg/commerce/weather/sunny,\
    /atg/commerce/weather/cloudy,\
    /atg/commerce/weather/rainy

    Thanks for your help :)

    ReplyDelete
    Replies
    1. Hi Carlos,

      It depends on how you declare "mWeathers" in your java file.
      Assuming that components [snowy, sunny, cloudy, rainy] all of them use the same class [say Weather], then declaring "ArrayList< Weather > mWeathers" is correct. Alternatively, you can also declare this as an array of Weather, e.g. "Weather[] mWeathers".

      A better way to do it would be by using a ServiceMap. It maps strings to components, and hence, it is a bit cleaner to access this in the code.

      You have have a look on this HERE: http://docs.oracle.com/cd/E23095_01/Platform.93/ATGProgGuide/html/s0204servicemapproperties01.html

      Delete
  2. Hi Monis,

    I have setup the ATG development environment in my local machine(Windows) and used ATG 11.1 and JBoss EAP 6.1. Whenever I make a code change in eclipse, I'm running the runAssembler utility to build the ear and restart the server, after that I verify the changes in the application. Could you please let me know are there anyways to do development without building the EAR? Thanks for your time.

    ReplyDelete
    Replies
    1. By Code change, i am assuming you are referring to JAVA class changes.
      Whenever you write a java class in eclipse, it automatically creates a .class file.
      When you are done, you can copy your class file(s) and replace them directly in the EAR and restart the server.
      Your changes will be reflected.
      Although, if you are changing multiple classes, its better to run runAssembler.bat.

      Delete
    2. Thanks for the information, Monis.

      Delete
    3. Hi Monis

      can you please provide us some information how to start hands on the ATG thing.

      Or Please provide the detail of the Insttalatin of the atg.

      Delete
    4. These topics are on the list and will be covered soon!

      Delete
  3. As already discussed by you that we will create the Weather.properties again at the same location for the appending task but there will be one Weather.properties already there in the path then how we can create two files with the same name in the same location. Moreover if the weather is the OOTB component then how we will know that it is present in atg/commerce/Weather.properties? Thanks in Advance.

    ReplyDelete
    Replies
    1. 1. Assume that Weather.properties is OOTB, and you are layering it in your module.
      2. You can go to dyn/admin and search for Weather component, if it exists, dyn/admin will show you the whole path, and then you can layer it.

      Delete
    2. Hi Monis,

      Asking the same question again.
      "Weather.properties already there in the path then how we can create two files with the same name in the same location"

      dyn/admin - is it a module, component what is it?
      sorry I dint read your complete blog yet.

      Thanks for your time

      Delete
    3. We cannot create two files in the same location.
      Suppose: ATG has an OOTB component called Weather (at the location or config-path /atg/commerce/Weather.properties)
      Now, since this is present OOTB, it should be present in an OOTB module inside a JAR file.
      The article says that, assuming this component is present OOTB, you can layer it IN YOUR MODULE. Therefore in your module, the Weather.properties will be present at /atg/commerce/Weather.properties.
      Since modules are different, the config-path may seem same, but they are physically different.
      Example:
      OOTB Weather:
      It would be present in some OOTB module, say DAS module.
      Therefore, the physical path will be
      D:/ATG/ATG11.0/DAS/config/config.jar/atg/commerce/Weather.properties
      Layered Weather (in your module)
      D:/ATG/ATG11.0/MyModule/config/atg/commerce/Weather.properties

      The config path is same in both cases, but physically different locations.

      Delete
  4. How to prevent circular reference deadlock

    ReplyDelete

Subscribe

Get All The Latest Updates Delivered Straight Into Your Inbox For Free!

Flickr