Package com.ibm.di.migration

Class BaseMigrationUtility

  • Direct Known Subclasses:
    MigrateAmConfig, PluginMigrationUtility
    public abstract class BaseMigrationUtility
extends java.lang.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

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

    • Constructor Summary

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

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      protected void applyChanges​(java.lang.StringBuilder sb, java.util.Map<java.lang.String,​java.lang.String> props, java.util.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 java.util.List<ChangeDescription> defineChanges​(java.util.Map<java.lang.String,​java.lang.String> props)
      Defines the changes that will be done over the properties of the source file.
      protected java.util.List<java.lang.String> getCommandStandaloneValuesList()  
      protected java.lang.String getCommandValueBySwitch​(java.lang.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​(java.lang.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​(java.lang.String[] args)
      Parses the command line arguments by filling commandLineOptions and commandValuesList structures.
      protected java.util.Map<java.lang.String,​java.lang.String> parseFile​(java.io.File srcFile)
      Parses the source file.
      protected java.util.Map<java.lang.String,​java.lang.String> parseFile​(java.io.InputStream source)
      Parses the source stream.
      protected void performPropertyAddition​(java.lang.StringBuilder sb, java.util.Map<java.lang.String,​java.lang.String> props, ChangeDescription change)
      Perform actual addition of the new property.
      protected void performPropertyCommenting​(java.lang.StringBuilder sb, java.util.Map<java.lang.String,​java.lang.String> props, ChangeDescription change)
      Perform actual commenting of an existing property.
      protected void performPropertyDeletion​(java.lang.StringBuilder sb, java.util.Map<java.lang.String,​java.lang.String> propsAvailable, ChangeDescription change)
      Perform actual deletion of the existing property.
      protected void performPropertyModification​(java.lang.StringBuilder sb, java.util.Map<java.lang.String,​java.lang.String> props, ChangeDescription change)
      Perform actual modification of the existing property.
      protected void performPropertyUncommenting​(java.lang.StringBuilder sb, java.util.Map<java.lang.String,​java.lang.String> props, ChangeDescription change)
      Perform actual uncommenting of the commented property.
      protected void printHelpInformation()
      Called to print the help information to the stdOut.
      protected java.lang.StringBuilder readFile​(java.io.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​(java.lang.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

      • SWITCH_MIG_FILE

        protected static final java.lang.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 java.lang.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 java.lang.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 java.lang.String SWITCH_VERBOSE
        The switch used for enabling verbose output.
        See Also:
        Constant Field Values

      • SWITCH_HELP

        protected static final java.lang.String SWITCH_HELP
        The switch used for requesting help information.
        See Also:
        Constant Field Values

    • Constructor Detail

      • BaseMigrationUtility

        public BaseMigrationUtility​(java.lang.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​(java.lang.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​(java.lang.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 java.util.List<java.lang.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 java.lang.String getCommandValueBySwitch​(java.lang.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.

      • applyChanges

        protected void applyChanges​(java.lang.StringBuilder sb,
                            java.util.Map<java.lang.String,​java.lang.String> props,
                            java.util.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​(java.lang.StringBuilder sb,
                                           java.util.Map<java.lang.String,​java.lang.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​(java.lang.StringBuilder sb,
                                         java.util.Map<java.lang.String,​java.lang.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​(java.lang.StringBuilder sb,
                                       java.util.Map<java.lang.String,​java.lang.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​(java.lang.StringBuilder sb,
                                           java.util.Map<java.lang.String,​java.lang.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​(java.lang.StringBuilder sb,
                                       java.util.Map<java.lang.String,​java.lang.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 java.util.Map<java.lang.String,​java.lang.String> parseFile​(java.io.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 java.util.Map<java.lang.String,​java.lang.String> parseFile​(java.io.InputStream source)
                                                                    throws java.io.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:
        java.io.IOException

      • 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:
        java.lang.IllegalArgumentException - if an error occurs manipulating the files provided by the user.
        java.lang.RuntimeException - if an error occurs while reading/writing the backup file.

      • readFile

        protected java.lang.StringBuilder readFile​(java.io.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​(java.lang.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 java.util.List<ChangeDescription> defineChanges​(java.util.Map<java.lang.String,​java.lang.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