HOWTO: Contribute a Command Line Converter

Since 7.1, there is a new converter class CommandLineConverter that can be used to contribute new converters executing a command line. A specific Java class calling the command line is not required anymore.

Let's see how we can contribute a new converter changing the format of an image using ImageMagick.

Contributing the Command Line

Add a new command line called changeFormat that changes the image format.

<extension target="org.nuxeo.ecm.platform.commandline.executor.service.CommandLineExecutorComponent"
  point="command">
  <command name="changeFormat" enabled="true">
    <commandLine>convert</commandLine>
    <parameterString>#{sourceFilePath} #{targetFilePath}.#{format}
    </parameterString>
    <installationDirective>You need to install ImageMagick.
    </installationDirective>
  </command>
</extension>

Notes on the parameters

• sourceFilePath: References the Blob passed as argument to the ConversionService. Here it will be the the image of which we want to change the format. This parameter will be computed by the CommandLineConverter from the input Blob.
• targetFilePath: The output file path, computed by the CommandLineConverter (see below).
• format: The format of the converted image. This parameter won't be computed by the CommandLineConverter and needs to be passed when calling the command line.

Contributing the Converter

Add a new converter using the CommandLineConverter class to call the changeFormat command line.

<extension target="org.nuxeo.ecm.core.convert.service.ConversionServiceImpl"
  point="converter">
  <converter name="changeFormat"
    class="org.nuxeo.ecm.platform.convert.plugins.CommandLineConverter">
    <parameters>
      <parameter name="CommandLineName">changeFormat</parameter>
    </parameters>
  </converter>
</extension>

Using the New Converter

Notes on the CommandLineConverter

• It accepts one parameter, targetFileName, to specify the name of the output file.
• All parameters passed to the converter will be passed to the command line: If a parameter name is passed to the converter, it can be also used in the command line referenced by the converter contribution.
• It computes three parameters passed to the command line:
  • sourceFilePath: The path of the input Blob
  • targetFilePath: The path of the output file, computed from a temporary directory + the targetFileName parameter. If the targetFileName parameter is empty, a temporary one will be used.
  • outDirPath: the temporary directory where to output the result. The targetFilePath references a file in this directory.

With Java

Assuming you have a BlobHolder which is the input image and you want to change its format to png, you can use the following Java code:

ConversionService cs = Framework.getService(ConversionService.class);
Map<String, Serializable> parameters = new HashMap<>();
parameters.put("targetFileName", "newImage");
parameters.put("format", "png");
BlobHolder result = cs.convert("changeFormat", parameters);

Blob newImage = result.getBlob();
// do whatever with the converted image
// assertEquals("newImage.png", mainBlob.getFilename());

With Automation

Since 7.1, there is a new operation RunConverter that can run any named converter with a set of parameters. Assuming you have as input a Blob which is the input image and you want to change its format to png, you can use the following operation:

- Blob.RunConverter:
    converter: changeFormat
    parameters:
      format: "png"

The output of this operation will be the converted image.