public interface AuditContext extends AuditContextCompatibility
Analyzer
methods that are invoked by the Audit framework as it
traverses the constructs of the object models of the files being audited.
The methods include enter
and exit
methods invoked as
the traversal enters and exits constructs, and Analyzer.review(oracle.jdeveloper.audit.analyzer.AuditContext, oracle.jdeveloper.audit.service.Violation)
methods invoked as issues are reported.
The Audit framework creates an instance of this interface for a given
construct just before traversal enters the construct and maintains the
instance until just after traversal exits the construct. The context must
not be used once the construct is exited.
Traversal Methodsreport
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
IssueReport
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 MethodsSourceClass
might set an enclosing class attribute to be used by the
visitor method for the enclosed SourceMethod
s. 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 IDE Workspaces
object is the first construct visited by Audit.
Setting Attributes for Child ConstructssetAttribute(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.
Modifier and Type | Interface and Description |
---|---|
static interface |
AuditContext.Key
A key identifying an attribute, created by
key(java.lang.Object) or
sharedKey(java.lang.Object) . |
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
INTENTIONAL_NULL
Deprecated.
|
Modifier and Type | Method and Description |
---|---|
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.
|
java.lang.Object |
getConstruct()
Gets the construct currently being traversed.
|
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> |
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> |
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> |
getModelAdapter(java.lang.Class<T> type,
java.net.URL url)
Deprecated.
|
<T extends ModelAdapter> |
getModelAdapter(java.lang.Class<T> type,
java.net.URL url,
Project project,
Workspace workspace)
|
Node |
getNode()
Gets the
IDE node for the model currently being traversed,
or null if none (in particular, if this is the root or a directory model). |
int |
getOffset()
Gets the character offset of the construct currently being traversed, or 0
if the construct currently being traversed is not text-based.
|
java.lang.Class<?> |
getPresentationType()
Gets the presentation type of construct currently being traversed, or null
if the type is not a presentation type.
|
Project |
getProject()
Gets the project currently being traversed, or null if the root or a
workspace is currently being traversed.
|
java.util.Set<java.lang.String> |
getTechnologies()
Gets the technologies that apply to the construct 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 |
markSuppressionLimit()
Marks the start of the current construct as the limit before which a
suppression cannot be reported.
|
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.
|
IssueReport |
report(Rule rule)
Reports an issue for the construct currently being traversed.
|
IssueReport |
report(Rule rule,
Location location)
Reports an issue for a location in the model currently being traversed
(i.e., location.getModel() == context.getModel()).
|
IssueReport |
report(Rule rule,
ModelAdapter model,
java.lang.Object construct)
Deprecated.
Violations reported on a model other than the one currently
being traversed are ignored.
|
IssueReport |
report(Rule rule,
java.lang.Object construct)
Reports an issue for a construct in the model currently being traversed.
|
SuppressionReport |
report(SuppressionScheme scheme,
java.lang.String name,
Location location)
Reports a suppression for the scope of a location in the model
currently being traversed.
|
SuppressionReport |
report(SuppressionScheme scheme,
java.lang.String name,
java.lang.Object construct)
Reports a suppression for the scope of a construct in the model
currently being traversed.
|
SuppressionReport |
report(SuppressionScheme scheme,
Violation issue)
Reports a suppression for the issue currently being reviewed.
|
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.
|
static final java.lang.String INTENTIONAL_NULL
Context.INTENTIONAL_NULL
Auditor getAuditor()
AuditContext getEnclosingContext()
int getDepth()
ModelAdapter getModel()
Workspace getWorkspace()
Project getProject()
Node getNode()
IDE node
for the model currently being traversed,
or null if none (in particular, if this is the root or a directory model).Context getIdeContext()
IDE context
for the model currently being
traversed.java.util.Set<java.lang.String> getTechnologies()
java.net.URL getUrl()
Location getLocation()
java.lang.Object getConstruct()
java.lang.Class<?> getPresentationType()
ModelType.getPresentationTypes()
java.lang.String getText()
int getLineOffset()
int getOffset()
int getLength()
boolean isCancelled()
void throwIfCancelled()
java.util.concurrent.CancellationException
- if cancelled.Location getLocation(java.lang.Object construct)
java.lang.String getText(java.lang.Object construct)
<T extends ModelAdapter> ModelAdapter getModel(java.lang.Class<T> type, java.net.URL url, Project project, Workspace workspace)
<T extends ModelAdapter> ModelAdapter getModel(java.lang.Class<T> type, java.net.URL url)
AuditContext.Key key(java.lang.Object object)
object
- An object which identifies the attribute.AuditContext.Key
for use with the set and get attribute methods.AuditContext.Key sharedKey(java.lang.Object object)
Class
as the object is typical.object
- An object which uniquely identifies the attribute.AuditContext.Key
corresponding to the object for use with the set and
get attribute methods.void setAttribute(AuditContext.Key key, java.lang.Object value)
key
- A key identifying the attribute to set.value
- The possibly null new value of the attribute.key(java.lang.Object)
,
sharedKey(java.lang.Object)
,
getAttribute(oracle.jdeveloper.audit.analyzer.AuditContext.Key)
void setAttribute(AuditContext.Key key, int value)
key
- A key identifying the attribute to set.value
- The new value of the attribute.key(java.lang.Object)
,
sharedKey(java.lang.Object)
,
getAttribute(oracle.jdeveloper.audit.analyzer.AuditContext.Key)
void setAttribute(AuditContext.Key key, float value)
key
- A key identifying the attribute to set.value
- The new value of the attribute.key(java.lang.Object)
,
sharedKey(java.lang.Object)
,
getAttribute(oracle.jdeveloper.audit.analyzer.AuditContext.Key)
java.lang.Object getAttribute(AuditContext.Key key)
key
- A key identifying the attribute to get.int getAttribute(AuditContext.Key key, int defaultValue)
key
- A key identifying the attribute to get.defaultValue
- The value to return if none set.java.lang.ClassCastException
- if the value cannot be cast to Integer
.float getAttribute(AuditContext.Key key, float defaultValue)
key
- A key identifying the attribute to get.defaultValue
- The value to return if none set.java.lang.ClassCastException
- if the value cannot be cast to Float
.void setChildAttribute(java.lang.Object child, AuditContext.Key key, java.lang.Object value)
child
- A child of the current construct.key
- A key identifying the attribute to set.value
- The new value of the attribute.key(java.lang.Object)
,
sharedKey(java.lang.Object)
,
getAttribute(oracle.jdeveloper.audit.analyzer.AuditContext.Key)
void setParentAttribute(AuditContext.Key key, java.lang.Object value)
key
- A key identifying the attribute to set.value
- The possibly null new value of the attribute.key(java.lang.Object)
,
sharedKey(java.lang.Object)
,
getAttribute(oracle.jdeveloper.audit.analyzer.AuditContext.Key)
java.lang.Object getChildAttribute(java.lang.Object child, AuditContext.Key key)
enableGetChildAttribute()
method must have been invoked
on the context of the child. This method does not search enclosing
contexts.child
- A child of the current construct.key
- A key identifying the attribute to set.java.lang.IllegalStateException
- if enableGetChildAttribute()
has not
been invoked in the context of the child.key(java.lang.Object)
,
sharedKey(java.lang.Object)
,
enableGetChildAttribute()
,
setAttribute(oracle.jdeveloper.audit.analyzer.AuditContext.Key, java.lang.Object)
void enableGetChildAttribute()
getChildAttribute(java.lang.Object, oracle.jdeveloper.audit.analyzer.AuditContext.Key)
to get the
the value of an attribute set in this context.void addDependency(Dependency dependency)
IssueReport report(Rule rule)
IssueReport
which allows parameters and other
attributes to be added to the issue.
See the class overview
for more information.
report
in interface AuditContextCompatibility
rule
- The rule violated.IssueReport report(Rule rule, java.lang.Object construct)
IssueReport
which allows parameters and
other attributes to be added to the issue.
See the class overview
for more information.
report
in interface AuditContextCompatibility
rule
- The rule violated.construct
- The construct with the issue.IssueReport report(Rule rule, Location location)
IssueReport
which allows parameters and other
attributes to be added to the issue.
See the class overview
for more information.
report
in interface AuditContextCompatibility
rule
- The rule violated.location
- The Location
of the issue.IssueReport report(Rule rule, ModelAdapter model, java.lang.Object construct)
SuppressionReport report(SuppressionScheme scheme, java.lang.String name, java.lang.Object construct)
SuppressionReport
which allows parameters and other attributes to be added.
A suppression may not be reported for any location before the construct
currently being traversed unless markSuppressionLimit()
is used to
relax that restriction (e.g., to allow a suppression to be reported for a
parent while the first child is being traversed).scheme
- The scheme to which the suppression belongs.name
- A name identifying the issues to suppress.construct
- The construct coincident with the scope of the suppression..SuppressionReport report(SuppressionScheme scheme, java.lang.String name, Location location)
SuppressionReport
which allows parameters and other attributes to be added.
A suppression may not be reported for any location before the construct
currently being traversed unless markSuppressionLimit()
is used to
relax that restriction (e.g., to allow a suppression to be reported for a
parent while the first child is being traversed).scheme
- The scheme to which the suppression belongs.name
- A name identifying the issues to suppress.location
- The location coincident with the scope of the suppression.SuppressionReport report(SuppressionScheme scheme, Violation issue)
SuppressionReport
which allows parameters and other
attributes to be added.
This method may only be called from Analyzer.review(oracle.jdeveloper.audit.analyzer.AuditContext, oracle.jdeveloper.audit.service.Violation)
for the issue
being reviewed.scheme
- The scheme to which the suppression belongs.issue
- The issue currently being reviewed.void markSuppressionLimit()
void report(Metric metric, java.lang.Object measurement)
metric
- The metric.measurement
- The value that was measured.void report(Metric metric, int measurement)
metric
- The metric.measurement
- The value that was measured.void report(Metric metric, float measurement)
metric
- The metric.measurement
- The value that was measured.void produceFragment(java.lang.Class<? extends ModelType> fragmentType)
void produceFragment(java.lang.Class<? extends ModelType> fragmentType, java.lang.Object construct)
void produceFragment(java.lang.Class<? extends ModelType> fragmentType, Location location)
ModelAdapter getModelAdapter()
getModel()
.<T extends ModelAdapter> ModelAdapter getModelAdapter(java.lang.Class<T> type, java.net.URL url, Project project, Workspace workspace)
<T extends ModelAdapter> ModelAdapter getModelAdapter(java.lang.Class<T> type, java.net.URL url)
getModel(Class, java.net.URL)