oracle.jdeveloper.audit.analyzer
Interface AuditContext

All Known Implementing Classes:

DefaultAuditContext

public interface AuditContext

The Audit traversal context.

The Audit framework traverses the constructs of the object models corresponding to the nodes being audited and at each construct invokes the applicable enter and exit methods of each registered analyzer. As the traversal enters a construct, it invokes all enter methods whose signature matches the construct. As the traversal exits a construct, it invokes all exit methods whose signature matches the construct. The enter and exit methods accept two parameters, a context and a construct. The context is an instance of this class, created by the Audit framework. It exists to provide services needed by the visitor method currently being invoked by the framework, and should not generally be used after that visitor method returns. However, methods of this class imply that the context used for the enter and exit methods of the same construct be indistinguishable, and that the context be maintained while enclosed constructs are traversed.

Traversal Methods

Many methods provide information about the current state of the traversal: construct, location, raw text, line number, depth, enclosing context, and so forth.

Report Methods
Violations and measurements are reported by the visitor methods using the report methods of this interface. There are two base methods, one for reporting violations and one for reporting measurements, and several convenience variations.

The simplest report method for violations is this one: report(Rule). It reports a violation associated with the construct currently being traversed. The other variations allow another construct to be indicated. In addition to the rule and construct, a violation will frequently require parameters to provide context for the message and for fixes. To avoid both massive overloading of the report methods and the creation of megabytes of useless container objects (problems which the previous version of this API suffered from), the report methods return a ViolationReport object which allows parameters and other properties to be added to the violation. If no parameters need to be added, the return value can be ignored.

Reporting measurements is much simpler. The basic method is report(Metric,Object). Measurements can only be reported for the current construct. A couple of variations are provided for reporting int- and float-valued measurements.

Attribute Methods
Even simple analyzers have to share data between visitor methods. Very commonly, a visitor method determines a value to be used by the visitor methods of enclosed constructs. For example, a visitor method for a SourceClass might set an enclosing class attribute to be used by the visitor method for the enclosed SourceMethods. Using a field to store the enclosing class attribute breaks down as soon as the visitor method for SourceClass gets invoked for an inner class, though. This can be fixed by making the instance field a stack, but in many situations, using attribute methods is more convenient. To use the attribute methods, a AuditContext.Key that identifies the attribute must be created using the key(java.lang.Object) method. Typically, this is done in an enter(AuditContext, Workspaces) visitor method, as shown below, since the Workspace object is the first construct visited by Audit.

Setting Attributes for Child Constructs
The setAttribute(AuditContext.Key,Object) sets an attribute on the current construct so that getAttribute(AuditContext.Key) on the current construct or any construct it encloses gets the same value. If a different value is set on an enclosed construct, that constructs enclosed constructs will see the different value, but the value seen from other constructs will be unaffected.

 private AuditContext.Key ENCLOSING_KEY;
 public void enter(AuditContext context, Workspaces construct) {
   ENCLOSING_KEY = context.key("enclosing-class");
 }
 public void enter(AuditContext context, SourceClass construct) {
   context.setAttribute(ENCLOSING_KEY, construct);
 }
 public void enter(AuditContext context, SourceMethod construct) {
   SourceClass enclosingClass = (SourceClass) context.getAttribute(ENCLOSING_KEY);
   // Do something with the class.
 }
 

Remember that enter(AuditContext,SourceClass) is invoked for both the outer class and for any inner classes encountered. The getAttribute call will always get the innermost enclosing class.

Setting Attributes for a Specific Child Construct
An attribute set as above is visible for all enclosed constructs. Sometimes, an attribute needs to be set visible for one contained construct but not for others. The setChildAttribute(Object,AuditContext.Key,Object) method sets a value visible only on the child construct and the constructs it encloses.

Setting Attributes for the Parent Construct
Propagating attributes from a construct to its enclosing construct is also sometimes necessary. The setParentAttribute(AuditContext.Key, Object) method is equivalent to getEnclosingContext().setAttribute

