com.ibm.di.migration
Class BaseMigrationUtility

java.lang.Object
  com.ibm.di.migration.BaseMigrationUtility

Direct Known Subclasses:

MigrateAmConfig, PluginMigrationUtility

public abstract class BaseMigrationUtility
extends Object

This is a base class which could be extended in order to provide an utility for migrating configuration files. This class provides the ability to work with Java properties files (descendant classes can change this). It expects the child classes to define the changes, that will be done over the configuration file, using the defineChanges(Map) method.

Since:

TDI 7.1

Field Summary

protected static ResourceHash	resHash
protected static String	SWITCH_HELP The switch used for requesting help information.
protected static String	SWITCH_MIG_FILE The switch used for providing the source file to be migrated.
protected static String	SWITCH_MIG_FILE_BAKUP The switch used for providing the name of the backup file.
protected static String	SWITCH_MIG_FILE_NEW The switch used for providing the name of the file used for output of the migration.
protected static String	SWITCH_VERBOSE The switch used for enabling verbose output.

Constructor Summary

BaseMigrationUtility(String[] args, org.apache.log4j.Logger log)
Create an instance by passing in the command line arguments.

Method Summary

protected void	applyChanges(StringBuilder sb, Map<String,String> props, List<ChangeDescription> chngs) Called to apply the defined changes to the in-memory buffer.
protected void	backupFile() Called to create a copy of the source file.
protected abstract List<ChangeDescription>	defineChanges(Map<String,String> props) Defines the changes that will be done over the properties of the source file.
protected List<String>	getCommandStandaloneValuesList()
protected String	getCommandValueBySwitch(String switchStr) Requests the value of the switch which have been passed to the command line.
org.apache.log4j.Logger	getLog()
protected void	interpretCommandLineOptions() Called to parse the passed command line arguments.
boolean	isHelpRequested()
protected boolean	isSwitch(String arg) Checks whether the specified string complies with the syntax of a command line switch.
boolean	isVerboseMode()
void	migrateFile() This is the entry point which drives the common flow of a standard migration utility.
protected void	parseArgs(String[] args) Parses the command line arguments by filling commandLineOptions and commandValuesList structures.
protected Map<String,String>	parseFile(File srcFile) Parses the source file.
protected Map<String,String>	parseFile(InputStream source) Parses the source stream.
protected void	performPropertyAddition(StringBuilder sb, Map<String,String> props, ChangeDescription change) Perform actual addition of the new property.
protected void	performPropertyCommenting(StringBuilder sb, Map<String,String> props, ChangeDescription change) Perform actual commenting of an existing property.
protected void	performPropertyDeletion(StringBuilder sb, Map<String,String> propsAvailable, ChangeDescription change) Perform actual deletion of the existing property.
protected void	performPropertyModification(StringBuilder sb, Map<String,String> props, ChangeDescription change) Perform actual modification of the existing property.
protected void	performPropertyUncommenting(StringBuilder sb, Map<String,String> props, ChangeDescription change) Perform actual uncommenting of the commented property.
protected void	printHelpInformation() Called to print the help information to the stdOut.
protected StringBuilder	readFile(File srcFile) Called to read the configuration file and put its content into the returned StringBuilder.
protected void	setLog(org.apache.log4j.Logger log) Sets the provided log for this utility.
protected void	validateCommandLineOptions() Called to check whether the parsed arguments are valid enough for the migration utility to continue.
protected void	writeFile(StringBuilder sb) Called to write the in-memory buffer to the destination file.

Methods inherited from class java.lang.Object

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

Field Detail

resHash

protected static final ResourceHash resHash

SWITCH_MIG_FILE

protected static final String SWITCH_MIG_FILE

The switch used for providing the source file to be migrated.

See Also:

Constant Field Values

SWITCH_MIG_FILE_BAKUP

protected static final String SWITCH_MIG_FILE_BAKUP

The switch used for providing the name of the backup file.

See Also:

Constant Field Values

SWITCH_MIG_FILE_NEW

