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:
- Serial Mode: Populare the Metadata Store directly using a Java serialized version from the file containers.dat.
- Folder Mode: Parsing all the XML files in a folder.
- 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.
- If serializedMode is true, the Serial mode is used.
- If useFolder is true, the Folder mode
is used.
- Otherwise, the File List mode will be used.
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:
- All the XML files are read.
- The store retreives inherited fields and properties on each container.
- 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:
- If the inherited attribute defines a value in the XML (value != null), take this value.
- If the inherited attribute doesn't define a value in the XML, take the value specified by the parent.
- If nobody defines a value in the XML, take the default.
The code that performs attribute inheritance is located at:
- For containers: MetadataStore.retrieveInheritedContainerProperties(Container container)
- For fields: Field.setProperties(Field aField)
How to add new fields and structures in the metadata
- Modify or create the required XSD files in the folder
\rpm_common_comp\rpm-metadata\resource\metadata\
- 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.
- 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\
- 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.
- Use your new fields in your code.