What is a Build Style?

A build style is a set of operations contributed by a build style provider that operate on iSeries Projects.  Typically a build style will provide push operations and build operations, although it need not provide these and may provide other operations.  These operations typically show up in the iSeries Project Navigator context menu under the heading "Remote Actions".  These operations are standard eclipse action contributions.

Each iSeries project has its own build style, which can be configured using the properties page of the project.  The workspace has a "default" build style – selectable by the user – that can be configured with defaults for each new project in the workspace.  A build style provider contributes the configuration dialogs for both of these and is responsible for storing any resulting configuration data.  The underlying build style support takes care of presenting these dialogs to the user and oversees the selection of a build style for a project.

In this example, we construct a build style that contributes push actions and the ability to submit and track a command for the selected project. This example build style is substantially similar to the IBM supplied "Command Build Style".

Why do I want to build one of these?

Build styles are meant to provide a means for IBM and other tool providers to incorporate the eclipse workbench tools and resource management and the iSeries Project Model into their existing tools.  Not everyone needs to write a build style, but you might consider it if you have any of the following requirements:
· You need to track files and other resources as they are uploaded to a host
· You need to interface to an existing build engine on the host that you support.
· You want to provide operations to your users other than the ones IBM supplies
· You want to drop IBM's support and supply your own

The build styles IBM provides are plugged into the workbench just as any other provider.  As such, they can be removed and new ones supplied.

How do I start?

You have to do three things to provide a build style:
(1) Define the build style in your plug-in using the plugin.xml file.
(2) Define the client code to support the actions that you define in your plug-in.
(3) Write your server code to interface to your build engine and your client-side actions.

Let's examine these more closely.

Defining your plugin.xml

See the plugin.xml file provided with this example. It will have various sections that extend the support provided by IBM and the base Eclipse workbench. These are devoted to describing how the build style is contributed.

The first tag of interest is the <buildStyle> tag. A build style is relatively simple -- it has the following attributes:
· A name that is shown to the workbench user whenever a build style needs to be selected.
· A unique ID that will distinguish it from any other build style installed in the workbench
· A priority that is used to determine the initial default for the workbench and for ordering all the installed build styles in a list
· A class that can be instantiated by the workbench to provide other information about the build style and which controls the gathering of information for a particular project.

In addition to the build style itself, you need to define actions to be taken by the build style.  These are normal eclipse object actions, defined by the <objectContribution> and embedded <filter> and <action> tags, that are provided objects in the model provided by the com.ibm.etools.iseries.perspectives plug-in.  You should filter these actions by the type of object in the model you want to operate on and also by the ActiveBuildStyle persistent property of the project.  Filtering actions by this property ensures that your actions show up only on projects that have your build style.

Lastly, if you want to use the properties model of the iSeries Project model to provide persistence for your attributes of your build style you need to define these properties.  See the plugin.xml which defines two properties -- one for the command to submit and one that saves the "auto push" value for that project. These properties are implicitly qualified by the plugin id and when you use them in the code you need to prefix them by the plugin id.  For example "BuildCommand" is really "com.ibm.etools.iseries.remotebuild.examples.BuildCommand".

Defining your client code

The code provided by your plugin must define the operations necessary to carry out the actions you defined in your plugin.xml.  You have to implement these operations yourself, but IBM provides a set of APIs and frameworks for you to use in building your build style.  These APIs and frameworks are defined in the package com.ibm.etools.iseries.remotebuild.  IBM uses these APIs and frameworks to build its own build styles.

This example consists of several classes, some of which provide a framework and support for the various classes that do the "real" work. It would be good to study this in some detail.

Defining the server code

As stated earlier a build style will usually provide push and build operations.  Push operations can be done entirely from the client side -- although fancy encodings or high-performance, high-volume pushes may require server assistance.  Only the simplest build operations, however, can be accomplished without any server code.  In this example, we use the IBM supplied server program QDEVTOOLS/QRBCMDBLD to run our command. So, for this example, we avoid having to write iSeries code.

Any provider of a build style should write their own build style server to "catch" build requests from the client.  IBM provides an API for assisting the development of build style servers.  This API is located in the service program QDEVTOOLS/QRBUTIL.  This program provides API for build style servers written either in C (the C API) or in other languages such as CL or RPG (the Standard API).  Both APIs accomplish the same thing.  The C API is more convenient to use with a build style servers written in C because it understands null-terminated strings and provides return values allocated on the C heap.  Build style servers may be written in Java as well, and may find it convenient to use the Standard API, PCML, and the AS400 Toolbox for Java classes.