This page contains an explanation of the Java INI Package, along with code examples and explanations. Although this document aims to be as concise as possible, developers are recommended to consult the javadoc for a more complete and upto date documentation of Java INI Package.

Contents

5. Getting and Setting Values
5.1 Setting a Values
5.2. Getting a Values
6. Reading and Writing IniFiles
6.1 Reading INI files from the hard disk
6.2. Writing IniFile object to the hard disk

5. Getting and Setting Values

In this section we'll show you how to get and set a value from\to an IniItem object.

5.1. Setting Values

The value of an item is stored as a String in an IniItem object, regardless on what you pass to the method setValue(). Currently the IniItem has 5 overloaded setValue() methods:

setValue( char )
The given character is converted to a string before being stored as the item's value.
setValue( long )
The non-floating point number is converted to a string before being stored as the item's value.
setValue( double )
The floating point number is converted to a string before being stored as the item's value.
setValue( String )
If the String reference is not null, then the string value is stored. If however the String reference is null then an empty string is stored.
setValue( Object )
If the Object reference is not null, then the string representation of the object is stored. If however the Object reference is null then an empty string is stored (i.e. "").

The following code demonstrates how to set the value for four different items.

import org.dtools.ini.*;

public class SetItemValues {

public static void main( String[] args ) {

/* assume that the structure of the INI file is as follows,
* and that the initial values for all items is an empty string:
*
* [person]
* name =
* initial =
* age =
*
* [java_experience]
* years_experience =
* favourite_class =
*/

IniSection personSection = ini.getSection( "person" );

personSection.getItem("name").setValue( "David" );
personSection.getItem("initial").setValue( 'L' );
personSection.getItem("age").setValue( 23 );

IniSection javaSection = ini.getSection( "java_experience" );

javaSection.getItem( "years_experience" ).setValue( 4.6 );
javaSection.getItem( "favourite_class" ).setValue( Math.class );
}
}

Which produces the following INI file:

[person]
name = David
initial = L
age = 23

[java_experience]
years_experience = 4.6
favourite_class = class java.lang.Math

Back to Top

5.2. Getting Values

To retrieve a value from an item is slightly more simplistic than setting the value, because all values are stored as String objects within an IniItem, and thus there is only one method that needs to be called getValue(). However, as only a String value is returned, if you need to retrieve an numberic value, you will need to convert the value from String to an Integer, as in the following example.

import org.dtools.ini.*;

public class GetItemValues {

public static void main( String[] args ) {

// assume that we are using the same ini object from the example above

// ****************************************************************
// read values from person Section
// ****************************************************************
IniSection personSection = ini.getSection( "person" );

String username = personSection.getItem("name").getValue();
String initialTmp = personSection.getItem("initial").getValue();
String userAgeTmp = personSection.getItem("age").getValue();

// as the value of age should be numeric
// convert the string value which was retrieved
int userAge = Integer.parseInt( userAgeTmp );

// as the value of initial should be of type char
// convert the string value which was retrieved
char initial = initialTmp.charAt( 0 );

// ****************************************************************
// now read values from java_experience section
// ****************************************************************
IniSection javaSection = ini.getSection( "java_experience" );

String experienceTmp = javaSection.getItem( "years_experience" ).getValue();
String favClass = javaSection.getItem( "favourite_class" ).getValue();

// as the value of experiance should be floating-point value
// convert the string value which was retrieved
double experience = Double.parseDouble( experienceTmp );
}
}

Back to Top

6. Reading and Writing IniFiles

Obviously, learning how to manipulate IniFile objects is of no good if we cannot read or write the contents to the hard disk as an INI file. We can do this in Java INI Package by using the classes IniFileReader and IniFileWriter for reading and writing INI files from and to the hard disk.

6.1. Reading INI files from the hard disk

To read an INI file from the hard disk, you first need to create an IniFileReader object using the constructor:

IniFileReader(IniFile ini, java.io.File file)

where ini is the IniFile object that will be populated, and file is a reference to the INI file on the hard disk which will be read. Once you've created an IniFileReader object, you simply call the IniFileReader's method read(). However, the method read() throws two exceptions, the java.io.IOException and a FormatException. To help explain this, have a look at the example below.

import org.dtools.ini.*;
import java.io.File;
import java.io.IOException;

public class ReadIniFileExample {

public static void main( String[] args ) {

/* assume that the contents of the INI file at "C:\settings.ini"
* contains the following data:
*
* [window_settings]
* width = 800
* height = 600
* start_minimized = no
*/

// Create the File object and pass the path of the file to the
// constructor.
File file = new File( "C:\\settings.ini" );

// Create the IniFile object which will be populated.
IniFile ini = new BasicIniFile();

// Create the IniFileReader object.
IniFileReader reader = new IniFileReader( ini, file );

// Finally, call the read() method to read the INI file and populate
// the IniFile object.
try {
reader.read();
}
catch( FormatException e ) {
// exception thrown because the INI file was in an unexpected format
e.printStackTrace();
}
catch( IOException e ) {
// exception thrown as an input\output exception occured
e.printStackTrace();
}

/* The ini object now contains the section "window_settings" and
* the items "width", "height" and "start_minimized"
*/
}
}

6.2. Writing IniFile object to the hard disk

Writing an IniFile to a file on the hard disk is an almost identical proceedure to that of reading an IniFile, but for writing though, we use the class IniFileWriter. To read an INI file, you first create the IniFileWriter object by calling the the constructor and pass the IniFile object that you want to write, and the java.io.File where you want to write to. Then, simply call the method write() to write the file.

Below is a simple example of writing an INI file.

import org.dtools.ini.*;
import java.io.File;
import java.io.IOException;

public class WriteIniFileExample {

public static void main( String[] args ) {

/* assume that the contents of the IniFile is:
*
* [users]
* user_01 = Steve
* user_02 = Mike
* user_03 = Tom
*
* [scores]
* user_01 = 627
* user_02 = 419
* user_03 = 664
*/

// Create the File object and pass the path of the file to the constructor.
File file = new File( "scores.ini" );

// Create the IniFileWriter object.
IniFileWriter writer = new IniFileWriter( ini, file );

// Finally, call the write() method to write the INI file to the file
// on the hard disk
try {
writer.write();
}
catch( IOException e ) {
// exception thrown as an input\output exception occured
e.printStackTrace();
}
}
}

Back to Top