oracle.jdeveloper.audit.service

Class Auditor

java.lang.Object

oracle.jdeveloper.audit.service.Auditor

Direct Known Subclasses:

DefaultAuditor

public abstract class Auditor
extends java.lang.Object

The executor of an audit over a particular set of constructs using a particular profile. The profile supplies the analyzers for the audit and is set by setProfile(oracle.jdeveloper.audit.service.Profile). The constructs audited are those added to this auditor by addElement(oracle.ide.model.Element, oracle.ide.model.Node, oracle.ide.model.Project, oracle.ide.model.Workspace), and/or addConstruct(java.lang.Object, java.net.URL, oracle.ide.model.Project, oracle.ide.model.Workspace). The audit is executed by run(), which invokes the visitor methods of the analyzers and delivers the results they produce to the listeners registered with addAuditListener(oracle.jdeveloper.audit.service.AuditListener). When the results are no longer needed, resources held by the auditor are released by clear().

An auditor can be reused: locations to be audited can be added and removed.

Constructor Summary

Constructors

Constructor and Description
Auditor()

Method Summary

Methods

Modifier and Type	Method and Description
abstract void	addAuditListener(AuditListener listener) Adds an audit listener to this auditor.
abstract boolean	addConstruct(java.lang.Object construct, java.net.URL file, Project project, Workspace workspace) Adds the location corresponding to a construct to the set of locations to be audited.
abstract boolean	addElement(Element element, Node node, Project project, Workspace workspace) Adds the location corresponding to an Element to the set of locations to be audited.
abstract boolean	addElements(Element[] elements, Node node, Project project, Workspace workspace) Adds the locations corresponding to an array of Elements in a Node to the set of locations to be audited.
abstract boolean	addNode(Node node, Project project, Workspace workspace) Adds the location corresponding to a Node to the set of locations to be audited.
abstract boolean	addUrl(java.net.URL url, Project project, Workspace workspace) Adds the location corresponding to a URL to the set of locations to be audited.
abstract java.lang.Throwable	applyDefaultTransforms(java.lang.String label) Audits the locations of this auditor in the current thread and applies all default transforms (see Transformer.applyDefaultTransforms(java.lang.String, java.util.Collection<? extends oracle.jdeveloper.audit.service.Violation>, oracle.jdeveloper.audit.service.TransformerListener, oracle.jdeveloper.audit.service.AuditModel).
abstract void	audit() Audits the locations of this auditor in the current thread.
abstract boolean	cancel() Cancel an executing audit.
abstract void	clear() Clears the results and locations from this auditor.
abstract ModelFactory	getFactory() Gets the factory used to create the models to be audited.
abstract IntersectedFilters	getFileFilters() Gets the supplemental filters to use when filtering application content, projects, and project content.
abstract long	getMaximumFileSize() Gets the size of the largest file that can be audited, in Mb.
abstract Profile	getProfile() Gets the profile for this audit.
abstract WorkingSet	getWorkingSet() Gets the working set to use when filtering projects and project content.
abstract boolean	isAuditable(Element element, Node node, Project project, Workspace workspace) Gets whether an Element is auditable.
abstract boolean	isAuditableType(java.net.URL url) Gets whether the element at an URL is of an auditable type.
abstract boolean	isAuditing() Gets whether an audit is in progress.
abstract boolean	isCancelled() Gets whether an audit in progress has been cancelled.
abstract boolean	isIgnoreAssists() Gets whether to ignore issues corresponding to assists (severity ASSIST).
abstract boolean	isVisitAncestors() Gets whether to visit ancestors of the locations to be audited.
abstract boolean	isVisitDescendants() Gets whether to visit descendants of the locations to be audited.
abstract void	removeAuditListener(AuditListener listener) Removes an audit listener from this auditor.
abstract void	run() Audits the locations of this auditor in the current thread.
abstract void	runAsynchronously() Audits the locations of this auditor in a background thread.
abstract void	runAsynchronously(java.lang.Thread.UncaughtExceptionHandler handler) Audits the locations of this auditor in a background thread.
abstract void	setAttribute(java.lang.Object key, java.lang.Object value) Sets a configuration attribute for this auditor.
abstract void	setDependencyCollector(CompositeDependency collector) Sets the collector of dependencies discovered when the audit is run, or null.
abstract void	setFileFilters(IntersectedFilters filters) Sets the supplemental filters to use when filtering application content, projects, and project content.
abstract void	setIgnoreAssists(boolean enabled) Sets whether to ignore issues corresponding to assists (severity ASSIST).
abstract void	setMaximumFileSize(long size) Sets the size of the largest auditable file.
abstract void	setProfile(Profile profile) Sets the profile for this audit.
abstract void	setVisitAncestors(boolean shallow) Sets whether to visit ancestors of the locations to be audited.
abstract void	setVisitDescendants(boolean shallow) Sets whether to visit descendants of the locations to be audited.
abstract void	setWorkingSet(WorkingSet workingSet) Sets the working set to use when filtering projects and project content.
abstract void	setWriteLockRequestListener(WriteLockRequestListener listener) Sets the listener to notify if a thread waits to acquire the write lock.
abstract void	throwIfCancelled() Throw CancellationException if the last audit to execute was cancelled.
abstract void	tryAudit() Audits the locations of this auditor in the current thread if the models for those locations are available without blocking.

Methods inherited from class java.lang.Object

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

Constructor Detail

Auditor

public Auditor()

Method Detail

addAuditListener

public abstract void addAuditListener(AuditListener listener)

Adds an audit listener to this auditor.

removeAuditListener

public abstract void removeAuditListener(AuditListener listener)

Removes an audit listener from this auditor.

isAuditable

public abstract boolean isAuditable(Element element,
                  Node node,
                  Project project,
                  Workspace workspace)

Gets whether an Element is auditable. An element is auditable if an Audit model for it has been registered with Audit, and if the context represented by the node, project, and workspace is sufficient: an element contained by a node requires node, project, and workspace; an element that is a node or directory requires project and workspace or, for application content, just workspace; a element that is a project requires just workspace, and an element that is a workspace requires nothing.

If the node is not a Workspace, or Project, then if the workspace is not null and not open, it will be opened and if the project is not null and not open, it will be scanned for technologies and the associated extensions will be loaded.

Parameters:

element - An Element corresponding to a construct in the Audit object model.

node - The Node containing the element. Ignored if element is a node or directory.

project - The project containing the element. Ignored if element is a Workspace or Project.

workspace - The workspace containing the element. Ignored if element is a Workspace.

addElement

public abstract boolean addElement(Element element,
                 Node node,
                 Project project,
                 Workspace workspace)

Adds the location corresponding to an Element to the set of locations to be audited. The location will not be added if the node is null, unless the element is a Node or directory; if the project is null, unless the element is a project or workspace; or if the workspace is null, unless the element is a workspace.

If the node is not a Workspace, or Project, then if the workspace is not null and not open, it will be opened and if the project is not null and not open, it will be scanned for technologies and the associated extensions will be loaded.

Parameters:

element - An Element corresponding to a construct in the Audit object model.

node - The Node containing the element. Ignored if element is a node.

project - The project containing the element. Ignored if element is a Workspace or Project.

workspace - The workspace containing the element. Ignored if element is a Workspace.

Returns:

True if the location was added.

See Also:

isAuditable(oracle.ide.model.Element, oracle.ide.model.Node, oracle.ide.model.Project, oracle.ide.model.Workspace)

addElements

public abstract boolean addElements(Element[] elements,
                  Node node,
                  Project project,
                  Workspace workspace)

Adds the locations corresponding to an array of Elements in a Node to the set of locations to be audited. For each element, the location will not be added if the node is null unless the element is a Node or directory; if the project is null, unless the element is a project or workspace; or if the workspace is null, unless the element is a workspace.

If the node is not a Workspace, or Project, then if the workspace is not null and not open, it will be opened and if the project is not null and not open, it will be scanned for technologies and the associated extensions will be loaded.

Parameters:

elements - An array of Elements each corresponding to a construct in the Audit object model.

node - The Node containing the elements.

project - The project containing the elements. Ignored for any element which is a Workspace or Project.

workspace - The workspace containing the elements. Ignored for any element which is a Workspace.

Returns:

True if at least one location was added.

See Also:

addElement(oracle.ide.model.Element, oracle.ide.model.Node, oracle.ide.model.Project, oracle.ide.model.Workspace)

addNode

public abstract boolean addNode(Node node,
              Project project,
              Workspace workspace)

Adds the location corresponding to a Node to the set of locations to be audited. The location will not be added if the project is null, unless the node is a project or workspace; or if the workspace is null, unless the node is a workspace.

If the node is not a Workspace, or Project, then if the workspace is not null and not open, it will be opened and if the project is not null and not open, it will be scanned for technologies and the associated extensions will be loaded.

Parameters:

node - A Node in the Audit object model.

project - The project containing the node. Ignored if node is a Workspace or Project.

workspace - The workspace containing the node. Ignored if node is a Workspace.

Returns:

True if the location was added.

addConstruct

public abstract boolean addConstruct(java.lang.Object construct,
                   java.net.URL file,
                   Project project,
                   Workspace workspace)

Adds the location corresponding to a construct to the set of locations to be audited. The location will not be added if the project is null, unless the url resolves to a project or workspace; or if the workspace is null, unless the the url resolves to a workspace, or if the construct is not a construct of the model corresponding to the URL. If the workspace is not null and not open, it will be opened. If the project is not null and not open, it will be scanned for technologies and the associated extensions will be loaded.

Parameters:

construct - A construct in the Audit object model (e.g., a Java object).

file - The URL of the file containing the construct.

project - The project containing the file.

workspace - The workspace containing the file.

Returns:

True if the location was added.

addUrl

public abstract boolean addUrl(java.net.URL url,
             Project project,
             Workspace workspace)

Adds the location corresponding to a URL to the set of locations to be audited. The location will not be added if the project is null, unless the url resolves to a project or workspace; or if the workspace is null, unless the the url resolves to a workspace. If the workspace is not null and not open, it will be opened. If the project is not null and not open, it will be scanned for technologies and the associated extensions will be loaded.

Parameters:

url - The URL of a file or directory in the Audit object model.

project - The project containing the file.

workspace - The workspace containing the file.

Returns:

True if the location was added.

isAuditableType

public abstract boolean isAuditableType(java.net.URL url)

Gets whether the element at an URL is of an auditable type.

getFactory

public abstract ModelFactory getFactory()

Gets the factory used to create the models to be audited.

getProfile

public abstract Profile getProfile()

Gets the profile for this audit.

setProfile

public abstract void setProfile(Profile profile)

Sets the profile for this audit.

Throws:

java.lang.IllegalStateException - if a profile has already been set.

setAttribute

public abstract void setAttribute(java.lang.Object key,
                java.lang.Object value)

Sets a configuration attribute for this auditor. Configuration attributes are accessible to model adapters through the ModelFactory.getAttribute method and to analyzers through the AuditContext.getAttribute(oracle.jdeveloper.audit.analyzer.AuditContext.Key) method with a AuditContext.sharedKey(java.lang.Object)

Typically, configuration attributes are used to allow an IDE command that is implemented using Audit to provide command-specific attributes to a model adapter or analyzer.

Parameters:

key - An object, typically a java.lang.Class, which uniquely identifies the attribute, used to create the shared key.

value - The possibly null value of the attribute.

Throws:

java.lang.IllegalStateException - if locations to be audited have already been added.

See Also:

AuditContext.sharedKey(java.lang.Object), AuditContext.getAttribute(oracle.jdeveloper.audit.analyzer.AuditContext.Key), ModelFactory.getAttribute(java.lang.Object)

isAuditing

public abstract boolean isAuditing()

Gets whether an audit is in progress.

isCancelled

public abstract boolean isCancelled()

Gets whether an audit in progress has been cancelled.

setMaximumFileSize

public abstract void setMaximumFileSize(long size)

Sets the size of the largest auditable file.

Parameters:

size - The size, in Mb, of the largest file that can be audited.

getMaximumFileSize

public abstract long getMaximumFileSize()

Gets the size of the largest file that can be audited, in Mb.

setWorkingSet

public abstract void setWorkingSet(WorkingSet workingSet)

Sets the working set to use when filtering projects and project content.

getWorkingSet

public abstract WorkingSet getWorkingSet()

Gets the working set to use when filtering projects and project content.

setFileFilters

public abstract void setFileFilters(IntersectedFilters filters)

Sets the supplemental filters to use when filtering application content, projects, and project content.

getFileFilters

public abstract IntersectedFilters getFileFilters()

Gets the supplemental filters to use when filtering application content, projects, and project content.

setIgnoreAssists

public abstract void setIgnoreAssists(boolean enabled)

Sets whether to ignore issues corresponding to assists (severity ASSIST).

isIgnoreAssists

public abstract boolean isIgnoreAssists()

Gets whether to ignore issues corresponding to assists (severity ASSIST).

setWriteLockRequestListener

public abstract void setWriteLockRequestListener(WriteLockRequestListener listener)

Sets the listener to notify if a thread waits to acquire the write lock.

Parameters:

listener - The listener to notify if a thread waits to acquire the write lock, or null if none.

Throws:

java.lang.IllegalStateException - if the auditor is auditing.

setDependencyCollector

public abstract void setDependencyCollector(CompositeDependency collector)

Sets the collector of dependencies discovered when the audit is run, or null. By default, dependencies are not collected. The client must remove itself as a listener when it no longer needs the dependencies.

Throws:

java.lang.IllegalStateException - if the auditor is auditing.

setVisitDescendants

public abstract void setVisitDescendants(boolean shallow)

Sets whether to visit descendants of the locations to be audited. By default, visitAncestors is true.

Throws:

java.lang.IllegalStateException - if the auditor is auditing.

See Also:

setVisitAncestors(boolean)

isVisitDescendants

public abstract boolean isVisitDescendants()

Gets whether to visit descendants of the locations to be audited.

See Also:

setVisitDescendants(boolean)

setVisitAncestors

public abstract void setVisitAncestors(boolean shallow)

Sets whether to visit ancestors of the locations to be audited. By default, visitAncestors is true.

See Also:

setVisitAncestors(boolean)

isVisitAncestors

public abstract boolean isVisitAncestors()

Gets whether to visit ancestors of the locations to be audited.

See Also:

setVisitAncestors(boolean)

audit

public abstract void audit()

Audits the locations of this auditor in the current thread. The locations audited are those added to this auditor by addElement(oracle.ide.model.Element, oracle.ide.model.Node, oracle.ide.model.Project, oracle.ide.model.Workspace), and addConstruct(java.lang.Object, java.net.URL, oracle.ide.model.Project, oracle.ide.model.Workspace). The results of the audit are passed to the audit listeners added by addAuditListener(oracle.jdeveloper.audit.service.AuditListener).

Throws:

java.lang.IllegalStateException - if no profile has been set or locations added, if no locations remain valid, or if the auditor is already auditing.

java.util.concurrent.CancellationException - if the audit is cancelled.

tryAudit

public abstract void tryAudit()

Audits the locations of this auditor in the current thread if the models for those locations are available without blocking. The locations audited are those added to this auditor by addElement(oracle.ide.model.Element, oracle.ide.model.Node, oracle.ide.model.Project, oracle.ide.model.Workspace), and addConstruct(java.lang.Object, java.net.URL, oracle.ide.model.Project, oracle.ide.model.Workspace). The results of the audit are passed to the audit listeners added by addAuditListener(oracle.jdeveloper.audit.service.AuditListener).

Throws:

java.lang.IllegalStateException - if no profile has been set or locations added, if no locations remain valid, or if the auditor is already auditing.

java.util.concurrent.CancellationException - if models are not available without blocking or if the audit is cancelled.

applyDefaultTransforms

public abstract java.lang.Throwable applyDefaultTransforms(java.lang.String label)

Audits the locations of this auditor in the current thread and applies all default transforms (see Transformer.applyDefaultTransforms(java.lang.String, java.util.Collection<? extends oracle.jdeveloper.audit.service.Violation>, oracle.jdeveloper.audit.service.TransformerListener, oracle.jdeveloper.audit.service.AuditModel). The locations audited are those added to this auditor by addElement(oracle.ide.model.Element, oracle.ide.model.Node, oracle.ide.model.Project, oracle.ide.model.Workspace), and addConstruct(java.lang.Object, java.net.URL, oracle.ide.model.Project, oracle.ide.model.Workspace). The results of the audit are passed to the audit listeners added by addAuditListener(oracle.jdeveloper.audit.service.AuditListener).

Throws:

java.lang.IllegalStateException - if no profile has been set or locations added.

run

public abstract void run()

Audits the locations of this auditor in the current thread. The locations audited are those added to this auditor by addElement(oracle.ide.model.Element, oracle.ide.model.Node, oracle.ide.model.Project, oracle.ide.model.Workspace), and addConstruct(java.lang.Object, java.net.URL, oracle.ide.model.Project, oracle.ide.model.Workspace). The results of the audit are passed to the audit listeners added by addAuditListener(oracle.jdeveloper.audit.service.AuditListener).

Throws:

java.lang.IllegalStateException - if no profile has been set or locations added, if no locations remain valid, or if the auditor is already auditing.

runAsynchronously

public abstract void runAsynchronously()

Audits the locations of this auditor in a background thread. The locations audited are those added to this auditor by addElement(oracle.ide.model.Element, oracle.ide.model.Node, oracle.ide.model.Project, oracle.ide.model.Workspace), and addConstruct(java.lang.Object, java.net.URL, oracle.ide.model.Project, oracle.ide.model.Workspace). The results of the audit are passed to the audit listeners added by addAuditListener(oracle.jdeveloper.audit.service.AuditListener).

runAsynchronously

public abstract void runAsynchronously(java.lang.Thread.UncaughtExceptionHandler handler)

Audits the locations of this auditor in a background thread. The locations audited are those added to this auditor by addElement(oracle.ide.model.Element, oracle.ide.model.Node, oracle.ide.model.Project, oracle.ide.model.Workspace), and addConstruct(java.lang.Object, java.net.URL, oracle.ide.model.Project, oracle.ide.model.Workspace). The results of the audit are passed to the audit listeners added by addAuditListener(oracle.jdeveloper.audit.service.AuditListener).

cancel

public abstract boolean cancel()

Cancel an executing audit.

Returns:

true iff an audit is running and not already cancelled.

throwIfCancelled

public abstract void throwIfCancelled()

Throw CancellationException if the last audit to execute was cancelled.

Throws:

java.util.concurrent.CancellationException - if cancelled.

clear

public abstract void clear()

Clears the results and locations from this auditor. This auditor can be reused after a location is added.