Developing plug-ins in Eclipse

The Plug-in Development Kit (PDK) includes an Eclipse plug-in that you can use in your Eclipse or Rational® Application Developer environment to create and edit some of the configuration files in the plug-ins that are used in your virtual applications.

Overview

You can use virtual application patterns to add third-party software to your existing platform in an efficient, reusable way by developing the corresponding plug-in for it. Developing a plug-in for your platform requires an understanding of the conventions, configuration, and details for your platform. You typically must edit your configuration files in your preferred text editor.

The Plug-in Development Kit (PDK) includes an Eclipse plug-in that you can use to help develop the plug-ins that are used in your virtual application patterns:
  • You can create new plug-in projects with the basic file and folder structure that is generated for you automatically.
  • You can import an existing plug-in project to modify the configuration as needed.
  • Several plug-in editors are provided to manage your critical JSON configuration files.
  • You can use more functions to create other artifacts that you might need for your plug-in.
  • Visual decorations of parts of the project structure are added automatically to help you locate specific plug-in content.
  • Integrated build and package functions are included to complete your plug-in package development.
  • You can also deploy your plug-in to a remote Cloud Pak System environment for testing and debugging.
  • You can choose to work with your plug-in project in either a simple form-based user interface, or switch to a formatted text editor to modify the project configuration files directly.

You can also access the Plug-in Development Kit documentation within the Eclipse IDE by clicking Help > Help Contents.

Using this Eclipse plug-in, your Eclipse IDE becomes a virtual application plug-in development environment. Developing workload plug-ins is easier with these plug-in development features and the power of the Eclipse IDE and other third-party plug-ins, such as PyDev.

Prerequisites

To use this Eclipse plug-in, verify that your environment includes the following prerequisites:
  • Java™ SE6, 32-bit
  • Eclipse version 3.6.2 or later, 32-bit

The Java Platform, Enterprise Edition version is recommended.

Installing the Eclipse plug-in

You can install the Eclipse plug-in into your Eclipse environment by completing the following steps:
  1. Start Eclipse to load the Eclipse SDK workspace.
  2. Click Help > Install New Software. The Available Software window is displayed.
  3. Click Add to add a software repository. The Add Repository window is displayed.
  4. Click Archive to define a local Eclipse repository archive.
  5. Go to the directory where you installed and unpacked the Plug-in Development Kit. For installation details, see "Installing the Plug-in Development Kit."
  6. Select the compressed file com.ibm.maestro.plugin.pdk.site.zip and click Open.
  7. In the Name field of the Add Repository window, specify a name for the new repository archive, such as IBM pureScale Eclipse plug-in.
  8. Click OK.
  9. After a moment, the Name area is updated to display the name IBM Workload Plug-in Development Kit.
  10. Click Select All.
  11. Clear the following check box: Contact all update sites during install to find required software.
  12. Click Next.
  13. Wait for the installation to complete.

Creating a project

You can create a virtual application plug-in project in Eclipse by using the following procedure:
  1. In your Eclipse environment, switch to the Workload Plug-in Development Perspective, if needed.
  2. Click File > New > Project to start the New Project wizard.
  3. Select IBM Workload Plug-in Development > IBM Workload Plug-in Project.
  4. Click Next. The Create an IBM Workload Plug-in Project window is displayed.
  5. In the Project name field, specify a name for your new project. Notice that the Plug-in name field is automatically populated with the same project name. However, you can change it to another name if preferred. The project name is the Eclipse project name, and the plug-in name is the name of this plug-in that you are developing.
  6. The Generate project skeleton check box is selected by default.
    • If this check box is selected, the wizard creates a number of files and folders automatically, which are needed by most plug-in projects.
    • If you clear this check box, the wizard creates an empty project that includes only the config.json file. You must add other files manually as needed.
  7. Click Finish. The new project is created and added to the list of projects in the Project Explorer tab.

Importing an existing project

