|
Oracle Fusion Middleware Java API Reference for Oracle Extension SDK Reference 11g Release 1 (11.1.1) E13403-04 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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 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 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)
|
|
void |
addOptionalAnalysis(Issue issue)
|
|
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. |
|
Analyzer |
getAnalyzer(java.lang.Class<? extends Analyzer> analyzerClass)
Gets the instance of an analyzer class used for the current audit. |
|
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. |
|
|
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. |
|
|
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() . |
|
|
getModelAdapter(java.lang.Class<T> type,
java.net.URL url)
Deprecated. Use getModel(Class, URL) |
|
|
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 a rule violation for the current construct. |
|
ViolationReport |
report(Rule rule,
Location location)
Reports a rule violation for a construct. |
|
ViolationReport |
report(Rule rule,
ModelAdapter model,
java.lang.Object construct)
Reports a rule violation for a construct. |
|
ViolationReport |
report(Rule rule,
java.lang.Object construct)
Reports a rule violation for a construct in the current node. |
|
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 |
---|
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.
Method Detail |
---|
Auditor getAuditor()
AuditContext getEnclosingContext()
int getDepth()
ModelAdapter getModel()
Workspace getWorkspace()
Project getProject()
Context getIdeContext()
IDE context
for the model currently being
traversed.
java.net.URL getUrl()
Location getLocation()
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)
Analyzer getAnalyzer(java.lang.Class<? extends Analyzer> analyzerClass)
<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.
getChildAttribute(java.lang.Object, oracle.jdeveloper.audit.analyzer.AuditContext.Key)
,
setAttribute(oracle.jdeveloper.audit.analyzer.AuditContext.Key, java.lang.Object)
void addDependency(Dependency dependency)
void addOptionalAnalysis(Issue issue)
ViolationReport report(Rule rule)
report
returns a ViolationReport
which allows parameters and other
attributes to be added to the violation. This variant is only applicable
when the violating construct is the one currently being visited by Audit.
See the class overview
for more information.
rule
- The rule violated.
ViolationReport
which allows the violation to be
modified.ViolationReport report(Rule rule, java.lang.Object construct)
report
returns a ViolationReport
which allows
parameters and other attributes to be added to the violation. This variant
is applicable when the violating construct is in the node currently being
visited by Audit.
See the class overview
for more information.
rule
- The rule violated.construct
- The violating construct.ViolationReport report(Rule rule, ModelAdapter model, java.lang.Object construct)
report
returns a ViolationReport
which allows parameters and other
attributes to be added to the violation. This variant is applicable for
any violating construct. See getModelAdapter()
,
getModelAdapter(Class,java.net.URL,oracle.ide.model.Project,oracle.ide.model.Workspace)
, and
Location.getModel()
for ways to obtain a model.
See the class overview
for more information.
rule
- The rule violated.model
- The model containing the violationg construct.construct
- The violating construct.ViolationReport report(Rule rule, Location location)
report
returns a ViolationReport
which allows parameters and other
attributes to be added to the violation. See the
class overview
for more information.
rule
- The rule violated.location
- The Location
of the the violating construct.void report(Metric metric, java.lang.Object measurement)
metric
- measurement
- The value that was measured.void report(Metric metric, int measurement)
metric
- measurement
- The value that was measured.void report(Metric metric, float measurement)
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)
getModel(Class, URL, Project, Workspace)
<T extends ModelAdapter> ModelAdapter getModelAdapter(java.lang.Class<T> type, java.net.URL url)
getModel(Class, URL)
|
Oracle Fusion Middleware Java API Reference for Oracle Extension SDK Reference 11g Release 1 (11.1.1) E13403-04 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |