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.
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);
would
./defaults-2.zip, if found;
Test.ini and
Test.fstab, if found in the folders ./etc or in
d:\test\temp.
User.ini and
User.fstab if found in the default path for user settings (a
null argument prompts for the usage of the default value for it).
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.
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();
methods.
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");
}
else{
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
System.out.println(fs.getRowsNumber());
//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.
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:fstab settings:
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.
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:
flushChanges()
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.
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 |
|
|