ModifyingTheExample

02 Modifying the example

Introduction

In the previous tutorial, we built the sources and played with some examples. In this tutorial, we are going to modify the .xml files to add more artists to our playlist switcher. This should take about 20 minutes to complete.

Files

The parameter framework is configured with .xml files.

In the case of our example, we have:

├── <ParameterFrameworkConfiguration>.xml
├── Settings
│   └── Genres.xml
└── Structure
    ├── MusicLibraries.xml
    └── MyMusic.xml

• To describe the architecture around our parameters, we use Structure files.
• To describe domains based on criterion, we use Settings files.

This completes the overview we discovered in tutorial 01:

Exploring a domain (settings file)

So, let's open ~/pfw_example/Settings/Genres.xml

This is the file with the rules describing which genre we are playing based on the users mood. As a reminder, here are the rules:

• If the user is sad, he wants to listen to Post-rock music (Explosions in the Sky)
• If the user is mad, he wants to listen to Heavy-metal music (Iron Maiden or Black Sabbath)
• If the user is glad, he wants to listen to Classical music (Beethoven)

The Genres.xml file can be splitted in three parts which are the following

Configurations

A configuration is a value a domain can take. In our example we have three configurations:

• Post-rock
• Heavy-metal
• Classical

Those configuration are applied to the Genre domain when a specific condition is matched. In our example, it is something like "If the Mood is mad apply the Heavy-metal configuration".

ConfigurableElements:

The ConfigurableElements are the elements (which contain parameters) which change based on the configurations. For our example, we care including/excluding artists based on the genre. The artists in our library are:

• Beethoven
• BlackSabbath
• ExplosionsInTheSky
• IronMaiden

Settings

In the settings part, we are applying values to the parameters. For example, if our configuration is Heavy-metal, we must include IronMaiden and BlackSabbath to the playlist and exclude every other artist. In our case, "including" an artist consists into affecting "Included" to the StringParameter value of the artist.

Adding a new domain configuration

So let's add another configuration to our existing Genre domain. We want to be able to play our favorite artists when we are in a sleepy mood. Let's add that to the ~/pfw_example/Settings/Genres.xml file

Configuration

We have to add a new Configuration

<Configuration Name="Favorites">
    <CompoundRule Type="All">
        <SelectionCriterionRule SelectionCriterion="Mood" MatchesWhen="Is" Value="sleepy"/>
    </CompoundRule>
</Configuration>

Note that the ConfigurableElements do not change since we did not decided to add artists to our system.

Settings

Of course, our favorite artists are IronMaiden and Beethoven. So here is the new settings part of the Configuration:

<Configuration Name="Favorites">
    <ConfigurableElement Path="/MusicLibrary/my_library/artists/IronMaiden">
        <StringParameter Name="IronMaiden">Included</StringParameter>
    </ConfigurableElement>
    <ConfigurableElement Path="/MusicLibrary/my_library/artists/BlackSabbath">
        <StringParameter Name="BlackSabbath">Excluded</StringParameter>
    </ConfigurableElement>
    <ConfigurableElement Path="/MusicLibrary/my_library/artists/Beethoven">
        <StringParameter Name="Beethoven">Included</StringParameter>
    </ConfigurableElement>
    <ConfigurableElement Path="/MusicLibrary/my_library/artists/ExplosionsInTheSky">
        <StringParameter Name="ExplosionsInTheSky">Excluded</StringParameter>
    </ConfigurableElement>
</Configuration>

Checking the validity of the .xml files

In order to validate the .xml files we have just edited, we can use the xmlValidator.py tool which is installed with the core components.

This tool takes two arguments: the directory which contain your .xml files and the directory which contains the schema files. Assuming that your parameter-framework repository is cloned into ~/parameter-framework, you can use it like this:

xmlValidator.py ~/pfw_example/ ~/parameter-framework/Schemas/
# [*] Validate xml files in /home/user/pfw_example/ with parameter-framework/Schemas/
# Attempt to validate ParameterFrameworkConfiguration.xml with ParameterFrameworkConfiguration.xsd
# ParameterFrameworkConfiguration.xml is valid
# Attempt to validate MyMusic.xml with Subsystem.xsd
# MyMusic.xml is valid
# Attempt to validate MusicLibraries.xml with SystemClass.xsd
# MusicLibraries.xml is valid
# Attempt to validate Genres.xml with ConfigurableDomains.xsd
# Genres.xml is valid

Refer to the readme of the tool for more information about it.

Change the Mood criterion

