org.safs.staf.service
Class SAFSAppMapFile

java.lang.Object
  org.safs.text.FileLineReader
      org.safs.text.INIFileReader
          org.safs.staf.service.SAFSAppMapFile

public class SAFSAppMapFile
extends INIFileReader

Copyright 2003 SAS Institute GNU General Public License (GPL) http://www.opensource.org/licenses/gpl-license.php

This SAFSAppMapFile class is intended as the file instance class for a SAFSAppMapService.
Although there are no STAF dependencies, the class is tightly integrated with the reader. It has not been evaluated for any other use. Though, standalone use is likely possible.

Physical SAFS AppMap files are expected to be in a particular format. This is very much like the format for Windows INI files--the same 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 mark)

An AppMap "Section" is delimited with square 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. If the closing bracket is missing, the handler will graciously except the entry. The line is first trimmed before the check for a section is made.

A section identifier is not case-sensitive.

If an AppMap 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 is not case-sensitive. 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.

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.)

See Also:

SAFSAppMapService

Nested Class Summary

Nested classes/interfaces inherited from class org.safs.text.INIFileReader

INIFileReader.JITLoader

Field Summary

protected java.lang.String	fileid
protected int	handle
protected java.lang.String	machine
protected java.lang.String	process
static java.lang.String	SAM_DEFAULT_MAP_SECTION_COMMAND
static int	SAM_MEMORY_MODE_MAPPED
static int	SAM_MEMORY_MODE_STORED

Fields inherited from class org.safs.text.INIFileReader

defaultsection, IFR_DEFAULT_MAP_SECTION, IFR_DEFAULT_MAP_SECTION_COMMAND, IFR_MEMORY_MODE_MAPPED, IFR_MEMORY_MODE_STORED, ignoreItemCase, jit, jitstop, memorymode, sections

Fields inherited from class org.safs.text.FileLineReader

DEFAULT_BUFFER_SIZE, eof, file, filename, firstline, fullpath, linetext, reader, stream

Constructor Summary

SAFSAppMapFile()
This constructor will create an inoperable (Closed) file object.

SAFSAppMapFile(java.lang.String machine, java.lang.String process, int handle, java.lang.String fileid, java.io.File file, int memorymode)
The constructor used by the SAFSAppMapReader.

Method Summary

java.lang.String	getFileID() Subclasses should not need to override this function.
int	getHandle() Subclasses should not need to override this function.
java.lang.String	getMachine() Subclasses should not need to override this function.
java.lang.String	getProcess() Subclasses should not need to override this function.

Methods inherited from class org.safs.text.INIFileReader

clearCache, clearHashtables, close, closeJIT, getAppMapItem, getDefaultSection, getItem, getItems, getMode, getNewHashtable, getSections, setDefaultSection, tryJITLoader

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

machine

protected java.lang.String machine

process

protected java.lang.String process

handle

protected int handle

fileid

protected java.lang.String fileid

SAM_DEFAULT_MAP_SECTION_COMMAND

public static final java.lang.String SAM_DEFAULT_MAP_SECTION_COMMAND

See Also:

Constant Field Values

SAM_MEMORY_MODE_STORED

public static final int SAM_MEMORY_MODE_STORED

See Also:

Constant Field Values

SAM_MEMORY_MODE_MAPPED

public static final int SAM_MEMORY_MODE_MAPPED

See Also:

Constant Field Values

Constructor Detail

SAFSAppMapFile

public SAFSAppMapFile()

This constructor will create an inoperable (Closed) file object. No use whatsoever. :)

SAFSAppMapFile

public SAFSAppMapFile(java.lang.String machine,
                      java.lang.String process,
                      int handle,
                      java.lang.String fileid,
                      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(machine, process, handle, fileid, file);

Parameters:

machine - The STAF machine that requested this file be opened.

process - The STAF process that requested this file be opened.

handle - The STAF process handle that requested this file be opened.

fileid - A unique String ID to identify this file for the requesting process. This is not a filename. Multiple open views of the same file could be opened and each should have a unique fileid within the process namespace. However, there is probably little value in multiple views unless MAPPED memory mode is used.

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.

Method Detail

getMachine

public java.lang.String getMachine()

Subclasses should not need to override this function.

Returns:

the value of the machine constructor parameter

getProcess

public java.lang.String getProcess()

Subclasses should not need to override this function.

Returns:

the value of the process constructor parameter

getFileID

public java.lang.String getFileID()

Subclasses should not need to override this function.

Returns:

the value of the fileid constructor parameter

getHandle

public int getHandle()

Subclasses should not need to override this function.

Returns:

the value of the handle constructor parameter