Setting Attributes for the Parent Construct for a Specific Child
The setParentAttribute method does not work if each of a variable number of enclosed constructs must set the same attribute for the enclosing context. The enableGetChildAttribute() method in an enclosed context enables the enclosing context to use getChildAttribute(Object, AuditContext.Key) to get the attribute from a specific enclosed construct.

Sharing Attributes Between Analyzers
The keys returned by two calls to the key(java.lang.Object) method never collide, and so two analyzers will never step on each others attributes. However, that also means that two analyzers cannot use the attribute methods to share data. The sharedKey(Object) allows multiple calls to return the same key if the argument objects are equal. If the data to be shared is an instance of a class specific to that usage, then the identifier is typically the class object for that class.

Nested Class Summary

static interface

AuditContext.Key A key identifying an attribute, created by key(java.lang.Object) or sharedKey(java.lang.Object).

Field Summary

static java.lang.String

INTENTIONAL_NULL Context property that asserts that null workspace, project or node values, if any, in the context are intentional.

Method Summary

void	addDependency(Dependency dependency) Adds a dependency of the current audit on a target.
void	enableGetChildAttribute() Enables the enclosing context to use getChildAttribute(java.lang.Object, oracle.jdeveloper.audit.analyzer.AuditContext.Key) to get the the value of an attribute set in this context.
java.lang.Object	getAttribute(AuditContext.Key key) Gets the value of an attribute in this or an enclosing context, or null if none.
float	getAttribute(AuditContext.Key key, float defaultValue) Gets the float value of an attribute in this or an enclosing context.
int	getAttribute(AuditContext.Key key, int defaultValue) Gets the int value of an attribute in this or an enclosing context.
Auditor	getAuditor() Gets the auditor running this traversal.
java.lang.Object	getChildAttribute(java.lang.Object child, AuditContext.Key key) Gets the value of an attribute in the context of a child of the current construct.
int	getDepth() Gets the depth (distance from root) of the construct currently being traversed.
AuditContext	getEnclosingContext() Gets the context of the enclosing construct of this context.
Context	getIdeContext() Gets an IDE context for the model currently being traversed.
int	getLength() Gets the length of the construct currently being traversed.
int	getLineOffset() Gets the line offset (zero-based) of the first character of the construct currently being traversed, or 0 if the construct currently being traversed is not text-based.
Location	getLocation() Gets the location of the construct currently being traversed.
Location	getLocation(java.lang.Object construct) Gets the location of a construct in the model currently being traversed.
ModelAdapter	getModel() Gets the model adapter for the model currently being traversed.
<T extends ModelAdapter> ModelAdapter	getModel(java.lang.Class<T> type, java.net.URL url) Gets the model adapter for the model corresponding to a URL in the workspace and project currently being traversed.
<T extends ModelAdapter> ModelAdapter	getModel(java.lang.Class<T> type, java.net.URL url, Project project, Workspace workspace) Gets the model adapter for the model corresponding to a workspace, project, and url.
ModelAdapter	getModelAdapter() Deprecated. Use getModel().
<T extends ModelAdapter> ModelAdapter	getModelAdapter(java.lang.Class<T> type, java.net.URL url) Deprecated. Use getModel(Class, URL)
<T extends ModelAdapter> ModelAdapter	getModelAdapter(java.lang.Class<T> type, java.net.URL url, Project project, Workspace workspace) Deprecated. Use getModel(Class, URL, Project, Workspace)
int	getOffset() Gets the character offset of the construct currently being traversed, or 0 if the construct currently being traversed is not text-based.
Project	getProject() Gets the project currently being traversed, or null if the root or a workspace is currently being traversed.
java.lang.String	getText() Gets the text of the construct currently being traversed, or null if the construct currently being traversed is not text-based..
java.lang.String	getText(java.lang.Object construct) Gets the text of a construct in the model currently being traversed.
java.net.URL	getUrl() Gets the non-null URL for the model currently being traversed.
Workspace	getWorkspace() Gets the workspace currently being traversed, or null if the root is currently being traversed.
boolean	isCancelled() Gets whether the current traversal has been cancelled.
AuditContext.Key	key(java.lang.Object object) Gets a key for an attribute visible only to this analyzer.
void	produceFragment(java.lang.Class<? extends ModelType> fragmentType) Produces a fragment of another model type from the construct currently being traversed.
void	produceFragment(java.lang.Class<? extends ModelType> fragmentType, Location location) Produces a fragment of another model type from a construct in the model currently being traversed.
void	produceFragment(java.lang.Class<? extends ModelType> fragmentType, java.lang.Object construct) Produces a fragment of another model type from a construct in the model currently being traversed.
void	report(Metric metric, float measurement) Reports a float-valued measurement for the current construct.
void	report(Metric metric, int measurement) Reports an int-valued measurement for the current construct.
void	report(Metric metric, java.lang.Object measurement) Reports a measurement for the current construct.
ViolationReport	report(Rule rule) Reports an issue for the construct currently being traversed.
ViolationReport	report(Rule rule, Location location) Reports an issue for a location in the model currently being traversed (i.e., location.getModel() == context.getModel()).
ViolationReport	report(Rule rule, ModelAdapter model, java.lang.Object construct) Deprecated. Violations reported on a model other than the one currently being traversed are mostly ignored; this method is effectively not supported.
ViolationReport	report(Rule rule, java.lang.Object construct) Reports an issue for a construct in the model currently being traversed This method returns a ViolationReport which allows parameters and other attributes to be added to the issue.
void	setAttribute(AuditContext.Key key, float value) Sets the value of a Float attribute in this context and in its enclosed contexts.
void	setAttribute(AuditContext.Key key, int value) Sets the value of an Integer attribute in this context and in its enclosed contexts.
void	setAttribute(AuditContext.Key key, java.lang.Object value) Sets the value of an attribute in this context and in its enclosed contexts.
void	setChildAttribute(java.lang.Object child, AuditContext.Key key, java.lang.Object value) Sets the value of an attribute in the context of a child of the current construct and in the enclosed contexts of the child.
void	setParentAttribute(AuditContext.Key key, java.lang.Object value) Sets the value of an attribute in the context of the construct enclosing the current construct, and in its enclosed contexts.
AuditContext.Key	sharedKey(java.lang.Object object) Gets a key for an attribute visible to all analyzers.
void	throwIfCancelled() Throw CancellationException if the current traversal has been cancelled.

