Overview

Contents

• Introduction
• Copyright
• Why Metamodels?
• Release Number and Model Name
• Administators and Developers
• The OpenMMS Directory Structure
• System Requirements for OpenMMS Administrators
• Executables
• Bug Reports and Feedback
• Additional Information

This overview describes the OpenMMS Toolkit software for creating macromolecular structure data representations in Corba, XML and SQL-relational-database forms. The translation into these data "expressions" is driven by a central metamodel based on the ontology contained in the mmCIF dictionary. All of the software for the metamodel and for generating the translated expressions is written in Java and is included with this distribution.

Several other high level documents are listed in the OpenMMS README. These include the complete Documentation Index and the OpenMMS API Specification.

All portions of the OpenMMS Toolkit are released under the UCSD Copyright.

An instance of a metamodel is simply a model. There are an infinite number models possible, each of which is simply a graph of inter-related class instances. Different models will generate different Corba IDL definitions, different relational database schema etc.

You may find that you want to change the relational database schema, the Corba interface or the XML representation. For example you may want to extract only a few data items from the mmCIF files and write these to a set of much smaller XML files. Or you may also wish to extend the OpenMMS toolkit so that it will incorporate proprietary data unique to your experiment and computations. You might also want to rename XML tags, SQL names or Corba field identifiers. All of these can be be accomplished by creating a new OpenMMS Model.

It should be pointed out here that there is a big difference here between what is possible and what is a good idea. Arbitrarily deleting or renaming items will often create confusion and cause unnecessary incompatibilities between software components. For example, the PDB will support Corba software that is compatible with the standard specified by the Object Management Group, Life Sciences Research Task Force. (The LSR-1.0 Model - See below) However, by exercising some care, it is possible to modify this model so as to add data types and functionality and still maintain compatibility with this standard.

A metamodel allows all the different models to be handled in an uniform and consistent way. Instances of the metamodel classes such as "Interface" and "Field" can be used to describe the particular model characteristics and act as the operands in the transformation methods. OpenMMS is an Ontology Driven Architecture which has at its core metamodel procedures to describe a particular model of interest and to generate the various MMS data representations and schemas from it.

To work correctly, the entire OpenMMS tree must be built (compiled and generated) from the same model. The particular model used during the build is given a name and corresponds to a particular "gmake build target". (For a discussion of how the build system enforces that incremental compiles use the same model see the Developers Guide).

The name of the OpenMMS distribution file identifies both the Release Number of the distribution and the Model Name that was used in creating the distribution. For example, the filename "OpenMMS-1.0.4_LSR-1.0.tar.gz" identifies the release number as "1.0.4" and the Model Name as "LSR-1.0". This same identifier string is also the name of the top-level directory created when the distribution is untar'ed. The one exception to this rule is "Source Only" distributions that contain all the source code but have never been compiled. These distributions have file names with the pattern "OpenMMS-x.y.z_SourceOnly.tar.gz", have not been built for any particular Model (i.e. build target) and do not contain any Java class files or metamodel derived information.

The OpenMMS distribution can be employed a two distinct levels: the Administrator Level and the Developer Level.

OpenMMS Administrator Level Interaction

The Administrator Level allows you to run Corba servers, load and query MMS relational databases and convert data files to XML format. All the scripts needed to run programs at this level are in the run directory and its subdirectories (described below). These scripts use the Class files that are pre-compiled and included with the distribution.

Although the run script defaults can always be overridden on the command line, before running the scripts you should run gmake in the run/unix directory. This will create the _vars.sh definitions file using information in the config/localdefs.gmake file. Some of the scripts may require changing some of the definitions of the variables (e.g. the location of the java run-time on the local machine) in the config/localdefs.gmake file, removing the _vars.sh file and then re-running gmake. Other than this, the scripts are ready to run a soon as the distribution is uncompressed and untarred.

At the administrator level, the model that defines the database schema etc. is fixed. Changing the model (i.e. using a new or modified gmake build target ) requires a top-level "gmake clean" followed by a recompile of all the source code i.e. Developer Level interaction.

However, most of the useful functionality of OpenMMS is available with the runtime scripts and does not require recompiling any of the Java Classes. The PDBase program can be used to load a relational database using the schema that is defined by the pre-compiled Build Target. Formulating SQL queries on that database is described in separate PDBase Document. The XmlConvert Document describes the administrator level commands for converting data to XML format.