You can import an existing plug-in project into your Eclipse plug-in development environment. You can import a project from your local workstation, or from Cloud Pak System if you are connected to your system from Eclipse. This existing project package must be in the standard tar.gz or .tgz format for a local project. Import your existing plug-in project by using the following procedure:
  1. In your Eclipse environment, switch to the Workload Plug-in Development Perspective, if needed.
  2. If you want to import a project from Cloud Pak System, connect to the system from Eclipse:
    1. Click Window > Preferences.
    2. Click IBM Pattern Toolkit.
    3. Enter the IP address of your Cloud Pak System, and the user name and password.
    4. Click OK.
  3. Click File > Import to start the Import wizard.
  4. Select IBM Workload Plug-in Development > IBM Workload Plug-in Package.
  5. Click Next. The Import an IBM Workload Plug-in Package window is displayed.
  6. Select Local import or Remote import. Click Browse to browse to the location of your plug-in package file if you selected Local import.
  7. Select the plug-in package file to import. The selected file path and name are displayed.
  8. Click Next. A second wizard page is displayed.
  9. The name of the project is initially set to the name of your plug-in the Project name field. Typically you do not need to change this name, but you can if preferred.
  10. The default project location is in the default workspace location of your Eclipse environment, but you can change that if preferred.
  11. Click Finish. The import wizard extracts the package and adds the project to the list of projects in the Project Explorer tab.

Pattern type project overview

Pattern types are a collection of plug-ins. The plug-ins contain the components, policies, and links of the virtual application pattern. To open the pattern type project overview page, double-click the patterntype.json file, or right-click the file and select Open.

The pattern type project overview page shows the following information about the pattern type:
  • Pattern type basic information:
    • name
    • short name
    • version
    • description
    • status
    • builder
      Note: If enabled, this field configures the pattern type to display in the pattern type list, which is accessed by clicking New on the virtual applications page that you open by clicking Patterns > Virtual Application Patterns in Cloud Pak System.
  • Prerequisites: Lists the prerequisites for the pattern type, such as the foundation pattern type.
  • Plug-in projects: Lists the plug-in projects that are associated with the pattern type.
    • Click New to add more plug-in projects to the pattern type.
  • Categories: Specify categories for components, which are defined by plug-ins. When you create a component for the pattern type in a plug-in project, you can assign it to one of these categories.

Plug-in project overview

The plug-in project includes the following key artifacts:
src folder
You can create your Java code in this directory.
build folder
This folder contains the build.plugin.xml file and Ant JAR files for building the plug-in.
i18n folder
This folder contains the globalization files.
lib folder
This folder contains all of the JAR files that are needed to compile the plug-in project.
META-INF folder
This folder contains metadata files.
OSGI-INF folder
This folder contains OSGi configuration files.
plugin folder
This folder is the plug-in configuration directory, which includes the config.json plug-in configuration file, and the following folders:
  • appmodel
  • nodeagents
  • parts
  • templates
build.xml
This Ant build file is needed to build the plug-in project.
You can add content to these artifacts to develop your plug-in, in the following areas:
  • The plug-in configuration, in the config.json file.
  • Components, links, and policies for the Pattern Builder in the metadata.json component property UI configuration file.
  • Operations available on the Pattern Builder console, in the operation.json configuration file.
  • Configuration parameters in the tweak.json file that can be changed on the running deployment.
  • You can create other typical plug-in artifacts, including OSGi service components, plug-in node parts, plug-in parts, and plug-in roles.

Managing the config.json plug-in configuration file

The config.json file contains the plug-in configuration.

You can modify the config.json file with the JSON Editor:
  1. In the Project Explorer view, expand the plug-in project node.
  2. Expand the plugin folder node.
  3. Double-click the config.json file, or right-click the file and select Open with > Json Editor.
The Configuration view is displayed by default, showing the contents of the config.json in a convenient form-based user interface. Using this interface, you can do the following tasks:
  • Specify or modify basic plug-in information, such as the ID and version.
  • Add and remove pattern types that are associated with this plug-in.
  • Add and remove plug-in file references as needed.
  • Add and remove plug-in configuration parameters as needed.

Values that you specify are immediately validated, and errors (such as missing required fields, duplicate IDs) are flagged (with help tips) for correction.

