DocRaptor in Java

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. 🙂

Coding Journey : Vector Headings

Lately, I’ve been watching quite a few YouTube videos on making video games (though I don’t plan to make any) and cool visuals with programming. Some notable ones include The Coding Train (the true inspiration that led to this article), SebastianLague, and DevDuck. And watching these has led me down quite the rabbit hole…

Don’t Mock Your Domain

Hello again, everybody! Today’s article is made possible by Leonardo Giordani. He wrote a pretty good book called Clean Architectures in Python which is pay-what-you-want. I’m not quite done with it yet, but it’s a pretty good book so far, especially considering its cost. 

He opens up by talking about TDD for several chapters in order to make sure you know what’s going on for the latter half, where he builds a simple Clean application from the ground up giving you his unit tests before the code. He didn’t go step-by-step, so it’s not tedious in that way. But there’s a problem I have with a part of the book that I’d like to address. To do that, I need to do the most basic primer on Clean Architecture first.

Advanced Creation of Hamcrest Matchers in Kotlin

This article is a rewrite of an older one done in Java. This one is done in Kotlin instead.

Intro

Last time, I went over what a Hamcrest Matcher was, how it’s used, and how to make one. In this article, I will explain more advanced steps in the creation of Hamcrest Matchers. First, I’ll share how to make your matchers more easily type-safe, then some techniques for stateless Matchers, then finally how to cut down on so many static imports on your test classes. I’ll also give some quick tips on naming your static factory methods.

Typesafe Matchers

You may have noticed in the matches() method that we developed last time, I put in a type check. Potentially, you’ll need null checks too, because the method accepts an Any?, which allows nulls. The type check should seem strange, since we inherited from a class that has a generic type that we specified to be a String.

How to Make Your Own Hamcrest Matchers in Kotlin

This article is a rewrite of an older one done in Java. This one is done in Kotlin instead.

Intro to Hamcrest Matchers

First things first, I should quickly explain what a Hamcrest Matcher is. When doing unit testing, the built-in assertion types that come with the testing framework are generally pretty limited. They make it very easy for a person to end up multiple asserts to essentially check one thing. Even if it doesn’t multiple asserts, those asserts aren’t the most fluent to read and don’t tell exactly what you’re checking.

That’s where Hamcrest Matchers come in (and other assertion libraries, but we’re looking at hamcrest right now). They allow you to define your own more robust and more fluent assertions, essentially. For example, if you were testing whether a method correctly returns an empty String, that test might look something like this:

@Test
fun testUsingMatcher() {
    val string = methodThatShouldReturnAnEmptyString();
    assertThat(string, isEmptyString());
}