net.sourceforge.drpetrea.jsettings
Class DefaultSettingsLoader

Object
  extended by DefaultSettingsLoader

public class DefaultSettingsLoader
extends Object

This class is used for loading the defaults and the rules for validating the settings of the program. It reads a zip archive that contains files for each settings category that the program needs. Each of these files has the extension .ini for an ini-style settings category and .fstab for a fstab-style category.

Both ini- and fstab-files have the following structure:

/* Header Line Name Default Rule * /
/*Line 1 * / setting-1 default-1 rule-1
/*Line 2 * / setting-2 default-2 rule-2
It contains all the possible settings in the respective category, so that the user can only modify them and not add extra ones.

The files are separated by spaces and/or tab characters; in case the user wishes to have any of the paths, defaults or rules containing spaces and/or tabs, the respective should be enclosed in round brackets(). Therefore, we can have such a line:

/* Header Line Name Default Rule * /
/*Line 1 * / (setting 1) (default 1) rule-1

The obvious consequence is that round brackets cannot be part of the settings paths, defaults or validation rules.

The class maintains two maps, one for the ini-style files and one for the fstab ones. The maps have as keys the name of the file in the archive, less the extension and as value a reference to a setting object of the specific type. When an ini-file is processed a new pair is added to the map, with the setting object being non-hierarchical, since it contains already all the possible files. When a fstab-file is processed, the map is being extended with a fstab setting object that is hierarchical, since it does not contain any files, but only field paths and validation rules.

The class allows for the division of the settings file into sections, that are stored separately - effectively a file with two sections behaves as two separate files. The only difference is the possibility to have the sections referenced hierarhicaly or not (flat referencing). For example, considering that we have two files with the following sections:

File 1
Section-1_1
Section-1_2
File 2
Section-2_1
Section-2_2
a hierarchically organized map of the settings would contain the keys

{File1:Section-1_1, File1:Section-1_2, File2:Section-2_1, File2:Section-2_2}

whereas a flat organized map would have the following structure

{Section-1_1, Section-1_2, Section-2_1, Section-2_2}.

The most important difference is that the hierarchical organization allows for the same section paths in different files whereas the flat one obviously does not.

As seen above, in the hierarchical organization, the referencing style is Higher_Level:Lower_Level (the separation is done by a colon-sign Constants.SECTIONSEPARATOR). The intention is to be able to allow for nested sections, therefore possibly reaching a structure like File_name:High_level_section:Low_level_section. For this reason, the colon sign Constants.SECTIONSEPARATOR will not be allowed in the name of a section (or of a file, but that is less to be worried about). If the user desires this, the way to diferentiate between higher and lower level sections is through the header of the section. If a normal (or high-level) section would have a header like

[Section Header]

(with the [ and ] signs being defined in the Constants file in the dpjtools package - in case the user defines more markers, say the ones before and also { and }, then they can be used interchangably, e.g. [Section} is a valid section name), a Sub-section header would have double section markers around the paths, like

[[Sub-section Header]]

a sub-sub-section would have

[[[Sub-section Header]]] etc.

This all looks very cumbersome and probably it will rarely be used, but the feature is there. In case the organization is flat, the multiple markers are ignored.

The rule for solving name conflicts is that in case a specific name is already defined (it is possible even in the case of hierarchical structures, in case the same file name is found in different directories) the subsequent occurances are not processed anymore. This means that the most important files should be processed first!

Another naming convention is that the first level name of a section is the name of the file. If the user wants a different name, he can add AS FIRST LINE (also before any comments) a statemenet of the form

Name:New name

where Name is defined in Constants.NAMECHANGE and anything after the colon sign (":"), less the surrounding whitespaces, is the new used name.

The two maps are private and accessible through the methods below by the user.

Author:
Dragos Petre

Field Summary
static LocaleTools lt
          The LocaleTools object.
 
Constructor Summary
DefaultSettingsLoader()
          The default constructor.
DefaultSettingsLoader(ArrayList<String> paths)
          The constructor that takes as arguments ArrayLists of possible paths.
DefaultSettingsLoader(ArrayList<String> paths, ArrayList<String> files)
          The constructor that takes as arguments ArrayLists of possible paths and file paths.
DefaultSettingsLoader(ArrayList<String> paths, ArrayList<String> files, boolean hierarchical)
          The constructor that takes as arguments ArrayLists of possible paths and file paths.
DefaultSettingsLoader(ArrayList<String> paths, boolean hierarchical)
          The constructor that takes as arguments ArrayLists of possible paths.
DefaultSettingsLoader(ArrayList<String> paths, String file)
          The constructor that takes as arguments an ArrayList of possible paths and the file name.
DefaultSettingsLoader(ArrayList<String> paths, String file, boolean hierarchical)
          The constructor that takes as arguments an ArrayList of possible paths and the file name.
DefaultSettingsLoader(boolean hierarchical)
          The constructor that takes as arguments the hierarchical flag.
DefaultSettingsLoader(boolean hierarchical, ArrayList<String> file)
          The constructor that takes as arguments the file paths and the hierarchical flag.
DefaultSettingsLoader(boolean dummy1, ArrayList<String> file, boolean dummy2)
          The constructor that takes as arguments the possible file paths.
DefaultSettingsLoader(boolean hierarchical, String file)
          The constructor that takes as arguments the file name and the hierarchical flag.
DefaultSettingsLoader(boolean dummy1, String file, boolean dummy2)
          The constructor that takes as arguments the file name.
DefaultSettingsLoader(String path)
          The constructor that takes as argument the possible path.
DefaultSettingsLoader(String path, ArrayList<String> files)
          The constructor that takes as arguments the path and an ArrayList of possible file paths.
DefaultSettingsLoader(String path, ArrayList<String> files, boolean hierarchical)
          The constructor that takes as arguments the path and an ArrayList of possible file paths.
DefaultSettingsLoader(String path, boolean hierarchical)
          The constructor that takes as argument the possible path.
DefaultSettingsLoader(String path, String file)
          The constructor that takes as arguments the path and the file name.
DefaultSettingsLoader(String path, String file, boolean hierarchical)
          The constructor that takes as arguments the path and the file name.
 
Method Summary
 
Methods inherited from class Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

lt

public static LocaleTools lt
The LocaleTools object.

Constructor Detail

DefaultSettingsLoader

public DefaultSettingsLoader(ArrayList<String> paths,
                             ArrayList<String> files,
                             boolean hierarchical)
The constructor that takes as arguments ArrayLists of possible paths and file paths.

Parameters:
paths - A String ArrayList containing all the possible paths where the settings zip file could be found.
files - A String ArrayList containing the possible paths of the zip files
hierarchical - A flag indicating whether the settings structure is hierarchical (true) or not (false)

DefaultSettingsLoader

public DefaultSettingsLoader(ArrayList<String> paths,
                             boolean hierarchical)
The constructor that takes as arguments ArrayLists of possible paths. It uses the DEFAULTSFILE in the Constants file for the possible file paths.

Parameters:
paths - A String ArrayList containing all the possible paths where the settings zip file could be found.
hierarchical - A flag indicating whether the settings structure is hierarchical (true) or not (false)

DefaultSettingsLoader

public DefaultSettingsLoader(String path,
                             ArrayList<String> files,
                             boolean hierarchical)
The constructor that takes as arguments the path and an ArrayList of possible file paths.

Parameters:
path - A String containing the path where the settings zip file could be found.
files - A String ArrayList containing the possible paths of the zip files
hierarchical - A flag indicating whether the settings structure is hierarchical (true) or not (false)

DefaultSettingsLoader

public DefaultSettingsLoader(String path,
                             boolean hierarchical)
The constructor that takes as argument the possible path. It uses the DEFAULTSFILE in the Constants file for the possible file paths.

Parameters:
path - A String containing all the possible paths where the settings zip file could be found.
hierarchical - A flag indicating whether the settings structure is hierarchical (true) or not (false)

DefaultSettingsLoader

public DefaultSettingsLoader(ArrayList<String> paths,
                             String file,
                             boolean hierarchical)
The constructor that takes as arguments an ArrayList of possible paths and the file name.

Parameters:
paths - A String ArrayList containing all the possible paths where the settings zip file could be found.
file - A String with the name of the zip file.
hierarchical - A flag indicating whether the settings structure is hierarchical (true) or not (false)

DefaultSettingsLoader

public DefaultSettingsLoader(String path,
                             String file,
                             boolean hierarchical)
The constructor that takes as arguments the path and the file name.

Parameters:
path - A String with the path where the settings zip file could be found.
file - A String with the name of the zip file.
hierarchical - A flag indicating whether the settings structure is hierarchical (true) or not (false)

DefaultSettingsLoader

public DefaultSettingsLoader(boolean hierarchical,
                             String file)
The constructor that takes as arguments the file name and the hierarchical flag.

Parameters:
file - A String with the name of the zip file.
hierarchical - A flag indicating whether the settings structure is hierarchical (true) or not (false)

DefaultSettingsLoader

public DefaultSettingsLoader(boolean hierarchical,
                             ArrayList<String> file)
The constructor that takes as arguments the file paths and the hierarchical flag.

Parameters:
file - An ArrayList of Strings with the paths of the zip file.
hierarchical - A flag indicating whether the settings structure is hierarchical (true) or not (false)

DefaultSettingsLoader

public DefaultSettingsLoader(boolean dummy1,
                             String file,
                             boolean dummy2)
The constructor that takes as arguments the file name. The booleans are dummys to create a different signature.

Parameters:
dummy1 - A dummy field to create a different signature.
file - A String with the name of the zip file.
dummy2 - A dummy field to create a different signature.

DefaultSettingsLoader

public DefaultSettingsLoader(boolean dummy1,
                             ArrayList<String> file,
                             boolean dummy2)
The constructor that takes as arguments the possible file paths.

Parameters:
dummy1 - A dummy field to create a different signature.
file - An ArrayList of Strings with the paths of the zip file.
dummy2 - A dummy field to create a different signature.

DefaultSettingsLoader

public DefaultSettingsLoader(ArrayList<String> paths,
                             ArrayList<String> files)
The constructor that takes as arguments ArrayLists of possible paths and file paths.

Parameters:
paths - A String ArrayList containing all the possible paths where the settings zip file could be found.
files - A String ArrayList containing the possible paths of the zip files

DefaultSettingsLoader

public DefaultSettingsLoader(ArrayList<String> paths)
The constructor that takes as arguments ArrayLists of possible paths. It uses the DEFAULTSFILE in the Constants file for the possible file paths.

Parameters:
paths - A String ArrayList containing all the possible paths where the settings zip file could be found.

DefaultSettingsLoader

public DefaultSettingsLoader(String path,
                             ArrayList<String> files)
The constructor that takes as arguments the path and an ArrayList of possible file paths.

Parameters:
path - A String containing the path where the settings zip file could be found.
files - A String ArrayList containing the possible paths of the zip files

DefaultSettingsLoader

public DefaultSettingsLoader(String path)
The constructor that takes as argument the possible path. It uses the DEFAULTSFILE in the Constants file for the possible file paths.

Parameters:
path - A String containing all the possible paths where the settings zip file could be found.

DefaultSettingsLoader

public DefaultSettingsLoader(ArrayList<String> paths,
                             String file)
The constructor that takes as arguments an ArrayList of possible paths and the file name.

Parameters:
paths - A String ArrayList containing all the possible paths where the settings zip file could be found.
file - A String with the name of the zip file.

DefaultSettingsLoader

public DefaultSettingsLoader(String path,
                             String file)
The constructor that takes as arguments the path and the file name.

Parameters:
path - A String with the path where the settings zip file could be found.
file - A String with the name of the zip file.

DefaultSettingsLoader

public DefaultSettingsLoader(boolean hierarchical)
The constructor that takes as arguments the hierarchical flag. The paths and the file paths are taken from the Constants class

Parameters:
hierarchical - A flag indicating whether the settings structure is hierarchical (true) or not (false)

DefaultSettingsLoader

public DefaultSettingsLoader()
The default constructor. The paths and the file paths are taken from the Constants class