In some cases, you might prefer to modify the configuration text directly, by clicking the Source tab to present the configuration information in a formatted text editor. Changes that are made in either the Configuration user interface or the source text editor are immediately reflected in both views.

Click the Overview tab to see the structure and contents of the plug-in. This tab has four sections:
Shared services
Lists whether the plug-in provides shared services.
Package
Lists the parts, node parts, and roles in the plug-in. Click Add to add a part, node part, or role to the plug-in.
Metadata
List the components, links, and policies in the plug-in. Click Add to create a metadata element in metadata.json.
Runtime
Provides links to the operation.json and tweak.json files for the plug-in.
If an item is available for editing in Eclipse, you can double-click to open it.

Managing the metadata.json component property UI configuration file

The metadata.json file defines the components, policies, and links between specific source and target component types for the Pattern Builder. Other files are referenced from the metadata.json file, such as image files for icons to display in Pattern Builder. The metadata describes how Pattern Builder visually displays components, links, and policies and determines which configuration parameters are exposed to users.

You can modify the metadata.json file with the metadata JSON Editor:
  1. In the Project Explorer view, expand the plug-in project node.
  2. Expand the plugin folder node.
  3. Expand the appmodel folder node.
  4. Double-click the metadata.json file, or right-click the file and select Open with > Json Editor.
The Overview page is displayed by default, showing a list of metadata elements that you can use to create a virtual application pattern. Using this form-based interface, you can do the following tasks:
  • Add or remove parts, node parts, or roles in the plug-in.
  • Add or remove application model elements by metadata type (component, policy, or link) to the list of metadata elements.
  • Click a metadata element in the list to open the Application Model tab, where you can view and modify the following metadata details:
    • ID
    • Label
    • Description
    • Category (for component type)
    • An associated image file (for component and policy types)
    • An associated thumbnail image file (for component and policy types)
    • Applicable components (for policy type)
    • Source and target components (for link type)
  • Add and remove attribute types (string, array, number, or file).
  • Add and remove attribute types (string, string-options, string-radio, string-password, string-multi, number, number-percentage, boolean, array, array-options, file, or range)
  • Modify attribute type information, specifying ID, Label, and Description information, and whether the attribute is required.
  • Manage the order in which the attribute information is displayed in the Pattern Builder.

Values that you specify are immediately validated, and errors (such as missing required fields, duplicate IDs) are flagged (with help tips) for correction.

In some cases you might prefer to modify the configuration text directly, by clicking the Source tab to present the configuration information in a formatted text editor. Changes that are made in either the Application Model user interface or the source text editor are immediately reflected in both views.
Note: For PDK versions 1.0.1.2 and earlier, if you use a string attribute type with a regular expression (RegExp) that contains a slash (/), the expression might be truncated. To avoid this issue, use an escape sequence (\) before each / in the regular expression.

Managing the operation.json configuration file

The operation.json file defines the operations that can be called when the virtual application is running. Operations are grouped by role, and each operation is associated with a Python script, which is provided by the plug-in. Users request the operation on the Pattern Builder console. This request is forwarded by Cloud Pak System, and any parameters are sent to the script on systems where the role is running.

You can modify the operation.json file with the Operation JSON Editor:
  1. In the Project Explorer view, expand the plug-in project node.
  2. Expand the plugin folder node.
  3. Expand the appmodel folder node.
  4. Double-click the operation.json file, or right-click the file and select Open with > Json Editor.
The Operation view is displayed by default, showing a list of operations. The name of the operation is the concatenation of the ID and role values that are associated with the operation. Using this form-based interface, you can do the following tasks:
  • Add or remove operations, specifying role and ID information, to the list of operations.

    The special configuration role defines a handler for changing configuration parameters, as specified in the tweak.json file.

  • Click an operation in the list to display and modify the following operation form details:
    • ID
    • Label
    • Description
    • Category
    • Script (the associated Python script)
  • Add and remove attribute types (string, array, number, or file).
  • Add and remove attribute types (string, number, boolean, array, file, or range)
  • Modify attribute type information, specifying ID, Label, and Description information, and whether the attribute is required.
  • Manage the order in which the attribute information is displayed in the Pattern Builder.

