com.joanju.cg.api
Class CgAPI

java.lang.Object
  com.joanju.cg.api.CgAPI

public class CgAPI
extends java.lang.Object

This is the public API to Joanju Callgraph. You may create an instance or use the default instance.

The only part of the API that triggers a refresh to the Callgraph database is the buildOrRefresh() function. Everything else treats the database as "read only".

Database location note: Joanju Callgraph uses the Eclipse API plugin.getStateLocation() in order to set the database location. If there is no Eclipse workbench, then "callgraphdb" in the context directory is used. For unit tests, that's just the "./" working directory. As a servlet in a container like Tomcat, that's the directory that Callgraph itself was installed into.

See Also:

getDefault(), buildOrRefresh(java.lang.String, java.io.File)

Constructor Summary

CgAPI()

Method Summary

void	buildIfNecessary(ParseUnit pu) Performs build/refresh on a parse unit only if it hasn't been built or is stale.
void	buildOrRefresh(java.lang.String projectName, java.util.Collection<java.io.File> compileUnitSourceFiles) Same as buildOrRefresh(String, File), but for a collection of files.
void	buildOrRefresh(java.lang.String projectName, java.io.File compileUnitSourceFile) Build or refresh the database for a given compile unit's source file.
static int	findOnPropathGetID(java.lang.String filename) Find a file on PROPATH and return a string ID for it.
static int[]	generateFileIndex(ParseUnit parseUnit) The filenames from the Callgraph API are lowercased canonical, but the ones we get from the ParseUnit are not.
java.util.ArrayList<CallSite>	getCallSites(java.io.File file) Get the list of call sites found in a compile unit.
static CgAPI	getDefault() Get a default instance of this API.
java.util.ArrayList<Procedure>	getProcedures(java.io.File file) Get the list of procedures found in a compile unit.
int	lookupStringID(java.lang.String string) Lookup a unique integer ID for a given string.
java.lang.String	lookupStringValue(int id) Lookup the string value for a unique integer ID.
void	updateCuFileTable() Update the table of compile unit files for the current project.
void	updateCuFileTable(java.lang.String projectname) Update the table of compile unit files for the input project name.

Methods inherited from class java.lang.Object

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

Constructor Detail

CgAPI

public CgAPI()

See Also:

getDefault()

Method Detail

buildIfNecessary

public void buildIfNecessary(ParseUnit pu)
                      throws java.lang.Exception

Performs build/refresh on a parse unit only if it hasn't been built or is stale. Xref tables are also checked, which may take a long time if a previous build/refresh was interrupted. The PUB file has to have been loaded or built before calling this.

Throws:

java.lang.Exception

buildOrRefresh

public void buildOrRefresh(java.lang.String projectName,
                           java.io.File compileUnitSourceFile)
                    throws java.lang.Exception

Build or refresh the database for a given compile unit's source file. An appropriate project name (as configured in Eclipse) must be input. For example, you might use org.eclipse.core.resources.IResource.getProject().getName() to find the currently selected project name.

ProRefactor's project settings - especially PROPATH and schema names - must be configured.

Throws:

java.lang.Exception

buildOrRefresh

public void buildOrRefresh(java.lang.String projectName,
                           java.util.Collection<java.io.File> compileUnitSourceFiles)
                    throws java.lang.Exception

Same as buildOrRefresh(String, File), but for a collection of files.

Throws:

java.lang.Exception

See Also:

buildOrRefresh(String, File)

findOnPropathGetID

public static int findOnPropathGetID(java.lang.String filename)
                              throws java.sql.SQLException,
                                     java.io.IOException

Find a file on PROPATH and return a string ID for it. The returned int ID would be the CUID if the file is compilable. Uses the OS to find the file on the propath, so it is case-sensitve on unix.

Returns:

0 if no such file found on PROPATH.

Throws:

java.io.IOException - if getCanonicalPath fails

java.sql.SQLException - if the database access fails

generateFileIndex

public static int[] generateFileIndex(ParseUnit parseUnit)
                               throws java.lang.Exception

The filenames from the Callgraph API are lowercased canonical, but the ones we get from the ParseUnit are not. Here we build a mapping from JPNode.getFileIndex() to CallSite.getSourceFileID(). The int[] returned here corresponds to the int[] returned from parseUnit.getFileIndex().

Throws:

java.lang.Exception

See Also:

lookupStringValue(int)

getCallSites

public java.util.ArrayList<CallSite> getCallSites(java.io.File file)
                                           throws java.sql.SQLException,
                                                  java.io.IOException

Get the list of call sites found in a compile unit. Call sites are RUN statements, references to user defined functions, etc. The list is sorted by internal instruction address.

Parameters:

file - Can be fully qualified, or else must be found on the current project's path.

Returns:

null if there is no record of the compile unit in Joanju Callgraph.

Throws:

java.io.IOException

java.sql.SQLException

getDefault

public static CgAPI getDefault()

Get a default instance of this API. The API caches some information about each compile unit it processes. If you are examining multiple compile units at once, then it may be more efficient to work with multiple instances of the API. Otherwise, just using the default instance is fine.

getProcedures

public java.util.ArrayList<Procedure> getProcedures(java.io.File file)
                                             throws java.sql.SQLException,
                                                    java.io.IOException

Get the list of procedures found in a compile unit. Procedures are internal procedures, user defined functions, etc. If the compile unit has no internal functions or procedures, then the list of procedures returned will contain a single procedure for the main program block, with the procedures name being an empty string "". The list is sorted by internal instruction address.

Parameters:

file - Can be fully qualified, or else must be found on the current project's path.

Returns:

null if there is no record of the compile unit in Joanju Callgraph.

Throws:

java.io.IOException

java.sql.SQLException

lookupStringID

public int lookupStringID(java.lang.String string)
                   throws java.sql.SQLException

Lookup a unique integer ID for a given string. This ID is persistent as long as the database is not cleared.

Returns:

Zero if the string is not in the strings table.

Throws:

java.sql.SQLException

lookupStringValue

public java.lang.String lookupStringValue(int id)
                                   throws java.sql.SQLException

Lookup the string value for a unique integer ID. This ID is persistent as long as the database is not cleared.

Returns:

null if the string is not in the strings table.

Throws:

java.sql.SQLException

updateCuFileTable

public void updateCuFileTable()
                       throws java.lang.Exception

Update the table of compile unit files for the current project. This table has to be up to date for calls to external procedures to be resolved. Just does: new CuFilenamesBuilder().run();.

Throws:

java.lang.Exception

See Also:

CuFileTable

updateCuFileTable

public void updateCuFileTable(java.lang.String projectname)
                       throws java.lang.Exception

Update the table of compile unit files for the input project name. This table has to be up to date for calls to external procedures to be resolved.

Throws:

java.lang.Exception

See Also:

CuFileTable