Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
COSMOS SDD Tooling BTG Design
Overview
The Build Time Generator (BTG) is an Eclipse Rich Client Platform (RCP) application with a command line interface. It inspects existing install packages and build environments, gathers information needed to create an SDD, aggregates the information collected and outputs a package descriptor and a deployment descriptor.
The BTG consists of three major components: the main application, the data collector plug-ins, and the aggregator plug-ins. The main application defines extension points for the data collector plug-ins and the aggregator plug-ins, and it also controls the flow of the plug-ins and outputs the SDD package. The data collector plug-ins are responsible for collecting data from existing install packages, databases, and user specific build environments, then stores those data in Java data objects and passes them back to the main application. The aggregator plug-ins receives the data collected from the main application, combines these data into a SDD package, and passes the SDD package back to the main application.
Component Diagram
Dataflow Diagram
The following diagram shows the data flow of the BTG application.
- SDDFragment object:
- Made up of a DataObject fragment of an SDD and another object that contains meta-data that describes the DataObject.
- Aggregator:
- Inputs: List of SDDFragments, Control file path, boolean for allow incomplete SDDs
- Outputs: SDD files.
- Data Collection Plug-in:
- Inputs: Properties to point to data to be collected
- Outputs: List of SDDFragments
- BTG Main program:
- Inputs: Properties file(s) that contain overall program settings and plug-in settings, Command line parameters
- Outputs: SDD files
Main Application
The BTG main application is an extension of the org.eclipse.core.runtime.applications extension point. It is the main plug-in that controls the flow of this RCP application.
Control flow
The main application takes command line parameters from the user and parses the properties file that defines packages or environments to be inspected. The main application finds all the available data collector plug-ins and passes the parsed properties to each plug-in, and gets back SDDFragments from each plug-in. It then finds the appropriate aggregator plug-in to use(logic TBD), and passes the SDDFragments, the control file if any, and a boolean variable to tell the aggregator if incomplete SDDs are allowed to be returned. Once the main application gets the SDD package from the aggregator, it will either print the SDDs to console or save them to the file system.
Extension points
This main plug-in has two extension points, one for the data collector plug-ins, and the other for the aggregator plug-ins. These extension points will each define an interface class that the plug-ins need to implement in order to completely define a data collector plug-in or an aggregator plug-in.
The IBTGDataAggregator class requires the aggregator plug-in to implement the method aggregateSDDData which takes in a list of SDDFragments, the path for the control file, and the boolean to determine if incomplete SDDs are allowed to be returned. The default value for the boolean is false. This method returns a list of SDDs back to the main application.
The IBTGDataCollector class requires the data collector plug-in to implement the method collectSDDData. This method takes in a properties object which contains information on the source that the data collector plug-in will inspect, and returns an array of SDDFragments.
The SDDFragment object contains an SDO DataObject and a meta-data object to describe the DataObject. The format of this meta-data object has not been determined at this point, it will contain information such as where the DataObject should be placed in the SDD, where the information in the DataObject came from, etc.
Command Line Options
Text here...
Properties File
The Properties File contains a list of name/value pairs that specify runtime options to the Build Time Generator. Options can be targeted to either the main BTG program or one of the Data Collection Plug-ins. When an option is specified both in the Properties File and on the command line, the command line option takes precedence. See the Command Line Options section for more information about controlling the BTG from the command line.
Format
The Properties File consists of sections which group together the options to use when calling a particular plug-in. Each section begins with a section header, which is the ID of the plug-in that section applies to, surrounded in square brackets. The closing square bracket should be the last character on the line, or a parse error will result. After the section header, the rest of the section is a list of name/value pairs, one per line. The section ends when a new section begins or the end of the file is reached. Blank lines are ignored. Any line starting with # is considered a comment and is ignored.
Here is an example Properties File:
[com.ibm.btg.rpm.RPMReader] enabled=true filename=/home/sdduser/TestInput.rpm [com.ibm.btg.sql.SQLReader] #Change the next line to "true" to enable the SQLReader Plug-in enabled=false dbtype=DB2 database=SAMPLE
To avoid ambiguity, the formatting requirements are very strict. The BTG will terminate if a parse error occurs during parsing of the Properties File.
How Options Control Program Flow
Each enabled section corresponds to a single call to the referenced plug-in with the options given. So, in the case of the example Properties File above, the BTG would make one call to the RPMReader plug-in and one call to the SQLReader plug-in. Multiple sections can reference the same plug-in ID, which will result in multiple calls to that plug-in, once with each set of options. If a data collection plug-in is loaded but there is no corresponding options section in the Properties File, the BTG will not call that plug-in.
Special Sections
The section name [com.ibm.isd.btg] is reserved for passing options to the main BTG program. The BTG performs validation of options in this section, so any required options that are missing will result in an error.
| Property Name | Required | Description |
|---|---|---|
| OutputFileNameBase | Yes | Base to use when generating output file names |
Reserved Property Names
Data Collector plug-ins may generally define whatever property names they wish. However, there are some property names which are either reserved for use by the BTG or required for all plug-ins. Reserved property names may not appear in the Properties File and required properties must be present in every section. Below is a list of the reserved and required property names.
| Property Name | Description |
|---|---|
| PluginID | Used internally by the BTG to match properties with the correct plugin |
| Property Name | Allowed Values | Description |
|---|---|---|
| Enabled | *true* or *false* | Allows a section of the Properties File to be ignored without having to removed the section |
Aggregator plug-ins
The purpose for aggregator plug-ins is to receive SDDFragments collected by the data collector plug-ins and aggregate them into on or more SDD packages. The BTG will include a sample aggregator that has a default set of rules for combining data into a single SDD, and it can also take a user defined control file that overwrites the default rules. If the user has chosen not to accept an incomplete SDD and the aggregator doesn't have enough information to form a complete SDD, an IncompleteSDDException will be thrown.
Users can choose to create their own aggregator plug-ins for more user-specific purposes, and plug it into the BTG RCP. If two or more aggregators are found, the main application will decide which aggregator to be used based on user input (logic TBD). Each aggregator plug-in needs to implement the IBTGDataAggregator interface in order to extend the main application's data aggregator extension point.
An aggregator may return more than one SDD, which can consist of many package descriptors and many deployment descriptors. In order for the BTG to correctly write the descriptors to files, it must have some way of knowing which package and deployment descriptors go together to form each SDD. The aggregator communicates this information using the metadata inside each SDDFragment. The metadata property *UniqueSDDName* must be set for each SDDFragment if the aggregator is returning more than one SDD. Fragments with the same uniqueSDDName will be treated as part of the same SDD.
More details about sample aggregator goes here.
Data Collector plug-ins
The Data Collector plug-ins receives properties about the source to be inspected, finds the source, collects information by inspecting it, and creates SDDFragments to be returned to the main application.
Each Data Collector plug-in usually inspects one specific type of source, for example, a type of install package, a database, or a build environment. It needs to implement the IBTGDataCollector interface in order to extend the main application's data collector extension point.
The BTG RCP includes a set of Data Collector plug-ins: