INIFileReader (SAFS API DOCUMENT)

java.lang.Object
- org.safs.text.FileLineReader
- - org.safs.text.INIFileReader

Direct Known Subclasses:

INIFileReadWrite, SAFSAppMapFile
```
public class INIFileReader
extends FileLineReader
```
Copyright 2004 SAS Institute GNU General Public License (GPL) http://www.opensource.org/licenses/gpl-license.php
This INIFileReader class is intended to read INI formatted text files.

Physical INI files are expected to be in a particular format. This is very much like the format for Windows INI files--which is the App Map format currently in use for the Rational Robot SAFS Engine (RRAFS). (Though, there may be slight differences.)
The following characters are allowed to indicate commentlines or are otherwise ignored. Lines are trimmed of leading whitespace before this check is made:
! (bang - exclamation point)
; (semicolon)
# (hash or pound mark)

However, if an equality character ('=') exists in the line the line will be treated as a valid text line. The assumption is the comment indicators are actually part of the NAME in a NAME=VALUE pair.
Each INI "Section" is delimited with brackets ([ ])containing the name of the section. In SAFS automation parlance, these are the "Window" definition sections. A section delimiter should appear all by itself on a line. There should be no additional text. The line is first trimmed before the check for a section is made.
A section identifier is not case-sensitive.
If an INI file contains a [ApplicationConstants] section, that will be considered the "default" section. Otherwise, any first, unnamed section is the "default".
Items within a section have a NAME=VALUE format.
To the left of the Equals sign is the NAME. The substring is trimmed of leading or trailing whitespace and by default is not case-sensitive. Enclose any space character(s) in double-quote characters. Everything to the right of the Equals sign is returned unmodified. It is NOT trimmed of leading or trailing whitespace and the text is returned unmodified. However, leading and trailing quotes will be removed if they exist.
An example is below:
! this line is ignored
; this line is ignored
# this line is ignored

; the following 2 items are in an initial, unnamed section.
; these are accessible by passing a NULL or empty string when
; specifying a Section parameter.

An Item = a value
Another = another value

[A Section Name]

An Item = a value
Another = another value

[A Second Section]

An Item = a value
Another = another value

The file uses a java.io.BufferedReader for STORED memory mode, or a java.io.RandomAccessFile for MAPPED memory mode. (MAPPED mode is not yet implemented.)

Version:

2.0, 02/23/2005

Author:

Carl Nagle, SAS Institute, Carl Nagle, 02/23/2005 Modified for use of CaseInsensitiveHashtable, Carl Nagle, 02/23/2007 Modified for optional use of java.util.Hashtable, Carl Nagle, 07/16/2010 Mod to support other valid Charset encodings. Software Automation Framework Support (SAFS) https://safsdev.github.io/
Software Testing Automation Framework (STAF) http://staf.sourceforge.net

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

protected class INIFileReader.JITLoader

Nested Classes
Modifier and Type	Class and Description
`protected class`	`INIFileReader.JITLoader`

Field Summary

Fields
Modifier and Type	Field and Description
`protected java.lang.String`	`defaultsection`
`static java.lang.String`	`IFR_DEFAULT_MAP_SECTION` the Default App Map section until reassigned: ApplicationConstants
`static java.lang.String`	`IFR_DEFAULT_MAP_SECTION_COMMAND` The text string that specifies to reference the "default" AppMap section in requests.
`static int`	`IFR_MEMORY_MODE_MAPPED` FUTURE:Specifies to store file pointers and map regions in memory for storage efficiency.
`static int`	`IFR_MEMORY_MODE_STORED` Specifies to completely read and store the file in memory for performance.
`protected boolean`	`ignoreItemCase`
`protected INIFileReader.JITLoader`	`jit`
`protected boolean`	`jitstop`
`protected int`	`memorymode` Determines if the file should be fully loaded and stored in memory.
`protected CaseInsensitiveHashtable`	`sections`

Fields inherited from class org.safs.text.FileLineReader
charset, DEFAULT_BUFFER_SIZE, eof, file, filename, firstline, fullpath, linetext, reader, stream

Constructor Summary

