IniFile (NetPhantom® 8.0 Java API Specification)

java.lang.Object
- se.entra.phantom.server.IniFile

```
public class IniFile
extends Object
```
Loads, edits and saves an INI-style configuration file such as SERVER.INI, organised into [sections] each containing item=data lines.
All values are stored as strings; there is no native decimal or hexadecimal type. Convenience getters parse int and boolean values on the fly (see getData(String,String,int) and getData(String,String,boolean)).
Case sensitivity (Windows/NTFS analogy)
Item names behave like file names on the Windows/NTFS file system: case-insensitive but case-preserving. A lookup ignores case (item names are folded to upper case internally), yet the original case you wrote is kept in the file text - just as Windows lets you create MyFile.TXT and open it as myfile.txt while the directory still shows the original spelling. This applies to item names always, regardless of any flag.
Section names are governed by the isCaseSensitive flag supplied at construction: when false (the default) they behave like items (case-insensitive, NTFS-style); when true they are matched exactly (case-sensitive, Unix-style). In all cases the original text case of a section header or item written to the file is preserved in the file lines; only the lookup keys are folded.
Editing and saving
An instance is editable only when created as such (the editable constructors or the createNewIniFile factories). Edits update both an in-memory line list and a section/item table, then set a "changed" flag (see hasChanged()). Call saveFile() to write the file, or saveFileWithBackup() to write a .bak copy of the previous file first. Both are no-ops when nothing has changed.
The accessor and mutator methods are synchronized; instances may be shared between threads.
Author:
Christopher Mindus

Constructor Summary

Constructors
Constructor and Description
`IniFile(boolean isCaseSensitive, PhantomFile in)` Loads the contents a the opened file (typically from a JAR or ZIP file).
`IniFile(boolean isCaseSensitive, PhantomFile in, boolean isEditable)` Loads the contents a the opened file (typically from a JAR or ZIP file).
`IniFile(boolean isCaseSensitive, String fileName)` The constructor loads the contents of the file.
`IniFile(boolean isCaseSensitive, String fileName, boolean isEditable)` The constructor loads the contents of the file.
`IniFile(PhantomFile in)` Loads the contents a the opened file (typically from a JAR or ZIP file).
`IniFile(PhantomFile in, boolean isEditable)` Loads the contents a the opened file (typically from a JAR or ZIP file).
`IniFile(String fileName)` The constructor loads the contents of the file.
`IniFile(String fileName, boolean isEditable)` The constructor loads the contents of the file.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static IniFile`	`createNewIniFile(boolean isCaseSensitive, String fileName)` Creates a new, empty, editable INI file with the given name and case mode.
`static IniFile`	`createNewIniFile(String fileName)` Creates a new, empty, editable INI file with the given name (not case sensitive).
`boolean`	`deleteSection(String name)` Removes a section from the INI file.
`boolean`	`doCreateUntitledSectionHeadings()` Returns whether untitled section headings are created.
`String`	`getData(String section, String item)` Gets an item's string value in a section.
`boolean`	`getData(String section, String item, boolean defaultData)` Gets an item's boolean value in a section, with a default if not found.
`int`	`getData(String section, String item, int defaultData)` Gets an item's integer value in a section, with a default if not found or not a valid integer.
`String`	`getData(String section, String item, String defaultData)` Gets an item's string value in a section, with a default if not found.
`String`	`getFileName()` Gets the file name of the INI file.
`Enumeration<String>`	`getItems(String section)` Gets an enumeration of all item names in a section.
`HashMap<String,String>`	`getSectionItems(String section)` Gets a copy of the item/data map of a section.
`Enumeration<String>`	`getSections()` Gets an enumeration of all section names in the file.
`int`	`getSize(String section)` Gets the number of items in a section.
`boolean`	`hasChanged()` Checks whether the INI file has unsaved changes.
`boolean`	`needsReload()` Check if this file needs to be reloaded.
`int`	`reload()` Reload internal state from external sources.
`boolean`	`removeAllItems(String section)` Removes all items defined in a section.
`boolean`	`renameSection(String oldName, String newName)` Renames a section in the INI file.
`void`	`save(OutputStream out)` Saves the INI file to an `OutputStream` without closing it, then clears the changed flag.
`void`	`save2(PhantomOutputFile out)` Saves the INI file to an already-open `PhantomOutputFile` without closing it, then clears the changed flag.
`void`	`saveFile()` Saves all changes (if any) made to the file.
`void`	`saveFileWithBackup()` Saves all changes (if any) made to the file, first creating a backup of the current file as `"filename[.extension].bak"`.
`void`	`setCreateUntitledSectionHeadings(boolean on)` Sets whether headings should be generated for untitled sections.
`boolean`	`setItem(String section, String item, boolean data)` Sets the topic and item to a specific boolean (0 or 1).
`boolean`	`setItem(String section, String item, int data)` Sets the topic and item to a specific integer.
`boolean`	`setItem(String section, String item, String data)` Sets the topic and item to a specific string.
`boolean`	`setItem(String section, String item, String data, String newSectionHeadingText)` Sets the topic and item to a specific string.
`boolean`	`setItems(String section, HashMap<String,String> itemDataPairs)` Sets the topic and item to a specific string.
`boolean`	`setItems(String section, HashMap<String,String> itemDataPairs, String newSectionHeadingText)` Sets the topic and item to a specific string.
`boolean`	`setItems(String section, Hashtable<String,String> itemDataPairs)` Sets the topic and item to a specific string.
`boolean`	`setItems(String section, Hashtable<String,String> itemDataPairs, String newSectionHeadingText)` Sets the topic and item to a specific string.
`boolean`	`setItems(String section, Set<Map.Entry<String,String>> entries)` Sets the topic and item to a specific string.
`boolean`	`setItems(String section, Set<Map.Entry<String,String>> entries, String newSectionHeadingText)` Sets the topic and item to a specific string.
`boolean`	`setItems(String section, String[] items)` Adds a set of items that does not include the equal sign to a topic.
`boolean`	`setItems(String section, String[] items, String newSectionHeadingText)` Adds a set of items that does not include the equal sign to a topic.
`void`	`updateLastModified()` Updates the stored last-modification time stamp, if a file-change checker is set.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - IniFile
```
public IniFile(String fileName)
        throws IOException,
               FileNotFoundException
