This is a long time in coming. Back when I posted the article on DocRaptor’s API in Python, I said I’d post an article on their Java API “soon”. That was in February 2018. But, anyone who’s paid attention to this blog knows that I’m pretty lousy at following up on promises on here. 🙂
I’d like to thank DocRaptor for sponsoring me again, and for reminding me to do it 😛 I’ve been hit pretty hard lately and could really use the money.
What is DocRaptor
So, as mentioned above, this is a follow-up of an older article about DocRaptor. I’ll give a brief refresher of what it is again, but if you want more details, check out the old article or their website.
DocRaptor is an online service for transforming HTML to PDFs or Excel documents. It’s a paid service with a 7-day free trial and several pay levels to customize to your needs.
To use it, you just sign up for the service to receive your API key and make a POST request with the right parameters and the PDF is sent back to you. It can be used in the command line, but it also has libraries for Ruby, Python, Node, PHP, Java, and C#, all with decent documentation. We’ve already looked at the Python library; let’s look at the Java one, now.
Installing the DocRaptor Library
DocRaptor is available for download from Maven Central with the group id of
com.docraptor3, artifact id of
docraptor, and the current version is 2.0.0. You can use this with your favored build system, or you can download it yourself.
Just like the Python API, the Java API is rather small. This is understandable, since there’s pretty much only one web API endpoint to do the job (there are also a couple others that can provide useful information as needed). One starred import is needed:
import com.docraptor.*, or you can import the classes individually. The necessary ones are
Doc. Another likely class is
PrinceOptions. We’ll discuss each in kind quickly here.
DocApi is your starting and ending point. It’s what gives you the
ApiClient by calling
getApiClient() and what you make the final call to
ApiClient is where you set a few API settings, such as your API key and whether to use debug mode. To set the API key, you call
setUsername(...) and pass in the String of the key. To change into or out of debug mode, call
setDebugging(...), passing a boolean of whether you want it to be on. By default, it seems to be off.
Doc is a big one, and is used to set up the document to convert. If you set test mode to true with
setTest(...), you’ll do test mode, which allows you to convert a document for free but will leave a watermark. The next big step is actually supplying the document to convert. If you have access to a String of the document, you can pass that into
setDocumentContent(...) method. If not, you can send a URL of the document’s location with
setDocumentUrl(...) instead. You can tell it whether to transform to pdf or xls using
setDocumentType(...) and passing in the proper
Doc.DocumentTypeEnum value. Don’t forget to set the name of the final document with
Those are all the basics, and there are quite a few more options available to set, which you can look into yourself in their documentation. The other big thing is what they call “prince options”. I think it’s a play on “print(s) options”? Anyway, with a
PrinceOptions object, you can adjust a bunch of styling options, it seems. There’s way too much there to put it in this article, so again, check out their documentation. Once you’re done setting up those options, you can add it to the
Doc object with
After all of the option-setting, don’t forget to call
createDoc() method, passing in your
There are a few setter methods on
Doc that aren’t really optional (though most could have defaults), so I don’t know why they don’t just accept them into the constructor or a couple static factory methods. Something that makes it a little bit handier to use is their fluent API. Instead of all the
setXxx(...) methods that don’t return anything, they also have methods called
xxx(...) that return
this, so you can immediately call the next one.
If I was using this a lot in Kotlin, I would use extension functions to make a couple factory methods to take in the basics, especially taking advantage of default and named arguments for
apply() function, along with automatic properties from Java interop:
Or you can use some kind of crazy combination of all the options 😛
There seems to be an excessive amount of engineering around
ApiClient as well. I’d like to find a way to pare that down.
When it comes to really digging in, there’s a lot to find for configuring the API, and I highly suggest looking into their documentation for it. It’s not bad. Not great, but not bad. And one of the best ways to learn once their documentation fails you is to look through their code, which is available on GitHub.
I didn’t check to see if there were any changes to the Python API, but this one doesn’t seem to have the same “Auto-generated” text in the documentation like Python’s did when I did the article. So, either they used a different method for their Java API, or they changed what they do overall with every/most languages.
Either way, it’s still a great service that is relatively easy to use, and I recommend it. But they’re paying me, so you’ll have to decide for yourself if it’s good enough for you. 🙂