Constructors
Constructor and Description
`INIFileReader()` This constructor will create an inoperable (Closed) file object.
`INIFileReader(java.io.File file, int memorymode)` The constructor used by the SAFSAppMapReader.
`INIFileReader(java.io.File file, int memorymode, boolean ignoreItemCase)` The constructor used to force Item case sensitivity.
`INIFileReader(java.io.File file, int memorymode, boolean ignoreItemCase, java.lang.String encoding)` The constructor used to force Item case sensitivity.
`INIFileReader(java.io.File file, int memorymode, java.lang.String encoding)` The constructor used by the SAFSAppMapReader.
`INIFileReader(java.io.InputStream stream, int memorymode, boolean ignoreItemCase)` The constructor used to force Item case sensitivity while using an InputStream.
`INIFileReader(java.io.InputStream stream, int memorymode, boolean ignoreItemCase, java.lang.String encoding)` The constructor used to force Item case sensitivity while using an InputStream.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`clearCache()` Clears any internally stored cache of prefetched items.
`protected void`	`clearHashtables()` All the stored Hashtables and the parent sections Hashtable are clear()ed.
`void`	`close()` Closes the file (if still open) and releases all stored resources via clearHashtables().
`protected void`	`closeJIT()` Shutdown the JIT file processor.
`java.lang.String`	`getAppMapItem(java.lang.String section, java.lang.String item)` Lookup an item in a particular section of the map.
`java.lang.String`	`getDefaultSection()` Return the "default" section setting
`java.lang.String`	`getItem(java.lang.String section, java.lang.String item)`
`java.util.Vector`	`getItems(java.lang.String section)` Returns the list of items in a section.
`int`	`getMode()` Retrieves the memorymode (STORED or MAPPED)
`java.util.Hashtable`	`getNewHashtable(int size)` Instantiates a new Hashtable or CaseInsensitiveHashtable depending on the type of storage to be used.
`java.util.Vector`	`getSections()` Retrieve the list of sections.
`int`	`setDefaultSection(java.lang.String section)` Set the "default" section.
`protected void`	`tryJITLoader()` Will run the JITLoader to populate the cache if the memorymode is appropriate.

Methods inherited from class org.safs.text.FileLineReader
closeReader, getFilename, getFullpath, isClosed, isEOF, open, openFile, openStream, readLine, resetpointers, setFile, setStream

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

- Field Detail
  - ignoreItemCase
```
protected boolean ignoreItemCase
```
  - sections
```
protected CaseInsensitiveHashtable sections
```
  - IFR_MEMORY_MODE_STORED
```
public static final int IFR_MEMORY_MODE_STORED
```
    Specifies to completely read and store the file in memory for performance. (DEFAULT)
    
    See Also:
    
    Constant Field Values
  - IFR_MEMORY_MODE_MAPPED
```
public static final int IFR_MEMORY_MODE_MAPPED
```
    FUTURE:Specifies to store file pointers and map regions in memory for storage efficiency.
    
    See Also:
    
    Constant Field Values
  - IFR_DEFAULT_MAP_SECTION_COMMAND
```
public static final java.lang.String IFR_DEFAULT_MAP_SECTION_COMMAND
```
    The text string that specifies to reference the "default" AppMap section in requests.
    
    See Also:
    
    Constant Field Values
  - IFR_DEFAULT_MAP_SECTION
```
public static final java.lang.String IFR_DEFAULT_MAP_SECTION
```
    the Default App Map section until reassigned: ApplicationConstants
    
    See Also:
    
    Constant Field Values
  - memorymode
```
protected int memorymode
```
    Determines if the file should be fully loaded and stored in memory. It would be more efficient to read and store relatively small files into object arrays. For this, there is the IFR_MEMORY_MODE_STORED mode.
    In this mode, a helper thread runs in the background populating our internal storage. The underlying file stream will actually be closed once the helper thread has loaded all values into memory. Yet, this file instance remains valid servicing data requests until it receives the official close() request from the object owner.
    For much larger files, it may be more efficient to simply store pointers to key locations in the file and then map sections in and out of memory as needed. For this there will be the IFR_MEMORY_MODE_MAPPED mode.
    The initial release of this file handler only supports the STORED memorymode. However, the MAPPED memory mode will be implemented using the RandomAccessFile and FileChannel support in Java.
  - defaultsection
```
protected java.lang.String defaultsection
```
  - jit
