Access Keys:
Skip to content (Access Key - 0)

GME


GME 1.3 Administrators Guide


[ caGrid 1.3 Documentation | GME 1.3 Documentation | GME 1.3 Administrators Guide]

Contents

Prerequisites


Installing the Software


Install caGrid and a Container

In this step you will download and install GME, and a grid service container, using the caGrid Installer. If you have already installed caGrid 1.3 and a suitable container on your machine, proceed to the next section.

Once you have installed caGrid, GME can be found in the directory location where you installed caGrid, in the caGrid/projects/globalmodelexchange directory. This guide refers to that location as GME_HOME

To install caGrid/GME and set up a container, do the following:

Installer Prerequisites

The caGrid Installer installs all prerequisites except for Java and MySQL.

  • Java 1.5 JDK
  • (Optional) If you are deploying caGrid core services locally, you may also need a MySQL database.
    Note
    MySQL is only required for the security services and GME. You can use 4.x (with transaction enabled; i.e., use InnoDB engine) or 5.x.
  • Make sure the JAVA_HOME environment variable is set and points to the correct location.

Install caGrid and Configure a Secure Container Using the caGrid 1.3 Installer

  1. Download the caGrid 1.3 Installer. The downloaded installer should be contained in the file caGrid-installer-1.3.zip.
  2. Unzip the file caGrid-installer-1.3.zip, this should create the directory caGrid-installer-1.3, from this point forward we will refer to this directory as CAGRID_INSTALLER_LOCATION.
  3. From a command prompt launch the installer:
     > cd <CAGRID_INSTALLER_LOCATION> 
    > java -jar caGrid-installer-1.3.jar
  4. Select the I agree to this license checkbox and click Next.
  5. Select the Install/Configure caGrid Software and Install/Configure Grid Service Container checkboxes and click Next.
  6. The installer detects whether or not you have already installed Ant. It installs or reinstalls it, depending on the installation status. In either case, you must specify where you want to install Ant.
  7. The installer detects whether or not you have already installed Globus. It installs or reinstalls it, depending on your installation status. In either case, you must specify where you want to install Globus.
  8. The installer prompts you to speciry where you want to install caGrid. Specify a location and then click Next.
  9. The installer displays a list of tasks that the installer will perform. Click Next to start the installation process. The installer downloads, builds, and installs several components. Note: This process takes several minutes.
  10. Once the installer has completed installing all the components, click Next.
  11. The installer ask you which Grid you would like to configure your installation to use. The installer supports configuring caGrid to work out of the box with many community Grid environments. For testing and development purposes we recommend selecting the Training Grid. If you do not want to configure caGrid to work with an existing Grid, you may select that as well. The installer can also be modified to support additional Grids.
  12. The installer shows a summary of the tasks to be completed. Click  Next to configure caGrid to use the selected target Grids. Note: This process takes several minutes.
  13. Once the installer has finished configuring caGrid to use the target Grid, click  Next.
  14. Select the Container to which  you want to deploy your service. This guide provides instructions for using the Tomcat container. Check the Should this container be secure? option and then click  Next.
  15. In the hostname box, enter the hostname of your server; this should match the hostname you used in creating your host credentials. Click Next.
    If you plan on using this container to deploy a service that registers to an existing grid, you must use a publicly resolvable DNS name (or static IP). If you do not, you will have to manually edit configuration files later.
  16. From the Obtain host credentials method list, select the option that applies to your situation and click Next.
    Options:
    • If you do not yet have credentials for your service, then select Use GAARDS to obtain host credentials.
    • If you have host credentials that are not in the default location, then select Browse to host credential on the file system
    • If you have host credentials that are in the default location, then select Host credentials are already installed

    Note: Use of the Copy in host credentials manually option is not recommended. Use the Browse to host credential on the file system option instead.


    Default credential location:

    • On Windows, this will be a path like "C:\Documents and Settings\<USERNAME>\.cagrid\certificates".
    • On Linux/MAC this will be a path like "/Users/YOUR_USERNAME/.cagrid/certificates".
  17. Enter the location of your host certificate into the Certificate box.  Enter the location of your private key into Key box. Click Next.
  18. The next screen prompts you to specify where you want to install Tomcat. In the Directory box, enter the installation location and then click Next.
  19. The next screen displays a list of tasks that the installer will perform to install and configure Tomcat. Click Next.
  20. Once the installer has completed installing all the components, click Next.
  21. Click Next. The final screen will remind you set your ANT_HOME, GLOBUS_LOCATION and CATALINA_HOME environment variables. Set these variables immediately and then click Finish.
    These instructions are also written to a file called CAGRID_POST_INSTALLATION.txt in the directory from which you ran the installer.
  22. Close the installer by clicking Close.