protected static final String SWITCH_MIG_FILE_NEW

The switch used for providing the name of the file used for output of the migration.

See Also:

Constant Field Values

SWITCH_VERBOSE

protected static final String SWITCH_VERBOSE

The switch used for enabling verbose output.

See Also:

Constant Field Values

SWITCH_HELP

protected static final String SWITCH_HELP

The switch used for requesting help information.

See Also:

Constant Field Values

Constructor Detail

BaseMigrationUtility

public BaseMigrationUtility(String[] args,
                            org.apache.log4j.Logger log)

Create an instance by passing in the command line arguments.

Parameters:

args - the command line arguments passed to the main method of the implementing class.

log - the destination to log into. If this is null a new log will be created.

Method Detail

parseArgs

protected void parseArgs(String[] args)

Parses the command line arguments by filling commandLineOptions and commandValuesList structures.

Parameters:

args - the array of all the command line arguments.

isSwitch

protected boolean isSwitch(String arg)

Checks whether the specified string complies with the syntax of a command line switch.

Parameters:

arg - the string to check.

Returns:

true if the passed argument is a switch, false otherwise.

getCommandStandaloneValuesList

protected List<String> getCommandStandaloneValuesList()

Returns:

the list of all the command line arguments which have not been prepended with a switch. This method returns the actual reference to the internal list.

getCommandValueBySwitch

protected String getCommandValueBySwitch(String switchStr)

Requests the value of the switch which have been passed to the command line.

Parameters:

switchStr - the switch which value to look for.

Returns:

the value as String, empty string (meaning that the switch is stand alone) or null (meaning no such switch has been provided).

setLog

protected void setLog(org.apache.log4j.Logger log)

Sets the provided log for this utility. If null a default log is initialized.

Parameters:

log - the log for this utility to use. Could be null which will create a new log automatically.

getLog

public org.apache.log4j.Logger getLog()

Returns:

the reference to the log object.

isVerboseMode

public boolean isVerboseMode()

Returns:

true if the user has requested more verbose logging.

migrateFile

public void migrateFile()

This is the entry point which drives the common flow of a standard migration utility. If the user has requested help information using the SWITCH_HELP switch this method will return ignoring all the other switches that might have been provided.

The standard flow is as follows:

• interpretCommandLineOptions()

-- Help is requested --
• printHelpInformation()

-- Help is not requested --
• validateCommandLineOptions()
• backupFile()
• parseFile(File)
• defineChanges(Map)
• readFile(File)
• findEndOfLineCharacterSequence(StringBuilder)
• #applyChanges(StringBuilder, Map, Map)
• writeFile(StringBuilder)

Throws:

IllegalArgumentException - if an argument provided to the command line is invalid.

RuntimeException - if an error occurs while manipulating files.

applyChanges

protected void applyChanges(StringBuilder sb,
                            Map<String,String> props,
                            List<ChangeDescription> chngs)

Called to apply the defined changes to the in-memory buffer. This could be overrided by the child class to get access to the updated in-memory buffer if there is the need to make some changes unsupported by the current design.

The default implementation applies the changes in the following way:

1. Comment - Searches for an existing (uncommented) property and comments it (if not found this operation is ignored). If the value is on multiple lines this operation will comment each new line if the previous ends with "\"
2. Uncomment - Searches for an existing (commented) property and uncomments it (if not found this operation is ignored). If the value is on multiple lines this operation will comment each new line if the previous ends with "\"
3. Add -
4. Modify -
5. Delete -

Parameters:

sb - the in-memory representation of the source file

props - the Map of properties read from the source file. Note this is an immutable representation of the map.

chngs - the changes defined by the descendant class using the method defineChanges(Map);

performPropertyUncommenting

protected void performPropertyUncommenting(StringBuilder sb,
                                           Map<String,String> props,
                                           ChangeDescription change)

Perform actual uncommenting of the commented property. Unable to uncomment properties with multi-line values.

Parameters:

sb - the StringBuffer to perform the change on.

props - the state of the StringBuffer as a Properties structure.

