Generate a PDF in a Spring Boot with Apache PDFBox and Kotlin

A featured image for category: Spring

1. Introduction

In this guide, I will walk you step by step through the process of generating and securing a PDF in a Spring Boot REST API with Apache PDFBox and Kotlin. After this tutorial you will be able to create PDF reports containing text and tables and expose them through the REST API in Spring Boot. Additionally, I will show you how to secure them with owner and user passwords and apply policies to them.

To better visualize the final effect, these are the two pages generated in this tutorial:

Image shows an example PDF generated in a Spring Boot project written in Kotlin with a help of Apache PDFBox and Boxable libraries.

2. Imports

Let’s start everything by adding a few dependencies to our Gradle project:



Personally, each time I start a new project, I use the Spring Initializr, which allows selecting necessary libraries pretty easily.

Similarly, I did this time, but you might have already noticed two more libraries we will need to generate the PDF:

Basically, the first one is an open-source Java tool for working with PDF documents. I will prove to you in the next chapters, how easy and neat the whole process of creating a PDF in Spring Boot becomes with this library.

Boxable, on the other hand, is a great extension for the first one, which will help us generate tables.

3. Create Test Data Provider

As the next step, let’s implement a logic responsible for example data generation:

object PeopleDataProvider {

  fun generateTestData(): List<Person> =
      Person("John", "Doe", "", 22),
      Person("Emma", "Smith", "", 20),
      Person("Wayne", "Johnson", "", 30),
      Person("Robert", "Robertson", "", 41),
      Person("Sophia", "Miller", "", 27),
      Person("Adam", "Williams", "", 52)

