How to update components inventory

All pages of the components inventory are static pages (there is no web application generating them on-demand). The pages can be customized from the Belisama Toys project, the project is committed to the CropForge.

1. Check-out the Belisama Toys project from the SVN repository:

   https://svn.cropforge.org/svn/pantheon/Belenus/projects/BelisamaToys

   You have to be a registered developer of the GCP Pantheon project (which is understandable because you are going to commit your customization back to the SVN repository).
2. Once you make your changes (see below what changes and how to make them) in your local copy of Belisama Toys, call an Ant task:

   ant dep-create

   It generates all needed files into docs/inventory. You can browse them locally and check if your changes look as planned.
   Oh, and in order to produce graphs, you have to have the Graphviz dot program on your machine, either have it on your your PATH, or set its path by the property dot.path.

   ant -Ddot.path=/your/dot/program/path/bin dep-create

   In order to get these files to the main Pantheon web site you need to copy them to the pantheon/docs/inventory/gen directory, and commit them there to the SVN repository (and wait up to three hours before they are propagated there). Assuming that you have a local copy of the pantheon/docs, put its path in your build.properties file as a property dist.inventory.dir and call Ant again:

   ant dep-deploy

   For example, my build.properties file looks like this:

   # --------------------------------------------------------------------
   # For deploying inventory documentation outside of this project
   # --------------------------------------------------------------------
   dist.inventory.dir = /home/senger/GCP/pantheon/docs/inventory/gen
   

   Finally, you probably want your changes in Belisama Toys to be permanent. Therefore, commit them back to the SVN repository, as well.

Changes in Applications

# --------------------------------------------------------------------
# Properties defining end-user applications
# (used for creating implementation dependency graph)
#
# Please be aware of a significance of the comma character. If it is
# used in the value, it must be escaped (otherwise it creates an array
# of values for such property.
# --------------------------------------------------------------------

# --- a list of IDs: the IDs are just internal for this property file -
# to link together properties of individual applications that are below
# (use only "decent" characters here - the IDs are also used as CSS
# class names)
apps = gd, k.iris, k.iwis, k.imis, k.mutants, k.passports

# --- GenDiversity application
app.gd.name = GenDiversity
app.gd.description = Web Application allowing to recover\, manipulate\,
combine and export genotyping data from various data sources.
app.gd.authority = CIRAD
#app.gd.version =
app.gd.contact = Gautier Sarah, Manuel Ruiz, Aminah Keliet
app.gd.contact.email = gautier.sarah@cirad.fr
app.gd.url.public = http://gendiversity.cirad.fr/
#app.gd.url.dev = 
app.gd.crop.name = barley, chickpea,coconut,lentil,musa,rice,sorghum, wheat
app.gd.datasource = fr.cirad.mobyservices.datasource.TropgeneDataSource
#app.gd.usage =

• The following properties are treated as lists (meaning that they can have more values, separated by commas): contacts, datasource, and crop. By the way, all list properties can be also repeated, using the same property name several times and having just one value in each of them.

• The datasource property (a very important one) should contain one or more data source's IDs, the IDs that are used by data sources to identify themselves. Each application should list here all GCP Data Sources that it uses. You can even used yet not existing data sources - they will also appear in the resulting graph.

• The url.public and url.dev are URLs that should point directly to your application (if it is a web application), or to a homepage of a stand-alone application where). Having these links here, it allows to start or view your application directly from the resulting graph.

• The usage property is a free text (be aware that commas must be escaped by backslashes) showing how much is your application used, perhaps by whom. You can put here a number of recent hits, etc. If there is a demand, we can make this a URL pointing to some dynamically created statistics page (let me know).

  Note that all property values, including the usage and the description are put always on a single line.

Changes in Data Sources

For each new data source you must update the SPI mechanism (so the data source can be automatically discovered) and the Maven dependencies; and you should add a property pointing to the data source's descriptor page.

For updating an already included data source, you have just to update Maven dependencies (putting there the current version of your deployed data source).

1. Update SPI data: Go to src/etc/config/spi/datasources/META-INF/services and edit there either file org.generationcp.core.datasource.DataSource or file org.generationcp.core.datasource.DataSourceFactory, depending whether your are using data source's factory or not. If the file does not exist yet, make it from the provided template. Put there a full name of the class that represents your data source (or a factory for your data sources).

   Your change will be used by the Ant's config task. But you do not need to run it yourself, it will be called when you run ant dep-create (as shown at the beginning of this document).

2. Update or create a dependency record in the xmls/project.pom file.

3. Add link to a descriptor page: Each data source should be documented using a descriptor page. This page serves to the developers of applications and tells them how to use your data source. The data source does not have metadata holding this information - that's why we use, once again, the Belisama Toys's project property file src/etc/config/project.properties.template (the same one used for describing applications). You will find there this section:

   # --------------------------------------------------------------------
   # Additional properties of data sources
   # (used for creating implementation dependency graph)
   #
   # There is very little needed here because the most of the information
   # is stored directly in the data source's metadata.
   #
   # The properties of one data source are those with the same AAA in
   # property names: ds.AAA.id. These AAAs should be also put in the
   # 'dss' property (as a comma-separated list).
   # --------------------------------------------------------------------
   dss = iris
   
   ds.iris.id = http://irislocal.irri.org
   ds.iris.usage.url = http://pantheon.generationcp.org/index.php?option=com_content&task=view&id=536&Itemid=197
   

   The property dss contains a comma-separated list of internal IDs (used just here, in this property file). Put any ID there, and use the same ID in the following two properties: ds.<you-chosen-ID>.id, and ds.<you-chosen-ID>.usage.url. The property id contains a real ID of your data source, the usage.url is a URL pointing to your descriptor page.
   The reason why we cannot use directly the real ID of a data source is that the real ID usually contains characters that are not allowed to be used in a property name.

Changes in Use Cases

The graphs, however, can also show the use cases that are not yet used by any data source. In order to do that, the new use cases must be deployed to Maven in the Pantheon Use Case Collection. This is done in the PantheonUseCases project (https://svn.cropforge.org/svn/pantheon/Ceres/projects/PantheonUseCases). Here, in the Belisama Toys project, you have to update the dependency in the xmls/project.pom:

<dependency>
  <groupId>org.generationcp.usecase</groupId>
  <artifactId>pantheon-collection</artifactId>
  <version>2.0.8</version>
</dependency>