Values that you specify are immediately validated, and errors (such as missing required fields, duplicate IDs) are flagged (with help tips) for correction.

In some cases you might prefer to modify the configuration text directly, by clicking the Source tab to present the configuration information in a formatted text editor. Changes that are made in either the Operation user interface or the source text editor are immediately reflected in both views.

Managing the tweak.json configuration file

The tweak.json file defines the configuration parameters that can be changed on the running deployment. The parameters in this file depend on an associated configuration operation that is defined in the operation.json file.

You can modify the tweak.json file with the Tweak JSON Editor:
  1. In the Project Explorer view, expand the plug-in project node.
  2. Expand the plugin folder node.
  3. Expand the appmodel folder node.
  4. Double-click the tweak.json file, or right-click the file and select Open with > Json Editor.
The Tweak view is displayed by default, showing a list of configuration parameters. The name of the parameter is the concatenation of the role and ID values that are associated with the parameter. Using this form-based interface, you can do the following tasks:
  • Add or remove parameters, specifying role and ID information, to the list of parameters.

    The ID specified must match the ID of a corresponding operation in the operation.json file, which is defined with the configuration role.

  • Click a configuration parameter in the list to display and modify the following configuration details:
    • ID
    • Role
    • Label
    • Description
    • Type (string, array, number, or file)
    • Reference (along with type, target, and ID)

Values that you specify are immediately validated, and errors (such as missing required fields, duplicate IDs) are flagged (with help tips) for correction.

In some cases you might prefer to modify the configuration text directly, by clicking the Source tab to present the configuration information in a formatted text editor. Changes that are made in either the Tweak user interface or the source text editor are immediately reflected in both views.

Managing OSGi service components

Cloud Pak System provides limited support for Open Services Gateway initiative (OSGi) services within plug-ins. Plug-ins can provide implementations of specific service interfaces:
  • Topology Provider (template-based and Java based)
  • Topology processor
  • Service Provisioner
  • Registry Provider
  • Post Provisioner
You can create a new plug-in OSGi service component by completing the following steps:
  1. In the Project Explorer view, expand the plug-in project node.
  2. Right-click the OSGI-INF folder.
  3. Select New > OSGI Service Component.

The OSGI Service Component window is displayed. Specify the information for your service component in the fields provided. The fields change depending on which service type you select. When you click Finish, the new service component is added to the OSGI-INF folder in the plug-in. Associated Java source files are generated automatically, and the MANIFEST.MF file is updated automatically.

Values that you specify are immediately validated, and errors (such as existing names or files) are flagged (with help tips) for correction.

Managing plug-in node parts

Node parts are installed by the activation script and generally contain binary files and scripts to augment the operating system. You can create new node parts for your plug-in, including the directory structure and optionally include a script stub, such as setup.py.

You can create a node part by completing the following steps:
  1. In the Project Explorer view, expand the plug-in project node.
  2. Right-click the nodeparts folder.
  3. Select New > Plug-in Node Part.

The Plug-in Node Part window is displayed. Specify a name for your node part, and indicate whether to generate only the necessary directory structure, or create the directory structure and available script stubs. When you click Finish, the new node part is added to the plugin/nodeparts folder in the plug-in.

Values that you specify are immediately validated, and errors (such as existing names or files) are flagged (with help tips) for correction.

After you create your plug-in node parts, you can edit the associated Python scripts with your preferred editor.

Managing plug-in parts

Plug-in parts are installed by the workload agent and generally contain binary and lifecycle scripts that are associated with roles and dependencies. You can create new parts for your plug-in, including the directory structure and optionally include one or more script stubs, such as install.py and uninstall.py.

If you created a new plug-in project and selected the Generate project skeleton check box, the resulting project is created with a plugin/parts folder that contains a set of scripts by default. You can add new plug-in parts to this folder.

Create a new plug-in part by completing the following steps:
  1. In the Project Explorer view, expand the plug-in project node.
  2. Right-click the parts folder.
  3. Select New > Plug-in Node Part.