```
    The constructor loads the contents of the file.
    Throws:
    IOException - if an I/O error occurs.
    FileNotFoundException - if the file is not found.
  - IniFile
```
public IniFile(boolean isCaseSensitive,
               String fileName)
        throws IOException,
               FileNotFoundException
```
    The constructor loads the contents of the file.
    Throws:
    IOException - if an I/O error occurs.
    FileNotFoundException - if the file is not found.
  - IniFile
```
public IniFile(String fileName,
               boolean isEditable)
        throws IOException,
               FileNotFoundException
```
    The constructor loads the contents of the file. Set isEditable to true if the contents of the file may be changed and later saved.
    Throws:
    IOException - if an I/O error occurs.
    FileNotFoundException - if the file is not found.
  - IniFile
```
public IniFile(boolean isCaseSensitive,
               String fileName,
               boolean isEditable)
        throws IOException,
               FileNotFoundException
```
    The constructor loads the contents of the file. Set isEditable to true if the contents of the file may be changed and later saved.
    Throws:
    IOException - if an I/O error occurs.
    FileNotFoundException - if the file is not found.
  - IniFile
```
public IniFile(PhantomFile in)
        throws IOException
```
    Loads the contents a the opened file (typically from a JAR or ZIP file).
    Throws:
    IOException - if an I/O error occurs.
  - IniFile
```
public IniFile(boolean isCaseSensitive,
               PhantomFile in)
        throws IOException
```
    Loads the contents a the opened file (typically from a JAR or ZIP file).
    Throws:
    IOException - if an I/O error occurs.
  - IniFile
```
public IniFile(PhantomFile in,
               boolean isEditable)
        throws IOException
```
    Loads the contents a the opened file (typically from a JAR or ZIP file).
    Throws:
    IOException - if an I/O error occurs.
  - IniFile
```
public IniFile(boolean isCaseSensitive,
               PhantomFile in,
               boolean isEditable)
        throws IOException
