Setting up the Visual Configuration Explorer SDK
The Visual Configuration Explorer
SDK is provided as an aid for developing additional content for the tool. For example, new
providers could be developed to allow the tool to support additional products. This guide
provides instructions for setting up an environment in which the SDK can be used.
These instructions were developed on a
Windows® XP system. They use a specific set of directories. If you choose to use
different directories, you must make the appropriate changes to the instructions.
- Download the IBM Support Assistant V4.0.2 Workbench for Windows from the
IBM web site. You will need an IBM ID.
- Click proceed directly to the download page.
- Select IBM Support Assistant V4.0.2 and click Continue.
- Update your business contact information, check the privacy boxes as appropriate,
view the license, check I agree, and click I confirm.
- Check IBM Support Assistant 4.0.2 Workbench for Windows and click Download now.
(You may have to install a java plug-in to enable the Download Director.) The file
ibmsa-v402-wb-win32.zip will be downloaded onto your machine.
- Extract the contents of the zip file to c:\temp\isawb402.
- From a Windows Command Prompt, run c:\temp\isawb402\setupwin32.exe and
proceed as directed. Do not start the workbench from the icon created on your desktop.
- Create a new text file vcesdk.link in the C:\Program Files\IBM\IBM Support Assistant\eclipse\links
directory. The content of the file should be:
path=C\:/Documents and Settings/userid/IBM/ISAv4/applications
- Download the eclipse-SDK-3.2.2-win32.zip file from the
Eclipse
web site.
- Extract the contents of the zip file to the c:\eclipse32 directory.
- Install a suitable Java virtual machine (JVM) or Java runtime environment (JRE)
if there is not one already installed on the machine. For a list of
suitable platforms see the C:\eclipse32\eclipse\readme\readme_eclipse.html file. These instructions were developed
using an IBM J2RE 1.5.0 installed at C:\Program Files\IBM\VCE\eclipse\jre.
- Open a Windows Command Prompt, and change the directory to \eclipse32\eclipse.
- Launch eclipse specifying the JVM or JRE using the following command:
eclipse -vm "C:\Program Files\IBM\VCE\eclipse\jre\bin\javaw"
(To enable ease in running this command, create a short cut on your desktop.)
- Allow the workspace folder to be set to C:\Documents and Settings\userid\workspace.
- Click the Workbench icon on the Eclipse Welcome page.
- In Eclipse's Window menu, select Preferences. Then in the resulting dialog, select Target Platform under Plug-in
Developement. In the Target Platform pane, specify the Location as C:\Program Files\IBM\IBM Support Assistant\eclipse, check
Group plug-ins by location, and click Reload, Apply, and OK.
SDK Installation
Under Eclipse's Help menu, highlight Software Updates and click Find and Install.... In the resulting dialog, select
Search for new features to install and click Next>. In the next dialog, check Callisto Discovery Site and click
Finish and OK. Expand the Callisto Discovery Site and select the following features:
- Batik 1.6.0
- Graphical Editing Framework 3.2.2
- Eclipse Modeling Framework (EMF) Runtime + End-User Tools 2.2.2
- XML Schema Infoset Model (XSD) Runtime + End-User Tools 2.2.2
- EMF Service Data Objects (SDO) Runtime + End-User Tools 2.2.1
- Graphical Modeling Framework 1.0.3
- Java EMF Model 1.2.1
- Web Standard Tools (WST) Project 1.5.4
- J2EE Standard Tools (JST) Project 1.5.4
Click Next>, specify you accept the license, click Next>, Finish, and Install All, and restart Eclipse.
Unzip the vce-dev-update-site.zip file from the alphaWorks distribution into the
C:\temp\vce-dev-update-site directory; preserve the folder names within the zip file.
Under Eclipse's Help menu, highlight Software Updates and click Find and Install.... In the resulting dialog, select
Search for new features to install and click Next>. In the next dialog, click New Local Site..., select the
c:\temp\vce-dev-update-site directory you created in the previous step and specify the name as
IBM VCE SDK Updates, and click OK and Finish.
Then, expand the newly-created site, check both VCE Provider Workbench Feature and Visual Configuration
Explorer SDK Feature, and click Next>. Specify you accept the license, click Next>, Finish, and Install All, and restart Eclipse.
Configuring Eclipse 3.2.2
- In Eclipse's Run menu, select Run.... In the resulting dialog, highlight
Eclipse Application, and click the New launch configuration button. Then, highlight the newly created eclipse
application and specify the following settings:
- Specify the Name as ISAv4.
- In the Main tab, specify the Location as C:\Documents and Settings\userid\IBM\ISAv4, check Run a product:
and specify com.ibm.esupport.platform.branding.isaproduct. Then, check java, and click Installed JREs....
In the resulting dialog, click Add; then, specify JRE type as Standard VM, JRE home directory as
C:\Program Files\IBM\IBM Support Assistant\rcp\eclipse\plugins\com.ibm.rcp.j2se.win32.x86_1.5.0.SR6-200802132253\jre,
and JRE name as ISAv4, and click OK. Check ISAv4 and click OK. Now, back in the Main tab, specify the Runtime JRE: as ISAv4.
- In the Arguments tab:
- Click Variables... in the VM Arguments area; in the dialog click Edit Variables, and in the next
dialog click New.... Finally, set the variable rcp_base to the value,
C:\Program Files\IBM\IBM Support Assistant\rcp\eclipse\plugins\com.ibm.rcp.base_6.1.2.200802132253, and click OK three times.
- Then, specify the Program arguments as:
-debug
-console
- And specify the VM arguments as:
-Xquickstart
"-Xbootclasspath/a:${rcp_base}/rcpbootcp.jar"
"-Drcp.home=c:\Program Files\IBM\IBM Support Assistant"
-Dinstall.configuration=user
-Dupdate.policy.managed=true
"-Dprovisioning.manifest=file\:/c:\Program Files\IBM\IBM Support Assistant/rcp/deploy/install.xml"
-Djvm.parent.feature.id=com.ibm.rcp.jvm.feature
"-Drcp.base.location=c:\Program Files\IBM\IBM Support Assistant/rcp/eclipse/plugins/com.ibm.rcp.base_6.1.2.200802132253"
-Dprovisioning.application=com.ibm.rcp.provisioning.application.ProvisioningApplication
-Drcp.install.id=1219771944625
-Dprovisioning=true
-Dosgi.splashPath=platform\:/base/../shared/eclipse/plugins/com.ibm.esupport.platform.branding,platform\:/base/../shared/eclipse/plugins/com.ibm.esupport.platform.branding.nl1,platform\:/base/../shared/eclipse/plugins/com.ibm.esupport.platform.branding.nl2,platform\:/base/../shared/eclipse/plugins/com.ibm.esupport.platform.branding.nl3
-Djvm.parent.feature.version=2.0.0.0-200802132253
"-Drcp.data=C:\Documents and Settings\dudley\IBM\ISAv4"
-Dprovisioning.manifest.version=1219771944625
- Under Working directory check Other and specify C:\Program Files\IBM\IBM Support Assistant\eclipse.
- In the Plug-ins tab, set Launch with to all workspace and enabled external plug-ins. Then click Validate Plug-in set;
you should see a dialog indicating No problems were detected; click OK.
- In the Configuration tab:
- In the Configuration Area, uncheck use default location and set the Location to C:\Documents and Settings\userid\IBM\ISAv4\.config.
- For the Configuration File, check Generate a config.ini file with default content.
- Then in the Run Configurations dialog, click Apply and click Run. The ISA workbench should
then be launched.
Installing Visual Configuration Explorer
In the launched ISA workbench, highlight Find new... under the Update menu and click Product add-ons. In
the resulting dialog, select Visual Configuration Explorer Topology Collector under Other and click Next>. Then,
select Visual Configuration Explorer ISA Feature under Configuration Tools and click Next>. Finally, check
I accept the terms in the license agreements, click Next> and click Finish. Don't restart the workbench; instead,
manually close the workbench.
In Eclipse's Window menu, select Preferences. Then in the resulting dialog, select Target Platform under Plug-in
Developement. Click Reload, Apply, and OK. Then, restart the workbench by selecting Run... in Eclipse's Run menu;
in the resulting dialog, select ISAv4 under Eclipse Application and click Run.
Using the Visual Configuration Explorer SDK
The SDK consists of two features that can be used to develop additional Visual Configuration Explorer providers.
The Visual Configuration Explorer SDK feature provides Javadoc for the Visual Configuration Explorer APIs and
utilities that are available for this task. It also provides Eclipse source code that can be useful when running the
Eclipse debugger. The VCE Provider Workbench feature simplifies the creation of a new provider by creating code
templates and a user interface plugin required by a working provider; it also simplifies the process of defining the topology objects
associated with the provider and encorporating the images used as icons for those objects.
Development of a new provider consists of several tasks. At a high-level these tasks are as follows:
- Deciding how to retrieve the topology configuration information from the product.
- Deciding how to represent the topology as a set of defined topology-object types.
- Creating the provider structure for those topology-object types.
- Writing the code to parse the topolgy configuration information, and create the topology objects to represent
the parsed topology.
- Creating and encorporating the images that will function as icons for the topology-object types.
The following instructions will describe some of the process
for creating a provider for "Product X". First, a new plug-in project is created; let's call this plug-in
productx.provider. We will use PX as an identifier for Product X.
- Under the Eclipse File menu, highlight New
and click Project.
- Then, select Plug-in Project under Plug-in Development and click Next>.
- Specify project name as productx.provider and
click Next>.
- Specify the plug-in name as Visual Configuration Explorer Product X Plugin and the
plug-in provider as your company name, and click Next> and Finish. If asked, agree to open the Plug-in
Development perspective.
Then, create a new provider model.
- Create a model folder by right clicking the productx.provider project and clicking Folder under New. Specify the
folder name as model and click Finish.
- Select the newly-created folder, right click, highlight New, and click Other....
- Then, select VCE Provider Model under Example EMF Model Creation Wizards and click Next>.
- Provide a file name with a file type of provider (e.g., PX.provider), and click Next>.
- Specify the Model Object as Providers and click Finish.
Next, create a provider diagram by:
- Right click the newly-created provider file and select
Initialize provider_diagram diagram file.
- Specify a file name with a file type of
provider_diagram (e.g., PX.provider_diagram) and click Next> and Finish.
Open the provider diagram, and use the pallate to define a provider type and the topology object types
associated with the new provider. Use RelationshipMetaInfo to define the hierarchical relationships among
the provider type and the topology object types. The following instructions define two topology object types:
a top-level object named Top and a second-level object named SecondLevel.
- Double click the provider diagram to open the diagram.
- Right click in the diagram and click Show Properties View. In the Properties view, select the
Advanced tab.
- Specify the following fields under EMF (type Enter after each item):
- Model Package as "productx.provider"
- Model Plugin Id as "productx.provider"
- Model Plugin Name as "Visual Configuration Explorer Product X Plugin"
- UI Directory as "/productx.provider.ui/src
- UI Package as "productx.provider.ui"
- UI Plugin Id as "productx.provider.ui"
- UI Plugin Name as "Visual Configuration Explorer Product X UI Plugin"
- Highlight Provider Type in the pallate and then click in the editor pane to create a new provider type.
- Right click the new provider-type object and click Show Properties View. In the Properties view, select the
Advanced tab.
- Specify the following fields under EMF(type Enter after each item):
- Short Name as "Provider"
- Type Namespace as "PX"
- Highlight Topology Object Type in the pallate and then click in the editor pane to create a new topology object type.
- Highlight RelationshipMetaInfo in the pallate and then click and hold the provider type object, move the cursor
to the new topology-object-type object, and release the mouse button.
- Right click the new topology-object-type object and click Show Properties View. In the Properties view, select the
Advanced tab.
- Specify the following fields under EMF(type Enter after each item):
- Highlight Topology Object Type in the pallate and then click in the editor pane to create a new topology object type.
- Highlight RelationshipMetaInfo in the pallate and then click and hold the first topology-object-type object, move
the cursor to the new topology-object-type object, and release the mouse button.
- Right click the new topology-object-type object and click Show Properties View. In the Properties view, select the
Advanced tab.
- Specify the following fields under EMF(type Enter after each item):
- Short Name as "SecondLevel"
- Enter cntl-s.
- Right click inside the editor pane and click Validate. If everything is ok, no error dialog will appear.
- Right click PX.provider in the Package Explorer view and click Generate provider code. No error
dialog should appear.
Warning! Remove the @generated comment from any method you change before running Generate provider code again;
otherwise, your change will be overwritten.
The following instructions will add some sample code to the generated code:
- Replace the code in the isValid method of PXConfigurationHandler with the following:
File dir = new File(location);
if (!dir.isDirectory())
return false;
File[] files = dir.listFiles();
for (int i = 0; i < files.length; i++) {
File file = files[i];
String fName = file.getName();
if (fName.equals("test.xml"))
return true;
}
return false;
- Click one of the three x's that will appear, highlight Import File (java.io), and type Enter. Save the changes.
- Replace the code in the initialize method of PXTopologyProvider with the following:
String configId = providerInfo.getProperty("provider.configurationId");
TopologyObjectType objectType = getObjectTypeByPublicType("PX.Provider");
TopologyObjectImpl providerObject = createTopologyObject(Integer.toString(objectType.hashCode()), "PX Provider", objectType);
PropertyList providerProperties = new PropertyList(PropertyList.DEFAULT_COMPARATOR_KEY);
providerProperties.addProperty(new Property("testKey", "testValue"));
providerProperties.addProperty(new Property("configurationId", configId));
providerObject.cacheProperties(providerProperties);
TopologyObjectImpl topObject = createTopologyObject(generateUniqueId(), "testTop", getObjectTypeByPublicType("PX.Top"));
cacheRelatedObjects(providerObject, topObject, getCompositionRelationship(providerObject, topObject));
PropertyList topProperties = new PropertyList(PropertyList.DEFAULT_COMPARATOR_KEY);
topProperties.addProperty(new Property("version", "1.0"));
topObject.cacheProperties(topProperties);
- Click the x that will appear next to TopologyObjectType, highlight Import TopologyObjectType (com.ibm.adt.topology.object), and type Enter.
- Add the following method to PX TopologyProvider
private RelationshipMetaInfo getCompositionRelationship(TopologyObject source, TopologyObject target) throws TopologyException
{
String key = "relationshipType=COMPOSITION::sourceType=" + source.getType() + "::targetType=" + target.getType();
return getRelationshipsMetaInfo(key)[0];
}
- Click the x that will appear next to new method, highlight Import TopologyObject (com.ibm.adt.topology.object), and type Enter.
- Click the x next to new method again, highlight Import RelationshipMetaInfo (com.ibm.adt.topology.object.relationship), and type Enter.
- Save the changes to the file.
Create a "topology collection" for the Product X provider:
- Create an empty file named test.xml in a new folder at some convenient location on your file system.
- Launch the ISA V4 workbench from the Eclipse environment (in the Run Configurations dialog, click Run.)
- Launch Visual Configuration Explorer from the ISA workbench.
- Click Analyze Problem.
- Click the Tools tab.
- Highlight Visual Configuration Explorer (Tech Preview) and click Launch.
- Add a new workspace to Visual Configuration Explorer.
- Click New VCE Workspace... under the File menu.
- Specify a file name of isav4.vce in a convenient directory, and click Save.
- Drag the folder containing test.xml (from Windows Explorer) into the Providers pane.
- In the resulting dialog, specify Product X as the alias prefix and click OK.
Enhancing a Provider
Validation Framework
Visual Configuration Explorer has other tools that can be used to make a
provider more valuable. Visual Configuration Explorer provides a validation
framework that can be used to check the validity of configurations based on
user defined rules. A user may create and edit rules files with a built-in
Rules Editor. Rules files are normal files on the filesystem, allowing them
to be shared among a community of Visual Configuration Explorer users. With
only a little effort, a user can also embed rules files into plugins which
can then be deployed using eclipse update mechanisms. See the Working
with the Validation Framework section of the Visual Configuration Explorer
Help information under Tasks.
Templates
Templates provide an easy and quick way to populate a diagram with
common patterns of topology objects and relationships.
Although VCE comes equiped with a set of templates, you can create your own
and share them with others by following the steps below.
Start by constructing a diagram that contains an example of what you wish
your template to produce.
Pick a starting object on your diagram and select it. It must be a Topology Object,
not a Topology Relationship, and it must be the only selected object.
Templates create connected subgraphs of objects. Accordingly, the
template generator works with only the set of objects that are connected
directly or indirectly to your start object in your diagram. Objects that
are not included in the connected subgraph are ignored during template
generation.
Note: If you have a cycle in your graph, the
resulting template might not work as you expect.
The template engine will repeatedly look for matching
objects. When you apply a template, the template engine
continues looking for matches until it finds no more. When
the example graph (and therefore also the template)
contains cycles, this may cause more
objects in your workspace to be matched than you intended.
If you apply your generated template to an object and get a warning that
a large number of objects are about to be added to the diagram, you
should examine your example graph and see if you can simplify it
by removing relationships that cause cycles, and then generate a new
template from your simplified graph.
From the context menu, select "Generate Template". Complete the fields in the
resulting dialog.
- Name (Required) Give a name to your template. This name will appear in the list of
applicable templates when you select the starting object, open the context menu,
and select the "Apply Template" menu item.
- Description (Optional) Provide a textual description for what your
template is doing.
- Add generated template to a template file Check this box if you
want to save your template in a file for later use. If you do not save your
template, it will be lost when you shut down VCE.
- Template Filename Pick an existing or new file where your template will
be stored.
When you hit the "OK" button, a template will be generated and is available for
you to use during the remainder of your VCE session. If you saved the template
to a file, you can use it again later by configuring the VCE preference page
to load it on startup. Bring up the preference page by lauching the preferences
editor from the Window/Preferences menu. In the editor, navigate down to
Visual Configuration Explorer/Topology Templates.
Test your new template be creating a new diagram and pasting only your start object
into it. Right click the object and select your new template from the "Apply Template"
menu item. It should add all the connected objects from your original diagram, plus
any that match the same pattern.