public class UastHints extends java.lang.Object implements HintsConstants
There are 2 levels of hints files:
The directory hints are loaded first and then file-specific hints are loaded. This allows generic (directory level) processing to be overridden by more specific values at the file level.
Directory hints are loaded in the order found. The search starts in the base path (top-level source directory) and then walks downward to each more deeply nested directory until the directory containing the file is searched. This means that all directory hints files that exist in that path will be loaded (the search does not stop when the first directory hints file is found). Also note that any value in a more specific directory may override a more enclosing directory hint.
Note that the format of both type of hints files are the same and there is no provision for removing a hint that is specified in a previously loaded hints file. Each specific type of hint handles this differently. Sometimes the hint will work as an addition, but in other cases the hint acts as a replacement. Here is the guide:
Hint Type Edit Type ------------------------- ------------------------- database adds to end of the list alias adds to end of the list variable adds to end of the list preprocessor args replacement preprocessor unix escapes replacement preprocessor marker replacement preprocessor batch mode replacement preprocessor opsys replacement preprocessor window system replacement preprocessor debug replacement propath replacement schema hints replacement callgraph rootlist replacement callgraph include-spec replacement embedded 4GL preprocessor replacement generic uast replacement
Once constructed, the hints file has been loaded into memory and the
contents are available via simple 'getter' method calls such as
getDatabases()
. This class hides the storage mechanism and the
file format from the callers. It also handles any conversion from the
string oriented XML format to the proper data type of the value in
question. Generally, if the hints file doesn't exist or if the value
being queried doesn't exist in that hints file, the result from a
lookup will be null
.
There is support for generic UAST hints that must be uniquely named (within a given file) and the value can be one of the following data types: boolean, long, double, string, string array. Each uniquely named value can be obtained using the name as a key.
The following is the structure of the XML file:
Modifier and Type | Field and Description |
---|---|
private java.util.ArrayList<java.lang.String[]> |
aliases
The set of all aliases and the corresponding database they reference.
|
private java.util.Map<java.lang.String,java.lang.String> |
arguments
Preprocessor arguments (positional or named) in name + value pairs.
|
private java.lang.String |
basePath
Path to the top-level source directory.
|
private boolean |
batch
BATCH-MODE preprocessor built-in variable value.
|
private java.lang.String[] |
databases
The list of databases that must be connected before parsing.
|
static java.lang.String |
DIR_HINTS
The standard name for the directory level hints file.
|
private java.lang.Boolean |
escaped
Schema escape attribute, null means that attribute is not set.
|
static java.lang.String |
HINTS_SUFFIX
The standard suffix appended to a source code filename to create a
unique filename for storing hints.
|
private java.lang.String |
includeSpec
Call graph included file spec
|
private char |
marker
Sets the internal character used for preprocessor synchronization.
|
private java.lang.String |
mode
E4GL preprocessor compatibility mode.
|
private java.lang.String |
opsys
OPSYS preprocessor built-in variable value.
|
private java.lang.String |
output
E4GL preprocessor output filename.
|
static int |
PATH_MOD_APPEND
Append the PROPATH with the associated string.
|
static int |
PATH_MOD_DYN_APPEND
Append the file's containing directory to the PROPATH.
|
static int |
PATH_MOD_DYN_PREPEND
Prepend the file's containing directory to the PROPATH.
|
static int |
PATH_MOD_NONE
No PROPATH modification is specified for this file.
|
static int |
PATH_MOD_PREPEND
Prepend the PROPATH with the associated string.
|
static int |
PATH_MOD_REPLACE
Replace the PROPATH with the associated string.
|
private java.lang.String |
pathModTxt
Encodes the text to use for PROPATH customization.
|
private int |
pathModType
Encodes any PROPATH customization specified for this file.
|
private boolean |
preprocDebug
Preprocessor debug flag.
|
private java.lang.String |
rootList
Path to a call graph root list XML file
|
private java.nio.charset.Charset |
sourceCharset
The source charset.
|
private java.lang.String |
sourceDir
Path to the source directory.
|
private java.util.Map<java.lang.String,TableHints> |
tableHints
Map of schema table hints, keyed by table name
|
private java.util.Map<java.lang.String,java.lang.Object> |
uast
Stores the mapping of a unique key to a generic UAST hint.
|
private boolean |
unixEscapes
The preprocessor should honor the backslash character as an escape
sequence (this corresponds to how the preprocessor works on UNIX).
|
private Variable[] |
variables
The set of all variables/widgets to be added to the global variable
dictionary or widget dictionaries before parsing begins.
|
private java.lang.String |
winsys
WINDOW-SYSTEM preprocessor built-in variable value.
|
private java.lang.String |
wsoptions
WSOPTIONS E4GL preprocessor value.
|
ATTR_CLASSNAME, ATTR_DB, ATTR_DTYPE, ATTR_ESCAPE, ATTR_NAME, ATTR_POS, ATTR_TYPE, ATTR_VAL, ELEM_ALIAS, ELEM_ARG, ELEM_ARRAY, ELEM_BASEPATH, ELEM_BATCH, ELEM_CALLGRAPH, ELEM_DATABASE, ELEM_DEBUG, ELEM_E4GL, ELEM_ESC, ELEM_INCLUDE_SPEC, ELEM_MARKER, ELEM_MODE, ELEM_OPSYS, ELEM_OUTPUT, ELEM_PREPROC, ELEM_PROPATH, ELEM_ROOTLIST, ELEM_SCHEMA, ELEM_TABLE, ELEM_UAST, ELEM_VAR, ELEM_WINSYS, ELEM_WSOPTIONS, SOURCE_CHARSET
Constructor and Description |
---|
UastHints(java.lang.String sourceName)
Constructs an instance, loads the associated hints file if it exists
and parses the contents.
|
Modifier and Type | Method and Description |
---|---|
private java.lang.String |
containingDirectory(java.io.File file)
Returns the containing directory for the given file or "." if the
file doesn't exist AND ALSO has no pathing included in the original
name.
|
static boolean |
defaultBatch()
Provides a standard way to get the default value for the batch value.
|
static char |
defaultMarker()
Provides a standard way to get the default value for the marker value.
|
static java.lang.String |
defaultOpsys()
Provides a standard way to get the default value for the opsys value.
|
static boolean |
defaultPreprocDebug()
Provides a standard way to get the default value for the preprocessor debug value.
|
static boolean |
defaultUnixEscapes()
Provides a standard way to get the default value for the unix-escapes value.
|
static java.lang.String |
defaultWinsys()
Provides a standard way to get the default value for the winsys value.
|
java.util.List<java.lang.String[]> |
getAliases()
Get the list of aliases (and associated database names) that must be
created in the schema dictionary.
|
java.util.Map<java.lang.String,java.lang.String> |
getArguments()
Get the runtime arguments that must be passed to the preprocessor or
null if no runtime arguments exist. |
java.lang.String[] |
getDatabases()
Get a list of all database names that must be connected before
the ProgressParser can execute.
|
java.lang.String |
getE4GLMode()
Get any override for the E4GL preprocessor's compatibility mode.
|
java.lang.String |
getE4GLOutputFile()
Get any override for the E4GL preprocessor's output file name.
|
java.lang.String |
getIncludeSpec()
Get a file specification of included call-graph files.
|
char |
getMarker()
Gets the character to use for the preprocessor's internal stream/state
synchronization mechanism.
|
java.lang.String |
getOpsys()
Get any override for the preprocessor's OPSYS setting.
|
java.lang.String |
getPathModTxt()
Get the text to use for
PROPATH customization. |
int |
getPathModType()
Get the type code that specifies the file-specific customization that
should be honored for the
PROPATH . |
java.lang.String |
getRootList()
Get the path to a call-graph root list XML file.
|
java.nio.charset.Charset |
getSourceCharset()
Returns the source charset hint value.
|
java.lang.String |
getSourceDir()
Get the parent directory of the source file.
|
java.util.Map<java.lang.String,TableHints> |
getTableHints()
Get an unmodifiable map of schema table hints, keyed by table name.
|
java.lang.Boolean |
getUastBoolean(java.lang.String key)
Get a UAST hint using a uniquely named key, accessing a boolean or
null if no such hint exists. |
java.lang.Double |
getUastDouble(java.lang.String key)
Get a UAST hint using a uniquely named key, accessing a double or
null if no such hint exists. |
java.lang.String[] |
getUastHints(java.lang.String prefix)
Get all the hint keys which have the specified prefix.
|
java.lang.Long |
getUastLong(java.lang.String key)
Get a UAST hint using a uniquely named key, accessing a long or
null if no such hint exists. |
java.lang.String |
getUastString(java.lang.String key)
Get a UAST hint using a uniquely named key, accessing a string or
null if no such hint exists. |
java.lang.String[] |
getUastStringArray(java.lang.String key)
Get a UAST hint using a uniquely named key, accessing a string array or
null if no such hint exists. |
java.lang.String |
getUastType(java.lang.String key)
Get the Java class name for a UAST hint using a uniquely named key,
or
null if no such hint exists. |
Variable[] |
getVariables()
Get a list of all variables and widgets that must be added to the
variable and widget dictionaries before the ProgressParser can execute.
|
java.lang.String |
getWindowSystem()
Get any override for the preprocessor's WINDOW-SYSTEM setting.
|
java.lang.String |
getWSOptions()
Get any override for the E4GL preprocessor's WSOPTIONS setting.
|
private void |
initPaths(java.io.File hints)
Initialize the base path and source path for this file.
|
boolean |
isBatchMode()
Gets the preprocessor's BATCH-MODE setting.
|
boolean |
isFieldEscaped(java.lang.String table,
java.lang.String field)
Checks if field should be escaped.
|
boolean |
isPreprocDebug()
Gets the preprocessor's debug flag.
|
boolean |
isSchemaEscaped()
Report whether the database schema name for this schema should be escaped.
|
boolean |
isTableEscaped(java.lang.String table)
Checks if table should be escaped.
|
boolean |
isTableReadOnly(java.lang.String table)
Checks if table is read-inly.
|
boolean |
isUastHint(java.lang.String key)
Checks if a UAST hint exists under a uniquely named key.
|
boolean |
isUnixEscapes()
Gets the preprocessor's escape sequence setting.
|
private void |
loadHints(java.io.File hintsFile)
Load UAST hints from an XML document associated with the specified
filename.
|
private void |
readAliases(org.w3c.dom.Element root)
Read XML hints file and create a list of string arrays (each with
2 elements) representing the set of all alias names and the associated
database name for each one.
|
private void |
readCallGraph(org.w3c.dom.Element root)
Read XML hints file and create a string representing the encoded
runtime preprocessor arguments and other preprocessor hints.
|
private void |
readDatabases(org.w3c.dom.Element root)
Read XML hints file and create a list of all databases to be connected.
|
private void |
readE4GL(org.w3c.dom.Element root)
Read XML hints file and create a string representing the encoded
E4GL preprocessor hints.
|
private void |
readPathMod(org.w3c.dom.Element root)
Read XML hints file and initialize the path modification members based
on the first
propath node found. |
private void |
readPreproc(org.w3c.dom.Element root)
Read XML hints file and create a string representing the encoded
runtime preprocessor arguments and other preprocessor hints.
|
private void |
readSchemaTables(org.w3c.dom.Element root)
Process sub-hierarchy which contains schema-related hints, if any.
|
private void |
readUastGeneric(org.w3c.dom.Element root)
Read XML hints file and create a map of objects representing the set of
all generic UAST hints, each element accessed by a unique name.
|
private void |
readVariables(org.w3c.dom.Element root)
Read XML hints file and create an array of
Variable
objects representing the set of all variables/widgets to add to the
associated dictionaries. |
private java.util.Iterator<java.lang.String> |
walkDirectoryTree()
Provides an iterator that allows one to walk downward through each
containing path of the current file, from less nested to more nested.
|
public static final int PATH_MOD_NONE
public static final int PATH_MOD_REPLACE
public static final int PATH_MOD_PREPEND
public static final int PATH_MOD_APPEND
public static final int PATH_MOD_DYN_PREPEND
public static final int PATH_MOD_DYN_APPEND
public static final java.lang.String HINTS_SUFFIX
public static final java.lang.String DIR_HINTS
private java.lang.String[] databases
private java.util.Map<java.lang.String,java.lang.String> arguments
private boolean unixEscapes
true
.private char marker
private boolean batch
private java.lang.String opsys
private java.lang.String winsys
private boolean preprocDebug
private java.lang.String wsoptions
private java.lang.String mode
private java.lang.String output
private java.util.ArrayList<java.lang.String[]> aliases
private Variable[] variables
private java.lang.Boolean escaped
private java.util.Map<java.lang.String,TableHints> tableHints
private java.lang.String rootList
private java.lang.String includeSpec
private java.util.Map<java.lang.String,java.lang.Object> uast
private int pathModType
private java.lang.String pathModTxt
private java.lang.String sourceDir
private java.lang.String basePath
private java.nio.charset.Charset sourceCharset
public UastHints(java.lang.String sourceName)
sourceName
- The Progress 4GL source program's filename with which this
hints file is associated.public static boolean defaultUnixEscapes()
true
if UNIX escapes should be honored.public static char defaultMarker()
public static boolean defaultBatch()
true
if batch mode is active in the preprocessor.public static boolean defaultPreprocDebug()
true
if debug mode is active in the preprocessor.public static java.lang.String defaultOpsys()
public static java.lang.String defaultWinsys()
public java.lang.String[] getDatabases()
null
if only the
default databases are required.public java.util.List<java.lang.String[]> getAliases()
null
if no aliases are
required.public Variable[] getVariables()
null
if no variables need
to be added.public int getPathModType()
PROPATH
. One of the well known
(public) constants of this class will be returned.public java.lang.String getPathModTxt()
PROPATH
customization.PROPATH
or if no replacement text was explicitly
specified, then the parent directory of the associated
source file will be returned.public java.lang.String getSourceDir()
public java.util.Map<java.lang.String,java.lang.String> getArguments()
null
if no runtime arguments exist.null
if no arguments
are required.public boolean isUnixEscapes()
true
if the preprocessor should honor UNIX
escape sequences (backslash).public char getMarker()
'\001'
if no
marker has been specified.public boolean isBatchMode()
true
if the preprocessor should be in batch mode.public java.lang.String getOpsys()
null
if not specified.public java.lang.String getWindowSystem()
null
if not specified.public boolean isPreprocDebug()
true
if the preprocessor should be in debug mode.public java.lang.String getWSOptions()
null
if not specified.public java.lang.String getE4GLMode()
null
if not specified.public java.lang.String getE4GLOutputFile()
null
if not specified.public java.util.Map<java.lang.String,TableHints> getTableHints()
null
if none have
been defined in the current hints file.public java.lang.String getRootList()
null
if not defined in hints file.public java.lang.String getIncludeSpec()
null
if not defined in hints file.public java.lang.String getUastString(java.lang.String key)
null
if no such hint exists.key
- Unique name for the hint, which is used as a key.null
.public java.lang.String[] getUastStringArray(java.lang.String key)
null
if no such hint exists.key
- Unique name for the hint, which is used as a key.null
.public java.lang.Long getUastLong(java.lang.String key)
null
if no such hint exists.key
- Unique name for the hint, which is used as a key.null
.public java.lang.Double getUastDouble(java.lang.String key)
null
if no such hint exists.key
- Unique name for the hint, which is used as a key.null
.public java.lang.Boolean getUastBoolean(java.lang.String key)
null
if no such hint exists.key
- Unique name for the hint, which is used as a key.null
.public java.lang.String[] getUastHints(java.lang.String prefix)
prefix
- The key prefix to match.public java.lang.String getUastType(java.lang.String key)
null
if no such hint exists.key
- Unique name for the hint, which is used as a key.null
.public boolean isFieldEscaped(java.lang.String table, java.lang.String field)
table
- The legacy table name.field
- The legacy field name.public boolean isTableEscaped(java.lang.String table)
table
- The legacy table name.public boolean isTableReadOnly(java.lang.String table)
table
- The legacy table name.false
public boolean isSchemaEscaped()
true
if schema name should be escaped, false
if schema
name should not be escaped, null
if attribute "escape" is
set not set for this schema.public boolean isUastHint(java.lang.String key)
key
- Unique name for the hint, which is used as a key.true
if a hint exists under that name.public java.nio.charset.Charset getSourceCharset()
null
when
no charset is explicitly defined in the hint file.private java.lang.String containingDirectory(java.io.File file)
file
- The file object to inspect.private void readDatabases(org.w3c.dom.Element root) throws java.lang.Exception
root
- The root element of the XML document.java.lang.Exception
private void readAliases(org.w3c.dom.Element root) throws java.lang.Exception
root
- The root element of the XML document.java.lang.Exception
private void readVariables(org.w3c.dom.Element root) throws java.lang.Exception
Variable
objects representing the set of all variables/widgets to add to the
associated dictionaries. Note that all variables are always flagged
to be loaded in the global namespace.root
- The root element of the XML document.java.lang.Exception
private void readPathMod(org.w3c.dom.Element root) throws java.lang.Exception
propath
node found.root
- The root element of the XML document.java.lang.Exception
private void readPreproc(org.w3c.dom.Element root) throws java.lang.Exception
root
- The root element of the XML document.java.lang.Exception
private void readSchemaTables(org.w3c.dom.Element root)
TableHints
is created for each table
element parsed within the
schema
section of the document. These are mapped for
later lookup by table name.root
- The root element of the XML document.private void readCallGraph(org.w3c.dom.Element root) throws java.lang.Exception
root
- The root element of the XML document.java.lang.Exception
private void readE4GL(org.w3c.dom.Element root) throws java.lang.Exception
root
- The root element of the XML document.java.lang.Exception
private void readUastGeneric(org.w3c.dom.Element root) throws java.lang.Exception
root
- The root element of the XML document.java.lang.Exception
private void loadHints(java.io.File hintsFile) throws AstException
hintsFile
- The hints file to read.AstException
- An unknown or unexpected failure.private void initPaths(java.io.File hints)
hints
- The file-level hints.private java.util.Iterator<java.lang.String> walkDirectoryTree()