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

3. Creating IniFiles, IniSections and IniItems
3.1. A Simple Way
3.2. A Better Way
4. Retrieving IniSections and IniItems
4.1. Retrieving an IniSection
4.2. Retrieving an IniItem

3. Creating IniFiles, IniSections and IniItems

3.1. A Simple Way

The following code demonstrates how to create an IniFile, IniSection and two IniItems in Java.

import org.dtools.ini.*;

public class CreateIniFile {

public static void main( String args[] ) {

// create an IniFile object
IniFile ini = new BasicIniFile();

// create an IniSection to hold personal data
IniSection dataSection = new BasicIniSection( "data" );
ini.addSection( dataSection );

// create an IniItem for name
IniItem nameItem = new BasicIniItem( "name" );
dataSection.addItem( nameItem );

// create an IniItem for age
IniItem ageItem = new BasicIniItem( "age" );
dataSection.addItem( ageItem );
}
}

In the above example, the first part of the code creates an IniFile object called a BasicIniFile, which manages the sections of an INI file. The next part:

IniSection dataSection = new BasicIniSection( "data" );
ini.addSection( dataSection );

creates a new IniSection by calling one of the constructors of the BasicIniSection class. The string passed to the constructor, "data", is the name of the IniSection and should be unique for all sections within an INI file. After the IniSection is created the code then adds the section to the previously created IniFile. The method addSection(IniSection) checks to see if the name of the given section is unique, and if so, adds the section to the IniFile.

The third and forth parts of the code add two IniItems to the section data:

IniItem nameItem = new BasicIniItem( "name" );
dataSection.addItem( nameItem );

IniItem ageItem = new BasicIniItem( "age" );
dataSection.addItem( ageItem );

In both cases, an IniItem is created by calling the constructor of the class BasicIniItem and passing the names of the items to the constructors. As with sections, item names should be unique, but only within the section they are being added to. After the two items are created, they are added to the data section by calling the addItem().

Overall the code produces an IniFile which represents something like this:

[data]

age = 

name = 

Back to Top

3.2. A Better Way

An alternative way of createing the exact same output above is to allow the IniFile to create the IniSection by itself, and to allow the IniSection to create the IniItems by itself. This is done by simply passing the names of the section and items to the methods addSection(String) and addItem(String) directly.

import org.dtools.ini.*;

public class CreateBetterIniFile {

public static void main( String args[] ) {

// create an IniFile object
IniFile ini = new BasicIniFile();

// create an IniSection to hold personal data
IniSection dataSection = ini.addSection( "data" );

// create an IniItem for name
IniItem nameItem = dataSection.addItem( "name" );

// create an IniItem for age
IniItem ageItem = dataSection.addItem( "age" );
}
}

In this example, creating an IniSection is different from the previous example, in that the creation of the IniSection and adding the IniSection to the IniFile are merged into one line.

IniSection dataSection = ini.addSection( "data" );

The advantages of this approach is that it is the method addSection(String) creates a compatible IniSection (more on compatibility at Advanced Topics: 10. Equality & Compatibility). As the IniSection is 100% compatible with the IniFile then the method needs to perform less checks than the method addSecion(IniSection) (the method used in the first example).

The same explanation is also true for adding IniItems to an IniSection.

IniItem ageItem = dataSection.ageItem( "age" );

Overall, it is advised to use the methods addSection(String) and addItem(String) rather than addSection(IniSection) and addItem(IniItem) as less checks are performed, the code is quicker to run and it is less likely to throw any exceptions.

Also see Advanced Topics: 9.3. Default Validation for an explanation of what names for IniSections and IniItems are considered valid and what names are considered invalid.

Back to Top

4. Retrieving IniSections and IniItems

Before you can begin to get and set values for the actual items, you need to get the sections from the IniFile, as well as get the items from the IniSection.

4.1. Retrieving an IniSection

To retrieve an IniSection from an IniFile object you can simply use the method getSection(String) where the String is the name of the section you would like to retrieve. So for example, in the following code, assume that the variable ini refers to an IniFile which contains two sections called "dates" and "scores".

import org.dtools.ini.*;

public class RetrieveIniSection {

public static void main( String args[] ) {

// retrieve a section called "dates"
IniSection datesSection = ini.getSection( "dates" );

// ... perform some operations of the datesSection

// retrieve a section called "scores"
IniSection scoresSection = ini.getSection( "scores" );

// ... perform some operations of the scoresSection

}
}

If you pass a name of an IniSection which doesn't exists, then the value null is returned by the method. Concerning case-sensitivity, see Advanced Topics: 8. Case-Sensitivity

However, passing the name of a section to an IniFile object isn't the only way of retrieving an IniSection. Below is a summary of the different methods in the IniFile class which can retrieve (or help to retrieve) an IniSection object.

public IniSection getSection(int index)
Get the section which is at the given index. The first section in an IniFile is at index 0.
public IniSection getSection(String name)
Returns the section that is called name, or null if no such section exists.
public Collection<String> getSectionNames()
Gets a collection of the names of all the sections in this IniFile.
public Collection<IniSection> getSections()
Gets a collection of all the sections within this INI file.

Back to Top

4.2. Retrieving an IniItem

Retrieving an IniItem from an IniSection is almost itentical to retrieving an IniSection from an IniFile, the only main difference is the name of the method to use, getItem(String). Again, as before, assume that the variable datesSection refers to an IniSection which contains two itmes called "start_date" and "end_date".

import org.dtools.ini.*;

public class RetrieveIniSection {

public static void main( String args[] ) {

// retrieve an item called "start_date"
IniItem startDateItem = datesSection.getItem( "start_date" );

// ... perform some operations of the startDateItem

// retrieve a section called "scores"
IniItem endDateItem = datesSection.getItem( "end_date" );

// ... perform some operations of the endDateItem
}
}

Similar to the method getSection(), the method getItem() returns a reference to the IniItem whose name matches "start_date" and "end_date". Also like getSection(), if a name of an item which doesn't exists is passed to the method getItem(), then the method returns null.

Back to Top