com.paypal.butterfly.extensions.api

Class TransformationUtility<T extends TransformationUtility>

java.lang.Object

com.paypal.butterfly.extensions.api.TransformationUtility<T>

All Implemented Interfaces:

Cloneable

Direct Known Subclasses:

Abort, ContextAttributeRetriever, FilterFiles, Log, ManualInstruction, MapValue, MultipleOperations, TransformationOperation, TransformationUtilityGroup, TransformationUtilityLoop, UtilityCondition

public abstract class TransformationUtility<T extends TransformationUtility>
extends Object
implements Cloneable

Gathers information about the project to be transformed without applying any modification on it. It is the key element of Butterfly transformation engine. The result information is saved in the TransformationContext object, to be used later by other transformation utilities.
Transformation utilities are executed against the to be transformed project, based on the absolute project root folder defined in runtime, and a relative path to a target file or folder, defined in compilation time.
Transformation utilities are also known by TU.
An example of a transformation operation utility would be to find recursively a particular file based on its name and from a particular location (which would be relative to the project root folder) See 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.

Author:

facarvalho

Field Summary

Fields

Modifier and Type	Field and Description
protected static String	UTILITY_NAME_SYNTAX

Constructor Summary

Constructors

Constructor and Description
TransformationUtility()

Method Summary

