public interface AstManagerPlugin
AstManager
plugin that implements
services for creating, deleting, editing and using Abstract Syntax Trees
(ASTs). The use of the term AST (by itself) refers to the entire tree. To
refer to a single node of the tree, the term "AST node" or "node" is used.
At the core of these services is the idea that a database or registry of trees exists.
Maintains a project-specific bidirectional indexing facility for mapping ASTs to project-unique IDs. Given a 64-bit unique ID, one can lookup the specific AST name that is associated with that ID. Likewise, given an AST name, one can obtain the 64-bit unique ID. In addition, this class tracks the next available 64-bit node ID for each tree.
A long
is used to store and represent the 64-bit IDs. These
64-bit IDs are 'partitioned' into an upper DWORD (32-bit unsigned value) and
a lower DWORD. The upper DWORD is associated with the name that is the source
of a given AST. Each tree name in a project will have a unique upper DWORD
that is assigned when the tree is added to the registry using the
addTree(java.lang.String)
method. All AST nodes in the tree created from/for that
tree will share the same upper DWORD. This upper DWORD is called the
'tree portion' of the ID. A 'tree ID' is an ID with the lower DWORD set
to 0x00000000 and the upper DWORD set to the tree portion of the specific
tree being referenced. The lower DWORD holds a value that is unique to
each AST node in that tree. This lower DWORD is called the 'node portion'
of the ID. When a node portion is combined with the tree portion of an
ID, the result is a 64-bit ID that uniquely identifies a specific AST node
in a specific tree. For this reason, such IDs can be used as persistent
references between ASTs in different trees or even between AST nodes in
the same tree.
An ID of 0xFFFFFFFFFFFFFFFF is invalid and is the equivalent to a
null
ID. Similarly, a tree ID (which by definition has a
a lower DWORD of 0x00000000) can never refer to a specific node and only
refers to a tree (to the entire tree rather than any given node of that
tree).
This class provides the assignment facility for obtaining unique tree IDs
as well as unique node IDs (see getNextNodeId(long)
).
Name lookups are done on a case sensitive basis.
To facilitate multi-threaded applications, a tree level locking facility
is provided. lockTree(long)
and unlockTree(long)
provide a mechanism
to obtain and release this lock respectively. This locking has nothing to
do with file system locks nor is there any non-Java locking backing this
lock. Rather, this lock is a cooperative agreement between all callers
that no use of the given tree will be made except when the caller holds
this exclusive lock to the tree.
Modifier and Type | Method and Description |
---|---|
long |
addTree(java.lang.String name)
Adds a mapping from the specified AST to a new ID.
|
static java.lang.String |
dom2string(org.w3c.dom.Node node)
Convert DOM Node to the formatted string.
|
default java.lang.String[] |
getFiles(long flags)
Obtain an array of
String representing the files which have a set of flags set. |
long |
getNextNodeId(long id)
Access the next unassigned node ID for the specified tree.
|
long |
getTreeId(long id)
Returns the tree ID portion of a node ID.
|
long |
getTreeId(java.lang.String name)
Reverse lookup of the ID that corresponds to a given AST name.
|
java.lang.String |
getTreeName(long id)
Lookup the name associated with the tree specified by this ID.
|
boolean |
isExistingAst(java.lang.String name)
Check if the AST specified by the given name exists already in the plugin's storage.
|
Aast |
loadTree(java.lang.String name)
Load a named AST from persistent storage.
|
void |
lockTree(long id)
Obtains a process-wide lock on any processing related to the given tree.
|
boolean |
removeTree(long id)
Removes all mapping data referencing the specified tree.
|
void |
resetNextNodeId(long treeId)
Resets the next unassigned AST node ID for the specified tree to the
first possible value (tree ID + 1).
|
void |
save()
Persistently store the current state of the AST manager plugin.
|
void |
saveTree(Aast ast,
java.lang.String name,
boolean terse)
Save the given AST to persistent storage under the given name.
|
default void |
setFlags(long id,
long flags)
Sets a flag (or a
or combination of them) for a specific tree. |
void |
unlockTree(long id)
Releases the process-wide lock on any processing related to the given
tree.
|
boolean |
usesMemoryStorage()
Does this plug-in use memory as its primary storage medium?
|
boolean usesMemoryStorage()
true
if ASTs are stored primarily in memory, else false
.java.lang.String getTreeName(long id)
id
- The ID to use as a key in the lookup. This ID may be a tree ID
or a specific node ID.null
if no such tree ID exists.long getTreeId(java.lang.String name)
name
- Tree name whose unique ID should be returned.AstManager.INVALID_ID
if the tree name doesn't
exist or if it is null
.long getTreeId(long id)
id
- The ID to use as a key in the lookup. This ID may be a tree ID or a specific node ID.AstManager.INVALID_ID
if the ID is invalid.Aast loadTree(java.lang.String name) throws AstException, java.lang.IllegalArgumentException
name
- The name of the tree. Often this is a file name.AstException
- On any error during the loading process.java.lang.IllegalArgumentException
- If the name is invalid or the specified resource doesn't exist.void saveTree(Aast ast, java.lang.String name, boolean terse) throws AstException, java.lang.IllegalArgumentException
ast
- The tree to save.name
- The name of the tree. Often this is a file name.terse
- Do not store line and column data when the node data is saved.AstException
- On any error during the saving process.java.lang.IllegalArgumentException
- If the name is invalid or the specified resource cannot be used as a target to store the AST.void lockTree(long id) throws java.lang.InterruptedException, java.lang.IllegalArgumentException
unlockTree(long)
is called the same number of times
as this lock method. Thus, the calls to this lock method and to
unlock
must always be balanced.
This locking has nothing to do with file system locks nor is there any non-Java locking backing this lock. Rather, this lock is a cooperative agreement between all callers (within the same JVM) that no use of the given tree will be made except when the caller holds this exclusive lock to the resource.
id
- Tree ID that is associated with the lock.java.lang.InterruptedException
- When an interruption occurs during blocking for the lock. If
this is thrown, the caller will NOT be holding the lock.java.lang.IllegalArgumentException
- If the ID is not a valid tree ID.void unlockTree(long id) throws java.lang.IllegalMonitorStateException, java.lang.IllegalArgumentException
lockTree(long)
method. Thus, the calls to this unlock method must always
be balanced with calls to this method.
This locking has nothing to do with file system locks nor is there any non-Java locking backing this lock. Rather, this lock is a cooperative agreement between all callers (within the same JVM) that no use of the given tree will be made except when the caller holds this exclusive lock to the resource.
id
- Tree ID that is associated with the lock.java.lang.IllegalMonitorStateException
- If the calling thread does not own the lock.java.lang.IllegalArgumentException
- If the ID is not a valid tree ID.long getNextNodeId(long id) throws AstException
id
- The ID that specifies a tree.AstManager.INVALID_ID
if
no such tree exists.AstException
- If too many AST nodes exist.void resetNextNodeId(long treeId) throws AstException
WARNING: there is no check on the current usage of node IDs for this file, so if AST nodes exist already they will have IDs at or above this value and duplicate IDs may (probably will) result!
treeId
- The ID that specifies a valid tree.AstException
- If the file ID is invalid.long addTree(java.lang.String name) throws AstException
name
- The tree name. Often this will be the name of a file.AstException
- If too many ASTs exist in the registry or if the input name is null
.boolean removeTree(long id) throws AstException
id
- The ID the tree to remove.true
if the tree existed in the registry (and was removed),
false
if the tree didn't exist.AstException
void save() throws AstException
AstException
- On any failure.boolean isExistingAst(java.lang.String name)
name
- The name (including path) of the AST file to be checked.true
if the specified AST is in the plugin's storage.default void setFlags(long id, long flags)
or
combination of them) for a specific tree.id
- The id
of the tree.flags
- A flag (or combination of them) to be set.default java.lang.String[] getFiles(long flags)
String
representing the files which have a set of flags set.flags
- The flags which the files should have set to be filtered.String
representing the original source files which have the flags set.static java.lang.String dom2string(org.w3c.dom.Node node)
node
- Node to be formatted.