com.goldencode.ast

Class BasePlugin

java.lang.Object

com.goldencode.ast.BasePlugin

All Implemented Interfaces:

AstManagerPlugin

Direct Known Subclasses:

InMemoryRegistryPlugin, XmlFilePlugin

public abstract class BasePlugin
extends java.lang.Object
implements AstManagerPlugin

Abstract base class for plugins which provides a common implementation for features which are not related to the state persistence mechanism.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	BasePlugin.Pair Simple container class to store the next available ID for a tree, the associated tree name and whether it was part of the original set of source files.

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	dirty Records if any changes have been made since the registry was read.
protected java.util.Map<java.lang.Long,BasePlugin.Pair>	fids Stores the ID to tree name mapping information.
protected java.util.Map<java.lang.String,java.lang.Long>	fnames Stores the tree name to ID mapping information.
protected static int	HIGH_BITS Number of bits to shift to make a file ID a normal int.
protected java.util.Map<java.lang.Long,java.util.concurrent.locks.ReentrantLock>	locklist Stores the tree name to lock mapping information.
protected static long	MAX_POSSIBLE Specifies the maximum possible number of files in the registry.
protected static long	TREE_MASK Allows easy removal of the node ID bits in an AST ID.

Constructor Summary

Constructors

Constructor and Description
BasePlugin()

Method Summary

Modifier and Type	Method and Description
long	addTree(java.lang.String name) Adds a mapping from the specified AST to a new ID.
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.
protected boolean	isInvalid(long id) Detects if the given ID is invalid.
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	setFlags(long id, long flags) Sets a flag (or a or combination of them) for a specific tree.
protected void	setNextNodeId(long treeId, long nodeId) Set the next unassigned AST node ID for the specified 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? This method returns false by default; subclasses should override as necessary.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.goldencode.ast.AstManagerPlugin

dom2string, isExistingAst, loadTree, save, saveTree

Field Detail

TREE_MASK

protected static final long TREE_MASK

Allows easy removal of the node ID bits in an AST ID.

See Also:

Constant Field Values

HIGH_BITS

protected static final int HIGH_BITS

Number of bits to shift to make a file ID a normal int.

See Also:

Constant Field Values

MAX_POSSIBLE

protected static final long MAX_POSSIBLE

Specifies the maximum possible number of files in the registry.

See Also:

Constant Field Values

fnames

protected java.util.Map<java.lang.String,java.lang.Long> fnames

Stores the tree name to ID mapping information.

fids

protected java.util.Map<java.lang.Long,BasePlugin.Pair> fids

Stores the ID to tree name mapping information.

locklist

protected java.util.Map<java.lang.Long,java.util.concurrent.locks.ReentrantLock> locklist

Stores the tree name to lock mapping information.

dirty

protected boolean dirty

Records if any changes have been made since the registry was read.

Constructor Detail

BasePlugin

public BasePlugin()

Method Detail

usesMemoryStorage

public boolean usesMemoryStorage()

Does this plug-in use memory as its primary storage medium? This method returns false by default; subclasses should override as necessary.

Specified by:

usesMemoryStorage in interface AstManagerPlugin

Returns:

false.

getTreeName

public java.lang.String getTreeName(long id)

Lookup the name associated with the tree specified by this ID. The ID can be a tree ID (an ID that represents an entire AST) or it can be the ID an individual AST node ID. Node IDs encode the tree ID and a portion that is node-specific. The node-specific portion will be ignored.

Specified by:

getTreeName in interface AstManagerPlugin

Parameters:

id - The ID to use as a key in the lookup. This ID may be a tree ID or a specific node ID.

Returns:

The name associated with the tree or null if no such tree ID exists.

getTreeId

public long getTreeId(java.lang.String name)

Reverse lookup of the ID that corresponds to a given AST name.

Specified by:

getTreeId in interface AstManagerPlugin

Parameters:

name - Tree name whose unique ID should be returned.

Returns:

The tree ID associated with the name or AstManager.INVALID_ID if the tree name doesn't exist or is null.

getTreeId

public long getTreeId(long id)

Returns the tree ID portion of a node ID.

Specified by:

getTreeId in interface AstManagerPlugin

Parameters:

id - The ID to use as a key in the lookup. This ID may be a tree ID or a specific node ID.

Returns:

