Summary
This article details the steps necessary to create a custom code action.
Synopsis
This article details the steps necessary to create a custom code action.
Discussion
In InstallAnywhere, here are the steps to create and use a Custom Code action:
- Create your Action or Panel. A good starting point is to use the Java source file templates found in the CustomCode/Templates folder inside the InstallAnywhere installation directory. These templates, CustomCodeActionTemplate.java and CustomCodePanelTemplate.java, provide frameworks for a complete custom code action and custom code panel, respectively, without implementing any actual functionality. You can implement your custom functionality where indicated in the comments. As you can discover from looking over the templates, custom actions should extend com.zerog.ia.api.pub.CustomCodeAction and custom panels should extend com.zerog.ia.api.pub.CustomCodePanel.
- Compile your source files. Add IAClasses.zip to the CLASSPATH of your IDE (if you are using one). Your Java compiler will need to reference the classes in this file when you compile your code. IAClasses.zip is located in the root installation directory of InstallAnywhere. Decide what additional files and resources you need. For example, you may need images (.gif), databases, text files, or other resources.
- Create a Java Archive (JAR) file which contains your compiled class files and your resource files. It is recommended that your class files and your resources be packaged into a directory structure such as com.acme (where your company's domain name is acme.com). This will avoid naming conflicts with other custom code. A sample make.bat file is included in the CustomCode/Samples folder. Here's an example of using Sun's jar utility to package your files (.class and .gif) into a JAR: jar cvfM myAction.jar com/acme/*.class com/acme/*.gif Note: Make sure that the archive you select has full path information in it (each file in the archive should be stored with its proper package path). Without this, java will not be able to properly find your packaged class files.
To reference the Custom code created previously, perform the following steps:
- Use the Execute Custom Code or Show Custom Code Panel actions in the InstallAnywhere Advanced Designer to add your custom code.
- Choose the JAR file you created in the previous step
- Enter your fully qualified package and class name, such as: com.acme.MyAction
Note: Since it is not possible to launch InstallAnywhere from within an integrated development environment, the best way to debug your custom code is to use the Output Debug Information action, or to use System.out.println(); statements to print debug output to the console during testing.
Writing The Action
This section will describe how to write a CustomCodeAction in more detail, and lead you through an example named com.acme.samples.SampleAction. This section also includes some notes on the CustomCodeAction API, and other related materials.
Note: It is assumed that the goals of the action are known, but no code has yet been written to implement the goal. After each relevant step, the example will show how this can be done.
1. Create your main class file and package it. This is the file that you will specify in the Class: field in the InstallAnywhere Advanced Designer (see Execute Custom Code documentation).
package com.acme;
public class SampleAction {
}
2. To create a custom action, your class must first extend the abstract class com.zerog.ia.api.pub.CustomCodeAction. This class provides the interface through which you will interact with the InstallAnywhere runtime.
package com.acme;
import com.zerog.ia.api.pub.*;
public class SampleAction extends CustomCodeAction {
public void install( InstallerProxy ip ) {}
public void uninstall( UninstallerProxy up) {}
public String getInstallStatusMessage() {}
public String getUninstallStatusMessage() {}
}
3. Description of public void install(InstallerProxy ip) {}
The installer calls this method during install-time, in the step where the CustomCodeAction was added. For example, if you add your custom action in Startup, this method will be called during the Startup phase of the installation. The InstallerProxy instance provides methods to access installer information, set installation status, and control installation flow. In SampleAction, we will display a message to the user.
package com.acme;
import com.zerog.ia.api.pub.*;
import java.awt.*;
import java.awt.event.*;
public class SampleAction extends CustomCodeAction implements ActionListener {
public void install( InstallerProxy ip )
{
// Get some variables from the VariableManager
// SAMPLE_ACTION_TITLE and SAMPLE_ACTION_MESSAGE
// should have been set earlier in installation
String title = (String) ip.substitute("$SAMPLE_ACTION_TITLE$");
String msg = (msg) ip.substitute("$SAMPLE_ACTION_MESSAGE$");
Label l = new Label( msg );
Button b = new Button( "Close" );
b.addActionListener( this );
Frame myFrame = new Frame( title );
myFrame.setLayout( new BorderLayout() );
myFrame.add( l, Center );
myFrame.add( b, South );
myFrame.pack();
myFrame.show();
}
public void uninstall(UninstallerProxy up) { }
public String getInstallStatusMessage() { }
public String getUninstallStatusMessage() { }
public void actionPerformed(ActionEvent ae){
Button source = (Button) ae.getSource();
Frame parent = (Frame) source.getParent();
Parent.dispose();
}
}
4. Description of public void uninstall(UninstallerProxy up) {}
This method is called by the uninstaller at uninstall-time, before the deletion of any files. The UninstallerProxy instance provides access to any information written at install-time. For example, in SampleAction, we will again display a small window with a message.
public void uninstall (UninstallerProxy up){
Label l = new Label("uninstall time message");
Button b = new Button("Close");
b.addActionListener(this);
Frame myFrame = new Frame( "Uninstall: Sample Action" );
myFrame.setLayout( new BorderLayout() );
myFrame.add(l, Center);
myFrame.add(b, South);
myFrame.pack();
myFrame.show();
}
5. Description of public String getInstallStatusMessage() {}
The installer calls this message to display a status message in the progress bar during installation. The message is displayed while the install (InstallerProxy ip) method is called. The method has no effect if the action is a Startup, Pre-Install, or Post-Install Action.
public String getInstallStatusMessage(){
return "Displaying a short installation message";
}
6. Description of public String getUninstallStatusMessage() {}
This method is called by the uninstaller to display a status message in the progress bar during uninstall. The message is displayed while the uninstall(UninstallerProxy up) method is called.
public String getUninstallStatusMessage(){
return "Displaying a long uninstallation message" ;
}
At this point, a basic Custom Action has been implemented. This sample code is located in: <IA HOME>/CustomCode/Samples/com/acme/SampleAction.java.
Additional Information
See the Java documentation (JavaDoc) for CustomCodeAction for additional information. The Java documentation (JavaDoc) for the InstallAnywhere APIs is located in <IA home>/javadoc/index.htm.
Click here for an online copy of our InstallAnywhere 2015 API documentation.
Case id: 00001065
Activity: Status change: 2 hours ago