OpenMMS Developer Level Interaction

To work at the developer level a programmer must operate on a suitable platform and have available Java and Corba IDL compilers and the GNU gmake utility. Working at this level is necessary if one wants to change the OpenMMS Model in order to change the particular Corba IDL, relational database schema or XML files generated from the model.

However, in addition to changing a particular the metamodel instance, programmers working at the Developer Level may also modify the software that uses the metamodel, or change how the code derived from the model is employed. Since all the source code is included with the distribution, at this level a software developer can pretty much do anything he wants. For a more complete description, see the Developers Guide.

The following diagram shows the main components of the OpenMMS directory structure.

    openmms
     |
     |--- config
     |
     |--- log
     |
     |--- classes
     |
     |--- run
     |     |
     |     |--- unix
     |     |
     |     |--- nt
     |
     |
     |--- docs
     |     |
     |     |--- papers
     |     |
     |     |--- specs
     |     |
     |     |--- guides
     | 	   |   	 |
     |	   |   	 |--- sql_examples
     | 	   |
     | 	   |
     |	   |--- api
     |
     |
     |--- import
     |
     |--- dicts
     |
     |--- src
     |     |
     |     |--- cifparse
     |     |
     |     |--- stats
     |     |
     |     |--- xconv
     |     |
     |     |--- mms
     |           |--- util
     |           |
     |           |--- meta
     |           |
     |           |--- deriv
     |           |     |
     |           |     |--- vimpl
     |           |     |
     |           |     |--- idl
     |           |     |     |
     |           |     |     |--- compile
     |           |     |
     |           |     |--- loader
     |           |     |
     |           |     |--- dbinsert
     |           |     |
     |           |     |--- sql
     |           |
     |           |
     |           |--- entry
     |           |     |
     |           |     |--- cifloader
     |           |
     |           |--- rdb
     |           |     |
     |           |     |--- pdbase
     |           |
     |           |--- xmc
     |           |
     |           |--- servers
     |           |     |
     |           |     |--- refserv
     |           |     |
     |           |     |--- dbserv
     |           |
     |           |--- clients
     |                 |
     |                 |--- text
     |
     |
     |--- data
           |
           |--- mmcif
           |
           |--- xml

These subdirectories of openmms contain some of the following information. More information about many of these, in particular the config and src directories is contained in the Developers Guide. Note that here and elsewhere these subdirectories are consistently refered to relative to the top-level openmms directory e.g. "src/mms/meta".

config

Contains all configuration data for the OpenMMS system. This includes the file localdefs.gmake which defines variables unique to the local development environment.

log

The file MAKE.LOG contained in this directory contains a complete log of the output of all commands that were executed during the last "top-level" build. This log file can be consulted when tracking down problems during development or testing.

classes

Subdirectories corresponding to the package name contain all of the compiled Java Class files

run

Subdirectories labeled by platform type, contains scripts to run the OpenMMS programs on various platforms.

docs

Contains this Overview document and various other documents describing the OpenMMS toolkit

docs/api

Contains the complete OpenMMS API document generated using the javadoc program

import

Contains information that comes from sources outside of RCSB such as the IDL that defines standard services required by the LSR-1.0 Model.

dicts

Contains the mmCIF dictionaries used by the Models

src

Contains all the Java source code that makes up the OpenMMS toolkit

src/cifparse

Contains the source code for the Java mmCIF file parser

src/stats

Contains the source for a simple statistics program that uses the mmCIF parser

src/mms/meta

Contains the OpenMMS metamodel source code

src/mms/deriv

Subdirectories of this directory contain all of the information that is derived from the metamodel instance. This includes the Corba IDL, relational database schema and Java Category loaders. In a "SourceOnly" distribution or after a "% gmake clean" this directory is empty.

src/mms/deriv/sql

Contains files with SQL commands, derived from the Model, to create and initialize the relational database tables

src/mms/deriv/dbinsert

Contains the generated JDBC code, derived from the Model, for inserting MMS data into, and retrieving data from an SQL relational database

src/mms/deriv/idl

Contains the generated Corba IDL, derived from the Model, that specifies the MMS server interface.

src/mms/deriv/idl/compile

Location where Java files generated by the IDL-to-Java compiler are processed.

src/mms/deriv/loader