The ID which corresponds to the tree itself, with all node ID portions removed (masked off) or AstManager.INVALID_ID if the ID is invalid.

lockTree

public void lockTree(long id)
              throws java.lang.InterruptedException,
                     java.lang.IllegalArgumentException

Obtains a process-wide lock on any processing related to the given tree. If the lock is already held, this method will block until it obtains the lock. When this method returns normally, the calling thread is guaranteed to be holding the lock. This may be called recursively by the same thread and if the current thread is already holding the lock, then this method will only update the reference count for the lock but otherwise it will immediately return. As a consequence, the lock will not be released unless 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.

Specified by:

lockTree in interface AstManagerPlugin

Parameters:

id - Tree ID that is associated with the lock.

Throws:

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.

unlockTree

public void unlockTree(long id)
                throws java.lang.IllegalMonitorStateException,
                       java.lang.IllegalArgumentException

Releases the process-wide lock on any processing related to the given tree. If the lock is already held by the calling thread, this method will decrement the reference count. If the resulting reference count is 0, the lock will be released. If the calling thread does not hold the lock, this method will exit abnormally. This may be called recursively by the same thread and must be called the same number of times as the 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.

Specified by:

unlockTree in interface AstManagerPlugin

Parameters:

id - Tree ID that is associated with the lock.

Throws:

java.lang.IllegalMonitorStateException - If the calling thread does not own the lock.

java.lang.IllegalArgumentException - If the ID is not a valid tree ID.

getNextNodeId

public long getNextNodeId(long id)
                   throws AstException

Access the next unassigned node ID for the specified tree. The value is looked up and returned, just before returning the internal cache is incremented and stored back for next use. Once this value is returned, it is considered "used" and will not be returned again.

Specified by:

getNextNodeId in interface AstManagerPlugin

Parameters:

id - The ID that specifies a tree.

Returns:

The newly assigned node ID or AstManager.INVALID_ID if no such tree exists.

Throws:

AstException - If too many AST nodes exist.

resetNextNodeId

public void resetNextNodeId(long treeId)
                     throws AstException

Resets the next unassigned AST node ID for the specified tree to the first possible value (tree ID + 1).

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!

Specified by:

resetNextNodeId in interface AstManagerPlugin

Parameters:

treeId - The ID that specifies a valid tree.

Throws:

AstException - If the file ID is invalid.

addTree

public long addTree(java.lang.String name)
             throws AstException

Adds a mapping from the specified AST to a new ID. The next available tree ID is assigned and this mapping is added to the registry. If the tree name already exists, the existing tree ID is returned.

Specified by:

addTree in interface AstManagerPlugin

Parameters:

name - The tree name. Often this will be the name of a file.

Returns:

The assigned tree ID.

Throws:

AstException - If too many ASTs exist in the registry or if the input name is null.

removeTree

public boolean removeTree(long id)
                   throws AstException

Removes all mapping data referencing the specified tree.

Specified by:

removeTree in interface AstManagerPlugin

Parameters:

id - The ID the tree to remove.

Returns:

true if the tree existed in the registry (and was removed), false if the tree didn't exist.

Throws:

AstException

setNextNodeId

protected void setNextNodeId(long treeId,
                             long nodeId)
                      throws AstException

Set the next unassigned AST node ID for the specified tree.

WARNING: there is no check on the validity of this new value, if AST nodes exist with IDs at or above this value, duplicate IDs may result!

Parameters:

treeId - The ID that specifies a tree.

nodeId - The ID used for the next node ID.

Throws:

AstException - If the any input is invalid.

isInvalid

protected boolean isInvalid(long id)

Detects if the given ID is invalid. An ID is invalid if it is equivalent to the AstManager.INVALID_ID or if the tree portion does not match a registered tree.

Parameters:

id - The tree or node ID to test.

Returns:

true if the ID is not valid.

setFlags

public void setFlags(long id,
                     long flags)

Sets a flag (or a or combination of them) for a specific tree.

Specified by:

setFlags in interface AstManagerPlugin

Parameters:

id - The id of the tree.

flags - A flag (or combination of them) to be set.

getFiles

public java.lang.String[] getFiles(long flags)

Obtain an array of String representing the files which have a set of flags set.

Specified by:

getFiles in interface AstManagerPlugin

Parameters:

flags - The flags which the files should have set to be filtered.

Returns:

An array of String representing the original source files which have the flags set.