5. Intended Usage

5.1. The constructor

5.2. Settings classes

5.3. Modifying values

5.4. Flushing changes

5.5. Undoing changes

This tutorial chapter explains the most basic way of getting up and running with the jSettings framework. This is also the intended way of using the framework - for the moment the tutorial will not go into explaining the less mainstream classes and methods, but they are all available in the package Javadoc.

The class through which most of the interaction takes place and which is hiding most of the implementation is called, as the package, jSettings.

5.1. The constructor

There are two main constructor types, the one that takes information about the paths and the file names to be processed and the one that takes no arguments, relying on the predefined defaults for finding settings files.

The main constructor is the one that takes as arguments the path and the names of both the default files and those of the settings files (see Javadoc). It takes as arguments the possible paths and file names where the desired files can be found. If the programmer doesn't want to take advantage of all the supplied arguments, she can just have as an argument a null and the respective argument will be skipped.

For example,

jSettings js =
new jSettings(new ArrayList<String>(Arrays.asList(new String[]{"."})) , new ArrayList<String>(Arrays.asList(new String[]{"defaults-2.zip"})) ,
new ArrayList<String>(Arrays.asList(new String[]{"."+System.getProperty("file.separator")+"etc","d:\\test\\temp"})) , new ArrayList<String>(Arrays.asList(new String[]{"Test.ini", "Test.fstab"})) ,
null , new ArrayList<String>(Arrays.asList(new String[]{"User.ini", "User.fstab"})),true);


The last argument states that the program assumes a hierarchical structure of the settings. There is a constructor that ommits this argument, in which case the default value is true (hierarchical structure).

One thing worth mentioning is that after loading the default values in the first step, the program freezes the addition of new sections, ini settings or fstab fields. That means that if it's not in the defaults, the user maintained files cannot load it.

The constructor with no arguments is equivalent to providing the above one all the arguments as null, which makes it default to the pre-determined values for them, which can be changed as seen in the Advanced Topics.

5.2. Settings Classes

The jSettings framework maintains two classes for dealing with the specific settings types: IniSettings and FstabSettings. An instance of one of these classes would hold the contents of a whole section of the respective settings types. That means that for example an IniSettings object would contain all the ini-type of settings in the respective section and the same would be true for FstabSettings (which would contain all the rows in a specific section).

The programmer can get a reference to these objects by calling the

IniSettings IniSetting(String name)

and the

FstabSettings FstabSetting(String name)

methods of jSettings, which return the object containing the section called name of the respective type. A list of available sections of each type can be returned using the methods:

ArrayList<String> IniSections(); ArrayList<String> IniSections(String name);

and the

ArrayList<String> FstabSections();



The IniSettings class provides an interface to the loaded ini-type of settings. The following is an example of possible usage:

//Get the object containing the settings in section first of file Test-ini.ini.
IniSettings is = js.IniSetting(new String("Test-ini:first"));

//Prints the value of setting1
System.out.println(is.getValue(new String("setting1"));

//Changes the value of setting1 if it passes validation.
if (is.putValue(new String("new Value")).length()==0){
    System.out.println("new value did not pass validation");
    System.out.println("change ok");

For more details on usage, please check out the Javadoc pages.

The FstabSettings class provides, as expected, an interface to the loaded fstab-type of rows. Again an example of possible usage:

//Get the object containing the settings in section first of file Test-fstab.fstab.
FstabSettings fs = js.FstabSetting(new String("Test-fstab:first"));

//Prints the number of rows in the section

//Prints the rows which contain value in field 1
System.out.println(fs.getRowsForValue(value, 1);

//Prints the values in row 3 in the rows which contain value in field 1
System.out.println(fs.getValuesForValue(value, 1, 3);

And here's the link to the Javadoc pages.

5.3. Modifying Values

You will see that the settings classes provide methods for modifying the values they contain. However, the prefered method is to use the methods in jSettings. The main reason is that the jSettings class also provides the possiblity of flushing these changes to the external files and to undo the changes.Also these methods are making sure that the new values are being validated - there is simply no way around it.

What you can do with them is this:

ini settings:
as mentioned, you can only modify the existing values: modifyIni(section, name, value, system)
fstab settings:
modify a specific field in a specific row: modifyFstab(section, row, field, value, system)
add a whole row: addFstabRow(section, row, system)
delete a whole row: deleteFstabRow(section, row, system)

You will have noticed the presence of the system argument - this is meant to diferentiate between changes to be made to the system-wide setting files or to the user-specific ones.

5.4. Flushing changes

Changes made to the settings can be flushed to the external files so that the next time these are loaded the changes will be in effect. There is only one method for it and its use is as simple as can be:


What the method does is goes through all the changes made with the above methods and looks for occurances of the changed settings/row in the system-wide or user-specific files. If it is found, then the old value is commented out (including a time stamp to identify the operation) and a row containing the new value is added. In the case of deleted rows, there is nothing added extra and in the case of newly added rows, the comment will ony display the timestamp.

If the method cannot find any occurances of the setting, then it adds it to the file that would be last read in the order given in the constructor. If there are no files altogether then it creates one.

5.5. Undoing changes

Changes made are saved to the memory until they are flushed to the files. The library provides support for undoing these changes, which practically adds back the deleted row, deletes the added row or reverts the changed setting to the previous value. Also, it makes sure that the change will not be flushed to the files later on.

There is no point at this moment to introduce methods to modify the changes flushed to files since this can be very easily done manually directly in the file.

Previous Home Next
4. Files Table Of Contents Advanced Topics

Valid XHTML 1.0 Transitional