Create a Database

GME requires the use of a database for its persistence mechanism. MySQL 5 is the officially supported database, but as described in the Configuration section, GME uses Hibernate, so you can theoretically configure it to use a different database.

GME will be configured to communicate with your database, via the settings in the GME Properties File, which is described in the Configuration section. The default configuration is set up to connect to a database called "gme" running on "localhost" on the default port, with the default user name of "root" and no password. You can change this to whatever you like but make sure you edit the properties consistently with the database you create in this step.

You only need to create the database, since the GME automatically creates all of the tables and other items it needs when the service starts.

If you create a new user, make sure you give that user the permission to do this.

If you have MySQL's bin directory on your path, you can create the database from the command line as follows:

 > mysqladmin -u root create gme 

Configuration


To simply deploy the GME with the default configuration, edit the service's standard ServiceMetadata, by following these instructions.
If you didn't use the default MySQL install locally, you also need to edit the GME Properties File according to your database installation.

ServiceMetadata

GME provides a single resource property, which acts as metadata for its clients and describes the service's capabilities and information on where it is being hosted. This resource property is the caGrid standard ServiceMetadata, and is loaded from a file on the filesystem (serviceMetadata.xml), which is located in the GME_HOME/etc directory, and is deployed with the service. This file is fully populated except for the information about where the service is being hosted. Before deploying the service, you must edit this file and provide a description of your organization.

If you aren't comfortable editing in XML, you can use Introduce's graphical editor instead when you deploy the service.

Below is the relevant section of the file that you should edit.

 <ns1:hostingResearchCenter>
  <ns18:ResearchCenter displayName="" shortName="" xmlns:ns18="gme://caGrid.caBIG/1.0/gov.nih.nci.cagrid.metadata.common">
   <ns18:Address country="" locality="" postalCode="" stateProvince="" street1="" street2=""/>
   <ns18:ResearchCenterDescription description="" homepageURL="" imageURL="" rssNewsURL=""/>
   <ns18:pointOfContactCollection>
    <ns18:PointOfContact affiliation="" email="" firstName="" lastName="" phoneNumber="" role=""/>
   </ns18:pointOfContactCollection>
  </ns18:ResearchCenter>
 </ns1:hostingResearchCenter>

Introduce Properties

GME is an Introduce-created service and supports all of the standard Introduce configuration points, which are described in the Introduce Administrator's Guide.

Service Properties (service.properties)

GME provides two Introduce Service Properties. The first is the gmeConfigurationFile, which specifies the location of the GME Configuration File to be used. The default value can be used in most cases, but this allows the service deployer the ability to point to an alternative configuration file at deploy time. This can be useful, for example, if multiple configurations are commonly used such that the default configuration doesn't need to be edited to switch configurations. The second property is the gmePropertiesFile, which specifies the location of the GME Properties File which contains the database-related properties used in the default GME Configuration File. The default value can be used in most cases, but this property allows the service deployer the option to point to an alternative database configuration during deployment.

Property Name
Value(s)
gmeConfigurationFile applicationContext-gme.xml
gmePropertiesFile gme.properties

Deployment Properties (deploy.properties)

The caGrid build process (or the caGrid installer) configures GME to register to the appropriate Index Service for the target grid you are using. You can follow these instructions to change your target grid before you deploy the GME. Alternatively, you can use a custom Index Service by following the documentation in the Introduce Administrator's Guide.

GME Configuration File

You should not edit the GME Configuration File unless you are familiar with the GME design, as described in the GME Design Guide. Simple database connection settings can be configured via the GME Properties File

