CONFIGPATH

An introduction to Dynamo's CONFIGPATH the layered configuration mechanism

Part 1 - Overview

• Namespaces
• Properties Files
• Dynamo CONFIGPATH

Part 2 - Configuration Layering

• Multiple CONFIGPATH directories
• Basic Configuration Layering
• Configuration Layering for arrays

CONFIGPATH - Part 1 - Overview

Properties files, CONFIGPATH and the Nucleus Namespace

Namespaces

A namespace is a hierarchical system where each item has it's own unique path. The most common namespace is the file system on your computer. Each folder can contain other folders or file items. Inside each folder the file item names are unique. You can have two files on your machine with the same name, but they have to be in different folders. You can refer to each of the files uniquely because the full path is different.

Properties Files

A .properties file is just a text file. Often these are generated by the DCC when you configure a component, but you can just as well write them by hand. A complete  properties file contains the class name, scope and initial property values for the component it is defining. The .properties file IS the component definition, the fact that a given .properties file exists (in the CONFIGPATH) means that a component is defined.

Dynamo CONFIGPATH

• The CONFIGPATH is a semicolon separated list of directories on the file system
• Each directory in the CONFIGPATH maps to the root of the nucleus name space
• Each .properties file in a folder under a CONFIGPATH entry defines a nucleus component
• The full nucleus name of the defined component is the path to the .properties file underneath the CONFIGPATH entry

Given the following:

• set CONFIGPATH="c:\music"
• A c:\music\artists\d\DaveMathews.properties file containing

  $class= atg.music.Artist

  $scope=global

  name=Dave Mathews

  genre=folk/pop

We have defined a single global nucleus component of class atg.music.Artist which can be referenced by the name /artists/d/DaveMathews from within Dynamo. Then name property of the instance will be set to Dave Mathews and the genre property will be set to folk/pop. In this case even though our Artist bean has website and email properties we have not set these properties so they remain uninitialized.

CONFIGPATH - Part 2 - Configuration Layering

Multiple CONFIGPATH directories

In the previous example there is only a single entry in the CONFIGPATH, in reality the CONFIGPATH contains several 'root' folders. This means that two or more properties files can specify the same component. What implications does this have? 

As we will see each entry in the CONFIGPATH represents and holds a layer of related configuration information. 

What??, well let's look at how does this work out...

Basic Configuration Layering

Given the following

• set CONFIGPATH="c:\music;c:\moreinfo"
• A c:\music\artists\d\DaveMathews.properties file containing

  $class= atg.music.Artist

  $scope=global

  name=Dave Mathews

  genre=folk/pop

• A second c:\moreinfo\artists\d\DaveMathews.properties file containing

  website=http://www.dmb.com

  email=dave@dmb.com

  genre=rock

We have defined a single global nucleus component of class atg.music.Artist which can be referenced by the name /artists/d/DaveMathews from within Dynamo. Then name property of the instance will be set to Dave Mathews, website to http://www.dmb.com, email to dave@dmb.com and the genre property will be set to rock.

How does this happen?

The config path is read from left to right. Properties set in later entries in the CONFIGPATH override earlier entries. In our case the genre property is specified in both properties files. The property is set to rock because that is the last value specified, (as we go from left to right through the CONFIGPATH). This process is know as configuration layering. 

What does this mean to you?

• By adding a entry to the config path you can customize any components in the system without losing the original configuration information
• You can have a global configuration common to all machines then have machine specific information in the last layer

Configuration Layering for Arrays

In the previous examples all the properties of our java bean were strings. Properties can be of any java type from Strings and doubles to object references and arrays of all of the above. 

Adding Items to an Array Property

Given the following

• set CONFIGPATH="c:\music;c:\moreinfo"
• A c:\music\albums\c\Crash.properties file containing

  $class= atg.music.Album

  $scope=global

  title=Crash

  tracks=#34, Lay Down Lover

  sessionPlayers=Tim Reynolds, Dizzy Wicks

• A second c:\moreinfo\albums\c\Crash.properties file containing

  tracks=Two Step, Crash

  sessionPlayers+=Peter Dixon, Jane Holloway

We have defined a single global nucleus component of class atg.music.Album which can be referenced by the name /albums/c/Crash from within Dynamo. Then title property of the instance will be set to Crash, tracks is set to an array of Strings: 'Two Step' and 'Crash'. sessionPlayers is initialized to an array of Strings:  Tim Reynolds, Dizzy Wicks, Peter Dixon, Jan Holloway.

How does this happen?

Why did the 'Peter Dixon' and 'Jan Holloway' get appended to the sessionPlayers array? Why did the tracks array get reset?

The difference lies in the use of the '=' and '+=' operators. The '+=' operator, used here for sessionPlayers, appends items to the array while the '=', used here for tracks removes any existing items in the array before adding the new items.

copyright 2000-2002 Stuart Jones

ATG Certified Dynamo Development Engineer