oracle.jdeveloper.audit.transform

Class Transform

java.lang.Object

oracle.jdeveloper.audit.extension.ExtensionBean

oracle.jdeveloper.audit.transform.Transform

Direct Known Subclasses:

CompositeTransform

public abstract class Transform
extends ExtensionBean

A source code transform. Concrete subclasses of this class implement single source transformations at one or more source locations. This base class supplies name and label methods which allow the Audit framework to describe the transform. Concrete subclasses must supply one or more 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 Rules, 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.

Constructor Summary

Constructors

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.

Method Summary

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

Methods inherited from class oracle.jdeveloper.audit.extension.ExtensionBean

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

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Transform

protected Transform(TransformAdapter adapter)

Creates a transform for the mutation model provided by a 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.

Parameters:

adapter - The adapter for the mutation model used by this transform.

Transform

protected Transform()

Creates a transform for the mutation model or models provided by 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.

Method Detail

copyInternalState

protected void copyInternalState(ExtensionBean bean,
                                 java.util.Map<java.lang.String,ExtensionBean> context)
                          throws java.lang.reflect.InvocationTargetException

Description copied from class: ExtensionBean

Copies internal subclass state as part of creating a copy of this bean.

Overrides:

copyInternalState in class ExtensionBean

Parameters:

bean - The partially initialized copy.

context - A map which allows subclasses to preserve object identity when copying a graph of extension beans.

Throws:

java.lang.reflect.InvocationTargetException

See Also:

ExtensionBean.createCopy(java.util.Map<java.lang.String, oracle.jdeveloper.audit.extension.ExtensionBean>)

createContexts

public TransformContext[] createContexts(Violation violation)

Creates the TransformContexts 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.:

   return new TransformContext[]{adapter.newWriteContext(this, violation)};
 

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 isApplicable, query, and apply methods in sequence for each context returned.

While the typical transform edits existing files, some transforms create, delete, or move files. The Audit framework tracks these distinctions through the shape property of 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.

Parameters:

violation - The violation addressed by the transform.

Returns:

One or more TransformContexts required to evaluate or apply the transform for the violation.

sequenceBegin

public void sequenceBegin()

Notifies the transform that an apply sequence has begun. The default Transform implementation does nothing.

sequenceEnd

public void sequenceEnd()

Notifies the transform that an apply sequence has ended (whether it succeeded or failed). The default 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.

definition

public TransformDefinition definition()

Gets the definition of this bean.

Overrides:

definition in class ExtensionBean

adapter

public TransformAdapter adapter()

Deprecated. Use TransformContext.getAdapter(). If in createContexts(oracle.jdeveloper.audit.service.Violation), create new context (and use no-argument superclass constructor).

Gets the transform adapter used by this transform. This method is deprecated. A transform may have multiple adapters so, depending on the constructor used and whether 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.

condition

public DeferredExpression condition()

Gets the condition for this transform, or null if none.

isEnabled

public boolean isEnabled()

Gets whether this transform is enabled. A disabled transform will not be exposed to a user outside of the profile user interface.

setEnabled

public void setEnabled(boolean enabled)

Sets whether this transform is enabled. A disabled transform will not be exposed to a user outside of the profile user interface.

unboundLabel

public java.lang.String unboundLabel()

Gets the localized label for this transform. The default 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.

See Also:

boundLabel(oracle.jdeveloper.audit.transform.TransformContext)

boundLabel

public java.lang.String boundLabel(TransformContext context)

Gets the localized label for this transform, bound in the context of a specific issue. The default 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}"
 

See Also:

unboundLabel(), TransformDefinition.boundLabel(java.lang.String)