Programming Ideas With Jake

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.

Java API

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 DocApi, ApiClient, and 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 createDoc(...) from.

The 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 Doc‘s 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 Doc‘s 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 setName(...) (include the file type extension). If the HTML you’re using some javascript processing to do first, you can enable javascript using setJavascript(true).

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 setPrinceOptions().

After all of the option-setting, don’t forget to call DocApi‘s createDoc() method, passing in your Doc object.

Improvements

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 test and javascript (which, if set to true, enables javascript processing) . Or you can at least use Kotlin’s apply() function, along with automatic properties from Java interop:

val doc = Doc().apply {
    test = ...
    documentContent = …
    name = …
    javascript = …
    …
}

Or you can use some kind of crazy combination of all the options

There seems to be an excessive amount of engineering around DocApi and ApiClient as well. I’d like to find a way to pare that down. 

Closing Thoughts

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.