Extension SDK 9.0.5

oracle.jdeveloper.audit.analyzer
Interface AuditContext


public interface AuditContext

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
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.

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 child, Key, Object value) 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 {@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

getEnclosingContext

public AuditContext getEnclosingContext()
Gets the context of the enclosing construct of this context.


getDepth

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


getDocument

public DocumentAdapter getDocument()
Gets the document currently being traversed. Documents are returned even if the construct currently being traversed is the root, a workspace, or a project.


getWorkspace

public Workspace getWorkspace()
Gets the workspace currently being traversed, or null if the root is currently being traversed.


getProject

public Project getProject()
Gets the project currently being traversed, or null if the root or a workspace is currently being traversed.


getLocation

public Location getLocation()
Gets the location of the construct currently being traversed.


getConstruct

public java.lang.Object getConstruct()
Gets the construct currently being traversed.


getText

public java.lang.String getText()
Gets the text of the construct currently being traversed.


getLineOffset

public int getLineOffset()
Gets the line offset (zero-based) of the first character of the construct currently being traversed.


getOffset

public int getOffset()
Gets the character offset of the construct currently being traversed.


getLength

public int getLength()
Gets the length of the construct currently being traversed.


getText

public java.lang.String getText(java.lang.Object construct)
Gets the text of a construct in the document currently being traversed.


getAnalyzer

public Analyzer getAnalyzer(java.lang.Class analyzerClass)
Gets the instance of an analyzer class used for the current audit.


getDocument

public DocumentAdapter getDocument(Workspace workspace,
                                   Project project,
                                   java.net.URL url)
Gets the document corresponding to a workspace, project, and url. This method provides the argument required to report a construct or related construct from outside the current document.


key

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public void enableGetChildAttribute()
Enables the enclosing context to use (@link #getChildAttribute} 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)

report

public ViolationReport report(Rule rule)
Reports a rule violation for the current construct. 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.

Parameters:
rule - The rule violated.
Returns:
a ViolationReport which allows the violation to be modified.

report

public ViolationReport report(Rule rule,
                              java.lang.Object construct)
Reports a rule violation for a construct in the current document. 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.

Parameters:
rule - The rule violated.
construct - The violating construct.

report

public ViolationReport report(Rule rule,
                              DocumentAdapter document,
                              java.lang.Object construct)
Reports a rule violation for a 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.

Parameters:
rule - The rule violated.
document - The document containing the violationg construct.
construct - The violating construct.

report

public ViolationReport report(Rule rule,
                              Location location)
Reports a rule violation for a construct. report returns a ViolationReport which allows parameters and other attributes to be added to the violation.See the class overview for more information.

Parameters:
rule - The rule violated.
location - The {@link Location) of the the violating construct.

report

public void report(Metric metric,
                   java.lang.Object measurement)
Reports a measurement for the current construct.

Parameters:
metric - The metric measured.
measurement - The value that was measured.

report

public void report(Metric metric,
                   int measurement)
Reports an int-valued measurement for the current construct.

Parameters:
metric - The metric measured.
measurement - The value that was measured.

report

public void report(Metric metric,
                   float measurement)
Reports a float-valued measurement for the current construct.

Parameters:
metric - The metric measured.
measurement - The value that was measured.

Extension SDK

 

Copyright © 1997, 2004, Oracle. All rights reserved.