The GME Configuration File is located by the value of the gmeConfigurationFile Introduce Service Property, and used to configure the service via Spring. The file is expected to minimally contain a bean with the id gme which identifies a class that is, or extends, the org.cagrid.gme.service.GME class.

The default GME Configuration File can be see here GME Configuration File, and will generally not need to be edited for normal use. However, this section provides a highlight of the beans in the GME Configuration File in case low-level modifications are desired, such as using a different database or changing its behavior. The default file exists in the GME_HOME/etc directory, and is called applicationContext-gme.xml, though this can be changed in the service properties or specified during deployment.

Main GME Bean

The main Spring Bean loaded by the GME Service is the gme bean, which simply specifies the org.cagrid.gme.service.GME Class as the GME implementation, and passes it a reference to the xmlSchemaInformationDao Bean. The GME uses a Data Access Object pattern to abstract the GME business logic from how XML schemas are persisted, and it relies on its XMLSchemaInformationDao to manage the details of saving, deleting, updating, and retrieving XML Schemas from is persistence store.

  <bean id="gme" class="org.cagrid.gme.service.GME">
    <property name="XMLSchemaInformationDao" ref="xmlSchemaInformationDao" />
  </bean>

xmlSchemaInformationDao Bean

The xmlSchemaInformationDao Bean simply specifies the org.cagrid.gme.service.dao.XMLSchemaInformationDao class as its implementation of the XML Schema Information DAO, which is a class that makes use of Spring's Hibernate DAO support to do the heavy-lifting relating to interacting with Hibernate. This bean is actually an extension of the more generic daoTemplate bean (also seen below), as seen by the parent="daoTemplate" setting. The abstract doaTemplate can be similarly used as a parent for any other DAO classes. The daoTemplate sets the hibernateTemplate property to a reference to the hibernateTemplate bean (also seen below). This bean instantiates Spring's default HibernateTemplate support, specifies the sessions should be checked for write permission before writing (as the GME makes use of read-only transactions where appropriate), and sets the sessionFactory property to a reference to the sessionFactory Bean.

  <bean id="hibernateTemplate" class="org.springframework.orm.hibernate3.HibernateTemplate">
    <property name="checkWriteOperations">
      <value>true</value>
    </property>
    <property name="sessionFactory">
      <ref bean="sessionFactory" />
    </property>
  </bean>

  <bean id="daoTemplate" abstract="true">
    <property name="hibernateTemplate">
      <ref bean="hibernateTemplate" />
    </property>
  </bean>

  <bean id="xmlSchemaInformationDao" parent="daoTemplate"
    class="org.cagrid.gme.service.dao.XMLSchemaInformationDao" />

sessionFactory Bean

The sessionFactory Bean specifies which Hibernate Session Factory implementation is used. The GME uses Hibernate Annotations, and this bean configures the Hibernate Sessions to use that feature by specifying the use of the org.springframework.orm.hibernate3.annotation.AnnotationSessionFactoryBean class, and by configuring the annotatedClasses property to contain a list of the annotated GME domain classes. The bean also configures some standard Hibernate Properties via the hibernateProperties property. Specifically, it configures Hibernate to create/update database tables as necessary (via the hibernate.hbm2ddl.auto) property, and passes the database dialect via the value of the cagrid.gme.db.dialect property from the GME Properties File. Hibernate is an extremely configurable framework, and a number of other properties can be specified here to fine-tune its behavior. See the Hibernate Documentation for more details.

To see the details of the SQL queries that are being executed by Hibernate, you can edit the hibernate.show_sql to be 'true' instead of 'false'

