Plug-in Development Kit
This chapter describes how to use the Plug-in Development Kit (PDK) to create custom virtual application patterns (VAPs). This chapter describes the following topics:
4.1 Overview of the Plug-in Development Kit
The PDK enables you to create custom content that you can add to a VAP in the IBM PureApplication System. You can create your own custom content by creating plug-ins and pattern types. The custom content can be third-party software, or an enhancement to existing software that is already available as a VAP.
The PDK includes an Eclipse plug-in that you can use to develop the pattern types and plug-ins, which you can later use to create your own VAPs.
To use the PDK Eclipse plug-in, you need to have Eclipse version 3.6 or later (32-bit) and Java SE6 (32-bit).
You can find the steps to set up your Eclipse environment with the PDK in the IBM PureApplication System Version 1.0 Information Center:
On that web page, go to Working with Virtual Applications → Working with virtual application pattern plug-ins → Plug-in development guide → Plug-ins for development → Developing plug-ins in Eclipse.
As part of the Eclipse plug-in, the PDK provides the following two perspectives:
•The Workload Plug-in Development perspective, which you use to develop plug-ins.
•The Workload Plug-in Runtime perspective, which you use to debug and test a deployment by connecting to an ongoing deployment in PureApplication System.
These perspectives are described in detail later in this chapter.
4.2 The Workload Plug-in Development perspective
The Workload Plug-in Development perspective helps you in your development by providing project skeletons for new plug-ins and pattern type projects. With the PDK, you can add new content within your plug-ins, such as parts, node parts, roles, components, links, policies, and so on.
In the Workload Plug-in Development perspective, you can complete the following tasks:
•Create a new plug-in project or a pattern type project. The project skeleton is created automatically.
•Import existing plug-in or pattern type projects into your workspace.
•Visually define components, links, and policies, and define their attributes.
•Visually define parts, node parts, and roles. The required folder structures are automatically created in the project.
To go to the Workload Plug-in Development perspective, follow these steps:
1. Click Open Perspective → Other in your Eclipse workspace to launch the Open Perspective window, as shown in Figure 4-1 on page 47.
2. Select Workload Plug-in Development and click OK.
Figure 4-1 The Workload Plug-in Development perspective
4.2.1 Structure of a Workload Pattern Type project
You use a pattern type to create a logical grouping of a set of related plug-ins.
You can create a new pattern type project by clicking File → New → Other → IBM Workload Pattern Type project.
Figure 4-2 shows a typical folder structure for a pattern type project.
Figure 4-2 Folder structure for a pattern type project
The main file of interest in a pattern type project is the JavaScript Object Notation file (patterntype.json).
Figure 4-3 shows an overview of a pattern type.
Figure 4-3 Overview of a pattern type
Example 4-1 shows the JavaScript Object Notation (JSON) code for the pattern type.
Example 4-1 patterntype.json
{
"name": "patterntype.simple",
"shortname": "patterntype.simple",
"version": "1.0.0.0",
"description": "A simple pattern type",
"status": "",
"prereqs": {
},
"categories": [
{
"id": "application",
"label": "Application",
"description": ""
}
],
"builder": true
}
You can use the pattern type to define the name, short name, and a version. You can also define the following things in the patterntype.json file:
•Dependencies: You can define a dependency on another pattern type using the prereqs element.
•Categories: Use the categories element to define groupings of components. Later, when you create the component in the plug-in project, you can assign one of the categories defined here.
•Builder: If you set the builder element to true, your pattern type is made available to the Virtual Application Builder (VAB) to display as a separate pattern type. If you are only extending an existing pattern type, and you do not want your pattern type to be made visible in the VAB, you can set this element to false.
In addition to the patterntype.json, you can find the following folders and files in the Pattern Type project:
•The locales folder contains subfolders for each locale that you support.
•Each subfolder contains a messages.json file.
You can insert your translated messages in the messages.json file for each locale, and in the messages.json file directly under the locales folder, which is the default.
For example, you can define the Name and Description. You can name the translated elements of the patterntype.json file in the messages.json file under it.
The messages.json file is a property file with name and value pairs for each translatable variable. For example, Figure 4-4 shows the Name (NAME) and Description (DESCRIPTION), and these can be in translated format in each of the messages.json files.
Figure 4-4 Pattern type with NAME and DESCRIPTION translated
Example 4-2 shows the corresponding messages.json file under the locales/en/ folder. It has the NAME and DESCRIPTION expanded.
Example 4-2 patterntype/locales/en/messages.json file
{
"NAME" : "Simple Pattern Type",
"DESCRIPTION" : "IBM Workload Deployer Pattern Type for a simple component."
}
The licenses folder contains the license text in HTML format. If you create the licenses folder and the content in <locale>.html under it, the PureApplication System console requires you to accept the license to enable the pattern type, as shown in Figure 4-5.
Figure 4-5 Pattern type with license acceptance enabled
|
Important: Licenses are always defined for a pattern type. You cannot have separate licensing terms for plug-ins. All of the plug-ins that are defined for a pattern type can be under the same licensing terms.
|
4.2.2 Structure of a Workload Plug-in project
A plug-in project contains all of the code for the interface elements through components, links, and policies, and the implementation code through packages, parts, and node parts.
To create a new Workload Plug-in project, follow these steps:
1. Click File → New → Other → IBM Workload Plug-in project.
The PDK creates a skeleton structure for the plug-in project, one that you can edit and enhance as needed. Figure 4-6 on page 51 shows a typical structure for a Workload Plug-in project.
2. The main content of the Workload Plug-in project is under the plugin folder. The plugin folder contains the following files and folders:
– The config.json file contains the configuration information of the plug-in project.
– The appmodel folder defines all of the items that are made visible in the VAB. This folder contains the following three files:
• In the metadata.json file, you define the component, links, and policies.
• The operation.json file exposes actions that can be started on a virtual application after deployment.
• The tweak.json file contains configuration attributes that can be changed during virtual application run time.
– The parts folder contains subfolders for creating artifacts for the Python lifecycle scripts.
– The templates folder contains the Apache Velocity template files. You can use the PDK to define Apache Velocity template patterns in the .vm format. These files transform your metadata into the Topology document. If you are using Java-based transformations, you do not need these files.
– The OSGi folder contains the Open Services Gateway Initiative (OSGi) Service component in the .xml format. Use this component to map the components, links, and policies defined in the metadata.json to the transformers (see Figure 4-6 on page 51).
Figure 4-6 Project structure of a Workload Plug-in project
3. Select config.json from the Project Explorer window to see a quick overview of the package and metadata information for your project, as shown in Figure 4-7 on page 52.
Use this view to define the folder structure required for parts, node parts, or roles.
4. To add a new node, node part, or role, click the plus sign (+) icon on the upper right of the Package pane, as shown in Figure 4-7 on page 52. From the pop-up window, you can select either part, node part, or role.
|
Important: This action only adds the required directory structure under the plugin/parts folder. You have to define the required entries in the config.json file separately.
|
5. The Overview window also has a metadata section that shows the component, links, and policies. You can click Add, which takes you to the Application Model view. There, you can define new components, links, or policies.
Figure 4-7 shows the Overview tab of the project.
Figure 4-7 Overview of the Workload Plug-in project
Configuration view: The config.json file
To view the configured options in a GUI, you can go to the Configuration view by selecting the Configuration tab in the Overview.
Figure 4-8 on page 53 shows the configuration view. You can use this view to perform the following functions:
•Modify the basic plug-in information, such as the name and version number.
•Add secondary pattern types, if you want your component to be visible under other pattern types.
•Define plug-in files that are specific to the software product, such as configuration files or install files that are to be included with the plug-in. Defining plug-in files creates a new entry as a files element in the config.json file.
•Create plug-in parameters in which you can define variables that can be used later in the part or role lifecycle scripts.
To perform any of the these actions, you can click Add next to the respective section and add the required details.
Figure 4-8 The Configuration tab of the plug-in
Example 4-3 shows the config.json file corresponding to the Configuration view in Figure 4-8. You can directly add or modify the config.json file to change the configuration. For example, the files section of the code corresponds to the Plug-in Files section of the Configuration view, and the parms section of the code corresponds to the Plug-in Parameters section of the Configuration view.
Example 4-3 A sample config.json file
{
"name": "plugin.com.ibm.simple1",
"version": "1.0.0.0",
"patterntypes": {
"primary": {
"ptype.simple1": "1.0"
}
},
"packages": {
"simple1": [
{
"parts": [
{
"part": "parts/installPart.tgz",
"parms": {
"installDir": "/opt/IBM/sample"
}
},
{
"part": "parts/configPart.tgz",
"parms": {
"installDir": "/opt/IBM/sample"
}
}
]
}
]
},
"parms": {
}
}
To logically split functionality into meaningful pieces, you can define more than one package in the packages section of the config.json file. Note that you have to edit the config.json file to add the packages. You cannot do this from the Configuration view.
When you define the configuration for your plug-in, you can choose all of the pattern types under which your component is made visible when the VAB is used. You can choose from the following options:
•Isolate your components within your own pattern type, so that only your components are visible when you open the VAB for your pattern type. To do this, define your plug-in with only one primary pattern type.
•Extend an existing pattern type to your own pattern type, so that all of the components of the existing pattern type are also displayed under your pattern type. You need to use the linked element in the config.json file to implement this option. Example 4-4 makes all of the components of the patterntype.other visible when you open the VAB for the patterntype.simple1.
Example 4-4 The linked option in config.json
"patterntypes": {
"primary": {
"patterntype.simple": "1.0"
},
"linked": {
"patterntype.other": "1.0"
}
}
•Add your plug-in to an existing pattern type, so that when a user opens the VAB for the existing pattern type, your components are also available to use. To do this, you need to set the secondary pattern type to the pattern type that you are adding your component to, as shown in Example 4-5. In addition to this, if you do not want your primary pattern type to be available as an option in the VAB, you have to set builder to false in your primary pattern type JSON file, patterntype.json. Adding a secondary pattern makes your components visible under the existing pattern type.
Example 4-5 Add a secondary pattern type in config.json
"patterntypes":{
"primary":{
"patterntype.simple":"1.0"
},
"secondary":[
{
"patterntype.other":"1.0"
}
]
}
Application Model view: The metadata.json file
In the Application Model view, you create the components, links, and policies. These are made available to the VAB console. To go to the application model, click the Application Model tab on the Overview page.
In the Application Model view, you can create new components, links, and policies by clicking Add in the Metadata List section. Each of the components, links, or policies can have their own attributes, which you define using the Attributes section.
The Category option determines the category under which your component is visible in the VAB palette.
Figure 4-9 shows the Application Model view of a project. This project has defined a single component called simple1. It has one attribute called name of type string. Based on the Category selection, the simple1 component is visible under the application section in the palette.
Figure 4-9 The Application Model view
Example 4-6 shows the same application model in the metadata.json file. You can view the metadata.json file directly, and modify any of the entries that you have already created.
Example 4-6 A sample metadata.json file
[
{
"id": "simple1",
"type": "component",
"image": "appmodel/images/EntApp_64.png",
"thumbnail": "appmodel/images/thumbnail/EntApp_48.png",
"attributes": [
{
"id": "name",
"type": "string",
"required": true,
"label": "Name:",
"description": "Please Enter your name"
}
],
"label": "Simple",
"description": "A simple component",
"category": "application"
}
]
Operation view: The operation.json file
Use the Operation tab to add entries to the list in the operation.json file. The operation.json file contains a list of operations that can be called during the virtual application run time. With this option, you can define new operations that can be started on a deployed virtual application instance. For instance, a maintenance operation, such as restarting the application run time, can be defined as an operation.
The operations defined here get displayed in the Operation tab of the Virtual Application Console in the PureApplication System GUI. To see these operations, follow these steps:
1. Click Manage on a deployed instance. A new window opens.
2. Click Operations on the menu to take you to the Operations tab.
3. You can then navigate to your role to see the operations that you defined. Figure 4-10 shows an Operation view.
4. Add operations by clicking Add and supplying details, such as the Role where the operation has to be defined.
Figure 4-10 The Operation view
Example 4-7 shows the equivalent operation.json file. The JSON entry script defines the script to be run whenever the operation is started through the Operations tab in the Virtual Application Console at run time.
Example 4-7 A sample operation.json entry
{
"WASCE": [
{
"id": "RESTART",
"label": "Restart WAS CE instance",
"script": "operation.py restart",
"description": "Run the shutdown and startup command against WAS CE"
},
{
"id": "configuration",
"label": "Update Configuration",
"description": "Update configuration of WAS CE",
"script": "change.py"
}
]
}
Tweak view: The tweak.json file
On the Tweak tab, you can add entries into the tweak.json file. The tweak.json file contains a list of configuration attributes that can be changed during the virtual application run time. Use this option to define which configuration attributes (as defined in the metadata.json file) can be modified in a deployed virtual application instance.
The entries mentioned in the tweak.json file get displayed on the Operations tab of the Virtual Application Console at run time.
Figure 4-11 on page 59 shows a simple Tweak entry. You can use the Tweak view to add new entries into the tweak.json file. You need to specify the details, such as the ID and the Role where this action has to be defined. There is also the option of referring the action to an existing application model attribute that is defined in the metadata.json file. You can do this by using the Reference option, and specifying the Reference type, Reference Target, and Reference ID.
Figure 4-11 The Tweak view
Example 4-8 shows the equivalent tweak.json file. This entry can result in the archive being modifiable through the Configuration section of the Operations tab of the Virtual Application Console at run time.
Example 4-8 A sample tweak.json entry
[
{
"id": "WASCE.ARCHIVE",
"ref-component": "WARCE",
"label": "WAR File",
"description": "Specifies the web application (*.war) to be uploaded.",
"ref-id": "archive"
}
]
Parts
The parts in a plug-in project define a folder structure for scripts for the parts, roles, and dependencies.
Figure 4-12 shows a sample structure of the parts. If you are in the Workload Plug-in Development perspective, you can see these components:
•Parts are displayed as a folder icon with the letter P.
•Roles are displayed as a folder icon with the letter R.
•Dependencies are displayed as a folder icon with the letter D.
•All of the lifecycle Python scripts are displayed as a sheet icon with an asterisk (*).
Figure 4-12 Parts folder structure in the Project Explorer
A part can contain the install.py and uninstall.py Python lifecycle scripts. These scripts are normally used for saving the software binary files, and for setting up for the installation or configuration of the software in later steps.
Lifecycle scripts
The actual software installation and the configuration for the virtual application are created in the lifecycle scripts defined under the roles and dependencies.
A role can have the following lifecycle scripts:
•The install.py script is a lifecycle script that contains all of the install code, which is started during the initial deployment.
•The configure.py script contains the configuration of the installed software, which is started during the initial deployment after install.py.
•The start.py script contains commands for starting the instance that is now configured, and is started during the initial deployment after start.py.
•The stop.py script contains commands for stopping the instance.
•The changed.py script is a lifecycle script that is started by the pattern engine when there is a change in the state of the peer role. Implement this script if you need to run some actions whenever a peer role changes its state.
•The suspend.py script runs during an upgrade of a pattern at run time. This lifecycle script is used to suspend the role, and is started by the pattern engine when the virtual machine (VM) is shutting down.
•The checkpoint.py script runs during the upgrade of a pattern at run time. The plug-in developer uses this lifecycle script to do a checkpoint during upgrade, and a backup of the role and related data can be taken. This is applicable for a scenario where a restore is required, either due to an upgrade failure, or when a rollback is initiated.
•The resume.py script runs during an upgrade of a pattern at run time. This lifecycle script is meant to bring the role back to a RUNNING state, which is started by the pattern engine when the stopped VM is rebooted again.
A dependency can have the same set of lifecycle scripts. The difference here is the order in which these lifecycle scripts are started.
Deployment
During deployment, the order of execution is shown in the following steps:
1. For each part defined in the VM template, run the install.py file of the part.
2. For each role defined, run the lifecycle scripts in the following order:
a. <Role>/install.py
b. <Role>/<dependency>/install.py (for each dependency)
c. <Role>/configure.py
d. <Role>/<dependency>/configure.py (for each dependency)
e. <Role>/start.py
Note that, although each of the scripts in a role runs serially, the roles are initiated concurrently.
You can, however, configure the script to run the scripts in a role concurrently, with specific restrictions (maestro.* variables are read-only).
Lifecycle events
The following lifecycle scripts are started based on certain events occurring during the lifecycle of the deployed virtual application instance. These scripts let you control the order of execution:
•The changed.py script under the role reacts to any changes in peer roles. You can use this script to implement actions that can occur when a peer role changes. For instance, a workload manager can take the necessary action when a new instance of the application server comes up.
•The changed.py script under the <role>/<dependency> folder reacts to any changes to the role dependency. You might need to wait for a different or dependent role (possibly in a different VM instance) to finish starting before your configuration takes place. In that case, you can create a dependency on that role in your transformer, and create the <role>/<dependency>/changed.py script to have those dependent commands.
OSGi folder
The OSGi service component is located in the OSGi folder. Create a new OSGi service component:
1. Click File → New → Other → OSGi Service Component. A new window opens.
2. Enter the name. The name has to match with the component, link, or policy for which the service is meant.
3. You have the choice to select either the template-based transformer or the Java-based transformer.
4. Figure 4-13 shows the creation of a template-based transformer. Specify the Component vm-template file and the Link vm-template file to be created.
Skeleton files for the component and link are created. These files are created in the templates folder that is explained in a later section in this chapter.
Figure 4-13 Create a new OSGi service component for template-based transformer
Figure 4-14 on page 63 shows the window for creating a new OSGi component for a Java-based transformer. You need to specify the class that you want to create as part of the Java implementation. The PDK creates the .java file as an extension to the TopologyProvider class. You have to implement one or both of the transformComponent and the transformLink methods, as required by your project.
Figure 4-14 Create a new OSGi service component for a Java-based transformer
Templates
When you create a plug-in, you have a choice about how to define the transformer, either using the VM templates, or using Java code by implementing the TopologyProvider API. If you use the VM template-based transformation, a file with a .vm extension (the VM template) has to be created under the templates folder. Example 4-9 shows a simple VM template file.
Example 4-9 A simple VM template file
{
"vm-templates": [
{
"name" : "${prefix}-simple",
"packages" : [ "simple1" ],
"roles" : [
{
"plugin": "$provider.PluginScope",
"type" : "SIMPLE",
"name" : "SIMPLE",
"parms" : {
"name" : "$attributes.name"
}
}
]
}
]
}
4.2.3 Upload the pattern type and plug-in from the PDK
You can upload your pattern type and plug-in projects directly from the Eclipse integrated development environment (IDE) using the PDK.
You first need to configure the PDK with IBM PureApplication System:
1. Click Preferences → IBM Workload Plug-in.
2. Complete the details, such as the IP of the PureApplication System console, your user name, and your password, as shown in Figure 4-15.
Figure 4-15 Configure PDK with PureApplication System
3. To upload the pattern type project into PureApplication System, right-click the pattern type project and select IBM Pattern Toolkit Build, and then click Install/update to deployer, as shown in Figure 4-16 on page 65.
Figure 4-16 Upload the pattern type and plug-in projects from the Eclipse IDE
4.3 The Workload Plug-in Runtime perspective
You can use the Workload Plug-in Runtime perspective to debug and test your deployed pattern directly from the Eclipse IDE. With this option, you can connect to a deployed instance of a virtual application, and see the status of the deployment in the Eclipse workspace. This perspective is useful during plug-in development, because you can debug the deployed plug-in from the Eclipse IDE itself.
You also have the additional option of modifying any failed Python files, and uploading them into the deployed instance to enable live debugging on the deployed instance.
Follow these steps to switch to the Workload Plug-in Runtime perspective:
1. Click Open Perspective → Other in your Eclipse workspace to launch the Open Perspective window.
2. Select the Workload Plug-in Runtime perspective and click OK.
Figure 4-17 shows the Workload Plug-in Runtime perspective on the Eclipse workspace, where a connection has been created to a deployed instance.
Figure 4-17 The Workload Runtime perspective
You will learn all about debugging using the Workload Plug-in Runtime perspective in Chapter 7, “Debugging and testing” on page 149.
4.4 Setting up the PDK environment
For the latest version of the PDK, and the steps to download it, install the PDK and set it up. See the PureApplication System binary files Information Center at the following website:
4.5 Create a simple plug-in project with the PDK
For step-by-step instructions on creating a simple pattern with the PDK, watch the video at the following website:
The video shows you how to create a simple pattern type and a plug-in. The video also shows you how to create a VAP and deploy the pattern in PureApplication System.
..................Content has been hidden....................
You can't read the all page of ebook, please click here login for view all page.