The Plug-in Part window is displayed. Specify a name for your part, and indicate whether to generate only the necessary directory structure, or create the directory structure and select one or more available script stubs. When you click Finish, the new part is added to the plugin/parts folder in the plug-in.

Values that you specify are immediately validated, and errors (such as existing names or files) are flagged (with help tips) for correction.

After you create your plug-in parts, you can edit the associated Python scripts with your preferred editor.

Managing plug-in roles

A plug-in role represents a managed entity within a virtual application instance.

You can create new roles for your plug-in, including the directory structure and optionally include one or more script stubs, such as install.py, configure.py, and start.py.

If you created a new plug-in project and selected the Generate project skeleton check box, the resulting project is created with a plugin/parts folder that contains a number of role scripts by default. You can add new plug-in roles to this folder.

Create a new plug-in role by completing the following steps:
  1. In the Project Explorer view, expand the plug-in project node.
  2. Right-click the parts folder.
  3. Select New > Plug-in Role.

The Plug-in Role window is displayed. Specify a name for your role, and indicate the part in which to create the role. If the specified part name does not exist, it is created for you. Indicate whether to generate only the necessary directory structure, or create the directory structure and select one or more available script stubs. When you click Finish, the new role is added to the plugin/parts/<project>.scripts/scripts folder in the plug-in.

Values that you specify are immediately validated, and errors (such as existing names or files) are flagged (with help tips) for correction.

After you create your plug-in roles, you can edit the associated Python scripts with your preferred editor.

Decorations for files and directories

As a visual aid to plug-in developers, certain decorations are dynamically added to files and folders of plug-in contents to help you identify things easier:
P
Designates a plug-in part.
N
Designates a plug-in node part.
R
Designates a plug-in role
Check mark
Designates standard scripts for node parts and parts.
*
Designates a role lifecycle script.

Building the plug-in

When you are ready to build and export your plug-in, complete the following steps:
  1. In the Project Explorer view, right-click the plug-in project node.
  2. Select one of the build options from the IBM Workload Plug-in menu:Select one of the build options from the IBM Pattern Toolkit menu:
    Build
    Builds the plug-in package without Java source code.
    Build with source
    Builds the plug-in package with Java source code.
    Build with binary
    Added in PDK version 1.0.1.2. Builds the plug-in package with binary files. You are prompted to set the location of the files, either in a local directory or by using a remote URL. The files are put in the files directory in the resulting .tgz file.
  3. The build is started. Examine the Console view that is opened to check the progress of the build and view the resulting log messages.
  4. A new export folder is created, including the plug-in package with the name format <ID>-<Version>.tgz and more source files. This exported package can later be imported back into your Eclipse environment and modified as needed.

Installing plug-ins

While in your Eclipse environment, you can upload your packaged plug-in to a remote Cloud Pak System environment for testing and debugging:
  1. If needed, modify your Eclipse environment preferences (select Window > Preferences > IBM Pattern Toolkit) to specify the system access information for the remote Cloud Pak System environment, including the Cloud Pak System IP address, and a valid user ID and password.
  2. Ensure that your project was built successfully.
  3. In the Project Explorer view, right-click the plug-in project node.
  4. Select IBM Workload Plug-in > Install/Update to deployer. The installation process is started.
  5. Select IBM Pattern Toolkit > Install/Update to deployer. The installation process is started.

Removing plug-ins

While in your Eclipse environment, you can remove an installed plug-in from a remote Cloud Pak System environment:
  1. If needed, modify your Eclipse environment preferences (select Window > Preferences > IBM Pattern Toolkit) to specify the system access information for the remote Cloud Pak System environment, including the Cloud Pak System IP address, and a valid user ID and password.
  2. In the Project Explorer view, right-click the plug-in project node.
  3. Select IBM Workload Plug-in > Remove from deployer. The uninstallation process is started.
  4. Select IBM Pattern Toolkit > Remove from deployer. The uninstallation process is started.

Connecting to virtual machines in a virtual application instance