The sessionFactory bean also sets the dataSource property to a reference to the dataSource Bean, which is how the underlying database is configured, and specifies a dependency on the databaseValidator bean to ensure the database is available before constructing the SessionFactory. This ensures an error is properly generated when the dataSource is mis-configured or unavailable.

 <bean id="sessionFactory"
    class="org.springframework.orm.hibernate3.annotation.AnnotationSessionFactoryBean"
    depends-on="databaseValidator">
    <property name="dataSource">
      <ref bean="dataSource" />
    </property>
    <property name="hibernateProperties">
      <props>
        <prop key="hibernate.dialect">${cagrid.gme.db.dialect}</prop>
        <!--
          <prop key="hibernate.hbm2ddl.auto">create-drop</prop>
         -->
        <prop key="hibernate.hbm2ddl.auto">update</prop>
        <prop key="hibernate.show_sql">false</prop>
      </props>
    </property>
    <property name="annotatedClasses">
      <list>
        <value>org.cagrid.gme.domain.XMLSchema</value>
        <value>org.cagrid.gme.domain.XMLSchemaBundle</value>
        <value>org.cagrid.gme.domain.XMLSchemaDocument</value>
        <value>org.cagrid.gme.domain.XMLSchemaImportInformation</value>
        <value>org.cagrid.gme.domain.XMLSchemaNamespace</value>
        <value>org.cagrid.gme.service.domain.XMLSchemaInformation</value>
        <value>org.cagrid.gme.service.GME</value>
      </list>
    </property>
  </bean>

dataSource Bean

The dataSource Bean simply passes the appropriate values of the database-related properties from the GME Properties File into a more configured parent bean, the dataSourceTemplate. The dataSourceTemplate configures the the JDBC DataSource to use Apache Common's Database Pooling (DBCP), and configures a variety of pooling properties. The details of these settings can be found in the DBCP Configuration Documentation. Of particular interest is the validationQuery, which you should set to the same string as the query in the databaseValidator bean (described below), since it is what is used to verify a connection returned from the pool. All these settings should generally be fine for most environments but can be tweaked as necessary, such as by increasing or decreasing the timeouts and number of connections in the pool.

The databaseValidator bean is used by the sessionFactory Bean to ensure that the database is configured properly and available at start time. It does so by using Spring's DatabaseStartupValidator class, and configuring it to make sure the query "Select 1" properly returns within 15 seconds.

  <bean id="dataSource" parent="dataSourceTemplate" p:url="${cagrid.gme.db.url}"
    p:username="${cagrid.gme.db.username}"
    p:password="${cagrid.gme.db.password}" />

  <bean id="dataSourceTemplate" abstract="true"
    class="org.apache.commons.dbcp.BasicDataSource"
    destroy-method="close"
    p:driverClassName="${cagrid.gme.db.driver}"
    p:maxActive="10"
    p:maxIdle="2"
    p:maxWait="180000"
    p:removeAbandoned="true"
    p:removeAbandonedTimeout="300"
    p:logAbandoned="true"
    p:testWhileIdle="true"
    p:testOnReturn="true"
    p:validationQuery="select 1"
    p:timeBetweenEvictionRunsMillis="300000"
    p:minEvictableIdleTimeMillis="600000" />

  <bean id="databaseValidator"
    class="org.springframework.jdbc.support.DatabaseStartupValidator">
    <property name="dataSource" ref="dataSource" />
    <!-- timeout in seconds -->
    <property name="timeout" value="15" />
    <property name="validationQuery" value="Select 1" />
  </bean>

transactionManager Bean

The GME uses Spring's Annotation Driven Transaction Support to create transactional boundaries for operations that modify the database and ensure read-only operations aren't inadvertently modifying the database. This support is enabled by the specification below, which references the sessionFactory Bean.

  <bean id="transactionManager"
    class="org.springframework.orm.hibernate3.HibernateTransactionManager">
    <property name="sessionFactory" ref="sessionFactory" />
  </bean>

  <tx:annotation-driven transaction-manager="transactionManager" proxy-target-class="true" />

GME Properties File

The GME Configuration File has some templated values, which are populated automatically at run-time based on the values provided in this properties file. This requires most administrators to only have to edit this properties file, and not the more complex GME Configuration File.

The location of the properties file is in the GME_HOME/etc directory, and is called gme.properties, though this can be changed in the service properties or specified during deployment.

The contents of these properties are detailed in the table below. All properties are required to exist, but most administrators will only need to edit the properties with bold formatting below (namely the database user name and password), and potentially the JDBC URL (cagrid.gme.db.url) if the database is running on a different host, port, or name.

