public abstract class TransformationUtility<T extends TransformationUtility>
extends java.lang.Object
implements java.lang.Cloneable
TransformationContext
object, to be used later by other transformation utilities.
TU
.
TransformationOperation
for a specialized transformation utility that
does modify the project
IMPORTANT:
Every TransformationUtility subclass MUST have a public no arguments default constructor,
and also public setters and getters for all properties they want to expose via set(String, String)
.
In addition to that, every setter must return the TransformationUtility instance.Modifier and Type | Field and Description |
---|---|
protected static java.lang.String |
UTILITY_NAME_SYNTAX |
Constructor and Description |
---|
TransformationUtility() |
Modifier and Type | Method and Description |
---|---|
T |
abortOnFailure(boolean abort)
If set to true, abort the whole transformation if validation or execution fails.
|
T |
abortOnFailure(java.lang.String abortionMessage)
Abort the whole transformation if validation or execution fails.
|
T |
absolute(java.lang.String contextAttributeName)
There are two ways to specify the file, or folder, the transformation
utility is suppose to perform against.
|
T |
absolute(java.lang.String contextAttributeName,
java.lang.String additionalRelativePath)
Same as
absolute(String, String) , however, the absolute
file is set with an additional relative path, which is defined via parameter
additionalRelativePath . |
protected void |
applyPropertiesFromContext(TransformationContext transformationContext)
Applies transformation utility properties during transformation time, but
prior to execution (right before it).
|
protected com.paypal.butterfly.extensions.api.Result |
checkDependencies(TransformationContext transformationContext)
Check if any of dependency of this TU failed.
|
protected static void |
checkForBlankString(java.lang.String name,
java.lang.String value)
Check if value is a blank String, if it is, then a
TransformationDefinitionException is thrown. |
protected static void |
checkForEmptyString(java.lang.String name,
java.lang.String value)
Check if value is an empty String, if it is, then a
TransformationDefinitionException is thrown. |
protected static void |
checkForNull(java.lang.String name,
java.lang.Object value)
Check if value is null, if it is, then a
TransformationDefinitionException is thrown. |
T |
clone()
Creates and returns a clone object identical to the original object,
except for the "has been performed" flag, which is set to
false
in the clone object to be returned. |
T |
copy()
Creates and returns a copy object similar to the original object.
|
T |
dependsOn(java.lang.String... dependencies)
Add all transformation utilities this utility depends on.
|
boolean |
equals(java.lang.Object obj)
Compare this instance against the specified object, and return
true only if they are equal.
|
T |
executeIf(java.lang.String conditionAttributeName)
When set, this TU will only execute if this transformation context
attribute is existent and true.
|
T |
executeIf(UtilityCondition utilityCondition)
When set, this TU will only execute if this
utilityCondition object,
executed right before this TU, result in true. |
T |
executeUnless(java.lang.String conditionAttributeName)
When set, this TU will execute, unless this transformation context
attribute is existent and true.
|
protected abstract ExecutionResult |
execution(java.io.File transformedAppFolder,
TransformationContext transformationContext)
The implementation execution of this transformation utility.
|
java.lang.String |
getAbortionMessage()
Returns a message to be logged if a fail happens and transformation has to be aborted
|
protected java.io.File |
getAbsoluteFile(java.io.File transformedAppFolder,
TransformationContext transformationContext)
Returns an absolute path to the file or folder the transformation
utility is supposed to perform against
|
java.lang.String |
getContextAttributeName()
Return the name to be used as key for the result of this utility
when saved into the transformation context.
|
protected java.util.List<java.lang.String> |
getDependencies()
Returns an unmodifiable list of names of utilities this utility instance depends on.
|
abstract java.lang.String |
getDescription()
Returns a short one line, but SPECIFIC, description about the transformation
utility, including mentioning the files and/or folders
to be manipulated.
|
java.lang.String |
getIfConditionAttributeName()
Return the "if" condition attribute name associated with this transformation operation,
or null, if there is none
|
java.lang.String |
getName() |
int |
getOrder()
Returns the execution order for this utility on its parent.
|
com.paypal.butterfly.extensions.api.TransformationUtilityParent |
getParent()
Returns the transformation utility parent
|
protected java.lang.String |
getRelativePath()
Returns relative path (from the application root folder) to the
file or folder the transformation utility is suppose to perform against
|
protected static java.lang.String |
getRelativePath(java.io.File baselineFile,
java.io.File targetFile)
Returns a relative path from
baselineFile to targetFile . |
protected java.lang.String |
getSimpleClassName()
Returns the transformation utility class simple name
(see
Class.getSimpleName() ), or "AnonymousTransformationUtility"
if that is an anonymous class |
TransformationTemplate |
getTransformationTemplate()
Returns the transformation template this utility belongs to.
|
java.lang.String |
getUnlessConditionAttributeName()
Return the "unless" condition attribute name associated with this transformation operation,
or null, if there is none
|
boolean |
hasBeenPerformed()
Returns true only if this utility has already been performed, even
if the execution was skipped.
|
int |
hashCode() |
protected int |
hashCode(int superHashCode,
java.lang.Object... elements)
Calculates and return a hash code starting from the
hash code generated from superclass
|
boolean |
isAbortOnFailure()
Returns whether this operation aborts the transformation or not in
case of an operation failure.
|
boolean |
isFileSet()
Return true only if a file has been set.
|
boolean |
isSaveResult()
This flag indicates whether the value produced by the transformation utility execution,
and also its result object as a whole, should both be saved in the transformation
context object.
|
protected static java.lang.String |
normalizeRelativePathSeparator(java.lang.String relativePath) |
PerformResult |
perform(java.io.File transformedAppFolder,
TransformationContext transformationContext)
Performs the transformation utility against
the application to be transformed.
|
T |
relative(java.lang.String relativePath)
Sets the relative path from the application root folder
to the file or folder the transformation utility should perform against.
|
T |
set(java.lang.String propertyName,
java.lang.String contextAttributeName)
This method allows setting properties in this transformation
utility during transformation time, right before its execution.
|
T |
setContextAttributeName(java.lang.String contextAttributeName)
Set the name to be used as key for the result of this utility
when saved into the transformation context.
|
protected T |
setName(java.lang.String name)
Set this transformation utility instance name.
|
T |
setParent(com.paypal.butterfly.extensions.api.TransformationUtilityParent parent,
int order)
Register this utility to its parent, and also assign it a name
based on the parent name and order of execution.
|
protected T |
setSaveResult(boolean saveResult)
Sets whether or not the value produced by the transformation utility execution,
and also its result object as a whole, should both be saved in the transformation
context object.
|
java.lang.String |
toString() |
boolean |
wasFileExplicitlySet()
Return true only if a file has been set explicitly either via
relative(String) , absolute(String) or absolute(String, String) . |
protected static final java.lang.String UTILITY_NAME_SYNTAX
protected T setName(java.lang.String name)
name
- transformation utility instance namepublic final java.lang.String getName()
public T setContextAttributeName(java.lang.String contextAttributeName)
contextAttributeName
- the name to be used as key for the result of this utility
when saved into the transformation context.public java.lang.String getContextAttributeName()
public final T setParent(com.paypal.butterfly.extensions.api.TransformationUtilityParent parent, int order)
TransformationTemplate
parent
- the parent to be set to this utilityorder
- the order of execution of this utilitypublic com.paypal.butterfly.extensions.api.TransformationUtilityParent getParent()
public TransformationTemplate getTransformationTemplate()
public abstract java.lang.String getDescription()
public int getOrder()
public final T relative(java.lang.String relativePath)
relativePath
- from the application root folder
to the file or folder the transformation utility should be performed againstprotected static java.lang.String normalizeRelativePathSeparator(java.lang.String relativePath)
protected final java.lang.String getRelativePath()
protected final java.io.File getAbsoluteFile(java.io.File transformedAppFolder, TransformationContext transformationContext) throws TransformationUtilityException
transformedAppFolder
- the folder where the transformed application code istransformationContext
- the transformation context objectTransformationUtilityException
protected static java.lang.String getRelativePath(java.io.File baselineFile, java.io.File targetFile)
baselineFile
to targetFile
.
The file separator used is specific to the current OS. If the baseline file
is not entirely within the path to target file, then the target file
absolute path is returned.baselineFile
- the file whose returned relative path should start from.
It must be aa direct or indirect parent file to targetFile
targetFile
- the file whose returned relative path should take tobaselineFile
to targetFile
public final T set(java.lang.String propertyName, java.lang.String contextAttributeName)
contextAttributeName
at the time this transformation utility is executed, a TransformationUtilityException
will be thrown.
TransformationUtilityException
) with
IllegalArgumentException
) as root cause.
propertyName
- the transformation utility Java property namecontextAttributeName
- the name of the transformation context attribute whose
value will be set as the property value right before
executionTransformationUtilityException
- if the transformation context does not have an
attribute named contextAttributeName
TransformationDefinitionException
- if propertyName
is not
an existent Java bean property
in this transformation utility classprotected final void applyPropertiesFromContext(TransformationContext transformationContext) throws TransformationUtilityException
transformationContext
- the transformation context objectTransformationUtilityException
public T absolute(java.lang.String contextAttributeName)
relative(String)
). That should be the chosen option whenever
the relative location is known during transformation template definition time.
getAbsoluteFile(File, TransformationContext)
, relative(String)
and getRelativePath()
contextAttributeName
- the name of the transformation context attribute whose
value will be set as the absolute file right before
executionpublic T absolute(java.lang.String contextAttributeName, java.lang.String additionalRelativePath)
absolute(String, String)
, however, the absolute
file is set with an additional relative path, which is defined via parameter
additionalRelativePath
. This method is powerful because it allows setting
the absolute file using a portion of the location (absolute) that is only known during
transformation time, plus also a second portion of the location (relative) that is
already known during definition time
getAbsoluteFile(File, TransformationContext)
, relative(String)
and getRelativePath()
contextAttributeName
- the name of the transformation context attribute whose
value will be set as the absolute file right before
executionadditionalRelativePath
- an additional relative path to be added to the absolute
file coming from the transformation context. The path
separator will be normalized, similar to what happens
in relative(String)
public PerformResult perform(java.io.File transformedAppFolder, TransformationContext transformationContext) throws TransformationUtilityException
hasBeenPerformed()
has to return true.
applyPropertiesFromContext(TransformationContext)
execution(File, TransformationContext)
transformedAppFolder
- the folder where the transformed application code istransformationContext
- the transformation context objectTransformationUtilityException
public final T abortOnFailure(boolean abort)
null
.
Use abortOnFailure(String)
instead to set abort on failure to true, but also
set a custom abortion message.
abort
- if set to true, abort the whole transformation if validation or execution fails.
If not, just state a warning, aborts the operation execution onlypublic final T abortOnFailure(java.lang.String abortionMessage)
abortOnFailure(true)
, but
it also allows setting an abortion message.
Notice that abortion here means interrupting the transformation.
It does not mean rolling back the changes that have might already been done
by this transformation operation by the time it failedabortionMessage
- a message to be logged if transformation has to be abortedpublic java.lang.String getAbortionMessage()
public final boolean isAbortOnFailure()
public boolean isSaveResult()
Log
,
where no value will be produced and nothing should be saved to the
transformation context attributeprotected T setSaveResult(boolean saveResult)
isSaveResult()
.saveResult
- if the value produced by the transformation utility execution,
and also its result object as a whole, should both be saved in the transformation
context objectpublic final boolean hasBeenPerformed()
public final T dependsOn(java.lang.String... dependencies)
PerformResult.Type.EXECUTION_RESULT
,
and the execution result type is one of the following:
TUExecutionResult.Type.NULL
(for TUs only)TUExecutionResult.Type.ERROR
(for TUs only)TOExecutionResult.Type.ERROR
(for TOs only)dependencies
- the names of all transformation utilities this utility depends onprotected final java.util.List<java.lang.String> getDependencies()
dependsOn(String...)
.protected com.paypal.butterfly.extensions.api.Result checkDependencies(TransformationContext transformationContext)
dependsOn(String...)
to find out the dependency failure criteriatransformationContext
- the transformation context object, in this case used
to check all past executed utilitiespublic final T executeIf(java.lang.String conditionAttributeName)
conditionAttributeName
- the name of the transformation context attribute which
holds a boolean value used to evaluate if this
utility should be executed or notpublic final T executeIf(UtilityCondition utilityCondition)
utilityCondition
object,
executed right before this TU, result in true.
executeIf(String)
:
attribute
) with the condition result, this method is based on the direct execution of the UtilityCondition
objectUtilityCondition
object is always executed necessarily against the same file set in the transformation utility it is being used. Because of that, any value set in the condition itself via relative(String)
or absolute(String)
is ignored.UtilityCondition
object does not produce any TCA, neither its result value or result object. Instead, it hands its result directly to the TU, so that the condition can be evaluated just before the TU executes (or not, if it fails).UtilityCondition
object does not exist from a transformation template point of view. That means this method is totally different than adding a new UtilityCondition
object by calling TransformationTemplate.add(TransformationUtility)
.UtilityCondition
object is not the one used, but a copy of itutilityCondition
- the condition to be executed and evaluated right before this TUpublic final T executeUnless(java.lang.String conditionAttributeName)
conditionAttributeName
- the name of the transformation context attribute which
holds a boolean value used to evaluate if this
utility should be executed or notpublic java.lang.String getIfConditionAttributeName()
public java.lang.String getUnlessConditionAttributeName()
protected abstract ExecutionResult execution(java.io.File transformedAppFolder, TransformationContext transformationContext)
isSaveResult()
returns false.
ExecutionResult
error object.transformedAppFolder
- the folder where the transformed application code istransformationContext
- the transformation context objectpublic final boolean isFileSet()
TransformationUtility
has its file set automatically by
default to "" which means the root of the application. That is NOT the case though for TransformationOperation
object, which must set them explicitly via relative(String)
or absolute(String)
.public final boolean wasFileExplicitlySet()
relative(String)
, absolute(String)
or absolute(String, String)
.
If set via relative(String)
it will only return true if set to anything other than "", which would mean the root of the application.relative(String)
, absolute(String)
or absolute(String, String)
public java.lang.String toString()
toString
in class java.lang.Object
public T clone()
false
in the clone object to be returned. See hasBeenPerformed()
.clone
in class java.lang.Object
public T copy()
protected static void checkForBlankString(java.lang.String name, java.lang.String value) throws TransformationDefinitionException
TransformationDefinitionException
is thrown.
name
- the name of the propertyvalue
- the value to be verifiedTransformationDefinitionException
- if check failsprotected static void checkForEmptyString(java.lang.String name, java.lang.String value) throws TransformationDefinitionException
TransformationDefinitionException
is thrown.
name
- the name of the propertyvalue
- the value to be verifiedTransformationDefinitionException
- if check failsprotected static void checkForNull(java.lang.String name, java.lang.Object value) throws TransformationDefinitionException
TransformationDefinitionException
is thrown.
name
- the name of the propertyvalue
- the value to be verifiedTransformationDefinitionException
- if check failspublic boolean equals(java.lang.Object obj)
equals
in class java.lang.Object
obj
- the object to be compared against this instancepublic int hashCode()
hashCode
in class java.lang.Object
protected final int hashCode(int superHashCode, java.lang.Object... elements)
superHashCode
- hash code generated from superclasselements
- array of Objects to be used to generate hashcode.
These elements should be the attributes used in
the equals methodprotected java.lang.String getSimpleClassName()
Class.getSimpleName()
), or "AnonymousTransformationUtility"
if that is an anonymous class