You can connect to a virtual machine in a virtual application instance to check the runtime status of the virtual machine or to debug an issue on a particular virtual machine:
  1. Change to the Workload Plug-in Runtime perspective if you are not already there:
    1. Click Window > Open Perspective > Other.
    2. Select Workload Plug-in Runtime.
    3. Click OK.
  2. Click Add new VM.
    • To add a specific virtual machine from a deployed instance, select Add a VM.
      1. Enter the IP address of the virtual machine.
    • To add all virtual machines in a virtual application instance on the system, select Add VM(s) from a deployed instance.
      1. Enter the IP address or host name, user name, and password for the system.
      2. Click Next.
      3. Select a virtual application instance.
  3. Optional: Click SSH Configuration to enter SSH properties for all virtual machines in the instance. Select the SSH connection mode: Key Mode or User/Password Mode.
    • If you are using Key Mode, enter the user name for the key. Click Browse and select the private key for the virtual application instance. Click Open, and then click OK.
    • If you are using User/Password Mode, enter the user name and password.
    Note:
    • Select Auto monitor running VM/Instance status (Will disable previous monitor setting) to automatically gather logs for the instance after the virtual machine is in a RUNNING status. The console tab shows the location of the logs in your Eclipse workspace.
    • If the SSH connection information changes in the future, you can click Connection Property for the virtual machine and update the properties.
    • Currently, only SSH-RSA format is supported.
  4. Click Finish.
  5. Select the virtual machine that you would like to connect to. Depending on the option that you chose in the previous step, the virtual machine is listed on its own or grouped with the virtual application instance that it belongs to.
    • If you did not configure the SSH connections information in the previous step, click Connection Property. Select the SSH connection mode: Key Mode or User/Password Mode.
      • If you are using Key Mode, enter the user name for the key. Click Browse and select the private key for the virtual application instance.
      • If you are using User/Password Mode, enter the user name and password.
      • Click OK.
    • If you configured the SSH connection information in the previous step, click Connect to VM.
    • If you connected to a specific virtual machine, the connection to the virtual machine occurs automatically.
    Note: If the SSH connection information changes in the future, select the virtual machine and click Connection Property to update the properties.

After you connect to the virtual machine, you can modify scripts that exist in the local workspace and upload them to replace the scripts in the virtual machine, check the runtime log, and view context data. If you installed the debug plug-in, you can select the Error Script node and resume the deployment process from an ERROR state, or restart the role lifecycle scripts from install.py.

Rerunning lifecycle scripts in a virtual application instance

You can connect to a virtual machine in a virtual application instance and rerun lifecycle scripts to debug issues:
  1. Change to the Workload Plug-in Runtime perspective if you are not already there:
    1. Click Window > Open Perspective > Other.
    2. Select Workload Plug-in Runtime.
    3. Click OK.
  2. Add the virtual machine with the script that you want to rerun if it is not already added. See the section "Connecting to virtual machines in a virtual application instance" for the steps to add a virtual machine.
  3. Expand the Roles section and locate the script that you want to rerun.
  4. Right-click the script and choose Restart from install.py. If the role is not in an ERROR state, the role scripts of that target role are rerun, starting from install.py.

Connecting to the console from Eclipse

You can open the console directly from Eclipse:
  1. Change to the Workload Plug-in Development perspective if you are not already there:
    1. Select a pattern type or plug-in project.
    2. Click Navigate to Deployer.
If your system is configured in the IBM Plug-in Toolkit preferences, which are accessed by clicking Window > Preferences > IBM Plug-in Toolkit, the console opens in your web browser.

If your system is not configured in the IBM Plug-in Toolkit preferences, the preferences page opens so that you can configure the settings for your system. After you enter the settings, you can click the Open Deployer console link on the preferences page to open the console in your web browser.

Limitations

This Eclipse plug-in development environment support does not support all configuration tasks that you might need to perform on your plug-in. Use your preferred text editor to configure any tasks that are not supported by this Eclipse plug-in directly in the plug-in configuration files.

Other reference

See the related links for references to plug-in development for virtual application patterns, the Plug-in Development Kit (PDK), and associated Java and Python script documentation that is provided with the PDK.