  data class Person(
    val firstName: String,
    val lastName: String,
    val email: String,
    val age: Int

The PeopleDataProvider is a simple Kotlin object with one function returning a list of random people’s data.

In a real-life scenario, this structure can be easily replaced with some other logic, like fetching from the database.

4. Create Controller

After that, let’s prepare the code responsible for exposing a REST endpoint, which will be used to fetch the PDF in our Spring Boot Kotlin app. (And please don’t worry about missing PdfService, we will take care of it in the next chapter):

class PdfController(
  private val pdfService: PdfService
) {

  fun getAllUsersCsvExport(response: HttpServletResponse): ResponseEntity<ByteArray> {
    val report = pdfService.generate()

    return ResponseEntity.ok()
      .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"report.pdf\"")

To put it simply, the above method handles all POST /api/report requests by invoking the generate() method. It produces a ByteArray object, which ends ups as a response body. Whatsoever, we explicitly specify two additionals headers:

  • Content-Type– indicating the original media type of the resource (PDF in our case)
  • Content-Disposition– instructing the client, whether the content is expected to be inlined in the browser, or downloaded as an attachment (and I believe there is no doubt about which one we’ve picked here)

5. Create PdfService

Nextly, let’s implement the missing PdfService:

class PdfService(
  private val firstPageGenerator: FirstPageGenerator
) {

  fun generate(): ByteArray {
    val document = PDDocument()

    val firstPage = firstPageGenerator.generate(document)

    val byteArray = generateByteArray(document)
    return byteArray

  private fun generateByteArray(document: PDDocument): ByteArray {
    val outputStream = ByteArrayOutputStream()
    return outputStream.toByteArray()


Just like in the previous example, the compiler complains about missing class and we will get rid of this error in the next chapter. But for now, let’s figure out what’s going on here.

In the first line, we create a PDDocument instance. At this point, it’s just an empty PDF document. Nevertheless, it’s not valid as long as we don’t add at least one page to it. As you might have already noticed, to do that we have to use the addPage() method, which as an argument takes the PDPage instance returned by the FirstPageGenerator.

Finally, we pass the document to the generateByteArray() function, which saves it to the output stream and converts it to the byte array.

6. Implement FirstPageGenerator

With all of that being done, let’s prepare a class responsible for the first page of the PDF:

class FirstPageGenerator {

  companion object {
    private const val FONT_SIZE = 50
    private const val TITLE = "Example test report"

    private val FONT = PDType1Font.TIMES_BOLD

  fun generate(document: PDDocument): PDPage {
    val page = PDPage()

    val titleWidth = calculateTitleWidth()
    val horizontalOffset = calculateHorizontalOffset(page, titleWidth)
    val verticalOffset = calculateVerticalOffset(page)

    val contentStream = PDPageContentStream(document, page)
    editContent(contentStream, horizontalOffset, verticalOffset)

    return page

  private fun editContent(
    contentStream: PDPageContentStream,
    horizontalOffset: Float,
    verticalOffset: Float
  ) {
    contentStream.setFont(FONT, FONT_SIZE.toFloat())
    contentStream.newLineAtOffset(horizontalOffset, verticalOffset)

  private fun calculateVerticalOffset(page: PDPage): Float =
    (page.mediaBox.height) / 2

  private fun calculateHorizontalOffset(page: PDPage, titleWidth: Float): Float =
    (page.mediaBox.width - titleWidth) / 2

  private fun calculateTitleWidth(): Float =
    FONT.getStringWidth(TITLE) / 1000 * FONT_SIZE

Basically, the whole purpose of this code is to generate a new PDPage instance, which will become the first page of the final document. However, the most important class here is the PDPageContentStream, which provides the ability to write a page content stream.

Moreover, we use the constructor overriding all existing content streams. In simple words, if the page instance passed to it contains any data, it will be removed. If we would like to put multiple content streams to it, then the library provides additional constructors allowing us to explicitly specify the behavior, like appending or prepending.

As you might have already noticed, the whole magic happens inside the editContent() function. The PDPageContentStream provides plenty of methods to work with, but it all depends on the particular things we would like to display. In our case, we write the predefined title with Times-Bold font and size set to 50 in the very center of the page.

Additionally, please remember that after we finish working with the content stream, we must call the close() method.

7. Testing PDF Spring Boot Generator

At this point, we should be able to finally generate the first version of the PDF document in our Spring Boot app. To do so, let’s run the app and invoke the cURL command:

curl -X POST http://localhost:8080/api/report --output file.pdf

As a result, the document should be generated and persisted within the directory. Please keep in mind, that it can be done with Postman, or another similar tool, as well.

8. Create Table Page

With that being done, let’s add a second page to our document.

8.1. Implement TablePageGenerator

Firstly, let’s create a TablePageGenerator class:

class TablePageGenerator {

  companion object {
    private const val MARGIN = 30f
    private const val TOP_MARGIN = 30f
    private const val BOTTOM_MARGIN = 30f

    // specified in px
    private const val ROW_HEIGHT = 20f

    // % of table width
    private const val CELL_WIDTH = 20f

    private val TABLE_WIDTH = PDRectangle.A4.width - 60
    private val Y_TABLE_START = PDRectangle.A4.height - 100

  fun generate(document: PDDocument, people: List<PeopleDataProvider.Person>): PDPage {
    val page = PDPage()

    val contentStream = PDPageContentStream(document, page)

    val table = createTable(document, page)
    addDataRows(people, table)


    return page

  private fun createTable(document: PDDocument, page: PDPage): BaseTable =
      MARGIN, document, page, true, true

  private fun addHeaderRow(table: BaseTable) {
    val row: Row<PDPage> = table.createRow(ROW_HEIGHT)

    createBoldHeaderCell(row, "Number")
    createBoldHeaderCell(row, "First Name")
    createBoldHeaderCell(row, "Last Name")
    createBoldHeaderCell(row, "Email")
    createBoldHeaderCell(row, "Age")

  private fun createBoldHeaderCell(row: Row<PDPage>, value: String) {
      .createCell(CELL_WIDTH, value)
      .font = PDType1Font.TIMES_BOLD

  private fun addDataRows(
    people: List<PeopleDataProvider.Person>,
    table: BaseTable
  ) {
    people.forEachIndexed { index, person ->
    val row = table.createRow(ROW_HEIGHT)
    createCell(row, (index + 1).toString())
    createCell(row, person.firstName)
    createCell(row, person.lastName)
    createCell(row, person.age.toString())

  private fun createCell(row: Row<PDPage>, value: String) {
      .font = PDType1Font.TIMES_ROMAN

Just like in the previous example, everything starts and ends with the PDPage and PDPageContentStream instances. However, this time, we make use of the Boxable library. I’ve mentioned in the beginning that it really simplifies the whole process of table generation for PDF in Spring Boot and I believe the above code proves it best.

As we can see, to generate a new table we need to create a BaseTable instance and pass the necessary parameters to its constructor. Additionally, all of the arguments taken from the companion object are pretty descriptive. Nevertheless, as a word of explanation- the two last boolean flags set the drawLines and the drawContent to true. As always, I highly encourage you to check it out with different, custom settings.

After that is done, we add the header row and data rows for each person from the provided list. To put it simply, we use the table instance, to add a new Row object with the createRow method, which is then used to add cells with the createCell function.

8.2. Edit PdfService

Nextly, we need to get back to the PdfService class and make use of our new class:

class PdfService(
  private val firstPageGenerator: FirstPageGenerator,
  private val tablePageGenerator: TablePageGenerator
) {

  fun generate(): ByteArray {
    val document = PDDocument()

    val people = PeopleDataProvider.generateTestData()
    val firstPage = firstPageGenerator.generate(document)
    val tablePage = tablePageGenerator.generate(document, people)

//... the rest of the code

Similarly to the first page, we’ve just added the TablePageGenerator to the constructor (line 4), and added to the document (line 15) the PDPage instance (line 12) generated with the data from our test provider (line 10).

After it’s done, let’s rerun the command from chapter 5. As a result, we should see that the generated PDF contains two, beautiful pages with a title and a table.

9. Secure The Document

Finally, let’s learn how to secure a PDF generated in the Spring Boot app and set additional policies.

9.1. Create ProtectionPolicyService

Let’s add the ProtectionPolicyService:

class ProtectionPolicyService {

  companion object {
    // either 40, 128 or 256
    private const val ENCRYPTION_KEY_LENGTH = 256
    private const val OWNER_PASSWORD = "owner"
    private const val USER_PASSWORD = "user"

  fun generateStandardProtectionPolicy(): StandardProtectionPolicy {
    val accessPermission = AccessPermission()
    return getStandardProtectionPolicy(accessPermission)

  private fun getStandardProtectionPolicy(accessPermission: AccessPermission): StandardProtectionPolicy {
    val protectionPolicy = StandardProtectionPolicy(OWNER_PASSWORD, USER_PASSWORD, accessPermission)
    protectionPolicy.encryptionKeyLength = ENCRYPTION_KEY_LENGTH
    return protectionPolicy

The StandardProtectionPolicy is a simpler implementation of the ProtectionPolicy class. With it we can configure password-based protection and specific permissions for users. It’s worth mentioning, that it allows us to only distinguish between the owner (full permissions) and a “standard” user (with permissions defined by the AccessPermission instance). If we would like to gain more control over the recipients’ privileges, then the PublicKeyProtectionPolicy would be the better choice. In the contrary, it allows us to handle multiple recipients with different permissions.

But for now, let’s focus on the code we’ve just written. I’ve mentioned above the AccessPermission class. As we can see, it allows us to define what exactly users can or can not do. By default, all permissions are granted. But given the above snippet we can clearly see that with this configuration users won’t be able to print or extract the content of the document. Nevertheless, it’s just a small part of all permissions we can grant and I highly encourage you to check out other possibilities.

Finally, we set the owner’s and users’ passwords followed by the encryption key length.

9.2. Modify PdfService

As the last step, we need to make use of the created code:

class PdfService(
  private val firstPageGenerator: FirstPageGenerator,
  private val tablePageGenerator: TablePageGenerator,
  private val protectionPolicyService: ProtectionPolicyService
) {

  fun generate(): ByteArray {
    val document = PDDocument()

    val people = PeopleDataProvider.generateTestData()
    val firstPage = firstPageGenerator.generate(document)
    val tablePage = tablePageGenerator.generate(document, people)
    val protectionPolicy = protectionPolicyService.generateStandardProtectionPolicy()

//... the rest of the code

Similarly to the 8.2, we’ve added the constructor parameter (line 5) and protected the document (line 18) with the generated policy (line 14).

And again, let’s rerun the application and invoke the test command to validate that everything behaves as expected. We should be able to print the document specifying the owner password. In contrary, it should be forbidden when the standard user password has been used.

10. Generate PDF With Spring Boot Summary

That’s all for today’s tutorial. I really hope that you enjoyed it and that it will help you generating your own PDFs using Apache PDFBox. The knowledge you’ve gathered today should be enough to start exploring this library and apply functionalities in your own use-cases.

Finally, if you would like to get the source code, please visit this GitHub repository.

As always, if you would like to ask about anything or need some more explanation, please do it in the comment section below, or by using the contact form.


If you find this material useful, you might be interested in my previous articles:

Share this:

Hi there! 👋

Hi there! 👋

My name is Piotr and I've created Codersee to share my knowledge about Kotlin, Spring Framework, and other related topics through practical, step-by-step guides. Always eager to chat and exchange knowledge.

Related content


Image presents 3 ebooks with Java, Spring and Kotlin interview questions.

Never miss any important updates from the Kotlin world and get 3 ebooks!

You may opt out any time. Terms of Use and Privacy Policy

To make Codersee work, we log user data. By using our site, you agree to our Privacy Policy and Terms of Use.