Developer-friendly & type-safe Java SDK specifically catered to leverage openapi API.
Important
This SDK is not yet ready for production use. To complete setup please follow the steps outlined in your workspace. Delete this section before > publishing to a package manager.
Stirling PDF - Processing API: API documentation for PDF processing operations including conversion, manipulation, security, and utilities.
JDK 11 or later is required.
The samples below show how a published SDK artifact is used:
Gradle:
implementation 'com.stirling:openapi:0.2.4'Maven:
<dependency>
<groupId>com.stirling</groupId>
<artifactId>openapi</artifactId>
<version>0.2.4</version>
</dependency>After cloning the git repository to your file system you can build the SDK artifact from source to the build directory by running ./gradlew build on *nix systems or gradlew.bat on Windows systems.
If you wish to build from source and publish the SDK artifact to your local Maven repository (on your filesystem) then use the following command (after cloning the git repo locally):
On *nix:
./gradlew publishToMavenLocal -Pskip.signingOn Windows:
gradlew.bat publishToMavenLocal -Pskip.signingpackage hello.world;
import java.lang.Exception;
import org.openapis.openapi.Stirling;
import org.openapis.openapi.models.components.SignatureValidationRequest;
import org.openapis.openapi.models.errors.*;
import org.openapis.openapi.models.operations.ValidateSignatureResponse;
public class Application {
public static void main(String[] args) throws ValidateSignatureBadRequestException, ValidateSignatureRequestEntityTooLargeException, ValidateSignatureUnprocessableEntityException, ValidateSignatureInternalServerError, Exception {
Stirling sdk = Stirling.builder()
.build();
SignatureValidationRequest req = SignatureValidationRequest.builder()
.fileId("a1b2c3d4-5678-90ab-cdef-ghijklmnopqr")
.build();
ValidateSignatureResponse res = sdk.security().validateSignature()
.request(req)
.call();
}
}An asynchronous SDK client is also available that returns a CompletableFuture<T>. See Asynchronous Support for more details on async benefits and reactive library integration.
package hello.world;
import java.util.concurrent.CompletableFuture;
import org.openapis.openapi.AsyncStirling;
import org.openapis.openapi.Stirling;
import org.openapis.openapi.models.components.SignatureValidationRequest;
import org.openapis.openapi.models.operations.async.ValidateSignatureResponse;
public class Application {
public static void main(String[] args) {
AsyncStirling sdk = Stirling.builder()
.build()
.async();
SignatureValidationRequest req = SignatureValidationRequest.builder()
.fileId("a1b2c3d4-5678-90ab-cdef-ghijklmnopqr")
.build();
CompletableFuture<ValidateSignatureResponse> resFut = sdk.security().validateSignature()
.request(req)
.call();
}
}The SDK provides comprehensive asynchronous support using Java's CompletableFuture<T> and Reactive Streams Publisher<T> APIs. This design makes no assumptions about your choice of reactive toolkit, allowing seamless integration with any reactive library.
Why Use Async?
Asynchronous operations provide several key benefits:
- Non-blocking I/O: Your threads stay free for other work while operations are in flight
- Better resource utilization: Handle more concurrent operations with fewer threads
- Improved scalability: Build highly responsive applications that can handle thousands of concurrent requests
- Reactive integration: Works seamlessly with reactive streams and backpressure handling
Reactive Library Integration
The SDK returns Reactive Streams Publisher<T> instances for operations dealing with streams involving multiple I/O interactions. We use Reactive Streams instead of JDK Flow API to provide broader compatibility with the reactive ecosystem, as most reactive libraries natively support Reactive Streams.
Why Reactive Streams over JDK Flow?
- Broader ecosystem compatibility: Most reactive libraries (Project Reactor, RxJava, Akka Streams, etc.) natively support Reactive Streams
- Industry standard: Reactive Streams is the de facto standard for reactive programming in Java
- Better interoperability: Seamless integration without additional adapters for most use cases
Integration with Popular Libraries:
- Project Reactor: Use
Flux.from(publisher)to convert to Reactor types - RxJava: Use
Flowable.fromPublisher(publisher)for RxJava integration - Akka Streams: Use
Source.fromPublisher(publisher)for Akka Streams integration - Vert.x: Use
ReadStream.fromPublisher(vertx, publisher)for Vert.x reactive streams - Mutiny: Use
Multi.createFrom().publisher(publisher)for Quarkus Mutiny integration
For JDK Flow API Integration: If you need JDK Flow API compatibility (e.g., for Quarkus/Mutiny 2), you can use adapters:
// Convert Reactive Streams Publisher to Flow Publisher
Flow.Publisher<T> flowPublisher = FlowAdapters.toFlowPublisher(reactiveStreamsPublisher);
// Convert Flow Publisher to Reactive Streams Publisher
Publisher<T> reactiveStreamsPublisher = FlowAdapters.toPublisher(flowPublisher);For standard single-response operations, the SDK returns CompletableFuture<T> for straightforward async execution.
Supported Operations
Async support is available for:
- Server-sent Events: Stream real-time events with Reactive Streams
Publisher<T> - JSONL Streaming: Process streaming JSON lines asynchronously
- Pagination: Iterate through paginated results using
callAsPublisher()andcallAsPublisherUnwrapped() - File Uploads: Upload files asynchronously with progress tracking
- File Downloads: Download files asynchronously with streaming support
- Standard Operations: All regular API calls return
CompletableFuture<T>for async execution
Available methods
- getSecurityInfo - Get security information
- getPageDimensions - Get page dimensions for all pages
- getPageCount - Get PDF page count
- getFormFields - Get form field information
- getFontInfo - Get font information
- getDocumentProperties - Get PDF document properties
- getBasicInfo - Get basic PDF information
- getAnnotationInfo - Get annotation information
- urlToPdf - Convert a URL to a PDF
- processPdfToXML - Convert PDF to XML
- processPdfToWord - Convert PDF to Word document
- processPdfToRTForTXT - Convert PDF to Text or RTF format
- processPdfToPresentation - Convert PDF to Presentation format
- pdfToPdfA - Convert a PDF to a PDF/A
- processPdfToMarkdown - Convert PDF to Markdown
- convertToImage - Convert PDF to image(s)
- processPdfToHTML - Convert PDF to HTML
- pdfToCsv - Extracts a CSV document from a PDF
- markdownToPdf - Convert a Markdown file to PDF
- convertToPdf - Convert images to a PDF file
- htmlToPdf - Convert an HTML or ZIP (containing HTML and CSS) to PDF
- processFileToPDF - Convert a file to a PDF using LibreOffice
- convertEmlToPdf - Convert EML to PDF
- pageSize - Checks if a PDF is of a certain size
- pageRotation - Checks if a PDF is of a certain rotation
- pageCount - Checks if a PDF is greater, less or equal to a setPageCount
- fileSize - Checks if a PDF is a set file size
- containsText - Checks if a PDF contains set text, returns true if does
- containsImage - Checks if a PDF contains an image
- splitPdf - Split PDF pages into smaller sections
- splitPdf1 - Split PDFs by Chapters
- splitPdf2 - Split a PDF file into separate documents
- autoSplitPdf1 - Auto split PDF pages into separate documents based on size or count
- scalePages - Change the size of a PDF page/document
- rotatePDF - Rotate a PDF file
- deletePages - Remove pages from a PDF file
- removeImages - Remove images from file to reduce the file size.
- rearrangePages - Rearrange pages in a PDF file
- pdfToSinglePage - Convert a multi-page PDF into a single long page PDF
- overlayPdfs - Overlay PDF files in various modes
- mergeMultiplePagesIntoOne - Merge multiple pages of a PDF document into a single page
- mergePdfs - Merge multiple PDF files into one
- extractBookmarks - Extract PDF Bookmarks
- editTableOfContents - Edit Table of Contents
- cropPdf - Crops a PDF document
- createBookletImposition - Create a booklet with proper page imposition
- metadata - Update metadata of a PDF file
- unlockPDFForms - Remove read-only property from form fields
- extractHeader - Grabs all JS from a PDF and returns a single JS file with all code
- scannerEffect - Apply scanner effect to PDF
- replaceAndInvertColor - Replace-Invert Color PDF
- repairPdf - Repair a PDF file
- removeBlankPages - Remove blank pages from a PDF file
- processPdfWithOCR - Process a PDF file with OCR
- flatten - Flatten PDF form fields or full page
- extractImages - Extract images from a PDF file
- extractImageScans - Extract image scans from an input file
- decompressPdf - Decompress PDF streams
- optimizePdf - Optimize PDF file
- autoSplitPdf - Auto split PDF pages into separate documents
- extractHeader1 - Extract header from PDF file
- addStamp - Add stamp to a PDF file
- addPageNumbers - Add page numbers to a PDF document
- overlayImage - Overlay image onto a PDF file
- addAttachments - Add attachments to PDF
- handleData - Execute automated PDF processing pipeline
- validateSignature - Validate PDF Digital Signature
- sanitizePDF - Sanitize a PDF file
- removePassword - Remove password from a PDF file
- removeCertSignPDF - Remove digital signature from PDF
- redactPdfManual - Redacts areas and pages in a PDF document
- getPdfInfo - Summary here
- signPDFWithCert - Sign PDF with a Digital Certificate
- redactPdfAuto - Redacts listOfText in a PDF document
- addWatermark - Add watermark to a PDF file
- addPassword - Add password to a PDF file
Handling errors in this SDK should largely match your expectations. All operations return a response object or raise an exception.
By default, an API error will throw a models/errors/APIException exception. When custom error responses are specified for an operation, the SDK may also throw their associated exception. You can refer to respective Errors tables in SDK docs for more details on possible exception types for each operation. For example, the validateSignature method throws the following exceptions:
| Error Type | Status Code | Content Type |
|---|---|---|
| models/errors/ValidateSignatureBadRequestException | 400 | application/json |
| models/errors/ValidateSignatureRequestEntityTooLargeException | 413 | application/json |
| models/errors/ValidateSignatureUnprocessableEntityException | 422 | application/json |
| models/errors/ValidateSignatureInternalServerError | 500 | application/json |
| models/errors/APIException | 4XX, 5XX | */* |
package hello.world;
import java.lang.Exception;
import org.openapis.openapi.Stirling;
import org.openapis.openapi.models.components.SignatureValidationRequest;
import org.openapis.openapi.models.errors.*;
import org.openapis.openapi.models.operations.ValidateSignatureResponse;
public class Application {
public static void main(String[] args) throws ValidateSignatureBadRequestException, ValidateSignatureRequestEntityTooLargeException, ValidateSignatureUnprocessableEntityException, ValidateSignatureInternalServerError, Exception {
Stirling sdk = Stirling.builder()
.build();
SignatureValidationRequest req = SignatureValidationRequest.builder()
.fileId("a1b2c3d4-5678-90ab-cdef-ghijklmnopqr")
.build();
ValidateSignatureResponse res = sdk.security().validateSignature()
.request(req)
.call();
}
}The default server can be overridden globally using the .serverURL(String serverUrl) builder method when initializing the SDK client instance. For example:
package hello.world;
import java.lang.Exception;
import org.openapis.openapi.Stirling;
import org.openapis.openapi.models.components.SignatureValidationRequest;
import org.openapis.openapi.models.errors.*;
import org.openapis.openapi.models.operations.ValidateSignatureResponse;
public class Application {
public static void main(String[] args) throws ValidateSignatureBadRequestException, ValidateSignatureRequestEntityTooLargeException, ValidateSignatureUnprocessableEntityException, ValidateSignatureInternalServerError, Exception {
Stirling sdk = Stirling.builder()
.serverURL("http://localhost:8080")
.build();
SignatureValidationRequest req = SignatureValidationRequest.builder()
.fileId("a1b2c3d4-5678-90ab-cdef-ghijklmnopqr")
.build();
ValidateSignatureResponse res = sdk.security().validateSignature()
.request(req)
.call();
}
}You can setup your SDK to emit debug logs for SDK requests and responses.
For request and response logging (especially json bodies), call enableHTTPDebugLogging(boolean) on the SDK builder like so:
SDK.builder()
.enableHTTPDebugLogging(true)
.build();Example output:
Sending request: http://localhost:35123/bearer#global GET
Request headers: {Accept=[application/json], Authorization=[******], Client-Level-Header=[added by client], Idempotency-Key=[some-key], x-speakeasy-user-agent=[speakeasy-sdk/java 0.0.1 internal 0.1.0 org.openapis.openapi]}
Received response: (GET http://localhost:35123/bearer#global) 200
Response headers: {access-control-allow-credentials=[true], access-control-allow-origin=[*], connection=[keep-alive], content-length=[50], content-type=[application/json], date=[Wed, 09 Apr 2025 01:43:29 GMT], server=[gunicorn/19.9.0]}
Response body:
{
"authenticated": true,
"token": "global"
}
WARNING: This should only used for temporary debugging purposes. Leaving this option on in a production system could expose credentials/secrets in logs. Authorization headers are redacted by default and there is the ability to specify redacted header names via SpeakeasyHTTPClient.setRedactedHeaders.
NOTE: This is a convenience method that calls HTTPClient.enableDebugLogging(). The SpeakeasyHTTPClient honors this setting. If you are using a custom HTTP client, it is up to the custom client to honor this setting.
Another option is to set the System property -Djdk.httpclient.HttpClient.log=all. However, this second option does not log bodies.
This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.
While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.