inteligr8/alfresco-transform-core
1
0
Fork 0
mirror of https://github.com/Alfresco/alfresco-transform-core.git synced 2025-08-14 17:58:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

Save point: [skip ci]

Browse Source 
* docs
This commit is contained in:
alandavis
2022-07-20 13:35:35 +01:00
parent 929b69384b
commit 6692946fb5
5 changed files with 30 additions and 260 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
README.md
View File

@@ -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-<name>` - multiple T-Engines; each one of them builds both a SpringBoot fat jar
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/<name>` - 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

10
deprecated/alfresco-transformer-base/README.md
View File

@@ -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:

2
deprecated/alfresco-transformer-base/src/main/java/org/alfresco/transformer/executors/AbstractCommandExecutor.java
View File

@@ -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");
}
}

224
docs/alfresco-transformer.yaml
View File

@@ -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

25
docs/engine_config.md
View File

@@ -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\<t-engine-name>\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/<t-engine-name>/src/main/resources
/<t-engine-name>_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\<t-engine-name>\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\<t-engine-name>\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**,