```
protected INIFileReader.JITLoader jit
```
  - jitstop
```
protected boolean jitstop
```
- Constructor Detail
  - INIFileReader
```
public INIFileReader()
```
    This constructor will create an inoperable (Closed) file object. No use whatsoever. :)
  - INIFileReader
```
public INIFileReader(java.io.File file,
                     int memorymode)
```
    The constructor used by the SAFSAppMapReader. All subclasses MUST invoke this constructor prior to completing their initialization.
    Invoke this constructor from the subclass with:
    super(file);
    
    Parameters:
    
    file - A valid File object for the file to be opened.
    
    memorymode - the memory model for this handler to use: STORED or MAPPED. Currently only the STORED model is used.
  - INIFileReader
```
public INIFileReader(java.io.File file,
                     int memorymode,
                     java.lang.String encoding)
```
    The constructor used by the SAFSAppMapReader. All subclasses MUST invoke this constructor prior to completing their initialization.
    Invoke this constructor from the subclass with:
    super(file);
    
    Parameters:
    
    file - A valid File object for the file to be opened.
    
    memorymode - the memory model for this handler to use: STORED or MAPPED. Currently only the STORED model is used.
    
    encoding - a valid Charset encoding like "UTF-16", etc...
  - INIFileReader
```
public INIFileReader(java.io.File file,
                     int memorymode,
                     boolean ignoreItemCase)
```
    The constructor used to force Item case sensitivity.
    
    Parameters:
    
    file - A valid File object for the file to be opened.
    
    memorymode - the memory model for this handler to use: STORED or MAPPED. Currently only the STORED model is used.
    
    ignoreItemCase - set to FALSE to make Item NAMES case-sensitive. By default Item names are not case-sensitive.
  - INIFileReader
```
public INIFileReader(java.io.File file,
                     int memorymode,
                     boolean ignoreItemCase,
                     java.lang.String encoding)
```
    The constructor used to force Item case sensitivity.
    
    Parameters:
    
    file - A valid File object for the file to be opened.
    
    memorymode - the memory model for this handler to use: STORED or MAPPED. Currently only the STORED model is used.
    
    ignoreItemCase - set to FALSE to make Item NAMES case-sensitive. By default Item names are not case-sensitive.
    
    encoding - a valid Charset encoding like "UTF-16", etc...
  - INIFileReader
```
public INIFileReader(java.io.InputStream stream,
                     int memorymode,
                     boolean ignoreItemCase)
```
    The constructor used to force Item case sensitivity while using an InputStream. For example, resources or files stored in JARs loaded via ClassLoaders. Files can be loaded from the file system if the directory is in the System CLASSPATH where getSystemResourceAsStream can find it.
    
    Parameters:
    
    stream - A valid InputStream object for the data to be read.
    
    memorymode - the memory model for this handler to use: STORED or MAPPED. Currently only the STORED model is used.
    
    ignoreItemCase - set to FALSE to make Item NAMES case-sensitive. By default Item names are not case-sensitive.
    
    See Also:
    
    ClassLoader.getSystemResourceAsStream(java.lang.String)
  - INIFileReader
```
public INIFileReader(java.io.InputStream stream,
                     int memorymode,
                     boolean ignoreItemCase,
                     java.lang.String encoding)
```
    The constructor used to force Item case sensitivity while using an InputStream. For example, resources or files stored in JARs loaded via ClassLoaders. Files can be loaded from the file system if the directory is in the System CLASSPATH where getSystemResourceAsStream can find it.
    
    Parameters:
    
    stream - A valid InputStream object for the data to be read.
    
    memorymode - the memory model for this handler to use: STORED or MAPPED. Currently only the STORED model is used.
    
    ignoreItemCase - set to FALSE to make Item NAMES case-sensitive. By default Item names are not case-sensitive.
    
    encoding - a valid Charset encoding like "UTF-16", etc...
    
    See Also:
    
    ClassLoader.getSystemResourceAsStream(java.lang.String)
- Method Detail
  - tryJITLoader
```
protected void tryJITLoader()
```
    Will run the JITLoader to populate the cache if the memorymode is appropriate. Currently, we only support the STORED memorymode; so the JITLoader will definitely run.
  - clearHashtables
