diff --git a/README.md b/README.md index 1ca7211f..a8c0c607 100644 --- a/README.md +++ b/README.md @@ -5,26 +5,23 @@ Contains the common transformer (T-Engine) code, plus a few implementations. ### Sub-projects -* `alfresco-transform-model` - library packaged as a jar file which contains the data model of json +* `model` - library packaged as a jar file which contains the data model of json configuration files and messages sent between clients, T-Engines and T-Router. Also contains code to - work out which transform should be used for a combination of configuration files; see the sub-project's - [README](https://github.com/Alfresco/alfresco-transform-core/blob/master/alfresco-transform-model/README.md) -* `alfresco-base-t-engine` - library packaged as a jar file which contains code that is common - to all the transformers; see the sub-project's - [README](https://github.com/Alfresco/alfresco-transform-core/blob/master/alfresco-base-t-engine/README.md) -* `alfresco-transform-` - multiple T-Engines; each one of them builds both a SpringBoot fat jar - and a [Docker image](https://github.com/Alfresco/alfresco-transform-core#docker) - + to combine and then work out which transform to use for a combination of source and target mimetypes + and transform options. +* `engines/base` - contains code common to t-engines, packaged as a jar. + [README](https://github.com/Alfresco/alfresco-transform-core/blob/master/engines/base/README.md) +* `engines/` - multiple T-Engines, which extend the `engines/base`; each one builds a SpringBoot jar + and a [Docker image](https://github.com/Alfresco/alfresco-transform-core#docker) +* `deprecated/alfresco-base-t-engine` - The original t-engine base, which may still be used, + but has been replaced by the simpler `engines/base` + [README](https://github.com/Alfresco/alfresco-transform-core/blob/master/deprecated/alfresco-base-t-engine/README.md) + ### Documentation -In addition to the subprojects (such as `alfresco-base-t-engine` README above) some additional documentation can be found in: - -* [this project's docs](docs) folder +* `docs` - provides additional documentation. * [ACS Packaging docs](https://github.com/Alfresco/acs-packaging/tree/master/docs) folder - -Note: if you're interested in the Alfresco Transform Service (ATS) that is part of the enterprise Alfresco Content Services (ACS) please see: - -* https://docs.alfresco.com/transform/concepts/transformservice-overview.html +* If you're interested in the Alfresco Transform Service (ATS) see https://docs.alfresco.com/transform/concepts/transformservice-overview.html ### Building and testing diff --git a/deprecated/alfresco-transformer-base/README.md b/deprecated/alfresco-transformer-base/README.md index 6044d549..fd5c95d0 100644 --- a/deprecated/alfresco-transformer-base/README.md +++ b/deprecated/alfresco-transformer-base/README.md @@ -1,7 +1,11 @@ -# Common code for Transform Engines +# Common code for Transform Engines (Deprecated) -This project contains code that is common between all the ACS T-Engine transformers that run as Spring Boot process (optionally within their own -Docker containers). It performs common actions such as logging, throttling requests and handling the streaming of content to and from the container. +This project holds the original code that was common to all ACS T-Engine transformers. Although +it is still possible to create T-Engines this way, the newer `engine/base` project provides a +simpler way to do it. + +This project provides a base Spring Boot process (optionally within their own Docker containers). +It performs common actions such as logging, throttling requests and handling the streaming of content to and from the container. For more details on build a custom T-Engine, please refer to the current docs in ACS Packaging, including: diff --git a/deprecated/alfresco-transformer-base/src/main/java/org/alfresco/transformer/executors/AbstractCommandExecutor.java b/deprecated/alfresco-transformer-base/src/main/java/org/alfresco/transformer/executors/AbstractCommandExecutor.java index a60fec06..b732224d 100644 --- a/deprecated/alfresco-transformer-base/src/main/java/org/alfresco/transformer/executors/AbstractCommandExecutor.java +++ b/deprecated/alfresco-transformer-base/src/main/java/org/alfresco/transformer/executors/AbstractCommandExecutor.java @@ -60,7 +60,7 @@ public abstract class AbstractCommandExecutor implements CommandExecutor if (!targetFile.exists() || targetFile.length() == 0) { - throw new TransformException(INTERNAL_SERVER_ERROR, Transformer failed to create an output file"); + throw new TransformException(INTERNAL_SERVER_ERROR, "Transformer failed to create an output file"); } } diff --git a/docs/alfresco-transformer.yaml b/docs/alfresco-transformer.yaml deleted file mode 100644 index d5adc79d..00000000 --- a/docs/alfresco-transformer.yaml +++ /dev/null @@ -1,224 +0,0 @@ -swagger: '2.0' -info: - description: | - **Alfresco Transform Engines REST API** - - Transform Request & Response API to allow a source file to be transformed into a - target file, given a set of transform options. - - The new JSON-based Transform Engines API is used by the Alfresco Transform Service (ATS). - ATS provides an independently-scalable transform service, initially used by ACS - Content Repository, as part of the overall Alfresco Digital Business Platform (DBP). - - Note: Each kind of Transform Engine implements this Transform Engines API, including: - - * ImageMagick - * LibreOffice - * PDF Renderer - * Tika - - In the future, this Transform Engines API may form the basis for adding custom Transform Engines. - - version: '1' - title: Alfresco Transform Engines REST API -basePath: /alfresco/api/-default-/private/transformer/versions/1 -tags: - - name: Transform - description: Transform Engine Request / Respone -paths: - '/transform': - post: - x-alfresco-since: "2.0" - tags: - - Transform - summary: Transform Engines API - description: | - **Note:** available with Alfresco Transform Engines 2.0 and newer versions. - - This endpoint supports both JSON and Multipart. The JSON API is used within the - Alfresco Transform Service (eg. ACS 6.1). The Multipart API remains for backwards - compatibility (eg. ACS 6.0). - - **Using JSON (application/json -> application/json)** - - The ACS Content Repository 6.1 (or higher) provides the option to offload - supported transformations to the Alfresco Transform Service. - - The JSON API is used within the Alfresco Transform Service. It relies on the - source and target files being stored and retrieved via the Alfresco Shared File - Store (see also [alfresco-sfs.yaml](https://github.com/Alfresco/alfresco-shared-file-store/blob/master/docs/api-definitions/alfresco-sfs.yaml)). - - Here's a pseudo-example transform request: - - ```JSON - { - "schema": 1, - "requestId": "0aead31c-e3ca-42c9-8e16-c1938ff64c3a", - "clientData": "opaque-client-specific-data-123xyz", - "sourceReference": "598387b8-d85d-4557-816e-50f44c969e04", - "sourceSize": 32713, - "sourceMediaType: "image/jpeg", - "sourceExtension": "jpeg", - "targetMediaType: "image/png", - "targetExtension": "png", - "transformRequestOptions": { - "resizeWidth": "25", - "resizePercentage": "true", - "maintainAspectRatio": "true" - } - } - ``` - - Here's a pseudo-example response of a successful transform: - - ```JSON - { - "schema": 1, - "status": 201 - "requestId": "0aead31c-e3ca-42c9-8e16-c1938ff64c3a", - "clientData": "opaque-client-specific-data-123xyz", - "sourceReference": "598387b8-d85d-4557-816e-50f44c969e04", - "targetReference": "5bc81e48-e17a-4727-bd1c-3a279aa6b421" - } - ``` - - Here's a pseudo-example response of a failed transform: - - ```JSON - { - "schema": 1, - "status": 400, - "errorDetails": "Lorem ipsum dolor sit amet, ..." - "requestId": "0aead31c-e3ca-42c9-8e16-c1938ff64c3a", - "clientData": "opaque-client-specific-data-123xyz", - "sourceReference": "598387b8-d85d-4557-816e-50f44c969e04" - } - ``` - - **Using Multipart (multipart/form-data -> application/octet-stream)** - - The Multipart API remains for backwards compatibility (eg. ACS 6.0). It requires - the source file to be uploaded via multipart/form-data (along with transformation - options). The target file is returned as a binary response (application/octet-steam). - - operationId: transformOperation - parameters: - - in: body - name: transformRequest - description: The Transform Request including source reference and transform options - required: true - schema: - $ref: '#/definitions/transformRequest' - consumes: - - application/json - - multipart/form-data - produces: - - application/json - - application/octet-stream - responses: - '201': - description: Successful response - schema: - $ref: '#/definitions/transformReply' - default: - description: Unexpected error - schema: - $ref: '#/definitions/Error' - '/transformer/options': - get: - tags: - - Transform - description: List transform options - operationId: transformOptions - produces: - - application/json - responses: - 200: - description: Successful response - schema: - type: array - xml: - name: transformOptions - wrapped: true - items: - $ref: '#/definitions/transformOption' -definitions: - Error: - type: object - required: - - error - properties: - error: - type: object - required: - - statusCode - - briefSummary - - stackTrace - - descriptionURL - properties: - errorKey: - type: string - statusCode: - type: integer - format: int32 - briefSummary: - type: string - stackTrace: - type: string - descriptionURL: - type: string - logId: - type: string - transformRequest: - type: object - properties: - requestId: - type: string - sourceReference: - type: string - sourceMediaType: - type: string - sourceSize: - type: integer - format: int64 - sourceExtension: - type: string - targetMediaType: - type: string - targetExtension: - type: string - clientData: - type: string - schema: - type: integer - transformRequestOptions: - type: object - additionalProperties: - type: string - transformReply: - type: object - properties: - status: - type: integer - requestId: - type: string - sourceReference: - type: string - targetReference: - type: string - clientData: - type: string - schema: - type: integer - errorDetails: - type: string - transformOption: - type: object - required: - - required - - name - properties: - required: - type: boolean - name: - type: string \ No newline at end of file diff --git a/docs/engine_config.md b/docs/engine_config.md index 40096af6..a0bcf8cd 100644 --- a/docs/engine_config.md +++ b/docs/engine_config.md @@ -1,16 +1,16 @@ ## T-Engine configuration T-Engines provide a */transform/config* end point for clients (e.g. Transform-Router or -Alfresco-Repository) that indicate what is supported. T-Engines store this +Repository) that indicate what is supported. T-Engines store this configuration as a JSON resource file named *engine_config.json*. -The config can be found under `alfresco-transform-core\\src\main\resources -\engine_config.json`; current configuration files are: -* [Pdf-Renderer T-Engine configuration](https://github.com/Alfresco/alfresco-transform-core/blob/master/alfresco-docker-alfresco-pdf-renderer/src/main/resources/engine_config.json). -* [ImageMagick T-Engine configuration](https://github.com/Alfresco/alfresco-transform-core/blob/master/alfresco-docker-imagemagick/src/main/resources/engine_config.json). -* [Libreoffice T-Engine configuration](https://github.com/Alfresco/alfresco-transform-core/blob/master/alfresco-docker-libreoffice/src/main/resources/engine_config.json). -* [Tika T-Engine configuration](https://github.com/Alfresco/alfresco-transform-core/blob/master/alfresco-docker-tika/src/main/resources/engine_config.json). -* [Misc T-Engine configuration](https://github.com/Alfresco/alfresco-transform-core/blob/master/alfresco-docker-transform-misc/src/main/resources/engine_config.json). +The config can be found under `alfresco-transform-core/engines//src/main/resources +/_engine_config.json`; current configuration files are: +* [Pdf-Renderer T-Engine configuration](https://github.com/Alfresco/alfresco-transform-core/blob/master/engines/pdfrenderer/src/main/resources/pdfrenderer_engine_config.json). +* [ImageMagick T-Engine configuration](https://github.com/Alfresco/alfresco-transform-core/blob/master/engines/imagemagick/src/main/resources/imagemagick_engine_config.json). +* [Libreoffice T-Engine configuration](https://github.com/Alfresco/alfresco-transform-core/blob/master/engines/libreoffice/src/main/resources/libreoffice_engine_config.json). +* [Tika T-Engine configuration](https://github.com/Alfresco/alfresco-transform-core/blob/master/engines/tika/src/main/resources/tika_engine_config.json). +* [Misc T-Engine configuration](https://github.com/Alfresco/alfresco-transform-core/blob/master/engines/misc/src/main/resources/misc_engine_config.json). *Snippet from Tika T-engine configuration:* ```json @@ -64,9 +64,7 @@ The config can be found under `alfresco-transform-core\\src\main\ T-Engines. In this example there are two groups of options called **tikaOptions** and **pdfboxOptions** which has a group of options **targetEncoding** and **notExtractBookmarksText**. Unless an option has a **"required": true** field it is - considered to be optional. You don't need to specify *sourceMimetype*, - *targetMimetype*, *sourceExtension* or *targetExtension* as options as - these are automatically added. + considered to be optional. *Snippet from ImageMagick T-engine configuration:* ```json @@ -93,11 +91,6 @@ The config can be found under `alfresco-transform-core\\src\main\ use this approach as it is easier to read. A transformOptionsGroup can contain one or more transformOptionsValue and transformOptionsGroup. - **Limitations**: - * For a transformOptions to be referenced in a different T-engine, another transformer - with the complete definition of the transformOptions needs to return the config to the client. - * In a transformOptions definition it is not allowed to use a reference to another tranformOption. - ### Transformers * **transformers** - A list of transformer definitions. Each transformer definition should have a unique **transformerName**,