pollexor builds Thumbor image URLs through a fluent Java API

A URL builder, not an image processor

pollexor is a Java client for the Thumbor image service that allows you to build URIs in an expressive fashion using a fluent API. That one sentence sets the scope precisely, and it is worth being explicit about where the work happens. Thumbor is the service that does the resizing, cropping and filtering. pollexor is the part that composes the request path, and the whole point of the library is that composing that path by hand is unpleasant. A Thumbor URL is a slash separated sequence of operations, and the ordering of those segments is part of the protocol, so a client that lets you chain calls in the order you want removes a class of bug where a hand written string puts the crop after the resize. The audience is Java and Android developers whose application displays images through a Thumbor instance, typically in a product where the same handful of transformations are applied in several places, which is where a shared builder earns its place rather than a one line string concatenation.

Two ways to create the client, with and without a key

The entry point is a Thumbor object, and it comes in two forms. Without encryption, you create it from the base URL of the service:

// Without encryption:
Thumbor thumbor = Thumbor.create("http://example.com/");

With encryption, you pass the shared key as well, which is what a Thumbor deployment with a security key requires:

// With encryption:
Thumbor thumbor = Thumbor.create("http://example.com/", "key");

The distinction shows up later in the URL. An unsecured service produces paths under /unsafe/, which is the segment Thumbor uses for unauthenticated requests, and a secured one produces a signed path instead. The library is compatible with the Android platform, which the project states explicitly, and that compatibility has a practical consequence: the client is a plain JVM library with no desktop specific dependencies, so it does not drag a heavier HTTP stack into a mobile application than it needs. The project is published under the group and artifact coordinates com.squareup:pollexor, and the documentation notes that development builds are published to Sonatype's development repository, which is the usual arrangement for a library that wants consumers to be able to try a branch before a release.

Chained calls produce a path in a defined order

The API is the chain. A simple resize is two calls:

thumbor.buildImage("http://example.com/image.png")
    .resize(48, 48)
    .toUrl()
// Produces: /unsafe/48x48/example.com/image.png

Adding a crop and a smart detection shows how the segments accumulate, and the order in which you call the methods is the order the segments appear in the path:

thumbor.buildImage("http://example.com/image.png")
    .crop(10, 10, 90, 90)
    .resize(40, 40)
    .smart()
    .toUrl()
// Produces: /unsafe/10x10:90x90/smart/40x40/example.com/image.png

Alignment is the same idea with a named constant rather than a string, since the segment is a readable token:

thumbor.buildImage("http://example.com/image.png")
    .crop(5, 5, 195, 195)
    .resize(95, 95)
    .align(BOTTOM, RIGHT)
    .toUrl()
// Produces: /unsafe/5x5:195x195/right/bottom/95x95/example.com/image.png

Note that the alignment segment comes out in the reverse of the argument order, so align(BOTTOM, RIGHT) produces right/bottom. That is the Thumbor protocol's ordering, not a quirk of the library, and it is the kind of detail that makes a typed, tested client worth having rather than a template string. The result of toUrl is a path, ready to be appended to the service's base URL, which is what makes the object composable with whatever HTTP client your application already uses.

Filters can nest one image transformation inside another

The filter API is where the fluent style pays off, because filters take arguments that can themselves be URLs built by the same builder. A filter list of a rounded corner, two watermarks and a quality setting looks like this:

thumbor.buildImage("http://example.com/background.png")
    .resize(200, 100)
    .filter(
        roundCorner(10),
        watermark(thumbor.buildImage("http://example.com/overlay1.png").resize(200, 100)),
        watermark(thumbor.buildImage("http://example.com/overlay2.png").resize(50, 50), 75, 25),
        quality(85)
    )
    .toUrl()
// Produces: /unsafe/200x100/filters:round_corner(10,255,255,255):watermark(/unsafe/200x100/example.com/overlay1.png,0,0,0):watermark(/unsafe/50x50/example.com/overlay2.png,75,25,0):quality(85)/example.com/background.png

The important structural point is in the output. The watermark filter takes a nested URL, and that nested URL is itself a full transformation path produced by the same builder, so the inner image is resized independently of the outer one. The first watermark inherits the outer resize of 200x100, while the second carries its own 50x50. Filters are serialised into a single filters segment with colon separated entries, and each watermark carries its own positioning arguments, defaulting to a corner placement when none are given. Nesting is the reason to use a builder here rather than string concatenation, because a nested path inside a filter argument inside a path is exactly the shape that goes wrong when it is assembled by hand.

Adding the library, and the release cadence question

The library is distributed the standard Java way, with the latest JAR available for download, a Gradle coordinate and a Maven dependency block. The Gradle form is a single line:

implementation 'com.squareup:pollexor:3.0.0'

And the Maven form is the usual coordinate block:

<dependency>
  <groupId>com.squareup</groupId>
  <artifactId>pollexor</artifactId>
  <version>3.0.0</version>
</dependency>

The version to note is 3.0.0, and it raises a question about maintenance that the repository layout does not answer on its own. The repository has no GitHub releases, so there is no release page to diff versions against, although it does carry a CHANGELOG.md, a RELEASING.md, a build.gradle with a gradle.properties and a gradle/ wrapper directory, so the project is set up for automated release work. The last push to the repository was on 2026-08-27 and it is not archived, so the code is being worked on. The practical advice is to read the changelog before pinning a version, because with a client library the interesting question is not whether the code compiles but whether the URL shape it produces matches the Thumbor version you run.

Where a URL builder is the wrong tool

Two situations make pollexor the wrong choice, and both are common. The first is when you do not have a Thumbor service. pollexor produces a path, and something has to serve it. If your images live in a cloud bucket and you want resized derivatives, an image processing service or a CDN with image transformation is the thing you need, and a Thumbor client is an extra layer with an extra deployment. The second is when the transformation set is fixed and small. If a whole application needs exactly one square thumbnail at one size, a single string format is clearer than a builder, and a library is a dependency to keep current. There is also a middle case worth naming. Thumbor's own URL scheme is not the only way to reach a Thumbor instance, and a service can be fronted by a gateway that rewrites paths, in which case a client that insists on producing the exact canonical path is more rigid than you need. The other limitation is shared with the whole Thumbor model rather than being specific to this library. Thumbor works on images it can fetch, so a source that requires authentication, sits behind a hotlink check or is not reachable from the service will not render no matter how well the URL is composed. That failure appears as a broken image at the far end of a request that succeeded.

Editorial conclusion

Adopt pollexor if you already run a Thumbor service and want to build transformation URLs from Java or Android code without hand assembling path segments. Do not adopt it if you have no Thumbor instance, since the library only produces URLs, and do not expect it to resize anything on its own. Before you build on it, check that the version of Thumbor you run supports the operations you plan to use, and read the changelog, because the current release line is 3.0.0 while the repository has no GitHub releases to track.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. square/pollexor on GitHub