changeKey - the key of the property to uncomment

performPropertyCommenting

protected void performPropertyCommenting(StringBuilder sb,
                                         Map<String,String> props,
                                         ChangeDescription change)

Perform actual commenting of an existing property.

Parameters:

sb - the StringBuffer to perform the change on.

props - the state of the StringBuffer as a Properties structure.

change - .getPropertyKey() the key of the property to comment

performPropertyAddition

protected void performPropertyAddition(StringBuilder sb,
                                       Map<String,String> props,
                                       ChangeDescription change)

Perform actual addition of the new property.

Parameters:

sb - the StringBuffer to perform the change on.

props - the state of the StringBuffer as a Properties structure.

changeKey - the key of the property to add

changeValue - specifies how the property should be added as well as its value.

performPropertyModification

protected void performPropertyModification(StringBuilder sb,
                                           Map<String,String> props,
                                           ChangeDescription change)

Perform actual modification of the existing property.

Parameters:

sb - the StringBuffer to perform the change on.

props - the state of the StringBuffer as a Properties structure.

changeKey - the key of the property to modify

newValue - the value to set on the existing property.

performPropertyDeletion

protected void performPropertyDeletion(StringBuilder sb,
                                       Map<String,String> propsAvailable,
                                       ChangeDescription change)

Perform actual deletion of the existing property.

Parameters:

sb - the StringBuffer to perform the change on.

props - the state of the StringBuffer as a Properties structure.

changeKey - the key of the property to modify

deletingComments -

parseFile

protected Map<String,String> parseFile(File srcFile)

Parses the source file.

The default implementation uses the Properties class to parse the source file.

Parameters:

srcFile - the file to parse.

Returns:

a Map of all the properties from the source file.

parseFile

protected Map<String,String> parseFile(InputStream source)
                                throws IOException

Parses the source stream.

The default implementation uses the Properties class to parse the source stream.

Parameters:

source - the input stream to read from

Returns:

a Map of all the properties from the source stream.

Throws:

IOException

interpretCommandLineOptions

protected void interpretCommandLineOptions()

Called to parse the passed command line arguments.

The default implementation is to get the values of the common switches: SWITCH_HELP, SWITCH_MIG_FILE_BAKUP, SWITCH_MIG_FILE_NEW, SWITCH_MIG_FILE and SWITCH_VERBOSE
The SWITCH_HELP is checked first, if it is specified then the rest of the common switches will not be considered.

validateCommandLineOptions

protected void validateCommandLineOptions()

Called to check whether the parsed arguments are valid enough for the migration utility to continue. If an invalid argument is found an IllegalArgumentException should be thrown.

The default implementation checks the validity of the common command line parameters - file names, existence, permissions, etc.

backupFile

protected void backupFile()

Called to create a copy of the source file.

The default implementation checks if the source and the destination files match. If they do the source file is only renamed to the backup file. If they don't the source file is copied as the backup file.

Throws:

IllegalArgumentException - if an error occurs manipulating the files provided by the user.

RuntimeException - if an error occurs while reading/writing the backup file.

readFile

protected StringBuilder readFile(File srcFile)

Called to read the configuration file and put its content into the returned StringBuilder.

Parameters:

srcFile - the file to read.

Returns:

a StringBuilder holding the file content.

writeFile

protected void writeFile(StringBuilder sb)

Called to write the in-memory buffer to the destination file.

Parameters:

sb - the in-memory representation of the source file

printHelpInformation

protected void printHelpInformation()

Called to print the help information to the stdOut.

isHelpRequested

public boolean isHelpRequested()

defineChanges

protected abstract List<ChangeDescription> defineChanges(Map<String,String> props)

Defines the changes that will be done over the properties of the source file.

Parameters:

props - the Map of properties read from the source file. Note this is an immutable representation of the map.

Returns:

a Map defining the changes that will be done. The keys of this map represent the names of the properties. The corresponding values describe the particular changes that should be done done over the specific property. Must not be null

See Also:

ChangeDescription