A Kotlin library that interacts with Gotenberg's different modules to convert a variety of document formats to PDF files.
To incorporate kotenberg
into your project, follow the snippets below for Gradle dependencies.
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")
}
Before attempting to use Kotenberg
, be sure you install Docker if you have not already done so.
Once the docker Daemon is up and running, you can start a default Docker container of Gotenberg as follows:
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 page and add it to your Java project classpath
.
Create an instance of Kotenberg
class and pass your Gotenberg
endpoint
url as a constructor parameter.
val client = Kotenberg("http://localhost:8090/")
Kotenberg
client comes with a convertUrl
, convertHtml
and convertMarkdown
methods that call one of Chromium's 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.
val response = client.convertUrl("https://gotenberg.dev/")
The only requirement is that one of the files name should be index.html
.
val index = File("path/to/index.html")
val header = File("path/to/header.html")
val response = client.convertHtml(listOf(index, header))
This route accepts an index.html
file plus markdown files. Check Gotenberg docs for details.
val index = File("path/to/index.html")
val markdown = File("path/to/markdown.md")
val response = client.convertMarkdown(listOf(index, markdown))
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.
val pageProperties = PageProperties.Builder().build()
val response = client.convertMarkdown(listOf(index), pageProperties)
Kotenberg
client provides a convertWithLibreOffice
method which interacts 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.
val docx = File("path/to/file.docx")
val xlsx = File("path/to/file.xlsx")
val response = client.convertWithLibreOffice(listOf(docx, xlsx))
Similarly, Kotenberg
client provides a convertWithPdfEngines
method which interacts with PDF Engines 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
.
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 merge the PDF files.
val pdf1 = File("path/to/first.pdf")
val pdf2 = File("path/to/second.pdf")
val response = client.mergeWithPdfEngines(listOf(pdf1, pdf2))
The following is a short snippet of how to use the library.
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<ByteArray>()
FileUtils.copyInputStreamToFile(pdfContent, tempFile)
} catch (e: Exception) {
throw RuntimeException(e)
}
}
}