public abstract class Transform extends ExtensionBean
apply
methods that apply the transform, and can supply
isApplicable
methods that evaluate whether the transform is
currently applicable, query
methods that query the user
for transforms that require user input, and isQueryRequired
methods that, when a query method is present, evaluate whether the user
really needs to be queried. The Audit framework discovers transforms through
their attachment to Rule
s, and
uses introspection to find the apply
, isApplicable
,
isQueryRequired
, and query
methods they declare.
Transforms are stateless objects. The Audit framework creates only
one instance of each kind of transform. Transform methods rely on a
context
argument supplied by the Audit framework
to supply the state they need. That state always includes the issue which
the transform addresses; transform methods can share state through the
context when necessary. Transform should not have instance fields.
A transform addresses a single violation and each violation is associated
with a construct in an object model. Different object models handle the
details of mutating an object model (locks, transaction, and so forth)
differently, so the Audit framework delegates this to an implementation of
the abstract TransformAdapter
class. A transform is constructed with
an appropriate transform adapter; for example, a transform for the JDeveloper
Java model (oracle.javatools.parser.java.v2.model
) would be constructed
with a JavaTransformAdapter
. The
apply
, isApplicable
, isQueryRequired
,
and query
methods all require access to the construct, and to
parameters of the violation, so they take two arguments, a
TransformContext
argument, and a construct argument. The actual
declared class of the transform context argument can be a subclass of
TransformContext
, and the actual declared class of the construct
argument can be its class or any supertype of its class. If more than one
apply
, isApplicable
, isQueryRequired
,
or query
method is present, the one with the most specific
matching construct type is invoked.
isApplicable, isQueryRequired, query, and apply Methods
An isApplicable(context,construct) method, if matched, should
return whether the transform can be applied in the context to the construct.
If no isApplicable method is matched, the transform is assumed to
be applicable.
An isQueryRequired(context,construct) method, if matched, should return whether the corresponding query method should be invoked to query the user. If no isQueryRequired method is matched, a query is assumed to be required only if a corresponding query method is present.
A query(context,construct) should query the user using a Swing
dialog and return true unless the user cancels. It should use
TransformContext.setAttribute(java.lang.String, java.lang.Object)
to save query results for apply
to use.
An apply(context,construct) method should apply the transform in
the context. It can assume that any conditions tested isApplicable are still
true. If a query was required, it should use TransformContext.getAttribute(java.lang.String)
to get the query results.
Composite Transforms
Some transforms require modifying a file other than the one containing the
violation, modifying more than one file, chaining to another transform,
and/or using more than one kind of transform adapter. That can be handled
by overriding createContexts(oracle.jdeveloper.audit.service.Violation)
to return one or more alternate
contexts in which to apply the transform. Each TransformContext
can call out a different Location
,
Transform
, and/or TransformAdapter
. When applying a transform,
the framework first calls all the iisApplicable methods in the
order returned from createContexts. If all are true, it then calls all the
isQueryRequired/query methods, if any, in order. If not cancelled, it then
calls all the apply methods in order. If any fail, the partial applies are
rolled back.
Modifier | Constructor and Description |
---|---|
protected |
Transform()
Creates a transform for the mutation model or models provided by
createContexts(oracle.jdeveloper.audit.service.Violation) . |
protected |
Transform(TransformAdapter adapter)
Creates a transform for the mutation model provided by a
TransformAdapter . |
Modifier and Type | Method and Description |
---|---|
TransformAdapter |
adapter()
Deprecated.
Use
TransformContext.getAdapter() . If in createContexts(oracle.jdeveloper.audit.service.Violation) , create new context (and use no-argument
superclass constructor). |
java.lang.String |
boundLabel(TransformContext context)
Gets the localized label for this transform, bound in the context of a
specific issue.
|
DeferredExpression |
condition()
Gets the condition for this transform, or null if none.
|
protected void |
copyInternalState(ExtensionBean bean,
java.util.Map<java.lang.String,ExtensionBean> context)
Copies internal subclass state as part of creating a copy of this bean.
|
TransformContext[] |
createContexts(Violation violation)
Creates the
TransformContext s required to evaluate or apply this
transform for a violation; returns null or an empty array if the contexts
cannot be created. |
TransformDefinition |
definition()
Gets the definition of this bean.
|
boolean |
isEnabled()
Gets whether this transform is enabled.
|
void |
sequenceBegin()
Notifies the transform that an apply sequence has begun.
|
void |
sequenceEnd()
Notifies the transform that an apply sequence has ended (whether it
succeeded or failed).
|
void |
setEnabled(boolean enabled)
Sets whether this transform is enabled.
|
java.lang.String |
unboundLabel()
Gets the localized label for this transform.
|
addPropertyChangeListener, addPropertyChangeListener, createCopy, description, equals, extensionId, extensionLine, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, formattedString, formattedString, formattedString, hashCode, id, label, logError, logError, logWarning, name, propertyDescription, propertyLabel, removePropertyChangeListener, removePropertyChangeListener, setters, string
protected Transform(TransformAdapter adapter)
TransformAdapter
. The Audit framework will inject the values of the
ExtensionBean.id()
, ExtensionBean.extensionId()
, (@link variations}, condition
,
and ExtensionBean.setters
from definitions in an extension manifest. This
constructor should not be used if createContexts(oracle.jdeveloper.audit.service.Violation)
is overridden
(though it continues to be allowed in that case for the sake of
compatibility). If createContexts(oracle.jdeveloper.audit.service.Violation)
is overridden, the
adapter specified here will be ignored.adapter
- The adapter for the mutation model used by this transform.protected Transform()
createContexts(oracle.jdeveloper.audit.service.Violation)
. The Audit framework will inject the values of the ExtensionBean.id()
, ExtensionBean.extensionId()
, (@link variations}, condition
, and
ExtensionBean.setters
fields based on an extension manifest definition. createContexts(oracle.jdeveloper.audit.service.Violation)
must be overridden.protected void copyInternalState(ExtensionBean bean, java.util.Map<java.lang.String,ExtensionBean> context) throws java.lang.reflect.InvocationTargetException
ExtensionBean
copyInternalState
in class ExtensionBean
bean
- The partially initialized copy.context
- A map which allows subclasses to preserve object identity
when copying a graph of extension beans.java.lang.reflect.InvocationTargetException
ExtensionBean.createCopy(java.util.Map<java.lang.String, oracle.jdeveloper.audit.extension.ExtensionBean>)
public TransformContext[] createContexts(Violation violation)
TransformContext
s required to evaluate or apply this
transform for a violation; returns null or an empty array if the contexts
cannot be created.
The default Transform
implementation invokes the
TransformAdapter.newWriteContext(Transform, Violation)
method of its
transform adapter to create a context for this transform at the violation
location, i.e.:
A transform can override this method to use one or more mutation models
at one or more locations. The Audit framework will attempt to match and
invoke transform methods, such as
return new TransformContext[]{adapter.newWriteContext(this, violation)};
isApplicable
, query
, and
apply
methods in sequence for each context returned.
TransformContext
. Of particular note,
for transforms that create or move a file, the location of interest does
not yet exist; the "pending location" is therefore specified as a URL
rather than as a Location
.
To allow a transform to chain from a context that creates or moves a file
to a new URL and a context that edits the file at the new URL, creating
an edit context with a pending location is allowed; the URL should match
the pending location of a preceding create or move context.violation
- The violation addressed by the transform.TransformContext
s required to evaluate or
apply the transform for the violation.public void sequenceBegin()
Transform
implementation does nothing.public void sequenceEnd()
Transform
implementation does
nothing.
This method is provided to allow the methods in the apply sequence, other
than createContexts(oracle.jdeveloper.audit.service.Violation)
and isApplicable
, to use fields to
communicate data such as model constructs which, if not cleared in a timely
fashion, would be considered leaks.public TransformDefinition definition()
definition
in class ExtensionBean
public TransformAdapter adapter()
TransformContext.getAdapter()
. If in createContexts(oracle.jdeveloper.audit.service.Violation)
, create new context (and use no-argument
superclass constructor).createContexts(oracle.jdeveloper.audit.service.Violation)
was overridden, the
adapter returned here may be null, may be the wrong one of multiple
adapters, or may not be the instance the framework is using! Transforms
that override createContexts(oracle.jdeveloper.audit.service.Violation)
should not create an adapter
in the constructor and should create the adapters in createContexts
. Any subsequent need for an adapter should be associated
with a TransformContext
, from which the associated adapter can be
obtained using TransformContext.getAdapter()
. Uses of this method
log a warning through AuditLogger
.public DeferredExpression condition()
public boolean isEnabled()
public void setEnabled(boolean enabled)
public java.lang.String unboundLabel()
Transform
implementation gets the template string using TopLevelDefinition.label()
and binds it using TopLevelDefinition.bind(java.lang.String, java.lang.Object, boolean)
. The template string can reference
properties of the transform.
Any references to properties of a transform context or parameters of a
violation (that would be valid for a transform label bound in the context
of a specific issue) are erased from the template string. This behavior
sometimes allows a single label to be used in both unbound and bound
contexts (e.g., in the Audit profile panel and in an editor light bulb
menu action, respectively), though it must be noted that such cleverness
is unlikely to translate well.public java.lang.String boundLabel(TransformContext context)
Transform
implementation gets the
template string using TransformDefinition.boundLabel(java.lang.String)
, which
returns the first defined of these names:
bound.label
label
and binds it using TopLevelDefinition.bind(java.lang.String, java.lang.Object, boolean)
.
The template string can reference properties of the transform context,
parameters of the violation, and properties of the transform.
For example, a concrete Transform named "rename-field" for which the
violation is expected to have name
and suggestedName
parameters might have the following in its resource bundle:
rename-field.label=Rename Field
rename-field.bound-label=Rename Field "{name}" to "{suggestedName}"