Modifier and Type	Method and Description
boolean	abortOnFailure() Returns whether this operation aborts the transformation or not in case of an operation failure.
T	abortOnFailure(boolean abort) If set to true, abort the whole transformation if validation or execution fails.
T	abortOnFailure(boolean abort, String abortionMessage) If set to true, abort the whole transformation if validation or execution fails.
T	absolute(String contextAttributeName) There are two ways to specify the file, or folder, the transformation utility is suppose to perform against.
T	absolute(String contextAttributeName, 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(String name, String value) Check if value is a blank String, if it is, then a TransformationDefinitionException is thrown.
protected static void	checkForEmptyString(String name, String value) Check if value is an empty String, if it is, then a TransformationDefinitionException is thrown.
protected static void	checkForNull(String name, 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(String... dependencies) Add all transformation utilities this utility depends on.
boolean	equals(Object obj) Compare this instance against the specified object, and return true only if they are equal.
T	executeIf(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(String conditionAttributeName) When set, this TU will execute, unless this transformation context attribute is existent and true.
protected abstract ExecutionResult	execution(File transformedAppFolder, TransformationContext transformationContext) The implementation execution of this transformation utility.
String	getAbortionMessage() Returns a message to be logged if a fail happens and transformation has to be aborted
protected File	getAbsoluteFile(File transformedAppFolder, TransformationContext transformationContext) Returns an absolute path to the file or folder the transformation utility is supposed to perform against
String	getContextAttributeName() Return the name to be used as key for the result of this utility when saved into the transformation context.
protected List<String>	getDependencies() Returns an unmodifiable list of names of utilities this utility instance depends on.
abstract String	getDescription() Returns a short one line, but SPECIFIC, description about the transformation utility, including mentioning the files and/or folders to be manipulated.
String	getIfConditionAttributeName() Return the "if" condition attribute name associated with this transformation operation, or null, if there is none
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 String	getRelativePath() Returns relative path (from the application root folder) to the file or folder the transformation utility is suppose to perform against
static String	getRelativePath(File baselineFile, File targetFile) Returns a relative path from baselineFile to targetFile.
TransformationTemplate	getTransformationTemplate() Returns the transformation template this utility belongs to
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
int	hashCode()
protected int	hashCode(int superHashCode, Object... elements) Calculates and return a hash code starting from the hash code generated from superclass
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 String	normalizeRelativePathSeparator(String relativePath)
PerformResult	perform(File transformedAppFolder, TransformationContext transformationContext) Performs the transformation utility against the application to be transformed This is the one called by the transformation engine, and regardless of any customization it could have, it must always: 1- Call applyPropertiesFromContext(TransformationContext) 2- Call execution(File, TransformationContext) This method is NOT supposed to be overwritten, unless you really know what you are doing.
T	relative(String relativePath) Sets the relative path from the application root folder to the file or folder the transformation utility should perform against.
T	set(String propertyName, String contextAttributeName) This method allows setting properties in this transformation utility during transformation time, right before its execution.
T	setContextAttributeName(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(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.
String	toString()
boolean	wasFileExplicitlySet() Return true only if a file has been set explicitly either via relative(String) or absolute(String).

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

UTILITY_NAME_SYNTAX

protected static final String UTILITY_NAME_SYNTAX

See Also:

Constant Field Values

Constructor Detail

TransformationUtility

public TransformationUtility()

Method Detail

setName

protected T setName(String name)

Set this transformation utility instance name. If not set, a default name will be assigned at the time it is added to a parent.

Parameters:

name - transformation utility instance name

Returns:

this transformation utility instance

getName

public final String getName()

setContextAttributeName

public T setContextAttributeName(String contextAttributeName)

Set the name to be used as key for the result of this utility when saved into the transformation context. If this is not set, or null, then the utility name will be used instead

Parameters:

contextAttributeName - the name to be used as key for the result of this utility when saved into the transformation context.

Returns:

this transformation utility instance

getContextAttributeName

public String getContextAttributeName()

Return the name to be used as key for the result of this utility when saved into the transformation context. If it is null, then the utility name will be used instead

Returns:

the name to be used as key for the result of this utility when saved into the transformation context

setParent

public final 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.
Usually the parent is a TransformationTemplate

Parameters:

parent - the parent to be set to this utility

order - the order of execution of this utility

Returns:

this transformation utility instance

getParent

public com.paypal.butterfly.extensions.api.TransformationUtilityParent getParent()

Returns the transformation utility parent

Returns:

the transformation utility parent

getTransformationTemplate

public TransformationTemplate getTransformationTemplate()

Returns the transformation template this utility belongs to

Returns:

the transformation template this utility belongs to

getDescription

public abstract String getDescription()

Returns a short one line, but SPECIFIC, description about the transformation utility, including mentioning the files and/or folders to be manipulated. This is supposed to be an one line statement about the specific transformation utility that was executed. This would be used for example in log statements or user interfaces.

Returns:

a short one line, but specific, description about the transformation utility

getOrder

public int getOrder()

Returns the execution order for this utility on its parent. Value -1 means it has not been registered to any parent yet, while 1 means first.

Returns:

the execution order for this utility on its parent

relative

public final T relative(String relativePath)

Sets the relative path from the application root folder to the file or folder the transformation utility should perform against. The path separator is automatically normalized, so there are three valid options when separating folders in the path:

1. File.separatorChar (e.g. relative("myFolder" + File.separator + "file.txt")
2. Forward slash (e.g. relative("myFolder/file.txt")
3. Two backward slashes (e.g. relative("myFolder\\file.txt")

The slashes are replaced by OS specific separator char in runtime.
The default value is ".". which means the root of the transformed application

Parameters:

relativePath - from the application root folder to the file or folder the transformation utility should be performed against

Returns:

this transformation utility instance

normalizeRelativePathSeparator

protected static String normalizeRelativePathSeparator(String relativePath)

getRelativePath

protected final String getRelativePath()

Returns relative path (from the application root folder) to the file or folder the transformation utility is suppose to perform against

Returns:

relative path (from the application root folder) to the file or folder the transformation utility is suppose to perform against

getAbsoluteFile

protected final File getAbsoluteFile(File transformedAppFolder,
                                     TransformationContext transformationContext)
                              throws TransformationUtilityException

Returns an absolute path to the file or folder the transformation utility is supposed to perform against

Parameters:

transformedAppFolder - the folder where the transformed application code is

transformationContext - the transformation context object

Returns:

an absolute path to the file or folder the transformation utility is suppose to perform against

Throws:

TransformationUtilityException

getRelativePath

public static String getRelativePath(File baselineFile,
                                     File targetFile)

Returns a relative path from 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

Parameters:

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 to

Returns:

a relative path from baselineFile to targetFile

set

public final T set(String propertyName,
                   String contextAttributeName)

This method allows setting properties in this transformation utility during transformation time, right before its execution. This is very useful when the property value is not known during transformation definition. Any attribute stored in the transformation context can be used as the value to be set to the property. In most of the cases the result of a prior transformation utility is used as property value. Notice that, because this feature relies on reflection, it is not cheap, especially because it happens during transformation time. So, use it only when really necessary.

Parameters:

propertyName - the transformation utility Java property name

contextAttributeName - the name of the transformation context attribute whose value will be set as the property value right before execution

Returns:

this transformation utility instance

applyPropertiesFromContext

protected final void applyPropertiesFromContext(TransformationContext transformationContext)
                                         throws TransformationUtilityException

Applies transformation utility properties during transformation time, but prior to execution (right before it). The properties values are gotten from the transformation context object.

Parameters:

transformationContext - the transformation context object

Throws:

TransformationUtilityException

absolute

public T absolute(String contextAttributeName)

There are two ways to specify the file, or folder, the transformation utility is suppose to perform against. The default and most commons one is by setting the relative path to it, which is done usually via the constructor or relative(String)). That should be the chosen option whenever the relative location is known during transformation template definition time.
However, sometimes that is not possible because that location will only be known during transformation time. In cases like this, usually another utility is used to find that location first, and then save it as transformation context attribute. In this case, this setter here can be used to set the absolute file location based on such context attribute. Whenever this is set, the relative path attribute is ignored.
See also getAbsoluteFile(File, TransformationContext), relative(String) and getRelativePath()

Parameters:

contextAttributeName - the name of the transformation context attribute whose value will be set as the absolute file right before execution

Returns:

this transformation utility instance

absolute

public T absolute(String contextAttributeName,
                  String additionalRelativePath)

Same as 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
See also getAbsoluteFile(File, TransformationContext), relative(String) and getRelativePath()

Parameters:

contextAttributeName - the name of the transformation context attribute whose value will be set as the absolute file right before execution

additionalRelativePath - 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)

Returns:

this transformation utility instance

perform

public PerformResult perform(File transformedAppFolder,
                             TransformationContext transformationContext)
                      throws TransformationUtilityException

Performs the transformation utility against the application to be transformed
This is the one called by the transformation engine, and regardless of any customization it could have, it must always:

1. 1- Call applyPropertiesFromContext(TransformationContext)
2. 2- Call execution(File, TransformationContext)

This method is NOT supposed to be overwritten, unless you really know what you are doing.

Parameters:

transformedAppFolder - the folder where the transformed application code is

transformationContext - the transformation context object

Returns:

the result

Throws:

TransformationUtilityException

abortOnFailure

public final T abortOnFailure(boolean abort)

If set to true, abort the whole transformation if validation or execution fails. If not, just state a warning, aborts the operation execution only. 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 failed

Parameters:

abort - if set to true, abort the whole transformation if validation or execution fails. If not, just state a warning, aborts the operation execution only

Returns:

this transformation utility instance

abortOnFailure

public final T abortOnFailure(boolean abort,
                              String abortionMessage)

If set to true, abort the whole transformation if validation or execution fails. If not, just state a warning, aborts the operation execution only. 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 failed

Parameters:

abort - if set to true, abort the whole transformation if validation or execution fails. If not, just state a warning, aborts the operation execution only

abortionMessage - a message to be logged if a fail happens and transformation has to be aborted

Returns:

this transformation utility instance

getAbortionMessage

public String getAbortionMessage()

Returns a message to be logged if a fail happens and transformation has to be aborted

Returns:

a message to be logged if a fail happens and transformation has to be aborted

abortOnFailure

public final boolean abortOnFailure()

Returns whether this operation aborts the transformation or not in case of an operation failure. Notice that this method does NOT change the state this object in any ways, it is just a getter.

Returns:

true only if this operation aborts the transformation or not in case of an operation failure

isSaveResult

public 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.
In most cases it should do so, because that is the main purpose of every transformation utility, to produce and share useful data with other transformation utilities and operations.
However, there are rare cases, for example Log, where no value will be produced and nothing should be saved to the transformation context attribute

Returns:

true only 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 object

setSaveResult

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. See also isSaveResult().

Parameters:

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 object

Returns:

this transformation utility instance

hasBeenPerformed

public final boolean hasBeenPerformed()

Returns true only if this utility has already been performed

Returns:

true only if this utility has already been performed

dependsOn

public final T dependsOn(String... dependencies)

Add all transformation utilities this utility depends on. Notice that this is not cumulative, meaning if this method has been called previously, that dependencies set will be entirely replaced by this new one.
This notion of "dependency" among TUs help resilience in two ways:

1. If TU B depends on TU A, and if TU A "fails" but doesn't abort transformation, then TU B would be skipped
2. If TU B depends on TU A, then that means TU A is necessarily supposed to be executed first, if not, TU B will be skipped

The term "fails" in this context means the perform result is of one of these types:

1. PerformResult.Type.ERROR
2. PerformResult.Type.SKIPPED_CONDITION
3. PerformResult.Type.SKIPPED_DEPENDENCY

A dependency failure is also possible if perform result type is PerformResult.Type.EXECUTION_RESULT, and the execution result type is one of the following:

1. TUExecutionResult.Type.NULL (for TUs only)
2. TUExecutionResult.Type.ERROR (for TUs only)
3. TOExecutionResult.Type.ERROR (for TOs only)

See also:

• checkDependencies(TransformationContext)
• Result.dependencyFailureCheck()
• TUExecutionResult.dependencyFailureCheck()
• TOExecutionResult.dependencyFailureCheck()
• PerformResult.dependencyFailureCheck()

Parameters:

dependencies - the names of all transformation utilities this utility depends on

Returns:

this transformation utility instance

getDependencies

protected final List<String> getDependencies()

Returns an unmodifiable list of names of utilities this utility instance depends on. See also dependsOn(String...).

Returns:

an unmodifiable list of names of utilities this utility instance depends on

checkDependencies

protected com.paypal.butterfly.extensions.api.Result checkDependencies(TransformationContext transformationContext)

Check if any of dependency of this TU failed. If that is true, returns a result object stating so. If not, returns null. If this TU has no dependencies it also returns null. See dependsOn(String...) to find out the dependency failure criteria

Parameters:

transformationContext - the transformation context object, in this case used to check all past executed utilities

Returns:

a result object if any of dependency of this utility failed, or null, if that is not the case, or if this utility does not have dependencies

executeIf

public final T executeIf(String conditionAttributeName)

When set, this TU will only execute if this transformation context attribute is existent and true. In other words, it will execute if not null and, if of Boolean type, true

Parameters:

conditionAttributeName - the name of the transformation context attribute which holds a boolean value used to evaluate if this utility should be executed or not

Returns:

this transformation utility instance

executeIf

public final T executeIf(UtilityCondition utilityCondition)

When set, this TU will only execute if this utilityCondition object, executed right before this TU, result in true.
Differences between this approach and executeIf(String):

1. Instead of relying on a TCA (attribute) with the condition result, this method is based on the direct execution of the UtilityCondition object
2. The UtilityCondition 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.
3. The 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).
4. The 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).

The actual UtilityCondition object is not the one used, but a copy of it

Parameters:

utilityCondition - the condition to be executed and evaluated right before this TU

Returns:

this transformation utility instance

executeUnless

public final T executeUnless(String conditionAttributeName)

When set, this TU will execute, unless this transformation context attribute is existent and true. In other words, it will execute, unless if not null and, if of Boolean type, true

Parameters:

conditionAttributeName - the name of the transformation context attribute which holds a boolean value used to evaluate if this utility should be executed or not

Returns:

this transformation utility instance

getIfConditionAttributeName

public String getIfConditionAttributeName()

Return the "if" condition attribute name associated with this transformation operation, or null, if there is none

Returns:

the "if" condition attribute name associated with this transformation operation

getUnlessConditionAttributeName

public String getUnlessConditionAttributeName()

Return the "unless" condition attribute name associated with this transformation operation, or null, if there is none

Returns:

the "unless" condition attribute name associated with this transformation operation

execution

protected abstract ExecutionResult execution(File transformedAppFolder,
                                             TransformationContext transformationContext)

The implementation execution of this transformation utility. The returned object is the result of the execution and is always automatically saved in the transformation context as a new attribute (whose key is the name of the transformation utility), unless isSaveResult() returns false.
Important: this method MUST NEVER return null, and it must catch its executions exceptions and wrap them into a ExecutionResult error object.

Parameters:

transformedAppFolder - the folder where the transformed application code is

transformationContext - the transformation context object

Returns:

an object with the result of this execution, to be better defined by the concrete utility class, since its type is generic

isFileSet

public final boolean isFileSet()

Return true only if a file has been set. Every 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).

Returns:

true only if a file has been set

wasFileExplicitlySet

public final boolean wasFileExplicitlySet()

Return true only if a file has been set explicitly either via relative(String) or absolute(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.

Returns:

true only if a file has been set explicitly either via relative(String) or absolute(String)

toString

public String toString()

Overrides:

toString in class Object

clone

public 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. See hasBeenPerformed().

Overrides:

clone in class Object

Returns:

the new object created as result of the clone operation

copy

public T copy()

Creates and returns a copy object similar to the original object. All attributes are the same, except for the following ones, which are reset:

1. parent
2. name
3. order
4. context attribute name
5. file relative and absolute path
6. has been performed flag

Returns:

the new object created as result of the copy operation

checkForBlankString

protected static void checkForBlankString(String name,
                                          String value)
                                   throws TransformationDefinitionException

Check if value is a blank String, if it is, then a TransformationDefinitionException is thrown.
This check is used for mandatory properties where value cannot be null neither an empty string.

Parameters:

name - the name of the property

value - the value to be verified

Throws:

TransformationDefinitionException - if check fails

checkForEmptyString

protected static void checkForEmptyString(String name,
                                          String value)
                                   throws TransformationDefinitionException

Check if value is an empty String, if it is, then a TransformationDefinitionException is thrown.
This check is used for optional properties where value can be null, but not an empty string.

Parameters:

name - the name of the property

value - the value to be verified

Throws:

TransformationDefinitionException - if check fails

checkForNull

protected static void checkForNull(String name,
                                   Object value)
                            throws TransformationDefinitionException

Check if value is null, if it is, then a TransformationDefinitionException is thrown.
This check is used for mandatory non-String properties, where value cannot be null

Parameters:

name - the name of the property

value - the value to be verified

Throws:

TransformationDefinitionException - if check fails

equals

public boolean equals(Object obj)

Compare this instance against the specified object, and return true only if they are equal. Notice though that the fact that the utility has been performed or not will NOT be used for this comparison.

Overrides:

equals in class Object

Parameters:

obj - the object to be compared against this instance

Returns:

true only if they are equal

hashCode

public int hashCode()

Overrides:

hashCode in class Object

hashCode

protected final int hashCode(int superHashCode,
                             Object... elements)

Calculates and return a hash code starting from the hash code generated from superclass

Parameters:

superHashCode - hash code generated from superclass

elements - array of Objects to be used to generate hashcode. These elements should be the attributes used in the equals method

Returns:

the generated hashcode