org.apache.uima.pear.tools

## Class LocalInstallationAgent

- java.lang.Object
- - org.apache.uima.pear.tools.LocalInstallationAgent

-     public class LocalInstallationAgent
      extends Object

  The `LocalInstallationAgent` allows localizing files of UIMA compliant components within the single PEAR structure, and verifying localized component's files using UIMA framework API.
  This class may be used in the following ways:
  - As a standalone Java application -
    `java -Xmx512M -DUIMA_HOME=%UIMA_HOME% org.apache.uima.pear.tools.LocalInstallationAgent main_component_root_directory`
    where the `main_component_root_directory` is the path to the root directory of the main component (root directory of the single PEAR structure);
  - As a Java object -
    in this case the caller is expected to set the `UIMA_HOME` variable, using the `setUimaHomePath()` method, immediately after creating a new instance of the `LocalInstallationAgent` class.
    Note: Some TAEs require large heap size, so the '-Xmx[heapSize]' JVM option may be needed.
    Localization of component files is performed by using the `localizeComponent()` method.
    Verification of localized files is performed by using the `verifyLocalizedComponent()` method.
    The applications prints all messages to the standard output and error messages to the standard error output.
  In both modes the application uses the `metadata/PEAR.properties` file for the component localization information.
  Note: during the localization phase the application creates backup copies of all files in both the `conf` and `desc` directories, adding the extension ".$" to each backup file. If the application fails, please make sure all original files in both the directories are restored from appropriate "*.$" backup copies.
  See Also:
    `InstallationDescriptor`, `InstallationProcessor`, `InstallationTester`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static String` | `BACKUP_FILE_SUFFIX`
    `protected static String` | `COMP_ROOT_PREFIX`
    `protected static String` | `COMP_ROOT_SUFFIX`
    `protected static String` | `MAIN_ROOT`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `LocalInstallationAgent(String mainComponentRootPath)` Constructs new instance of the `LocalInstallationAgent` class, using a given main component root directory.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static boolean` | `checkPackageConfig(Properties packageConfig, InstallationDescriptor insdObject)` Checks that a specified PEAR configuration corresponds to a given installation descriptor.
    `boolean` | `localizeComponent()` Performs localization of the component files in the 'conf' and 'desc' subdirectories of the specified main root directory, as well as localization of the installation descriptor.
    `static void` | `localizeComponentFile(File file, InstallationDescriptor insdObject, Properties packageConfig)` Performs localization of a given component file using information from a given installation descriptor and a specified PEAR configuration.
    `protected File[]` | `localizeComponentFiles()` Performs localization of the component files in the 'conf' and 'desc' directories by replacing $main_root and $component_id$root macros with the actual path values from the PEAR configuration file.
    `static void` | `localizeInstallationDescriptor(InstallationDescriptor insdObject, Properties packageConfig)` Performs localization of a given installation descriptor object using information from a specified PEAR configuration.
    `static void` | `main(String[] args)` Starts the application.
    `void` | `setUimaHomePath(String uimaHomePath)` Sets a given UIMA local home directory path.
    `boolean` | `undoComponentLocalization()` Restores original files in the 'conf' and 'desc' directories from the back-up copies (with extension '.$').
    `boolean` | `verifyLocalizedComponent()` Performs verification of the localized component by running the `InstallationTester` application.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### BACKUP_FILE_SUFFIX

          protected static final String BACKUP_FILE_SUFFIX

      See Also:
        Constant Field Values

    - #### MAIN_ROOT

          protected static final String MAIN_ROOT

      See Also:
        Constant Field Values

    - #### COMP_ROOT_PREFIX

          protected static final String COMP_ROOT_PREFIX

      See Also:
        Constant Field Values

    - #### COMP_ROOT_SUFFIX

          protected static final String COMP_ROOT_SUFFIX

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### LocalInstallationAgent

          public LocalInstallationAgent(String mainComponentRootPath)

      Constructs new instance of the `LocalInstallationAgent` class, using a given main component root directory.
      Parameters:
        `mainComponentRootPath` - The given main component root directory path.

  - ### Method Detail

    - #### checkPackageConfig

          public static boolean checkPackageConfig(Properties packageConfig,
                                                   InstallationDescriptor insdObject)

      Checks that a specified PEAR configuration corresponds to a given installation descriptor.
      Parameters:
        `packageConfig` - The specified PEAR configuration (`Properties` object).
        `insdObject` - The given installation descriptor object.
      Returns:
        `true` if the specified PEAR configuration corresponds to the given installation descriptor, `false` otherwise.

    - #### localizeComponentFile

          public static void localizeComponentFile(File file,
                                                   InstallationDescriptor insdObject,
                                                   Properties packageConfig)
                                            throws IOException

      Performs localization of a given component file using information from a given installation descriptor and a specified PEAR configuration.
      Parameters:
        `file` - The given component file to be localized.
        `insdObject` - The given installation descriptor object.
        `packageConfig` - The specified PEAR configuration.
      Throws:
        `IOException` - if any I/O exception occurred.

    - #### localizeInstallationDescriptor

          public static void localizeInstallationDescriptor(InstallationDescriptor insdObject,
                                                            Properties packageConfig)

      Performs localization of a given installation descriptor object using information from a specified PEAR configuration.
      Parameters:
        `insdObject` - installation descriptor object
        `packageConfig` - pear configuration properties

    - #### main

          public static void main(String[] args)

      Starts the application. This application expects the following JVM run-time settings:
      - -DUIMA_HOME=<local_uima_root_dir>
      Parameters:
        `args` - main_component_root_dir

    - #### localizeComponent

          public boolean localizeComponent()
                                    throws IOException

      Performs localization of the component files in the 'conf' and 'desc' subdirectories of the specified main root directory, as well as localization of the installation descriptor.
      Returns:
        `true` if the localization process completed successfully, `false` otherwise.
      Throws:
        `IOException` - if any I/O exception occurred.

    - #### localizeComponentFiles

          protected File[] localizeComponentFiles()
                                           throws IOException

      Performs localization of the component files in the 'conf' and 'desc' directories by replacing $main_root and $component_id$root macros with the actual path values from the PEAR configuration file. Back-up copies of original files are stored with '.$' extension.
      Returns:
        The array of localized files.
      Throws:
        `IOException` - if any I/O exception occurred.

    - #### undoComponentLocalization

          public boolean undoComponentLocalization()
                                            throws IOException

      Restores original files in the 'conf' and 'desc' directories from the back-up copies (with extension '.$').
      Returns:
        `true` if the operation completed successfully, `false` otherwise.
      Throws:
        `IOException` - if any I/O exception occurred.

    - #### verifyLocalizedComponent

          public boolean verifyLocalizedComponent()
                                           throws IOException,
                                                  ResourceInitializationException,
                                                  UIMAException

      Performs verification of the localized component by running the `InstallationTester` application.
      Returns:
        `true` if the verification completed successfully, `false` otherwise.
      Throws:
        `IOException` - if any I/O exception occurred.
        `ResourceInitializationException` - if the specified component cannot be instantiated.
        `UIMAException` - if this exception occurred while identifying UIMA component category.
      See Also:
        `InstallationTester`

    - #### setUimaHomePath

          public void setUimaHomePath(String uimaHomePath)

      Sets a given UIMA local home directory path.
      Parameters:
        `uimaHomePath` - The given UIMA local home directory path.

Copyright © 2006–2022 The Apache Software Foundation. All rights reserved.