alfresco-transform-core/docs/transform-specific-code.md

## Transform specific code

To create a new t-engine an author uses a base t-engine (a Spring Boot
application) and implements the following interfaces. An implementation of
the `CustomTransformer` provides the actual transformation code and the
implementation of the `TransformEngine` says what it is capable of
transforming. The `TransformConfig` is normally read from a json file on the
classpath. Multiple `CustomTransformer` implementations may be in a singe
t-engine. As a result the author can concentrate on the code that transforms
one format to another without really worrying about all the plumbing.
Typically, the transform specific code uses a 3rd party library or an
external executable which needs to be added to the Docker image.

~~~
package org.alfresco.transform;

import org.alfresco.transform.config.TransformConfig;
import org.alfresco.transformer.probes.ProbeTestTransform;

import java.util.Set;

/**
 * Interface to be implemented by transform specific code. Provides information
 * about the t-engine as a whole. So that it is automatically picked up, it must
 * exist in a package under {@code org.alfresco.transform} and have the Spring
 * {@code @Component} annotation.
 */
public interface TransformEngine
{
    /**
      * @return the name of the t-engine. The t-router reads config from t-engines
      *         in name order.
      */
    String getTransformEngineName();

    /**
     * @return a definition of what the t-engine supports. Normally read from a json
     *         Resource on the classpath.
     */
    TransformConfig getTransformConfig();

    /**
     * @return a ProbeTestTransform (will do a quick transform) for k8 liveness and
     *         readiness probes.
     */
    ProbeTransform getProbeTransform();
}
~~~

implementations of the following interface provide the actual transform code.

~~~
package org.alfresco.transform;

import java.io.InputStream;
import java.io.OutputStream;
import java.util.Map;

/**
 * Interface to be implemented by transform specific code. The
 * {@code transformerName} should match the transformerName in the
 * {@link TransformConfig} returned by the {@link TransformEngine}. So that it is
 * automatically picked up, it must exist in a package under
 * {@code org.alfresco.transform} and have the Spring {@code @Component} annotation.
 *
 * Implementations may also use the {@link TransformManager} if they wish to
 * interact with the base t-engine.
 */
public interface CustomTransformer
{
    String getTransformerName();

    void transform(String sourceMimetype, InputStream inputStream,
                   String targetMimetype, OutputStream outputStream,
                   Map<String, String> transformOptions,
                   TransformManager transformManager) throws Exception;
}
~~~

The implementation of the following interface is provided by the t-base,
allows the `CustomTransformer` to interact with the base t-engine. The
creation of Files is discouraged as it is better not to leave files on disk.

~~~
package org.alfresco.transform.base;

import java.io.File;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.Map;

/**
 * Allows {@link CustomTransformer} implementations to interact with the base
 * t-engine.
 */
public interface TransformManager
{
    /**
     * Allows a CustomTransformer to use a local source File rather than the
     * supplied InputStream. To avoid creating extra files, if a File has already
     * been created by the base t-engine, it is returned.
     */
    File createSourceFile();

    /**
     * Allows a CustomTransformer to use a local target File rather than the
     * supplied OutputStream. To avoid creating extra files, if a File has already
     * been created by the base t-engine, it is returned.
     */
    File createTargetFile();

    /**
     * Allows a single transform request to have multiple transform responses. For
     * example, images from a video at different time offsets or different pages of
     * a document. Following a call to this method a transform response is made with
     * the data sent to the current {@code OutputStream}. If this method has been
     * called, there will not be another response when {@link CustomTransformer#
     * transform(String, InputStream, String, OutputStream, Map, TransformManager)}
     * returns and any data written to the final {@code OutputStream} will be
     * ignored.
     * @param index    returned with the response, so that the fragment may be
     *                 distinguished from other responses. Renditions use the index
     *                 as an offset into elements. A {@code null} value indicates
     *                 that there is no more output and any data sent to the current
     *                 {@code outputStream} will be ignored.
     * @param finished indicates this is the final fragment. {@code False} indicates
     *                 that it is expected there will be more fragments. There need
     *                 not be a call with this parameter set to {@code true}.
     * @return a new {@code OutputStream} for the next fragment. A {@code null} will
     *                 be returned if {@code index} was {@code null} or {@code
     *                 finished} was {@code true}.
     * @throws TransformException if a synchronous (http) request has been made as
     *                 this only works with requests on queues, or the first call to
     *                 this method indicated there was no output, or another call is
     *                 made after it has been indicated that there should be no more
     *                 fragments.
     * @throws IOException if there was a problem sending the response.
    OutputStream respondWithFragment(Integer index);
}
~~~