```
    Loads the contents a the opened file (typically from a JAR or ZIP file).
    Throws:
    IOException - if an I/O error occurs.
- Method Detail
  - createNewIniFile
```
public static IniFile createNewIniFile(String fileName)
```
    Creates a new, empty, editable INI file with the given name (not case sensitive).
    Parameters:
    fileName - The file name to associate with the new INI file.
    Returns:
    A new editable IniFile.
  - createNewIniFile
```
public static IniFile createNewIniFile(boolean isCaseSensitive,
                                       String fileName)
```
    Creates a new, empty, editable INI file with the given name and case mode.
    Parameters:
    isCaseSensitive - true to treat section names case-sensitively.
    fileName - The file name to associate with the new INI file.
    Returns:
    A new editable IniFile.
  - setCreateUntitledSectionHeadings
```
public void setCreateUntitledSectionHeadings(boolean on)
```
    Sets whether headings should be generated for untitled sections.
    Parameters:
    on - true to create untitled section headings.
  - doCreateUntitledSectionHeadings
```
public boolean doCreateUntitledSectionHeadings()
```
    Returns whether untitled section headings are created.
    Returns:
    true if untitled section headings are created.
  - needsReload
```
public boolean needsReload()
```
    Check if this file needs to be reloaded.
    Returns:
    boolean
  - reload
```
public int reload()
           throws IOException
```
    Reload internal state from external sources.
    Returns:
    int IReloadable.SUCCESS, IReloadable.NOTHING_DONE or IReloadable.FAILURE.
    Throws:
    IOException
  - getFileName
```
public String getFileName()
```
    Gets the file name of the INI file.
    Returns:
    The file name.
  - getSections
```
public Enumeration<String> getSections()
```
    Gets an enumeration of all section names in the file.
    Returns:
    An enumeration of the section names.
  - getItems
```
public Enumeration<String> getItems(String section)
```
    Gets an enumeration of all item names in a section.
    Section names follow the isCaseSensitive flag; item names are always matched case-insensitively but stored case-preserving, the way the Windows/NTFS file system treats file names (write as MyItem, find as MYITEM, but the original case is kept in the file).
    Parameters:
    section - The section name.
    Returns:
    An enumeration of the item names, or null if the section is not found.
  - getSectionItems
```
public HashMap<String,String> getSectionItems(String section)
```
    Gets a copy of the item/data map of a section.
    Parameters:
    section - The section name.
    Returns:
    A new HashMap copy of the section's items, or null if the section is not found.
  - getSize
```
public int getSize(String section)
```
    Gets the number of items in a section.
    Parameters:
    section - The section name.
    Returns:
    The number of items, or 0 if the section is not found.
  - getData
```
public String getData(String section,
                      String item)
```
    Gets an item's string value in a section.
    The item name is matched case-insensitively but case-preserving (NTFS-style; see the class description). The section name follows the isCaseSensitive flag.
    Parameters:
    section - The section name.
    item - The item name (always matched case-insensitively).
    Returns:
    The value, or null if the section or item is not found, or if the item had no = sign (e.g. a bare "ItemWithoutEqualSign").
  - getData
```
public String getData(String section,
                      String item,
                      String defaultData)
```
    Gets an item's string value in a section, with a default if not found.
    Parameters:
    section - The section name.
    item - The item name.
    defaultData - The value to return if the item is not found.
    Returns:
    The value, or defaultData if not found.
  - getData
```
public int getData(String section,
                   String item,
                   int defaultData)
```
    Gets an item's integer value in a section, with a default if not found or not a valid integer.
    Parameters:
    section - The section name.
    item - The item name.
    defaultData - The value to return if the item is missing or unparsable.
    Returns:
    The parsed integer, or defaultData.
  - getData
```
public boolean getData(String section,
                       String item,
                       boolean defaultData)