In order to have our system react to the new sleepy mood, we have to change the SelectionCriterion to add the new state. For that, first stop the test-platform system and restart it

remote-process localhost 5001 exit
# Done
test-platform ~/pfw_example/ParameterFrameworkConfiguration.xml
# Done

Then run remote-process to create the new Mood criterion:

remote-process localhost 5001 createExclusiveSelectionCriterionFromStateList Mood mad sad glad sleepy
# Done
remote-process localhost 5001 start
# Done

View results

Now we should be able to test our new configuration.

remote-process localhost 5001 setCriterionState Mood sleepy
# Done
remote-process localhost 5001 applyConfigurations
# Done
grep '.' ~/pfw_example/libraries/*
# /home/user/pfw_example/libraries/beethoven:Included
# /home/user/pfw_example/libraries/blackSabbath:Excluded
# /home/user/pfw_example/libraries/explosionInTheSky:Excluded
# /home/user/pfw_example/libraries/ironMaiden:Included

Changing the structure

Now that we know how to add new configurations to a domain, let's discover how to add new parameters to our structure. For our example, that means adding new artists to the music library.

Definition of a structure

First, open the ~/pfw_example/Structure/MyMusic.xml file.

We are going to add an artist: Dream Theater

<ComponentType Name="Artists">
    <!-- other artists declared here ... -->
    <StringParameter Name="DreamTheater" Mapping="File:dreamTheater" MaxLength="32"/>
</ComponentType>

Since we are using the filesystem plugin, we also have to create the corresponding files on the filesystem.

touch ~/pfw_example/libraries/dreamTheater

Adapt ConfigurableDomain for the new Subsystem

Since we have changed our structure, we have to edit the Settings in order to include DreamTheater into playlist. We only want to hear this artist when being sleepy.

Let's add that to the Settings/Genres.xml file

Configuration

Nothing to add

ConfigurableElements

We have added a new element to our structure, so we have to add it to the ConfigurableElements

<ConfigurableElements>
    <!-- other artists here -->
    <ConfigurableElement Path="/MusicLibrary/my_library/artists/DreamTheater"/>
</ConfigurableElements>

Settings

We have to tell in which Configuration DreamTheater is included in the playlist.

<Settings>
    <Configuration Name="Heavy-metal">
        <!-- other artists here -->
        <ConfigurableElement Path="/MusicLibrary/my_library/artists/DreamTheater">
            <StringParameter Name="DreamTheater">Excluded</StringParameter>
        </ConfigurableElement>
    </Configuration>
    <Configuration Name="Classical">
        <!-- other artists here -->
        <ConfigurableElement Path="/MusicLibrary/my_library/artists/DreamTheater">
            <StringParameter Name="DreamTheater">Excluded</StringParameter>
        </ConfigurableElement>
    </Configuration>
    <Configuration Name="Post-rock">
        <!-- other artists here -->
        <ConfigurableElement Path="/MusicLibrary/my_library/artists/DreamTheater">
            <StringParameter Name="DreamTheater">Excluded</StringParameter>
        </ConfigurableElement>
    </Configuration>
    <Configuration Name="Favorites">
        <!-- other artists here -->
        <ConfigurableElement Path="/MusicLibrary/my_library/artists/DreamTheater">
            <StringParameter Name="DreamTheater">Included</StringParameter>
        </ConfigurableElement>
    </Configuration>
</Settings>

Don't forget to check the validity of your .xml files after your changes to ensure that it will behave as expected.

View results

Run test-platform with the configuration file:

test-platform ~/pfw_example/ParameterFrameworkConfiguration.xml

Create the criterion and start the parameter-framework:

remote-process localhost 5001 createExclusiveSelectionCriterionFromStateList Mood mad sad glad sleepy
# Done

Now what happens if we change the Mood criterion?

remote-process localhost 5001 setCriterionState Mood sleepy
# Done
remote-process localhost 5001 applyConfigurations
# Done

Lets have a look:

grep '.' ~/pfw_example/libraries/*
# /home/user/pfw_example/libraries/beethoven:Included
# /home/user/pfw_example/libraries/blackSabbath:Excluded
# /home/user/pfw_example/libraries/explosionInTheSky:Excluded
# /home/user/pfw_example/libraries/dreamTheater:Included
# /home/user/pfw_example/libraries/ironMaiden:Excluded

As expected, Dream Theater is now included in the playlist.

To conclude

As you might have discovered, editing .xmls by hand is quite annoying. That's why we invented a special language for a more easy-to-write configuration files: the .pfw language. We will discover the .pfw language in the next tutorial!