This page contains an explanation of the advanced topics 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

9. Validation
9.1. Why Validate?
9.2. Create your own IniValidator
9.3. Default validation

9. Validation

9.1. Why Validate?

When creating an IniSection or IniItem object, you must specify a name for the section or item, which can only be done by providing the name via one of their constructors. However, it is important for the IniSection and IniItem classes to check whether the names are valid. For example, consider the following Java statement:

// create a new IniSection
IniSection section = new BasicIniSection( "sub[section" );

If this IniSection were to be later written to an INI file on the hard disk, the output would be:

[sub[section]

We now have a problem, because when this is INI file is parsed by the IniFileReader object, or even parsed by any other parser, the parser will do one of three things:

  1. The parser will interprete the section "[sub[section]" to have the name "section".
  2. The parser will interprete the section "[sub[section]" to have the name "sub[section".
  3. The parser will recognise that the section "[sub[section]" is invalid and may throw an exception or simply ignore the section and any items within that section.

As the effect of the name is ambiguous, the name "[sub[section]" should be considered invalid. Fortunately, validation of names is handled by the class IniValidator.

An IniFile object and the IniSections and IniItems within the IniFile object all share the same instance of an IniValidator, which validates if a given section name or item name is valid or not. It is not important how this is done, but it may be useful to know how to create your own instances of an IniValidator in case the default IniValidator is not appropriate or if you need to define your own custom specification of an INI file (e.g the "@" symbol could be the default item for a section, as in the case of Microsoft Windows Registry files).

Back to Top

9.2. Create your own IniValidator

To create your own IniValidator you will need to know regular expression, which is a fairly large topic and could not possibly cover here. If you do need a tutorial on regular expression you can easily find some on the internet with the aid of everyone's favourite search engine.

To create your own IniValidator you first need to pass a regular expression pattern to the methods setSectionRegEx() and setItemRegEx() and then pass the IniValidator to the IniFiles constructor. We will demonstrate this with an example.

import org.dtools.ini.*;
import java.util.regex.*; // Java's regular expression package

public class IniValidatorExample {

public static void main( String args[] ) {

//******************************************************************
// Step 1 - set up an IniValidator which only accepts numbers
//******************************************************************
IniValidator validator = new IniValidator();

validator.setSectionNameRegEx( Pattern.compile("[0-9]+") );
validator.setItemNameRegEx( Pattern.compile("[0-9]+") );

//******************************************************************
// Step 2 - Create an IniFile object and set the new validator
//******************************************************************
IniFile ini = new BasicIniFile( validator );

//******************************************************************
// Step 3 - Test the validator by creating sections and items
//******************************************************************
System.out.println( "Number of sections: " + ini.getNumberOfSections() );

ini.addSection( "00001" );
System.out.println( "Number of sections: " + ini.getNumberOfSections() );

ini.addSection( "9" );
System.out.println( "Number of sections: " + ini.getNumberOfSections() );

// now adding an illegal value
ini.addSection( "hello" );
System.out.println( "Number of sections: " + ini.getNumberOfSections() );
}

}

The above code, when ran, produces the following output:

Number of sections: 0
Number of sections: 1
Number of sections: 2
Exception in thread "main" org.dtools.ini.InvalidNameException: The section given does not have a valid name for this IniFile.
      at org.dtools.ini.AbstractIniFile.addSection(AbstractIniFile.java:202)
      at IniValidatorExample.main(IniValidatorExample.java:33)

As you can see, the first two sections were added successfully as they both contain numbers and therefore are considered valid by the IniValidator. However the third section, "hello" is not valid, and when added to the IniFile the method addSection throws an InvalidNameException object.

Back to Top

9.3. Default validation

By default the IniValidator considers all names to be valid, with the exception of the following rules:

  • The name cannot contain reserved characters, which are:
    • new line characters ("\n")
    • tab characters ("\t")
    • carriage return characters ("\r")
    • left square bracket ("[")
    • right square bracket ("]")
    • equal characters ("=")
    • semi-colon characters (";")
    • forward slash ("/")
    • backwards slash ("\\")
    • double quote characters ("\"")
  • Names can contain spaces, but the names cannot begin with a space, cannot end with a space, and (naturally) cannot contain only space characters.

Back to Top