The Metadata Store

Goal

The goal of the metadatastore is to store information about object relationships within RPM and allow developers to access this information easily. Either at build time or at runtime.

Source

All the content of the metadata store comes from the XML files in the rpm-metadata project stored in clearcase under rpm_pvob - RPM - common - model. They are located in the folder: \rpm_common_comp\rpm-metadata\resource\metadata

How to edit

Use any text/XML editor you want and change the XML files directly.

How to read the data at runtime

The content of the metadata can be read at runtime by getting the MetadataStore.INSTANCE singleton. From there, use the methods to find the Container objects that you need. Those Containers hold the Field objects as well.

XML to Java ?

The Java model at runtime is populated through the use of a tool called Betwixt. http://jakarta.apache.org/commons/betwixt/

This tool makes a mapping between XML files and java bean properties. It uses configuration files which are located in the folder : \rpm_common_comp\rpm-metadata\resource\java\com\ibm\rpm\metadata\model\

XML Validation

The XML structure is validated using a XSD file at build time. \rpm_common_comp\rpm-metadata\resource\metadata\rpm-object.xsd

Content Validation

During the build, the content of the actual XML files is checked for internal validity. Checks include using valid type names, prevent class and field duplication, etc...

Read Modes at runtime

The metadatastore can be populated in 3 modes. They are:
  1. Serial Mode: Populare the Metadata Store directly using a Java serialized version from the file containers.dat.
  2. Folder Mode: Parsing all the XML files in a folder.
  3. File list Mode: Parsing all the XML files specified in a XML file list.
To decide which mode to use, the metadata will use the resource named : metadatastore.properties. This file also defines the folder to use for the Folder mode and the resource to use to read the XML file list in the File List mode.

When the metadata jars are built, a jar called metadata-serial-(versin).jar will be created. This jar contains the data used in the 3rd mode. The advantage of this mode is that it's faster to read (by about 1 second) and it also allows us to package our application without Betwixt.

How the metadatastore is built

The following steps are used to populate the metadata store:
  1. All the XML files are read.
  2. The store retreives inherited fields and properties on each container.
  3. The store then fills various maps and list such as inheritance trees, populate links between fields and objects, etc....
Once this is done, the store is ready to be used. The code for this process is located in the MetadataStore constructor.

How attribute inheritance works

Some attributes in objects and fields are automatically inherited from parent classes. But in some cases, the inherited object/field will want to override the values specified in its parent. The process to resolve the value of an inherited field goes like this:
  1. If the inherited attribute defines a value in the XML (value != null), take this value.
  2. If the inherited attribute doesn't define a value in the XML, take the value specified by the parent.
  3. If nobody defines a value in the XML, take the default.
The code that performs attribute inheritance is located at:

How to add new fields and structures in the metadata

  1. Modify or create the required XSD files in the folder
    \rpm_common_comp\rpm-metadata\resource\metadata\
  2. Modify or create the java classes that will be used to read those new attributes. For example: Field.java or Container.java.  
    Add the new fields that you need and generate getters and setters as required. Note that betwixt requires add$fieldName and remove$fieldName methods if you include a list of objects.
  3. Modify or create the BETWIXT files to make the mapping between the XML files and the Java classes.
    \rpm_common_comp\rpm-metadata\resource\java\com\ibm\rpm\metadata\model\
  4. If you need your properties to behave in special ways when certain values are defined (such as "@default" ) or if you want to generate default values that depend on certain rules (such as inheritance), you will need to modify the MetadataStore.java file to apply those rules.
  5. Use your new fields in your code.