dameikle / okapi-maven-plugin

Maven Plugin for Okapi Framework

okapi-maven-plugin

Maven plugin that allows execution of common actions using the Okapi Framework within a Maven Project, inspired by the okapi-ant project.

Currently, it supports performing the following actions:

• Execute a Pipeline
• Export a Batch Configuration (BCONF)
• Install a Batch Configuration (BCONF)

These actions can all be configured within the project's POM file.

Building

You need the following pre-requisites:

• Java 11+
• Maven 3.9.0+

To build run the following from inside the okapi-maven-plugin directory:

mvn clean package

The plugin is released via Maven Central (see Usage below for more details), however to install a local copy from this repo, you can run:

mvn clean install

Usage

The plugin requires Java 11+ and Maven 3.9.0.

The plugin is being released to Maven Central via the Sonatype OSSRH (OSS Repository Hosting) repository.

To use the plug-in you can simply include it in your project's POM file in the plugins section, adding configuration details relevant to the action required (see Available Mojos for more details).

  <build>
    <plugins>
      <plugin>
        <groupId>io.meikle.maven.okapi</groupId>
        <artifactId>okapi-maven-plugin</artifactId>
        <version>1.1</version>
        <configuration>
            ...
        </configuration>
      </plugin>
    </plugins>
  </build>

To access snapshot versions during development, you will need to add the OSSRH to your Maven settings and enable it to resolve snapshots.

The plugin repository details required for this guide are shown below:

<pluginRepository>
    <id>oss-sonatype</id>
    <name>oss-sonatype</name>
    <url>https://s01.oss.sonatype.org/content/repositories/snapshots/</url>
    <snapshots>
        <enabled>true</enabled>
    </snapshots>
</pluginRepository>

This could be added in a profile within your settings.xml, or alternatively you could add a section to your project's POM file:

<pluginRepositories>
    <pluginRepository>
        <id>oss.sonatype.org-snapshot</id>
        <url>https://s01.oss.sonatype.org/content/repositories/snapshots/</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </pluginRepository>
</pluginRepositories>

Available Mojos

okapi:version

Overview

The OkapiVersionMojo outputs the version of Okapi used by the plugin.

It can be mapped against an existing phase, or executed directly using:

mvn okapi:version

Configuration

N/A

okapi:pipeline

Overview

The OkapiPipelineExecuteMojo executes a pipeline contained in a pipeline configuration file (a pln file) against the supplied input file(s).

It can be mapped against an existing phase, or executed directly using:

mvn okapi:pipeline

Configuration

<configuration>
    <!-- Mandatory Path to pipeline to execute -->
    <pipeline>test.pln</pipeline>
    <!-- Mandatory inputFiles using Maven FileSet format-->
    <!-- See https://maven.apache.org/shared/file-management/fileset.html for more details -->
    <inputFiles>
        <!-- Optional directory - can be absolute (include Maven variables), or relative to project baseDir -->
        <!-- defaults to project baseDir -->
        <directory>input</directory>
        <!-- Optional - Includes or Excludes -->
        <includes>
            <include>**/*.txt</include>
            <include>**/*.md</include>
        </includes>
        <excludes>
            <exclude>**/*.xml</exclude>
        </excludes>
    </inputFiles>
    <!-- Mandatory Source Language Name or Code-->
    <sourceLang>English</sourceLang>
    <!-- Mandatory Target Language Name or Code-->
    <targetLang>fr-FR</targetLang>
    <!-- Optional directory containing custom plugins -->
    <!-- Defaults to the project directory -->
    <pluginsDirectory>pluginsDir</pluginsDirectory>
    <!-- Optional Explicit Plugins using Maven FileSet format- -->
    <!-- See https://maven.apache.org/shared/file-management/fileset.html for more details -->
    <plugins>
        <!-- Optional directory - can be absolute (include Maven variables), or relative to project baseDir -->
        <!-- defaults to project baseDir -->
        <directory>input</directory>
        <!-- Optional - Includes or Excludes -->
        <includes>
            <include>**/*.jar</include>
        </includes>
    </plugins>
    <!-- Optional directory containing custom filters -->
    <!-- Defaults to the project directory -->
    <filtersDirectory>filtersDir</filtersDirectory>
    <!-- Optional output directory for the Okapi pipeline -->
    <!-- Defaults to the Maven target directory -->
    <outputDirectory>/tmp</outputDirectory>
</configuration>

okapi:export

Overview

The OkapiExportBatchConfigMojo builds and export a Binary Configuration file (a bconf) based on the configuration supplied.

It can be mapped against an existing phase, or executed directly using:

mvn okapi:export

Configuration

<configuration>
    <!-- Mandatory Name or Path to Export the BCONF to -->
    <bconf>export.bconf</bconf>
    <!-- Optional Pipeline to be used in the BCONF -->
    <pipeline>test.pln</pipeline>
    <!-- Optional Custom Filter Mapping(s) to be embedded in the BCONF -->
    <filterMappings> 
        <filterMapping>
            <!-- File extension to be mapped -->
            <extension>.htm</extension>
            <!-- Configuration to be used -->
            <configuration>okf_html@test</configuration>
        </filterMapping>
    </filterMappings>
    <!-- Optional Plugins to be included in the BCONF using Maven FileSet format- -->
    <!-- See https://maven.apache.org/shared/file-management/fileset.html for more details -->
    <plugins>
        <!-- Optional directory - can be absolute (include Maven variables), or relative to project baseDir -->
        <!-- defaults to project baseDir -->
        <directory>input</directory>
        <!-- Optional - Includes or Excludes -->
        <includes>
            <include>**/*.jar</include>
        </includes>
    </plugins>
    <!-- Optional output directory for the Okapi pipeline -->
    <!-- Defaults to the Maven target directory -->
    <outputDirectory>/tmp</outputDirectory>
</configuration>

okapi:install

Overview

The OkapiInstallBatchConfigMojo installs a Binary Configuration file (a bconf) to a folder on the local machine so it can be used.

It can be mapped against an existing phase, or executed directly using:

mvn okapi:install

Configuration

<configuration>
    <!-- Mandatory relative or absolute path to the BCONF to be installed -->
    <bconf>export.bconf</bconf>
    <!-- Mandatory relative or absolute path to install the BCONF to -->
    <outputDirectory>/tmp/install-test</outputDirectory>
</configuration>

Advanced Configuration

Different Okapi Version

The plugin has been developed against the latest released version at the time of writing (i.e. 1.45.0) and will aim to track against the latest version.

If you want to use a different Okapi version, you can override the Okapi Framework dependency in the plugin's configuration section of the POM.

For example, to use Okapi Framework version 1.44.0 you could use the following:

<build>
    <plugins>
        <plugin>
            <groupId>io.meikle.maven.okapi</groupId>
            <artifactId>okapi-maven-plugin</artifactId>
            <version>1.0-SNAPSHOT</version>
            <configuration>
                ...
            </configuration>
            <dependencies>
                <dependency>
                    <groupId>net.sf.okapi</groupId>
                    <artifactId>okapi-core</artifactId>
                    <version>1.44.0</version>
                </dependency>
                <dependency>
                    <groupId>net.sf.okapi.applications</groupId>
                    <artifactId>okapi-application-rainbow</artifactId>
                    <version>1.44.0</version>
                    <!-- Exclude non-required UI dependencies -->
                    <exclusions>
                        <exclusion>
                            <artifactId>*</artifactId>
                            <groupId>org.eclipse.platform</groupId>
                        </exclusion>
                    </exclusions>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>

Licence

Copyright 2021-23 David Meikle

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.