|
Extension SDK 9.0.5 | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
The Audit traversal context.
The Audit framework traverses the constructs of the object models
corresponding to the documents 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 class. 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 metric, Object measurement)
. Measurements can
only be reported for the current construct. A couple of variations are
provided for reporting int- and float-valued measurements.
Attribute Methods
Setting Attributes for a Specific Child Construct
Setting Attributes for the Parent Construct
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
JotClasses might set an enclosing class attribute to be used by the
visitor method for the enclosed JotMethods. Using a field to store the
enclosing class attribute breaks down as soon as the visitor method for
JotClass 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(Key,Object value)
sets an attribute on the current
construct so that #getAttribute(Key)
on the current construct
or any construct it encloses gets the same value. If a different valeu 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.
,pre>
private AuditContext.Key ENCLOSING_KEY;
public void enter(AuditContext context, Workspaces construct) {
ENCLOSING_KEY = context.key("enclosing-class");
}
public void enter(AuditContext context, JotClass construct) {
context.setAttribute(ENCLOSING_KEY, construct);
}
public void enter(AuditContext context, JotMethod construct) {
JotClass enclosingClass = (JotClass) context.getAttribute(ENCLOSING_KEY);
// Do something with the class.
}
Remember that
enter(JotClass)
is invoked for both the outer
class and for any inner classes encountered. The getAttribute
will always get the innermost enclosing class.
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 child, Key, Object value) method
sets a value visible only on the child construct and the constructs it
encloses.
Propagating attributes from a construct to its enclosing construct is also
sometimes necessary. The {@link #setParentAttribute(Key, Object value)} 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 {@link #enableGetChildAttribute} method in an enclosed context
enables the enclosing context to use {@link #getChildAttribute(Object construct, Key)}
to get the attribute from a specific enclosed construct.
Sharing Attributes Between Analyzers
The keys returned by two calls to the {@link #key} 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
{@link #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) . |
Method Summary | |
void |
enableGetChildAttribute()
Enables the enclosing context to use (@link #getChildAttribute} to get the the value of an attribute set in this context. |
Analyzer |
getAnalyzer(java.lang.Class 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. |
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. |
DocumentAdapter |
getDocument()
Gets the document currently being traversed. |
DocumentAdapter |
getDocument(Workspace workspace,
Project project,
java.net.URL url)
Gets the document corresponding to a workspace, project, and url. |
AuditContext |
getEnclosingContext()
Gets the context of the enclosing construct of this context. |
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. |
Location |
getLocation()
Gets the location of the construct currently being traversed. |
int |
getOffset()
Gets the character offset of the construct currently being traversed. |
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. |
java.lang.String |
getText(java.lang.Object construct)
Gets the text of a construct in the document currently being traversed. |
Workspace |
getWorkspace()
Gets the workspace currently being traversed, or null if the root is currently being traversed. |
AuditContext.Key |
key(java.lang.Object object)
Gets a key for an attribute visible only to this analyzer. |
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,
DocumentAdapter document,
java.lang.Object construct)
Reports a rule violation for a construct. |
ViolationReport |
report(Rule rule,
Location location)
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 document. |
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. |
Method Detail |
public AuditContext getEnclosingContext()
public int getDepth()
public DocumentAdapter getDocument()
public Workspace getWorkspace()
public Project getProject()
public Location getLocation()
public java.lang.Object getConstruct()
public java.lang.String getText()
public int getLineOffset()
public int getOffset()
public int getLength()
public java.lang.String getText(java.lang.Object construct)
public Analyzer getAnalyzer(java.lang.Class analyzerClass)
public DocumentAdapter getDocument(Workspace workspace, Project project, java.net.URL url)
public 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.public 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.public 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)
public 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)
public 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)
public java.lang.Object getAttribute(AuditContext.Key key)
key
- A key identifying the attribute to get.
public 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
.public 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
.public 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)
public 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)
public 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)
public void enableGetChildAttribute()
getChildAttribute(java.lang.Object, oracle.jdeveloper.audit.analyzer.AuditContext.Key)
,
setAttribute(oracle.jdeveloper.audit.analyzer.AuditContext.Key, java.lang.Object)
public 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.public 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 document
currently being visited by Audit.
See the class overview
for more information.
rule
- The rule violated.construct
- The violating construct.public ViolationReport report(Rule rule, DocumentAdapter document, 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 getDocument()
getDocument(Workspace, Project, URL)
and Location.getDocument()
for ways to obtain a document.
See the class overview
for more information.
rule
- The rule violated.document
- The document containing the violationg construct.construct
- The violating construct.public 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 {@link Location) of the the violating construct.public void report(Metric metric, java.lang.Object measurement)
metric
- The metric measured.measurement
- The value that was measured.public void report(Metric metric, int measurement)
metric
- The metric measured.measurement
- The value that was measured.public void report(Metric metric, float measurement)
metric
- The metric measured.measurement
- The value that was measured.
|
Extension SDK | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright © 1997, 2004, Oracle. All rights reserved.