Summary

This article describes how to use the Extract To File Plugin in order to extract a file that is contained in the installer's archive to a location that is in the installer's classpath during the Pre-Install summary.

Synopsis

This article describes how to use the Extract To File Plugin in order to extract a file that is contained in the installer's archive to a location that is in the installer's classpath during the Pre-Install sequence. This is especially useful if the installer uses custom actions which need a native library in the installer's classpath in order to make native calls using JNI.

A sample InstallAnywhere project is attached to this article which demonstrates how to extract a file which is included in the installer's $DO_NOT_INSTALL$ Magic Folder to a directory which will be in the classpath of the installer.

Discussion

It is often necessary to add a file to the installer's classpath after the installer has been launched. There is a directory in the installer's temporary directory which is always added to the classpath of the installer. Because of this, adding files to this directory will make them available in the installer's classpath as well.

Download the attached zip file (public_Q201177.zip), extract its contents, and open the project using InstallAnywhere 2010 or later. Navigate to the Install sequence and notice that the file Test.txt is included in the $DO_NOT_INSTALL$ Magic Folder. This will include the file in the installer's archive, but will ensure that the file is not installed on the target machine. Also, notice the Source Path of the file, $IA_PROJECT_DIR$\Test.txt, as this will be used later when configuring the Extract To File Plugin.

The second and third actions in the Pre-Install sequence are Extract To File Plugins. One of these will run on Windows and the other on all non-Windows platforms. The need for two separate actions is caused by slight variations in the path to which the file should be extracted based on the target platform. These differences will be discussed below. Each Plugin has a Check Platform Rule which limits it to executing on the correct platform.

The plugin takes two input parameters. The first, ExtractToFile_Source, is the path in the installer's archive where the file to extract is located. When a file is included in the $DO_NOT_INSTALL$ Magic Folder, that file is built into the installer's archive using its Source Path property. Because the Source Path property of the file is $IA_PROJECT_DIR$, it will be included in a directory literally named $IA_PROJECT_DIR$. Due to the fact that the value of this property will be resolved, it must use the IA Variable $DOLLAR$ to represent the leading and trailing dollar signs. The value will also use the IA Variable for the platform specific path separator, $\$. The property is then set as follows:
ExtractToFile_Source = $DOLLAR$IA_PROJECT_DIR$DOLLAR$$\$Test.txt

The second property which must be set for the plugin is ExtractToFile_Destination. This is the path on the target machine where the file will be extracted. In order to ensure the file is available in the installer's classpath, it will be extracted to a directory which is always added to the classpath. The Java System Property user.dir will resolve to the directory from which the installer was launched, which is a temporary directory created by the installer launcher. Within this location is a directory named InstallerData which will always be added to the installer's classpath. In order to extract the file to this directory, the property should be set as follows:

On Windows:

ExtractToFile_Destination = $prop.user.dir$$/$..$/$InstallerData$/$Test.txt

On Non-Windows Platforms:

ExtractToFile_Destination = $prop.user.dir$$/$InstallerData$/$Test.txt

At runtime, this will resolve to the InstallerData directory in the installer's temporary directory which is in the installer's classpath. The IA Variable $prop.user.dir$ will resolve to the value of the Java System Property user.dir. In addition, the IA Variable for the platform specific path separator, $/$, is also used.

In order to test this behavior, build the attached sample project. The project is configured to build a Windows and Linux Without VM installer, but may be configured to build launchers for other platforms as well. After launching the installer, a console window will be opened and debug output written there. After the Introduction Panel displays, click the Next button and the Extract To File Plugin will execute. The next panel is a Display Message Panel which will display the path to which the file has been extracted in order to verify that it does in fact exist. At this time, please navigate to the directory indicated on the Panel to see that the file was extracted successfully.

In the debug output on the console, a listing of the classpath used by the installer will be written like:

java.class.path:
    C:\Users\ADMINI~1\AppData\Local\Temp\I1317227398\InstallerData\IAClasses.zip
    C:\Users\ADMINI~1\AppData\Local\Temp\I1317227398\InstallerData\Execute.zip
    C:\Users\ADMINI~1\AppData\Local\Temp\I1317227398\Windows\InstallerData\Execute.zip
    C:\Users\ADMINI~1\AppData\Local\Temp\I1317227398\InstallerData\Resource1.zip
    C:\Users\ADMINI~1\AppData\Local\Temp\I1317227398\Windows\InstallerData\Resource1.zip
    C:\Users\ADMINI~1\AppData\Local\Temp\I1317227398\InstallerData
    C:\Users\ADMINI~1\AppData\Local\Temp\I1317227398\Windows\InstallerData

Notice that the path:
C:\Users\ADMINI~1\AppData\Local\Temp\I1317227398\InstallerData
is included in the classpath. This is also the directory where the test file was extracted and the file should then be in the installer's classpath.

Additional Information

• When attempting to determine the path to which a file included in the $DO_NOT_INSTALL$ Magic Folder was built, it is often helpful to build the project as an Other Java Enabled Platforms launcher. This will build a .jar file which can be opened using most zip utilities. The file can then be located in the archive and its path determined.
• For more information regarding InstallAnywhere Variables, please see the following HelpNet documentation.
• Because this file is being extracted to a location within the temporary directory used by the installer, it should be deleted as the installer exits along with the rest of the installer's temporary files. The installation developer does not need to explicitly add any action to delete this file.
• In order to extract a file, it MUST be built into the $DO_NOT_INSTALL$ Magic Folder. If the file needs to be installed but also needs to be available during the Pre-Install Sequence, it will need to be included in both the $DO_NOT_INSTALL$ Magic Folder and the $USER_INSTALL_DIR$ or other suitable Magic Folder in which it will be installed.