Rational Developer for System z

Creating a property group

This sample demonstrates how to programmatically create a property group that has values for predefined properties and properties that are registered with Rational® Developer for System z®.

Sample Scenario

To create a property group, select the API Sample Actions -> Create Property Group action from the pop-up menu of an MVS Files node in the Remote Systems view.

Statements are displayed when the property group is created and when the property values are set. Also, if any error conditions are detected, error messages are displayed as well. They will be displayed in the standard output associated with the workbench. This can be found in the DOS window from which the workbench was started, or in the Console view of the hosting workbench in the case of the runtime workbench.

Note: The standard output for a workbench started with the standard Eclipse icon may not be visible depending on the runtime settings for the workbench.

The following illustration shows the results of successfully creating the property group and setting the values:

Artwork for createPropertyGroupResults

Sample Code Walk-through

Retrieving the Property Group Container for the System

The following code snippet from the CreatePropertyGroupAction class demonstrates how to retrieve the property group container for the selected system:
  
if (selectedItem == null) {
  System.err.println("Create Property Group Action - Selected resource must be an MVS File subsystem.");
  return;
}
if (selectedItem instanceof ZOSSystemReference) {
  System.out.println("");
  System.out.println("-----------------------");
  System.out.println("Beginning Create Property Group Action...");
  ZOSSystemReference reference = (ZOSSystemReference) selectedItem;
  ZOSSystemImage system = (ZOSSystemImage) reference.getReferent();
  // Get the property group container for this system.
  ZOSPropertyGroupManager manager = ZOSPropertyGroupManager.getZOSPropertyGroupManager();
  IPropertyGroupContainer container = manager.getPropertyGroupContainer(system.getName());
  if (container == null) {
    System.err.println("Create Property Group Action - No container for system: " + system.getName());
    return;
  }

It starts by verifying that the selectedItem is an instance of the ZOSSystemReference class. If so, it retrieves the ZOSSystemImage from the ZOSSystemReference using the getReferent method.

For each system connection, there is a property group container. The property group container for a given system name can be retrieved by using the getPropertyGroupContainer method of the ZOSPropertyGroupManager class.

Creating a Property Group

The following code snippet from the CreatePropertyGroupAction class demonstrates how to create a property group that consists of a category instance from a user-defined category as well as a category instance from a predefined category.
 
IPropertyGroup group = null;
try {
  group = container.createPropertyGroup(PROPERTY_GROUP_NAME, "");
  System.out.println(PROPERTY_GROUP_NAME + " created.");
} catch (DuplicatePropertyGroupException e1) {
  System.err.println("Create Property Group Action - Property group already exists.");
  return;
}

The property group is created by using the createPropertyGroup method. If the property group already exists, a DuplicatePropertyGroupException is thrown and an error message is printed.

Using a User-Defined Category

The following code snippet demonstrates how to create a category instance for a user-defined category and add it to a property group:
// Create an instance of the user-defined category, set properties,
// and add the instance to the property group. These properties will not appear
// in the UI, but they are available through the API.
try {
  ICategory category = manager.getCategory("SAMPLE_CATEGORY");
  if (category == null) {
    System.err.println("Create Property Group Action - Could not find category SAMPLE_CATEGORY.");
    return;
  }
  ICategoryInstance instance = category.makeInstance();
  instance.setValue("PROPERTY_1", "value1");
  System.out.println("PROPERTY_1 set to value1");
  instance.setValue("PROPERTY_2", "value2");
  System.out.println("PROPERTY_2 set to value2");
  group.addCategoryInstance(instance);
} catch (UnregisteredPropertyException e) {
  System.err.println("Create Property Group Action - Unregistered property: " + e.getName());
  return;
} catch (DuplicateInstanceException e) {
  System.err.println("Create Property Group Action - Duplicate instance of category: " + e.getCategoryInstance().getCategory().getName());
  return;
}
An instance of the SAMPLE_CATEGORY category is created by the previous code snippet. This category is registered with Rational Developer for System z using the following Eclipse extension point:
<extension point="com.ibm.ftt.properties.api.category">
  <category name="SAMPLE_CATEGORY">
    <property name="PROPERTY_1" />
    <property name="PROPERTY_2" />
  </category>
</extension>

These property values are not displayed in the Rational Developer for System z user interface, because the user interface is not extensible, but they are available through the API.

Using a Predefined Category

The following code snippet demonstrates how to create a category instance for a predefined category and add it to a property group.
// Create an instance of a pre-defined category, set properties,
// and add the instance to the property group. The values are not
// realistic values, this is just an example of how to work with
// pre-defined properties.
try {
  ICategory category = manager.getCategory(IPropertyGroupConstants.JCL_OPTIONS);
  if (category == null) {
    System.err.println("Create Property Group Action - Could not find category " + IPropertyGroupConstants.COBOL_SETTINGS);
    return;
  }
  ICategoryInstance instance = category.makeInstance();
  instance.setValue(IPropertyGroupConstants.JOBCARD, "//sample jobcard");
  System.out.println(IPropertyGroupConstants.JOBCARD + " set to //sample jobcard");
  instance.setValue(IPropertyGroupConstants.GENERATED_JCL_DATASET, "sample.test.jcl");
  System.out.println(IPropertyGroupConstants.GENERATED_JCL_DATASET + " set to sample.test.jcl");
  group.addCategoryInstance(instance);
} catch (UnregisteredPropertyException e) {
  System.err.println("Create Property Group Action - Unregistered property: " + e.getName());
  return;
} catch (DuplicateInstanceException e) {
  System.err.println("Create Property Group Action - Duplicate instance of category: " + e.getCategoryInstance().getCategory().getName());
}

(IPropertyGroupConstants) contains the names of the predefined categories and properties.


Feedback