OMTD-SHARE Java Annotatations 3.0.2.0

The document explains the how to embed OpenMinTeD-SHARE descriptor in software components and resource packages and how to use related tooling.

Introduction

OpenMinTeD SHARE is a set of metadata elements to describe text and data-mining (TDM) and natural language processing (NLP) resources.

Useful links

Get sources for this project from GitHub:

https://github.com/openminted/omtd-share-annotations

Package structure

We expect that the resource you distribute is packaged as a ZIP or JAR file. Within this file, you can place your OpenMinTeD descriptors at any location you like best. If you package descriptors for TDM software components, you may wish to place them directly next to the classes that implement the these components. If you package multiple resources, e.g. annotation schema descriptions, in a single ZIP file you might wish to place the respective OpenMinTeD-SHARE descriptions directly next to them.

However, in order to allow for the automatic detection of your OpenMinTeD-SHARE descriptors, you will have to set up a file in a well-known location which points to your descriptors. This is described in the next section.

Discovery

Making descriptors discoverable

In order to make your descriptors discoverable, you have to create a folder called META-INF/eu.openminted.share in your ZIP or JAR file. Into this folder, you have to place a file called descriptors.txt with pointers to the actual descriptor files.

Example descriptors.txt file
../../descriptors/Component1.xml
../../descriptors/Component2.xml

Discovering descriptors

We presently provide a convenience API for Java to discover descriptors. Additionally, we assume for the moment, that any descriptors you may wish to discover exist on your Java classpath, i.e. they are packaged as Maven artifacts.

In the near future, we will also provide convenience methods to discover descriptors in explicitly named JAR and ZIP files that do not need to be on the Java classpath.

To locate the descriptors, you can use the DescriptorFactory class.

Example of locating descriptors using the DescriptorFactory class
URL[] descriptorPaths = DescriptorFactory.scanDescriptors();

Annotating components

Java classes can be directly annotated with OpenMinTeD-SHARE metadata so you do not have to manually maintain a separate XML file. The OpenMinTeD-SHARE Maven Plugin can then be used to generate the OpenMinTeD-SHARE descriptor automatically as part of a build.

Example OpenMinTeD-SHARE annotations on a Java class
import eu.openminted.share.annotations.api.Component;
import eu.openminted.share.annotations.api.ComponentClass;

@Component(classes=ComponentClass.READER)
class TextCorpusReader

Using the Maven Plugin

A set of properly annotated class files within a Maven project can be automatically processed as part of the build to produce the relevant descriptor files using the Maven plugin we provide. To use this plugin simply add the following to your existing pom.xml.

<repositories>
    <repository>
      <id>omtd-releases</id>
      <url>https://repo.openminted.eu/content/repositories/releases</url>
      <releases>
        <enabled>true</enabled>
      </releases>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </repository>
    <repository>
      <id>omtd-snapshots</id>
      <url>https://repo.openminted.eu/content/repositories/snapshots</url>
      <releases>
        <enabled>false</enabled>
      </releases>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>eu.openminted.share.annotations</groupId>
        <artifactId>omtd-share-annotations-api</artifactId>
        <version>0.0.1-SNAPSHOT</version>
    </dependency>
</dependencies>

<pluginRepositories>
    <pluginRepository>
        <id>omtd-releases</id>
        <name>OpenMinTeD releases repository</name>
        <url>https://repo.openminted.eu/content/repositories/releases</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </pluginRepository>
    <pluginRepository>
            <id>omtd-snapshots</id>
            <name>OpenMinTeD snapshots repository</name>
            <url>https://repo.openminted.eu/content/repositories/snapshots</url>
            <releases>
                <enabled>false</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </pluginRepository>
</pluginRepositories>

<build>
   <plugins>
      <plugin>
         <groupId>eu.openminted.share.annotations</groupId>
         <artifactId>omtd-share-annotations-maven-plugin</artifactId>
         <version>3.0.2.0-SNAPSHOT</version>
         <executions>
            <execution>
               <phase>process-classes</phase>
               <goals>
                  <goal>generate</goal>
               </goals>
            </execution>
         </executions>
      </plugin>
   </plugins>
</build>

Note that if you already have a repositories, pluginRepositories or build section within your pom.xml you will only need to include the relevant repository or plugin element.