```
    Gets an item's boolean value in a section, with a default if not found.
    The string "1" is true and "0" is false; any other value (including missing) yields defaultData.
    Parameters:
    section - The section name.
    item - The item name.
    defaultData - The value to return if the item is missing or not "0"/"1".
    Returns:
    The boolean value, or defaultData.
  - setItem
```
public boolean setItem(String section,
                       String item,
                       int data)
```
    Sets the topic and item to a specific integer. If the topic or item doesn't exist, they will be created.
    Item names are matched case-insensitively but case-preserving (NTFS-style; see the class description): an existing entry keeps its original case, and new topics/items are added at the end of the topic or the file respectively.
    Use the method saveFile to save all changes made to the file.
    Returns:
    true for file changed, false otherwise.
  - setItem
```
public boolean setItem(String section,
                       String item,
                       boolean data)
```
    Sets the topic and item to a specific boolean (0 or 1). If the topic or item doesn't exist, they will be created.
    Item names are matched case-insensitively but case-preserving (NTFS-style; see the class description): an existing entry keeps its original case, and new topics/items are added at the end of the topic or the file respectively.
    Use the method saveFile to save all changes made to the file.
    Returns:
    true for file changed, false otherwise.
  - setItem
```
public boolean setItem(String section,
                       String item,
                       String data)
```
    Sets the topic and item to a specific string. If the topic or item doesn't exist, they will be created.
    Item names are matched case-insensitively but case-preserving (NTFS-style; see the class description): an existing entry keeps its original case, and new topics/items are added at the end of the topic or the file respectively.
    Use the method saveFile to save all changes made to the file.
  - setItem
```
public boolean setItem(String section,
                       String item,
                       String data,
                       String newSectionHeadingText)
```
    Sets the topic and item to a specific string. If the topic or item doesn't exist, they will be created.
    Item names are matched case-insensitively but case-preserving (NTFS-style; see the class description): an existing entry keeps its original case, and new topics/items are added at the end of the topic or the file respectively.
    This method doesn't do anything if the item already has the specified data.
    Use the method saveFile to save all changes made to the file.
    Returns:
    true for file changed, false otherwise.
  - setItems
```
public boolean setItems(String section,
                        String[] items)
```
    Adds a set of items that does not include the equal sign to a topic. If the topic doesn't exist, it will be created. Note that the topic may be in any character case (and any existing entry will preserve the original case). New topics/items are added at the end of the topic or the file respectively.
    Use the method saveFile to save all changes made to the file.
  - setItems
```
public boolean setItems(String section,
                        String[] items,
                        String newSectionHeadingText)
```
    Adds a set of items that does not include the equal sign to a topic. If the topic doesn't exist, it will be created. Note that the topic may be in any character case (and any existing entry will preserve the original case). New topics/items are added at the end of the topic or the file respectively.
    Use the method saveFile to save all changes made to the file.
  - setItems
```
public boolean setItems(String section,
                        Hashtable<String,String> itemDataPairs)
```
    Sets the topic and item to a specific string. If the topic or item doesn't exist, they will be created. Note that the topic may be in any character case (and any existing entry will preserve the original case). New topics/items are added at the end of the topic or the file respectively.
    Use the method saveFile to save all changes made to the file.
  - setItems
```
public boolean setItems(String section,
                        Hashtable<String,String> itemDataPairs,
                        String newSectionHeadingText)
```
    Sets the topic and item to a specific string. If the topic or item doesn't exist, they will be created. Note that the topic may be in any character case (and any existing entry will preserve the original case). New topics/items are added at the end of the topic or the file respectively.
    Use the method saveFile to save all changes made to the file.
  - setItems
```
public boolean setItems(String section,
                        HashMap<String,String> itemDataPairs)
```
    Sets the topic and item to a specific string. If the topic or item doesn't exist, they will be created. Note that the topic may be in any character case (and any existing entry will preserve the original case). New topics/items are added at the end of the topic or the file respectively.
    Use the method saveFile to save all changes made to the file.
  - setItems
```
public boolean setItems(String section,
                        HashMap<String,String> itemDataPairs,
                        String newSectionHeadingText)
