Java SDK

Java SDK to generate reports through the Carbone Cloud API in few lines of codes.

The source code is available on Github: https://github.com/carboneio/carbone-sdk-java

Install

<dependency>
    <groupId>io.carbone</groupId>
    <artifactId>carbone-sdk</artifactId>
    <version>2.0.0</version>
</dependency>

Quickstart with the Java SDK

Try the following code to render a report in 10 seconds. Just insert your API key, the template path you want to render, and the JSON data-set as string. Get your API key on your Carbone account: https://account.carbone.io/.

ICarboneServices carboneServices = CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create(API_KEY);
String json = "{ "data": { "id": "AF128","firstname": "John", "lastname": "wick"}, "reportName": "invoice-{d.id}","convertTo": "pdf"}";

/** Generate the document */
try{
    CarboneDocument report = carboneServices.render(json ,"/path/to/template.docx");
}
catch(CarboneException e)
{
    // handle error
    System.out.println("Error message : " + e.getMessage() + "Status code : " + e.getHttpStatus());
}

// Get the name of the document with the `getName()`. For instance the name of the document, based on the JSON, is: "invoice-AF128.pdf"
try (FileOutputStream outputStream = new FileOutputStream(report.getName())) {
    /** Save the generated document */
    outputStream.write(report.getFileContent());
} catch (IOException ioe) {
    // handle error
}

Carbone SDK Constructor

Definition

public CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create(String... config);

Example

Example of a new SDK instance for Carbone Cloud: Get your API key on your Carbone account: https://account.carbone.io/.

// For Carbone Cloud, provide your API Access Token as first argument:
ICarboneServices carboneServices = CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create("API_TOKEN");
Example of a new SDK instance for Carbone On-premise or Carbone On-AWS:

// Define the URL of your Carbone On-premise Server or AWS EC2 URL:
CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.SetCarboneUrl("ON_PREMISE_URL");
// Then get a new instance by providing an empty string to the "create" function:
ICarboneServices carboneServices = CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create("");

Generate and Download Document

Prototype

public CarboneDocument render(String jsonData, String pathOrTemplateID) throws CarboneException;

The render function generates a document using a specified template and data. It takes two parameters:

• jsonData: A stringified JSON containing the data to populate the template.
• pathOrTemplateID: The path to your local file or a template ID.

The render function returns a CarboneDocument, it provides two methods:

• getFileContent(): Return the document as byte[].
• getName(): Return the document name as String.

Function Behavior

1. Template File Path as Second Argument:
   • If a template file path is provided, the function first checks if the template has been uploaded to the server.
   • If the template has not been uploaded, it calls the addTemplate function to upload the template and generate a new template ID.
   • The function then calls renderReport followed by getReport to generate and retrieve the report.
   • If the provided path does not exist, an error is returned.
2. Template ID as Second Argument:
   • If a template ID is provided, the function calls renderReport to generate the report. It then calls getReport to retrieve the generated report.
   • If the template ID does not exist, an error is returned.

🔎 Tip: Providing the Template File Path is the best solution, you won't have to deal with template IDs.

Example

try{
    CarboneDocument report = carboneServices.render(json ,"/path/to/template.xlsx");
    // report.getFileContent() returns the generated document as byte[]
    // report.getName() returns the document name as String
}
catch(CarboneException e)
{
    // handle error
    System.out.println("Error message : " + e.getMessage() + "Status code : " + e.getHttpStatus());
}

Add Template

Definition

public String addTemplate(byte[] templateFile) throws CarboneException, IOException;

or

public String addTemplate(String templatePath) throws CarboneException, IOException;

Add a template as path String or as byte[] and the function return the template ID as String.

Example

Add a template as file path:

ICarboneServices carboneServices = CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create(apiKey);

try{
    String templateId = carboneServices.addTemplate("/path/to/template.docx");
}
catch(CarboneException e)
{
    System.out.println("Error message : " + e.getMessage() + "Status code : " + e.getHttpStatus());
}

System.out.println(templateId);

Add a template as byte[]:

ICarboneServices carboneServices = CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create(apiKey);

try{
    String templateId = carboneServices.addTemplate(Files.readAllBytes(Paths.get("/path/to/template.docx")));
}
catch(CarboneException e)
{
    System.out.println("Error message : " + e.getMessage() + "Status code : " + e.getHttpStatus());
}

System.out.println(templateId);

Delete Template

Definition

public boolean deleteTemplate(String templateId) throws CarboneException;

Delete a template by providing a template ID as String, and it returns whether the request succeeded as a Boolean.

Example

ICarboneServices carboneServices = CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create(apiKey);

try{
    boolean result = carboneServices.deleteTemplate(templateId.get());
}
catch(CarboneException e)
{
    System.out.println("Error message : " + e.getMessage() + "Status code : " + e.getHttpStatus());
}

System.out.println(result);