Contains the loaders specific to the mmCIF Category data structures

src/mms/entry

In mmCIF terminology an "Entry" is equivalent to a molecular structure and usually maps one-to-one to a standard PDB flat file. This directory contains the source code for classes that deal with Entry objects.

src/mms/servers/refserv

Contains the source code for a Corba reference server that parses mmCIF files and provide the information to clients in a manner compliant with the IDL generated from the metamodel instance.

src/mms/servers/dbserv

Contains the source code for a Corba server that provides the same interface and data as the reference server above but retrieves the data from a relational database loaded with pdbase. This program provides very fast, reliable and efficient MMS retrieval service for client applications.

src/mms/clients/text

Contains the source code for a simple test client to obtain values from an OpenMMS Corba server and print their text values

src/mms/rdb/pdbase

Contains the GUI code and main program for loading Entries into a relational database

src/xconv

Contains the source code to translate mmCIF data into XML expressions

data

Test data directory

data/mmcif

Contains a small number of small mmCIF test data files used by the OpenMMS test and demonstration programs

data/xml

Destination directory for XML output of the XmlConvert translation

To run the executables listed below, OpenMMS you only need to have availabe the "Java Runtime Environment" (JRE). Those wishing to load MMS data into a relational database, may also require a specific JDBC Driver for the particular database they are using. There are pointers to information about downloading the JRE and JDBC drivers are in the section on Additional Information.

The openmms/run directory contains executable scripts grouped by particular runtime platforms. The URLs for the script names below link to the unix versions of the scripts.

mmCIF Parser Example

The script cifstats executes the main program in the Java Class org.rcsb.openmms.apps.stats.CifStats. This application provides a simple example of using the CifParser to gather statistics about which items are present in a set of mmCIF datafiles.

Relational Database Loader

The script pdbase executes the main program in the Java Class org.rcsb.openmms.apps.rdb.PDBase. This application parses mmCIF files and loads them into a SQL relational database.

XML Translation

The script xmlconv executes the main program in the Java Class org.rcsb.openmms.apps.xconv.XmlConvert which translates mmCIF files to an XML representation.

Corba Reference Server

The script refserv executes the main program in the Java Class org.rcsb.openmms.apps.refserv.CFileServer. This application implements the Corba services defined by the IDL generated from the MMS Model by reading the data from the native mmCIF files. This server registers itself with the specified Corba naming service so that it can be located by client applications.

Corba Database Server

The script dbserv executes the main program in the Java Class org.rcsb.openmms.apps.dbserv.DBServ. This application implements the Corba services defined by the IDL generated from the MMS Model by reading the data from a relational database loaded using PDBase. This server registers itself with the specified Corba Naming Service so that it can be located by client applications.

Corba Test Client

The script txclient executes the main program in the Java Class org.rcsb.openmms.apps.text.TextMMSClient. This application tests an MMS Corba server by requesting specific items and printing their text values. The MMS server is located by looking up the name in the specified Corba Naming Service.

Corba Naming Service

The script nameserver starts up the "tnameserv" Corba Naming Service that is included as part of the Java runtime environment.

Send mail to: info@rcsb.org

For additional information, refer to these World Wide Web sites:

http://www.rcsb.org/

The Research Collaboratory for Structural Bioinformatics

http://pdb.rutgers.edu/mmcif/

mmCIF Resources

http://www.omg.org/homepages/lsr/index.html

The Object Management Group, Life Science Research Task Force

Java Runtime Environments and JDBC Drivers for OpenMMS Administrators:

JREs: http://www.google.com/ ... Java/Implementations

This Google directory provides a fairly extensive set of links to Java runtime environments on various platforms. Also consult individual vendors for support on their platforms.

J2SE: http://java.sun.com/j2se/1.4/

Runtime environments for the Windows, Linux and Solaris platforms are available directly from the Sun.

JDBC: http://industry.java.sun.com/products/jdbc/drivers

This web page provides an online search for JDBC drivers. Additional information about JDBC access to a particular vendors database may also be available from that vendor.

Tools For OpenMMS Developers:

Java: http://java.sun.com

The main web site for the Java Programming Language.

gmake: http://www.gnu.org/software/make/make.html

GNU Make software. Note this is referred to in the OpenMMS documentation and elsewhere as "gmake" to distinguish it from the standard unix make utility.