public class ReportApi extends java.lang.Object implements ReportConstants
WebApi
annotation
represent API entry points, using a remote procedure call model. These methods can return
simple Java objects with a bean interface, or lists, maps, or arrays of such objects. Each API
must be annotated with a unique message type via its WebApi
annotation; this type must
match the message type used by the client application when invoking the API call.
This class must be registered with the server before an API call is first made by the client.
This is done with a static initializer in the ReportWebServer
class.
Modifier and Type | Class and Description |
---|---|
private static class |
ReportApi.Coord
This class represents a specific location within a source file, as represented by the line
and column number of a particular character.
|
Modifier and Type | Field and Description |
---|---|
private static AstManager |
astManager
Object used to load ASTs from the file system
|
private java.util.Map<java.lang.Integer,OverviewRow[]> |
cachedMasterResults
Cache of master report results by report/file type, using the current filter profile
|
private static DatabaseService |
dbs
Database services helper object
|
private static long |
defaultFilterId
Default file filter ID to include all files
|
private long |
filterId
Active file filter ID
|
private static int |
MSG_ALL_SOURCE_FILES
API to retrieve the qualified names of all source files
|
private static int |
MSG_BASE
Base message type for all report-specific APIs
|
private static int |
MSG_DEF_FILTER
API to define a new file filter profile
|
private static int |
MSG_DEF_RPT
API to define a new or update an existing report
|
private static int |
MSG_DEL_FILTER
API to delete a file filter profile
|
private static int |
MSG_DEL_RPT
API to delete an existing report
|
private static int |
MSG_DETAIL_RPT
API to retrieve a particular detail report
|
private static int |
MSG_FILT_BASE
Base message type for all filter-specific APIs
|
private static int |
MSG_FILTER_INFO
API to retrieve all file filter profile data and the ID of the active filter
|
private static int |
MSG_FILTER_SPEC
API to retrieve all files specifications for the target filter
|
private static int |
MSG_MST_CODE_RPT
API to retrieve master code report information
|
private static int |
MSG_MST_SCHEMA_RPT
API to retrieve master schema report information
|
private static int |
MSG_RUN_RPT
API to run a single report incrementally
|
private static int |
MSG_SEARCH
API to run search
|
private static int |
MSG_SEARCH_HISTORY
API to retrieve search history for current user
|
private static int |
MSG_SET_FILTER
API to set the active file filter profile
|
private static int |
MSG_SOURCE_DATA
API to retrieve source code and AST data for a specific source file
|
private static int |
MSG_SUMMARY_RPT
API to retrieve a particular summary report
|
private long |
sessionId
Current session ID
|
private static java.lang.String |
sqlDelFileFilter
Delete a filter profile
|
private static java.lang.String |
sqlDelRptResults
Delete results for a single report
|
private static java.lang.String |
sqlDelUsrRpt
Delete a single report
|
private static java.lang.String |
sqlQryAllSrcFiles
Query list of all source file names
|
private static java.lang.String |
sqlQryAllUsers |
private static java.lang.String |
sqlQryAstId
SQL query to get AST ID associated with a file id and source type
|
private static java.lang.String |
sqlQryCustCells
SQL query for a particular custom report's cell data
|
private static java.lang.String |
sqlQryCustCols
SQL query for a particular custom report's column (meta) data
|
private static java.lang.String |
sqlQryDefFileFilter
SQL query to get ID of default file filter
|
private static java.lang.String |
sqlQryDetail
SQL query for a detail report
|
private static java.lang.String |
sqlQryFidsNames
Query all source file ids and names of a certain type
|
private static java.lang.String |
sqlQryFileID
Query the ID of a file record with the given name.
|
private static java.lang.String |
sqlQryFiles
Query all source file names of a certain type
|
private static java.lang.String |
sqlQryFilters
Query all filter profiles
|
private static java.lang.String |
sqlQryFilterSpec
Query list of files specifications for the target filter
|
private static java.lang.String |
sqlQryFltExactFiles
Query all source file names in the specified filter with non-WILD mark.
|
private static java.lang.String |
sqlQryFltFiles
Query all source file names of a certain type, applying active filter
|
private static java.lang.String |
sqlQryFltWildFiles
Query all source file names in the specified filter with WILD mark.
|
private static java.lang.String |
sqlQryMasterAgg
SQL query for master code report using aggregate roll-ups
|
private static java.lang.String |
sqlQryMasterAll
SQL query for master code report using cached statistics, including all source files
|
private static java.lang.String |
sqlQryNonDefFlt |
private static java.lang.String |
sqlQryRptDef
Query a report definition
|
private static java.lang.String |
sqlQrySourceLines
SQL query for all source lines (except marker line 0) for a particular source file
|
private static java.lang.String |
sqlQrySrchHist
Query search history for the current user
|
private static java.lang.String |
sqlQrySummaryStd
SQL query for a standard summary report
|
private static java.lang.String |
sqlQryUser
SQL query to retrieve a user by name
|
private static java.lang.String |
sqlQryUserRptDefs
SQL query to gather user reports of a certain type with their associated tags
|
private static java.lang.String |
sqlUsrPassChg
Update the user table with a new salt, password, and password changed date
|
private static java.lang.String |
sqlUsrSrchHist |
private User |
user
Authenticated user
|
CVT_LVL_BASIC, CVT_LVL_FULL, CVT_LVL_FULL_RESTR, CVT_LVL_MASK, CVT_LVL_NONE, CVT_LVL_PARTIAL, LVL_UNKNOWN, RT_LVL_BASIC, RT_LVL_FULL, RT_LVL_FULL_RESTR, RT_LVL_MASK, RT_LVL_NONE, RT_LVL_PARTIAL, RT_LVL_STUB, RT_LVL_UNTESTED, SORT_ALL, SORT_NONE, SORT_NOT_LAST, SRC_CODE_BASE, SRC_CODE_CACHE, SRC_SCHEMA, SRC_UNKNOWN
Constructor and Description |
---|
ReportApi()
Default constructor.
|
Modifier and Type | Method and Description |
---|---|
java.util.List<java.lang.String> |
allSourceFiles()
Get a list of the names of all source files.
|
private static void |
applyFileFilter(java.sql.Connection conn,
java.lang.Long profileId,
long sessionId)
Apply a file filter to the active session.
|
(package private) Authentication |
authenticate(java.sql.Connection conn,
java.lang.String name,
java.lang.String pass)
Authenticate the given user name and password.
|
(package private) void |
changePassword(java.lang.String name,
java.lang.String oldPass,
java.lang.String newPass1,
java.lang.String newPass2)
Change the given user's password, following some basic conventions for a valid new
password:
it must not be the same as the old password;
it must be at least 6 characters in length;
it must contain at least one letter and one digit.
The user is authenticated with the old password before the password change is allowed.
|
long |
defineFilterProfile(FilterProfile profile,
FileFilter[] filters)
Define a new file filter profile, or update an existing profile.
|
long |
defineReport(ReportDefinition definition,
int srcType)
Define a new report, or update an existing definition.
|
boolean |
deleteFilterProfile(long profileId)
Delete a file filter profile, but only if it is not the default profile.
|
void |
deleteReportDefinition(long reportId)
Delete a single report definition.
|
java.util.List<DetailRow> |
detailReport(long categoryId,
int astType)
Get a list of
DetailRow objects which represent the rows of a detail report for
the specified match category of a report of the given type. |
java.lang.Object[] |
filterProfileInfo()
Get all file filter profile records and the ID of the currently active profile.
|
java.util.List<FileFilter> |
filterSpecInfo(long id)
Get all files specifications for the target filter.
|
private FileList |
gatherFiles(java.sql.Connection conn,
boolean applyFilter,
int srcType)
Gather the full list of filenames of the specified type from the database file map table.
|
(package private) static int |
getFileId(java.lang.String filename)
Get the record ID for the given file in the report database.
|
(package private) static java.util.List<FilterProfile> |
getNonDefaultFilters()
Retrieve a list of all non-default
FilterProfile records, including their file
filter specifications. |
java.util.List<java.lang.String> |
getSearchHistory()
Gather the search history, if any, for the current user.
|
java.lang.Object[] |
getSourceData(long fileId,
long astId,
int sourceType)
Get the source code lines and AST nodes for a particular source file.
|
(package private) static java.util.List<UserRecord> |
getUserRecords()
Retrieve a list of
UserRecord records, each of which holds the details of a user. |
(package private) static java.util.List<ReportDefinition> |
getUserReports(int srcType)
Get a list of all user-defined reports of the given type.
|
(package private) static java.util.List<SearchHistory> |
getUserSearchHistory()
Retrieve a list of
SearchHistory records, each of which holds a search history
record's ID and criteria expression, and one or more user names. |
(package private) static java.util.List<java.lang.String> |
listFilesFromProfile(long id)
List all files in this filter.
|
(package private) Authentication |
logIn(java.lang.String name,
java.lang.String pass,
long sessionId)
Authenticate the given user name and password and log the user in if authentication
succeeds.
|
OverviewRow[] |
masterCodeReport()
Query and return information necessary to produce the master report of overview results
for all code summary reports.
|
private OverviewRow[] |
masterReport(int type)
Query and return information necessary to produce the master report of overview results
for all summary reports of the given type.
|
OverviewRow[] |
masterSchemaReport()
Query and return information necessary to produce the master report of overview results
for all schema summary reports.
|
private void |
persistSearchHistory(java.sql.Connection conn,
java.lang.String criteria)
Persist a (presumably successful) search/report TRPL expression.
|
private java.util.List<AstNode> |
prepareAstNodes(Aast ast)
Flatten an AST into a list of
AstNode objects suitable for marshalling and
transport to the web client. |
void |
runReport(long reportId)
Run a single report in incremental mode.
|
java.lang.Object[] |
runSearch(java.lang.String criteria,
boolean applyFilter,
int srcType)
Run an ad-hoc search of the specified type using the given expression.
|
void |
setFilter(long pid,
boolean force)
Set the active file filter profile.
|
(package private) static void |
shutdownDatabase()
Explicitly shut down the database.
|
private java.lang.String |
stripSchemaName(java.lang.String name)
Given the name of a schema export file AST, strip out the
namespace portion of the
path, and append a .df extension. |
java.lang.Object[] |
summaryReport(long reportId,
int totalMatches,
int totalFiles)
Retrieve information necessary to display a particular summary report.
|
private static final int MSG_BASE
private static final int MSG_FILT_BASE
private static final int MSG_MST_CODE_RPT
private static final int MSG_MST_SCHEMA_RPT
private static final int MSG_SUMMARY_RPT
private static final int MSG_DETAIL_RPT
private static final int MSG_SOURCE_DATA
private static final int MSG_DEF_RPT
private static final int MSG_DEL_RPT
private static final int MSG_RUN_RPT
private static final int MSG_SEARCH
private static final int MSG_SEARCH_HISTORY
private static final int MSG_FILTER_INFO
private static final int MSG_SET_FILTER
private static final int MSG_FILTER_SPEC
private static final int MSG_ALL_SOURCE_FILES
private static final int MSG_DEF_FILTER
private static final int MSG_DEL_FILTER
private static final java.lang.String sqlQryUser
private static final java.lang.String sqlQryDefFileFilter
private static final java.lang.String sqlDelFileFilter
private static final java.lang.String sqlQryUserRptDefs
private static final java.lang.String sqlQryAllUsers
private static final java.lang.String sqlQryNonDefFlt
private static final java.lang.String sqlUsrSrchHist
private static final java.lang.String sqlQryMasterAgg
private static final java.lang.String sqlQryMasterAll
private static final java.lang.String sqlQryCustCols
private static final java.lang.String sqlQryCustCells
private static final java.lang.String sqlQrySummaryStd
private static final java.lang.String sqlQryDetail
private static final java.lang.String sqlQrySourceLines
private static final java.lang.String sqlQryAstId
private static final java.lang.String sqlQryFileID
private static final java.lang.String sqlQryFilters
private static final java.lang.String sqlQryFilterSpec
private static final java.lang.String sqlQryAllSrcFiles
private static final java.lang.String sqlQryRptDef
private static final java.lang.String sqlQryFiles
private static final java.lang.String sqlQryFltWildFiles
private static final java.lang.String sqlQryFltExactFiles
private static final java.lang.String sqlQryFltFiles
private static final java.lang.String sqlQryFidsNames
private static final java.lang.String sqlDelUsrRpt
private static final java.lang.String sqlDelRptResults
private static final java.lang.String sqlUsrPassChg
private static final java.lang.String sqlQrySrchHist
private static final AstManager astManager
private static final DatabaseService dbs
private static final long defaultFilterId
private final java.util.Map<java.lang.Integer,OverviewRow[]> cachedMasterResults
private long sessionId
private User user
private long filterId
static java.util.List<java.lang.String> listFilesFromProfile(long id)
id
- The ID of a filter profile..static int getFileId(java.lang.String filename)
filename
- The filename (as in the FWD registry.xml).static java.util.List<ReportDefinition> getUserReports(int srcType)
srcType
- Type of report (schema or code).ReportDefinition
objects of the given type; may be empty, but will
not be null
.static java.util.List<UserRecord> getUserRecords()
UserRecord
records, each of which holds the details of a user.static java.util.List<FilterProfile> getNonDefaultFilters()
FilterProfile
records, including their file
filter specifications.static java.util.List<SearchHistory> getUserSearchHistory()
SearchHistory
records, each of which holds a search history
record's ID and criteria expression, and one or more user names.static void shutdownDatabase()
DB_CLOSE_ON_EXIT=FALSE
database option to enable our auto-export shutdown hook to run.java.lang.RuntimeException
- if there is an SQL error during shutdown.private static void applyFileFilter(java.sql.Connection conn, java.lang.Long profileId, long sessionId)
The filter works by storing in a global temporary table (active_file
) the primary
keys of records from the file
table which match the selected filter profile. All
regular reports then join their results on the active_file
table to select only
those results which match the set of filtered files for the current session.
conn
- Database connection.profileId
- ID of the filter profile to apply, or null
to apply the default filter.public OverviewRow[] masterCodeReport()
OverviewRow
objects, each providing the high level match
statistics for its associated summary report.public OverviewRow[] masterSchemaReport()
OverviewRow
objects, each providing the high level match
statistics for its associated summary report.public java.lang.Object[] summaryReport(long reportId, int totalMatches, int totalFiles)
reportId
- ID of the summary report for which information is requested.totalMatches
- Total number of matches for this report. Used to calculate match percentages for
individual match categories.totalFiles
- Total number of files for this report. Used to calculate file percentages for
individual match categories.true
if the
report represents a custom report, else false
; the second represents the
report results, either in the form of a CustomReport
object (for a custom
report) or an array of SummaryRow
objects (for a standard report).public java.util.List<DetailRow> detailReport(long categoryId, int astType)
DetailRow
objects which represent the rows of a detail report for
the specified match category of a report of the given type.categoryId
- Unique identifier of a category of detailed report results.astType
- Type of ASTs to retrieve (schema or code).public java.lang.Object[] getSourceData(long fileId, long astId, int sourceType)
fileId
- File ID for the source file.astId
- ID of the root node of the source file's AST. If astId == 0
, an additional
query is executed to determine the AST ID for the given file id and source type.
If astId < 0
, AST node data is not returned.sourceType
- Type of source file (SRC_CODE_CACHE
, SRC_CODE_BASE
, or SRC_SCHEMA
).null
.public java.lang.Object[] filterProfileInfo()
FilterProfile
objects
representing all available filter profiles; the second is the ID of the currently
active profile.public void setFilter(long pid, boolean force)
pid
- The identifier of the filter_profile
to set.force
- True
to force the filter update, even if the filter ID hasn't changed
(presumably the filter definition has been updated).java.lang.RuntimeException
- if pid
is not a valid profile identifier, or if there is any error setting
the active profile.public java.util.List<FileFilter> filterSpecInfo(long id)
id
- The id of the target filterFileFilter
objects representing all files specifications
for the target filter.public java.util.List<java.lang.String> allSourceFiles()
public long defineReport(ReportDefinition definition, int srcType)
TODO: add security check.
definition
- Report definition.srcType
- Type of report (schema or code).public long defineFilterProfile(FilterProfile profile, FileFilter[] filters)
TODO: add security check.
profile
- Report definition.filters
- The filters associated with the profile.public boolean deleteFilterProfile(long profileId)
TODO: synchronize; this method makes changes to the database.
TODO: add security check.
profileId
- ID of the profile to delete.True
if the profile was deleted, else false
.public void deleteReportDefinition(long reportId)
TODO: synchronize; this method makes changes to the database.
TODO: add security check.
reportId
- ID of the report to delete.public void runReport(long reportId)
TODO: synchronize; this method makes changes to the database.
reportId
- ID of the report to be run.public java.lang.Object[] runSearch(java.lang.String criteria, boolean applyFilter, int srcType)
criteria
- TRPL expression which must evaluate to true or false.applyFilter
- True
to apply the current file filter when gathering the list of files to
search; false
to apply the search to all files.srcType
- Type of report (schema or code).public java.util.List<java.lang.String> getSearchHistory()
null
if not tracking search history.
An empty list may be returned.Authentication authenticate(java.sql.Connection conn, java.lang.String name, java.lang.String pass) throws java.security.NoSuchAlgorithmException, java.security.spec.InvalidKeySpecException
conn
- Database connection.name
- User name to authenticate.pass
- Clear text password candidate to authenticate.User
instance which represents the
authenticated user, if authentication was successful; null
if it was not.java.security.NoSuchAlgorithmException
- if the requested encryption algorithm is not available in the current environment.java.security.spec.InvalidKeySpecException
- if the specifications for the cryptographic key are invalid.Authentication logIn(java.lang.String name, java.lang.String pass, long sessionId) throws java.security.NoSuchAlgorithmException, java.security.spec.InvalidKeySpecException
name
- User name to authenticate.pass
- Clear text password candidate to authenticate.User
instance that will be associated
with the current session, if authentication was successful; null
if it was
not.java.security.NoSuchAlgorithmException
- if the requested encryption algorithm is not available in the current environment.java.security.spec.InvalidKeySpecException
- if the specifications for the cryptographic key are invalid.void changePassword(java.lang.String name, java.lang.String oldPass, java.lang.String newPass1, java.lang.String newPass2) throws java.security.NoSuchAlgorithmException, java.security.spec.InvalidKeySpecException
name
- User name.oldPass
- Existing password.newPass1
- New password.newPass2
- Repeat of new password; must be identical to newPass1
.java.security.NoSuchAlgorithmException
- if the requested encryption algorithm is not available in the current environment.java.security.spec.InvalidKeySpecException
- if the specifications for the cryptographic key are invalid.private java.lang.String stripSchemaName(java.lang.String name)
namespace
portion of the
path, and append a .df
extension.name
- Original name.private FileList gatherFiles(java.sql.Connection conn, boolean applyFilter, int srcType) throws java.sql.SQLException
conn
- Database connection.applyFilter
- True
to apply the current file filter when gathering the list of files;
false
to gather all files.srcType
- Type of files (schema or code).java.sql.SQLException
- if there was an error with the database query.private java.util.List<AstNode> prepareAstNodes(Aast ast)
AstNode
objects suitable for marshalling and
transport to the web client. A large, hierarchical AST structure does not marshall well
over Jackson (results in StackOverflowException
due to recursion), so we create
a flat list of simplified beans instead.
Also compute additional information during this process needed by the web client, such as effective starting and ending line and column numbers.
ast
- AST to be marshalled.AstNode
objects, one per node in the original tree.private OverviewRow[] masterReport(int type)
type
- Type of reports (SRC_CODE_CACHE
or SRC_SCHEMA
).OverviewRow
objects, each providing the high level match
statistics for its associated summary report.private void persistSearchHistory(java.sql.Connection conn, java.lang.String criteria) throws java.sql.SQLException
conn
- Database connection.criteria
- TRPL expression to be persisted.java.sql.SQLException
- if a database error occurs.