```
protected void clearHashtables()
```
    All the stored Hashtables and the parent sections Hashtable are clear()ed. The sections Hashtable is left empty on exit.
  - closeJIT
```
protected void closeJIT()
```
    Shutdown the JIT file processor. The JIT will be nulled on exit.
  - close
```
public void close()
```
    Closes the file (if still open) and releases all stored resources via clearHashtables(). This is the call to shutdown for termination. This also forwards the close request to the superclass which will shutdown the file reader.
    
    Overrides:
    
    close in class FileLineReader
    
    See Also:
    
    closeJIT(), clearHashtables()
  - getAppMapItem
```
public java.lang.String getAppMapItem(java.lang.String section,
                                      java.lang.String item)
```
    Lookup an item in a particular section of the map. The section can be an empty string--the first, unnamed section. You may also specify to use the "default" section by specifying "DefaultMapSection" for the section parameter. The parameters are not case-sensitive. If no "default" section has been set, the first unnamed section is used.
    
    Parameters:
    
    section - the section of the Map to find an item in. If section is null, an empty String will be used to identify the the first, unnamed section. This is not case-sensitive. To use the "default" section, specify "DefaultMapSection" for this parameter. All "keys" are stored in lower-case.
    
    item - the item in the section to find a value on. This is not case-sensitive. If the item parameter is null or empty then a null value will be returned. All "keys" are stored in lower-case.
    
    Returns:
    
    the value of the item in the specified section. If the value appears to be a quoted string then any leading/trailing blanks outside the quotes and the quotes themselves will be removed. null if the item parameter is invalid or the item cannot be found.
  - getItem
```
public java.lang.String getItem(java.lang.String section,
                                java.lang.String item)
```
  - getMode
```
public int getMode()
```
    Retrieves the memorymode (STORED or MAPPED)
  - getSections
```
public java.util.Vector getSections()
```
    Retrieve the list of sections. An object with no elements is returned if there are no sections in the map.
  - getDefaultSection
```
public java.lang.String getDefaultSection()
```
    Return the "default" section setting
  - setDefaultSection
```
public int setDefaultSection(java.lang.String section)
```
    Set the "default" section.
    
    Parameters:
    
    section - the section to set as default. If the value is null or 0-length, then we will set the default to be the first, unnamed section.
    
    Returns:
    
    0 on success. STAFResult.DoesNotExist (48) if the specified section does not exist.
  - getItems
```
public java.util.Vector getItems(java.lang.String section)
```
    Returns the list of items in a section.
    
    Parameters:
    
    section - the section to query for list items. If the value is null or 0-length, then we will get the list of items in the first, unnamed section. If the value is DEFAULTMAPSECTION, then we will get the list of items in the "default" section.
    
    Returns:
    
    the list of items for the section. size() should be 0 if no items exist. A NULL object is returned if the requested section does not exist in the map.
  - clearCache
```
public void clearCache()
```
    Clears any internally stored cache of prefetched items. This will cause the App Map to again be opened and read as necessary. This is especially necessary for STORED memory mode after the user has made changes to the App Map file.
  - getNewHashtable
```
public java.util.Hashtable getNewHashtable(int size)
```
    Instantiates a new Hashtable or CaseInsensitiveHashtable depending on the type of storage to be used.
    
    Returns:
    
    A Hashtable or CaseInsensitiveHashtable as needed to store items.

Class INIFileReader

Nested Class Summary

Field Summary

Fields inherited from class org.safs.text.FileLineReader

Constructor Summary

Method Summary

Methods inherited from class org.safs.text.FileLineReader

Methods inherited from class java.lang.Object

Field Detail

ignoreItemCase

sections

IFR_MEMORY_MODE_STORED

IFR_MEMORY_MODE_MAPPED

IFR_DEFAULT_MAP_SECTION_COMMAND

IFR_DEFAULT_MAP_SECTION

memorymode

defaultsection

jit

jitstop

Constructor Detail

INIFileReader

INIFileReader

INIFileReader

INIFileReader

INIFileReader

INIFileReader

INIFileReader

Method Detail

tryJITLoader

clearHashtables

closeJIT

close

getAppMapItem

getItem

getMode

getSections

getDefaultSection

setDefaultSection

getItems

clearCache

getNewHashtable