```
    Sets the topic and item to a specific string. If the topic or item doesn't exist, they will be created. Note that the topic may be in any character case (and any existing entry will preserve the original case). New topics/items are added at the end of the topic or the file respectively.
    Use the method saveFile to save all changes made to the file.
  - setItems
```
public boolean setItems(String section,
                        Set<Map.Entry<String,String>> entries)
```
    Sets the topic and item to a specific string. If the topic or item doesn't exist, they will be created. Note that the topic may be in any character case (and any existing entry will preserve the original case). New topics/items are added at the end of the topic or the file respectively.
    Use the method saveFile to save all changes made to the file.
  - setItems
```
public boolean setItems(String section,
                        Set<Map.Entry<String,String>> entries,
                        String newSectionHeadingText)
```
    Sets the topic and item to a specific string. If the topic or item doesn't exist, they will be created. Note that the topic may be in any character case (and any existing entry will preserve the original case). New topics/items are added at the end of the topic or the file respectively.
    Use the method saveFile to save all changes made to the file.
  - removeAllItems
```
public boolean removeAllItems(String section)
```
    Removes all items defined in a section.
  - deleteSection
```
public boolean deleteSection(String name)
```
    Removes a section from the INI file. This will comment the section heading and remove all the uncommented items in it.
    Returns:
    true for success; false for failure.
  - renameSection
```
public boolean renameSection(String oldName,
                             String newName)
```
    Renames a section in the INI file. The section should not contain the [brackets]. To remove a section from the INI file, i.e. to comment it, just set newName to null. This will comment the section heading and remove all the uncommented items in it.
    Returns:
    true for success; false for failure.
  - hasChanged
```
public boolean hasChanged()
```
    Checks whether the INI file has unsaved changes.
    Returns:
    true if there are changes that a save would write.
  - saveFile
```
public void saveFile()
              throws IOException
```
    Saves all changes (if any) made to the file. No backup copy is made; to write a backup of the previous file first, use saveFileWithBackup() instead.
    If nothing has changed (hasChanged() is false) this method does nothing and the file on disk is left untouched.
    Throws:
    IOException - if an I/O error occurs while writing the file.
  - saveFileWithBackup
```
public void saveFileWithBackup()
                        throws IOException
```
    Saves all changes (if any) made to the file, first creating a backup of the current file as "filename[.extension].bak".
    If nothing has changed (hasChanged() is false) this method does nothing: neither the file nor a backup is written.
    Otherwise the previous backup (if any) is deleted, the current file is renamed to the backup name, and the new contents are written to the original file name. If the current file does not yet exist (first save), no backup is made and the file is simply written.
    Throws:
    IOException - if the previous backup cannot be deleted, the current file cannot be renamed to the backup, or an I/O error occurs while writing the new file.
  - save2
```
public void save2(PhantomOutputFile out)
           throws IOException
```
    Saves the INI file to an already-open PhantomOutputFile without closing it, then clears the changed flag.
    Parameters:
    out - The open output file to write the INI lines to.
    Throws:
    IOException - if an I/O error occurs.
  - save
```
public void save(OutputStream out)
          throws IOException
```
    Saves the INI file to an OutputStream without closing it, then clears the changed flag.
    Parameters:
    out - The output stream to write the INI lines to.
    Throws:
    IOException - if an I/O error occurs.
  - updateLastModified
```
public void updateLastModified()
```
    Updates the stored last-modification time stamp, if a file-change checker is set. Used by the Editor to track external modifications.

Class IniFile

Case sensitivity (Windows/NTFS analogy)

Editing and saving

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

IniFile

IniFile

IniFile

IniFile

IniFile

IniFile

IniFile

IniFile

Method Detail

createNewIniFile

createNewIniFile

setCreateUntitledSectionHeadings

doCreateUntitledSectionHeadings

needsReload

reload

getFileName

getSections

getItems

getSectionItems

getSize

getData

getData

getData

getData

setItem

setItem

setItem

setItem

setItems

setItems

setItems

setItems

setItems

setItems

setItems

setItems

removeAllItems

deleteSection

renameSection

hasChanged

saveFile

saveFileWithBackup

save2

save

updateLastModified