Field Detail

INTENTIONAL_NULL

static final java.lang.String INTENTIONAL_NULL

Context property that asserts that null workspace, project or node values, if any, in the context are intentional.

See Also:

Constant Field Values

Method Detail

getAuditor

Auditor getAuditor()

Gets the auditor running this traversal.

getEnclosingContext

AuditContext getEnclosingContext()

Gets the context of the enclosing construct of this context.

getDepth

int getDepth()

Gets the depth (distance from root) of the construct currently being traversed. The root construct has depth 0.

getModel

ModelAdapter getModel()

Gets the model adapter for the model currently being traversed. A model adapter is returned even if the construct currently being traversed is the root or a workspace, project, or package.

getWorkspace

Workspace getWorkspace()

Gets the workspace currently being traversed, or null if the root is currently being traversed.

getProject

Project getProject()

Gets the project currently being traversed, or null if the root or a workspace is currently being traversed.

getIdeContext

Context getIdeContext()

Gets an IDE context for the model currently being traversed.

getUrl

java.net.URL getUrl()

Gets the non-null URL for the model currently being traversed.

getLocation

Location getLocation()

Gets the location of the construct currently being traversed.

getText

java.lang.String getText()

Gets the text of the construct currently being traversed, or null if the construct currently being traversed is not text-based..

getLineOffset

int getLineOffset()

Gets the line offset (zero-based) of the first character of the construct currently being traversed, or 0 if the construct currently being traversed is not text-based.

getOffset

int getOffset()

Gets the character offset of the construct currently being traversed, or 0 if the construct currently being traversed is not text-based.

getLength

int getLength()

Gets the length of the construct currently being traversed.

isCancelled

boolean isCancelled()

Gets whether the current traversal has been cancelled.

throwIfCancelled

void throwIfCancelled()

Throw CancellationException if the current traversal has been cancelled.

Throws:

java.util.concurrent.CancellationException - if cancelled.

getLocation

