Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/marrek13/kotenberg
https://github.com/marrek13/kotenberg
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/marrek13/kotenberg
- Owner: marrek13
- License: mit
- Created: 2023-11-29T22:40:01.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2024-05-26T08:34:27.000Z (6 months ago)
- Last Synced: 2024-06-03T09:32:16.806Z (5 months ago)
- Language: Kotlin
- Size: 684 KB
- Stars: 8
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-gotenberg - Kotlin - marrek13/kotenberg
README
# Kotenberg
[](https://github.com/marrek13/kotenberg/actions/workflows/build.yml)
A Kotlin library that interacts with [Gotenberg](https://gotenberg.dev/)'s different modules to convert a variety of document formats to PDF files.
## Snippets
To incorporate `kotenberg` into your project, follow the snippets below for Gradle dependencies.
### Gradle Kotlin DSL
```kotlin
repositories {
maven {
url = uri("https://maven.pkg.github.com/marrek13/kotenberg")
credentials {
username = project.findProperty("gpr.user")?.toString() ?: System.getenv("GITHUB_USERNAME")
password = project.findProperty("gpr.key")?.toString() ?: System.getenv("GITHUB_TOKEN")
}
}
}
dependencies {
implementation("dev.marrek13:kotenberg:1.0.0")
}
```
## Prerequisites
Before attempting to use `Kotenberg`, be sure you install [Docker](https://www.docker.com/) if you have not already done so.
Once the docker Daemon is up and running, you can start a default Docker container of [Gotenberg](https://gotenberg.dev/) as follows:
```bash
docker run --rm -p 8090:8090 gotenberg/gotenberg:7 gotenberg --api-port=8090
```
After that, you need to download the latest `Kotenberg` JAR library from the GitHub [Releases](https://github.com/marrek13/kotenberg/releases) page and add it to your Java project `classpath`.
## Get Started
Create an instance of `Kotenberg` class and pass your `Gotenberg` `endpoint` url as a constructor parameter.
```kotlin
val client = Kotenberg("http://localhost:8090/")
```
### Chromium
`Kotenberg` client comes with a `convertUrl`, `convertHtml` and `convertMarkdown` methods that call one of Chromium's [routes](https://gotenberg.dev/docs/modules/chromium#routes) to convert `html` and `markdown` files, or a `url` to a `CloseableHttpResponse` that contains the `HttpEntity` which holds the content of the converted PDF file.
`convert` expects two parameters; the first parameter represents what will be converted (i.e. `url`, `html`, or `markdown` files), and the second one is a `PageProperties` parameter.
#### URL
```kotlin
val response = client.convertUrl("https://gotenberg.dev/")
```
#### HTML
The only requirement is that one of the files name should be `index.html`.
```kotlin
val index = File("path/to/index.html")
val header = File("path/to/header.html")
val response = client.convertHtml(listOf(index, header))
```
#### Markdown
This route accepts an `index.html` file plus markdown files. Check [Gotenberg docs](https://gotenberg.dev/docs/routes#markdown-files-into-pdf-route) for details.
```kotlin
val index = File("path/to/index.html")
val markdown = File("path/to/markdown.md")
val response = client.convertMarkdown(listOf(index, markdown))
```
### Customization
`Kotenberg` client comes with `PageProperties` which is a builder class that allows you to customize the style of the generated PDF. The default page properties can be found [here](https://gotenberg.dev/docs/routes#page-properties-chromium).
```kotlin
val pageProperties = PageProperties.Builder().build()
val response = client.convertMarkdown(listOf(index), pageProperties)
```
### LibreOffice
`Kotenberg` client provides a `convertWithLibreOffice` method which interacts with [LibreOffice](https://gotenberg.dev/docs/routes#convert-with-libreoffice) to convert different types of documents such as `.docx`, `.epub`, `.eps`, and so on. You can find the list of all file extensions [here](https://gotenberg.dev/docs/routes#office-documents-into-pdfs-route).
```kotlin
val docx = File("path/to/file.docx")
val xlsx = File("path/to/file.xlsx")
val response = client.convertWithLibreOffice(listOf(docx, xlsx))
```
### PDF Engines
Similarly, `Kotenberg` client provides a `convertWithPdfEngines` method which interacts with [PDF Engines](https://gotenberg.dev/docs/routes#office-documents-into-pdfs-route) to convert PDF files to a specific format (i.e. `PDF/A-1a`, `PDF/A-2b`, `PDF/A-3b`)).
The supported formats can be found in `PdfFormat`.
```kotlin
val pdf1 = File("path/to/first.pdf")
val pdf2 = File("path/to/second.pdf")
val pageProperties = PageProperties.Builder()
.addPdfFormat(PdfFormat.A_3B.format())
.build()
val response = client.convertWithPdfEngines(listOf(pdf1, pdf2), pageProperties)
```
Additionally, you can also use `mergeWithPdfEngines` method to [alphabetically](https://gotenberg.dev/docs/routes#merge-pdfs-route) merge the PDF files.
```kotlin
val pdf1 = File("path/to/first.pdf")
val pdf2 = File("path/to/second.pdf")
val response = client.mergeWithPdfEngines(listOf(pdf1, pdf2))
```
## Example
The following is a short snippet of how to use the library.
```kotlin
import dev.marrek13.kotenberg.Kotenberg
import dev.marrek13.kotenberg.PageProperties
import org.apache.commons.io.FileUtils
import java.nio.file.Files
import java.nio.file.Paths
class Main {
fun main() {
val client = Kotenberg("http://localhost:80/")
try {
val url = "https://gotenberg.dev/"
val properties = PageProperties.Builder()
.addMarginTop(1.0f)
.addMarginLeft(0.5f)
.addMarginBottom(1.0f)
.addMarginTop(0.5f)
.addPrintBackground(true)
.build()
val response = client.convertUrl(url, properties)
val projectDir = Paths.get("").toAbsolutePath().normalize()
val tempDir = Files.createTempDirectory(projectDir, "temp_")
val tempFile = Files.createTempFile(tempDir, "PDF_", ".pdf").toFile()
val pdfContent = response.body()
FileUtils.copyInputStreamToFile(pdfContent, tempFile)
} catch (e: Exception) {
throw RuntimeException(e)
}
}
}
```