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

1. Before We Begin
1.1. Definitions for Java INI Package and this Tutorial
1.2. Package Overview
1.2.1. Interfaces
1.2.2. Concrete Classes
2. Steps needed to run in Java
2.1. Importing package in Java
2.2. Setting the Class Path

1. Before We Begin

1.1. Definitions for Java INI Package and this Tutorial

The Java INI Package and this website uses the following definitions:

INI file
The physical INI file on the hard disk, often has the extention .ini
IniFile
The Java representation of the INI file. If any Java classes, interfaces, methods or other Java specific terms are mentioned, then they will be presented with a mono-space font.
Section
A group of items in an INI file, sections are defined by a unique name in the file and begin with square brackets (e.g. a settings section is: "[settings]").
Item
A item stores the actual data in an INI file and consits of a name, followed by an equals sign ("="), and then a value.

For more information on the specifications of an INI file, click here.

Back to Top

1.2. Package Overview

The Java INI Package is made up of numerouse classes (both concrete and abstract). Here, we describe the essential parts of the package.

1.2.1. Important Classes

Since v1.0.0, the Java INI Package contains three important abstract classes which represent an INI File, its sections, and the section's items.

IniFile
This abstract class represents an INI file. The IniFile class defines the operations to add or remove sections from the IniFile, as well as other operations for managing the ordering of the sections. This class is abstract as it leaves the internal management of the sections to the concrete classes (such as the BasicIniFile and AdvancedIniFile).
IniSection
This abstract class represents a secion within an INI file. The IniSection class defines the methods to add or remove items from the section, as well as other operations for managing the ordering of the items. Just like the IniFile abstract class, this class is abstract as it leaves the internal management of the items to the concrete classes (such as the BasicIniSection and AdvancedIniSection).
IniItem
Interface for representing an item from a section. The IniItem interface defines the operations to set or get the value of the item.

The reason for defining interfaces is simply to seperate the implementation from the API, and therefore allows different implementations for the interfaces.

Back to Top

1.2.2. Concrete Classes

Currently, the Java INI Package contains two implementations of the above interfafces, the Basic and Advanced concrete classes. The basic concrete classes are very small and simple implementation of the interfaces, and consistis of the following classes:

BasicIniFile
implements the IniFile interface.
BasicIniSection
implements the IniSection interface.
BasicIniItem
implements the IniItem interface.

The Advanced concrete classes were introduced in version 0.2.00 and run quicker than the Basic concrete classes, but at the expence of more memory usage. Developers are recomended to use these classes over the Basic classes, unless memory usage is very critical. The following classes make up the Advanced concrete classes:

AdvancedIniFile
implements the IniFile interface.
AdvancedIniSection
implements the IniSection interface.
BasicIniItem
This is the same class from the Basic concrete classes as there is no AdvanceIniItem equivalent.

It is important to remember that we never refer to the concrete classes by their names, but by their interfaces instead (similar to how you refer to a list object in Java as java.util.List rather than java.util.ArrayList). We refer to interfaces both in text and in java code and will only refere to a concrete class in java code or, if we are explicitly discussing it, in text.

Back to Top

2. Steps needed to run in Java

2.1. Importing package in Java

Before you can use the classes and interfaces that are in Java INI Package, you first need to tell Java where to look for the classes, which is done using the following import statement:

import org.dtools.ini.*;

public class MyFunnyIniClass {
    ...
}

Then write your java code as usual.

Back to Top

2.2. Setting the Class Path

This section explains how to use a .jar file (i.e. dTools's Java INI Package) with your java code. For the more experienced developers, you can skip this part and go straight to the next chapter, however, if you don't know how to include a jar file with their code, please read this.

When you are readly to compile and run your java code (lets say you were compiling a class called MyExample.java), you must:

  1. Type the following into the command line to compile your work:

    javac  -cp  org.dtools.javaini-v##.##.##.jar  MyExample.java

    Where ##.##.## is the version number of the Java INI Package (e.g. 0.1.25).

  2. To run your compiled code, type the following into the command line:

    java  -cp  org.dtools.javaini-v##.##.##.jar;.  MyExample

    Make sure you include the ;. after the package name, as this tells the java application to find the class MyExample in the current directory (and not inside the jar file).

    If you are developing your software on a Linux based OS instead of Microsoft Windows, replace the semi-colon (;) in the command line with a colon (:).

Back to Top