Location getLocation(java.lang.Object construct)

Gets the location of a construct in the model currently being traversed.

getText

java.lang.String getText(java.lang.Object construct)

Gets the text of a construct in the model currently being traversed.

getModel

<T extends ModelAdapter> ModelAdapter getModel(java.lang.Class<T> type,
                                               java.net.URL url,
                                               Project project,
                                               Workspace workspace)

Gets the model adapter for the model corresponding to a workspace, project, and url. This method provides the argument required to report a construct or parameter from outside the current model.

getModel

<T extends ModelAdapter> ModelAdapter getModel(java.lang.Class<T> type,
                                               java.net.URL url)

Gets the model adapter for the model corresponding to a URL in the workspace and project currently being traversed. This method provides the argument required to report a construct or parameter from outside the current model.

key

AuditContext.Key key(java.lang.Object object)

Gets a key for an attribute visible only to this analyzer.

Parameters:

object - An object which identifies the attribute.

Returns:

a unique AuditContext.Key for use with the set and get attribute methods.

sharedKey

AuditContext.Key sharedKey(java.lang.Object object)

Gets a key for an attribute visible to all analyzers. Multiple invocations of this method on the same object will return the same key. Using a Class as the object is typical.

Parameters:

object - An object which uniquely identifies the attribute.

Returns:

a AuditContext.Key corresponding to the object for use with the set and get attribute methods.

setAttribute

void setAttribute(AuditContext.Key key,
                  java.lang.Object value)

Sets the value of an attribute in this context and in its enclosed contexts. The value seen by getAttribute on contexts which enclose this one is unnaffected.

Parameters:

key - A key identifying the attribute to set.

value - The possibly null new value of the attribute.

See Also:

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

setAttribute

void setAttribute(AuditContext.Key key,
                  int value)

Sets the value of an Integer attribute in this context and in its enclosed contexts. The value seen by getAttribute on contexts which enclose this one is unnaffected.

Parameters:

key - A key identifying the attribute to set.

value - The new value of the attribute.

See Also:

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

setAttribute

void setAttribute(AuditContext.Key key,
                  float value)

Sets the value of a Float attribute in this context and in its enclosed contexts. The value seen by getAttribute on contexts which enclose this one is unnaffected.

Parameters:

key - A key identifying the attribute to set.

value - The new value of the attribute.

See Also:

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

getAttribute

java.lang.Object getAttribute(AuditContext.Key key)

Gets the value of an attribute in this or an enclosing context, or null if none.

Parameters:

key - A key identifying the attribute to get.

Returns:

The value of the attribute, or null if none.

getAttribute

int getAttribute(AuditContext.Key key,
                 int defaultValue)

Gets the int value of an attribute in this or an enclosing context.

Parameters:

key - A key identifying the attribute to get.

defaultValue - The value to return if none set.

Returns:

The value of the attribute, or the default value if none.

Throws:

java.lang.ClassCastException - if the value cannot be cast to Integer.

getAttribute

float getAttribute(AuditContext.Key key,
                   float defaultValue)

Gets the float value of an attribute in this or an enclosing context.

Parameters:

key - A key identifying the attribute to get.

defaultValue - The value to return if none set.

Returns:

The value of the attribute, or the default value if none.

Throws:

java.lang.ClassCastException - if the value cannot be cast to Float.

setChildAttribute

void setChildAttribute(java.lang.Object child,
                       AuditContext.Key key,
                       java.lang.Object value)

Sets the value of an attribute in the context of a child of the current construct and in the enclosed contexts of the child. The value seen by getAttribute on this context and contexts which enclose this one is unnaffected.

Parameters:

child - A child of the current construct.

key - A key identifying the attribute to set.

value - The new value of the attribute.

See Also:

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

setParentAttribute

void setParentAttribute(AuditContext.Key key,
                        java.lang.Object value)

Sets the value of an attribute in the context of the construct enclosing the current construct, and in its enclosed contexts.

Parameters:

key - A key identifying the attribute to set.

value - The possibly null new value of the attribute.

See Also:

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

getChildAttribute

java.lang.Object getChildAttribute(java.lang.Object child,
                                   AuditContext.Key key)