Property Name
Default Value(s)
Description
cagrid.gme.db.dialect org.hibernate.dialect.MySQLInnoDBDialect
The class name of the Hibernate dialect of the database to use (this needs to support transactions).
cagrid.gme.db.driver com.mysql.jdbc.Driver
The class name of the JDBC Driver to use.
cagrid.gme.db.url jdbc:mysql://localhost:3306/gme
The JDBC URL to the database the GME should use (this must already exist before the service is started).
cagrid.gme.db.username root
The user id of the Mysql user (must have table creation privileges on start up if the tables don't already exist).
cagrid.gme.db.password   The password of the Mysql user (defaults to no password).

Deployment


GME is an Introduce-created service and supports all standard Introduce deployment processes, which are described in the Introduce Administrator's Guide

For example, to deploy the service to Tomcat from the command line, you can type the following command from the GME_HOME directory:

 > ant deployTomcat 
You should then start up Tomcat so that your service is available. For Tomcat, you can run this command:

 > $CATALINA_HOME/bin/startup.sh 
or in Windows

 > %CATALINA_HOME%\bin\startup.bat 

Validation


You can validate GME for proper functioning by interacting with the service directly via its API, as well as indirectly by using the Introduce features which rely on it. This section details the steps you can take to validate GME.

Validate the Service is Running

To ensure that GME is working properly, we first need to validate that the service is actually running and that there are no errors in its log. For example, if you deployed to Tomcat, look at the log file in $CATALINA_HOME/logs/catalina.out and make sure no exceptions are present. Then open your web browser and point it to the URL of your service. This should be of the form:

https:/YOUR_HOST:YOUR_PORT/wsrf/services/cagrid/GlobalModelExchange

For example, if you used the default ports, you should be able to use the following URL on the machine on which you deployed GME:
https://localhost:8443/wsrf/services/cagrid/GlobalModelExchange

When you connect to this URL, you should see the following text on the screen:

cagrid/GlobalModelExchange

Hi there, this is an AXIS service!
Perhaps there will be a form for invoking the service here...

If you see an error, the service is not deployed correctly. If you get a connection refused, check that your container is actually running, and that the URL you are using is correct.

Validate the GME (Introduce)

GME provides a data type browsing extension of Introduce, which can be used to browse, upload, and download schemas to and from the GME. You can use this capability to verify the functionality of the GME.

You can launch Introduce from the directory in which you installed caGrid (there should be a caGrid folder), by typing the following command:

 > ant introduce 
Once Introduce starts, go to Window > Preferences and set the GME Service URL as your service URL, and press Save.

With Introduce now configured to communicate with your GME service, you can use the data type browser to browse schemas in GME. To do this, follow these steps:

  1. In Introduce's top toolbar, click Browse Data Types. The Browse Data Types window appears.
  2. Click the Global Model Exchange tab.
  3. Click the Upload tab.
  4. Click Add Schemas... to launch a file browser window.
  5. Browse to the GME_HOME/test/resources/schema/simple directory, and highlight all the XSD Files (A.xsd, B.xsd, C.xsd, D.xsd, E.xsd, and F.xsd).
  6. Click OK/Open.
    You should now see the namespaces of all six schemas in the XML Schemas panel. When you click on one, you should see the contents of the file in the Schema Preview panel. See below for how this should look. If you are missing a file, you can add it by pressing Add Schemas... again.
  7. Once you have verified that the schemas are properly loaded into the panel, click Publish Schemas. A dialog box appears that says "Successfully published (6) schemas." Click OK.
  8. Return to the Browse panel by selecting the Browse tab.
  9. Click Refresh. The Target Namespace list appears and is now populated with the six namespaces you just published. When you select one of them, the Schema Root Document Text panel is populated with the contents of the appropriate schema.
    Once uploaded, you cannot upload the same schema to the GME again; you must delete it first programmatically.

Management


The current release of the GME has no management operations that need to be performed on the running service. The only changes that can be made to the service are described in the Configuration section. Make any such changes to the configuration in the files in GME_HOME, then redeploy the service and restart the container.

Future releases of GME will add a service-managed security model, which will require management operations for provisioning the authorization policy.

Last edited by
Clayton Clark (1618 days ago) , ...
Adaptavist Theme Builder Powered by Atlassian Confluence