Gets the value of an attribute in the context of a child of the current construct. The enableGetChildAttribute() method must have been invoked on the context of the child. This method does not search enclosing contexts.

Parameters:

child - A child of the current construct.

key - A key identifying the attribute to set.

Throws:

java.lang.IllegalStateException - if enableGetChildAttribute() has not been invoked in the context of the child.

See Also:

key(java.lang.Object), sharedKey(java.lang.Object), enableGetChildAttribute(), setAttribute(oracle.jdeveloper.audit.analyzer.AuditContext.Key, java.lang.Object)

enableGetChildAttribute

void enableGetChildAttribute()

Enables the enclosing context to use getChildAttribute(java.lang.Object, oracle.jdeveloper.audit.analyzer.AuditContext.Key) to get the the value of an attribute set in this context.

See Also:

getChildAttribute(java.lang.Object, oracle.jdeveloper.audit.analyzer.AuditContext.Key), setAttribute(oracle.jdeveloper.audit.analyzer.AuditContext.Key, java.lang.Object)

addDependency

void addDependency(Dependency dependency)

Adds a dependency of the current audit on a target.

report

ViolationReport report(Rule rule)

Reports an issue for the construct currently being traversed. This method returns a ViolationReport which allows parameters and other attributes to be added to the issue.

See the class overview for more information.

Parameters:

rule - The rule violated.

report

ViolationReport report(Rule rule,
                       java.lang.Object construct)

Reports an issue for a construct in the model currently being traversed This method returns a ViolationReport which allows parameters and other attributes to be added to the issue.

See the class overview for more information.

Parameters:

rule - The rule violated.

construct - The construct with the issue.

report

ViolationReport report(Rule rule,
                       Location location)

Reports an issue for a location in the model currently being traversed (i.e., location.getModel() == context.getModel()). This method returns a ViolationReport which allows parameters and other attributes to be added to the issue.

See the class overview for more information.

Parameters:

rule - The rule violated.

location - The Location of the issue.

report

void report(Metric metric,
            java.lang.Object measurement)

Reports a measurement for the current construct.

Parameters:

metric -

measurement - The value that was measured.

report

void report(Metric metric,
            int measurement)

Reports an int-valued measurement for the current construct.

Parameters:

metric -

measurement - The value that was measured.

report

void report(Metric metric,
            float measurement)

Reports a float-valued measurement for the current construct.

Parameters:

metric -

measurement - The value that was measured.

produceFragment

void produceFragment(java.lang.Class<? extends ModelType> fragmentType)

Produces a fragment of another model type from the construct currently being traversed.

produceFragment

void produceFragment(java.lang.Class<? extends ModelType> fragmentType,
                     java.lang.Object construct)

Produces a fragment of another model type from a construct in the model currently being traversed.

produceFragment

void produceFragment(java.lang.Class<? extends ModelType> fragmentType,
                     Location location)

Produces a fragment of another model type from a construct in the model currently being traversed.

getModelAdapter

ModelAdapter getModelAdapter()

Deprecated. Use getModel().

Gets the adapter for the model currently being traversed. An adapter is returned even if the construct currently being traversed is the root or a workspace, project, or package.

getModelAdapter

<T extends ModelAdapter> ModelAdapter getModelAdapter(java.lang.Class<T> type,
                                                      java.net.URL url,
                                                      Project project,
                                                      Workspace workspace)

Deprecated. Use getModel(Class, URL, Project, Workspace)

Gets the adapter for the model corresponding to a workspace, project, and url. This method provides the argument required to report a construct or parameter from outside the current model.

getModelAdapter

<T extends ModelAdapter> ModelAdapter getModelAdapter(java.lang.Class<T> type,
                                                      java.net.URL url)

Deprecated. Use getModel(Class, URL)

Gets the adapter for the model corresponding to a URL in the workspace and project currently being traversed. This method provides the argument required to report a construct or parameter from outside the current model.

report

ViolationReport report(Rule rule,
                       ModelAdapter model,
                       java.lang.Object construct)

Deprecated. Violations reported on a model other than the one currently being traversed are mostly ignored; this method is effectively not supported.