The data access layer is such an ubiquitous component of our applications, one could dare to say it’s the essence of it—business logic is derived from this data after all. As a programmer you’ll spend a great deal of time in this layer, which means you’ve probably run into the following piece of code:

// Long and unformatted query...
String jpql = "FROM Store s JOIN s.guitars g WHERE g.price > " +
        "(SELECT max(g2.price) FROM Guitar g2 JOIN g2.store s2 WHERE s2 = :folsomStore) ";
if (someCondition) {
    // ...split across different conditions
    jpql += "AND g.fretboardWood NOT IN (:maple, :ebony) ";
}
jpql += "ORDER BY s.location ASC";

Query query = entityManager.createQuery(jpql);
// ... set query parameters
return query.getResultList(); // No type safety

In such a small example you can already spot a few code smells, not to mention that string mangling can become extremely gruesome in most cases. Given the amount of time we spent maintaining modules with this particular pattern found in every method, surely there must be a better way to build complex queries without developer experience trade-offs.

Criteria API

Criteria API was introduced with the release of JSR 317: Java Persistence API, Version 2.0 in 2009. Criteria queries are written in plain Java, are type safe, and just like its JPQL (formerly Java Persistence Query Language) counterpart, they work regardless of the underlying data store.

Switching your plain string queries to Criteria API is, in my opinion, the single most significant improvement you can make to your application’s data layer:

• Drastically enhance the developer experience by unlocking powerful programmatic control flow techniques, without sacrificing readability. Say goodbye to complicated string mangled spaghetti code.
• Reduce potentially hundreds of lines of duplicate queries with little to no differences by encouraging modularity and reuse. Client requests a change be reflected in multiple reports? Modifying a single query is often enough.
• Improve performance by skipping unnecessary JOIN clauses you might have to support a single (and rarely materialized) condition in your string appending line of WHEREs.

Spring Data JPA abstracts this API even further and introduces the concept of Specifications as small building blocks which can be combined and used with JpaRepository without the need to declare a query (method) for every needed combination.

Guitar Inventory Example

I’m not joking when I say that after using Criteria API/Specifications you’ll never want to write a single string query again. And to make that case, I’ve created a sample project using the three styles of query definitions. I’m using Spring Boot 2.7 which, while way past its open source support window, still runs Java 8 code. This choice is deliberate so this article can reach a much wider audience.

If you’re not using Spring, but do have access to the EntityManager, then this article still applies to you. So I encourage you to download the source code and follow along with me!

The project consists of a guitar inventory management system for multiple brick-and-mortar store locations:

Business Logic

Suppose the client’s point of sale needs to fetch available guitars for sale based on the following rules:

1. By default, only the current store (Roseville) inventory is shown, but one can toggle the full catalog
2. Due to a shortage, no maple fretboards are available for sale
3. Dave is a new hire and only sells guitars priced at $100 or less

We start by creating a getInventory method with a signature like so:

List<Guitar> getInventory(boolean showAllStores, int salesPersonId);

Using JPQL (String queries)

Because we wouldn’t want to define a new string query for every single escenario (which is subject to change), the usual approach is appending conditionals to the WHERE clause in the JPQL string:

// CustomizedGuitarRepositoryImpl.java stub
List<Guitar> getInventoryUsingJPQL(boolean showAllStores, int salesPersonId) {
    boolean isNewHire = salesPersonId == DAVE;

     /*
      * I manually format the string here, but I've witnessed incredibly unreadable
      * one-liners. Plus there's a lack of tooling to standardize this.
      */
     String jpql =
             "SELECT g " + // We have to deliberately add spacing
             "FROM Guitar g " +
             "JOIN g.fretboardWood f " +
             "JOIN g.store s " + // Premature JOIN clause (what if showAllStores is true?)
             "WHERE ";

    jpql += "f.id != :maple AND ";

    if (!showAllStores) {
        jpql += "s.id = :roseville AND ";
    }

    if (isNewHire) {
        jpql += "g.price <= :priceCap AND ";
    }

    jpql += "1 = 1"; // Make sure the query does not end with AND
    
    Query query = entityManager.createQuery(jpql);
    // ... set query parameters
    return query.getResultList(); // No type safety
}

While the current business logic is not very complex, there’s no doubt that the previous code is unfit for more elaborate requirements. The string mangling will quickly become unmaintainable and the lack of modularity makes it impossible to reuse the conditions in a different query or even expand upon it (i.e. additional filtering). On that last note, we might be tempted to filter the query results in a different layer of our application, like the front-end, but this means losing the performance of the query optimizer of our database to custom filtering code of a data structure (meaning we now have to maintain code in two different locations).

Using Criteria API

With Criteria API, each conditional is represented with a Predicate. These can be manipulated programmatically, expanded upon, and reused across our codebase:

// CustomizedGuitarRepositoryImpl.java stub
List<Guitar> getInventoryUsingCriteria(boolean showAllStores, int salesPersonId) {
    CriteriaBuilder cb = entityManager.getCriteriaBuilder();
    CriteriaQuery<Guitar> cq = cb.createQuery(Guitar.class);
    Root<Guitar> guitar = cq.from(Guitar.class);
    boolean isNewHire = salesPersonId == DAVE;

    Predicate noMapleFretboards = cb.notEqual(guitar.get(Guitar_.FRETBOARD_WOOD).get(FretboardWood_.ID),
            FretboardWood.MAPLE);
    Predicate fromRosevilleStore = cb.equal(guitar.get(Guitar_.STORE).get(Store_.ID), Store.ROSEVILLE);
    Predicate atNewHirePriceCap = cb.lessThanOrEqualTo(guitar.get(Guitar_.PRICE), NEW_HIRE_PRICE_CAP);

    List<Predicate> predicates = new ArrayList<>();
    predicates.add(noMapleFretboards);

    if (!showAllStores) {
        predicates.add(fromRosevilleStore);
    }

    if (isNewHire) {
        predicates.add(atNewHirePriceCap);
    }

    cq = cq.select(guitar).where(toVarargs(predicates));
    TypedQuery<Guitar> query = entityManager.createQuery(cq);
    return query.getResultList();
}

Predicate[] toVarargs(List<Predicate> predicates) {
    return predicates.toArray(new Predicate[predicates.size()]);
}

Now you might be wondering just what the heck is this Guitar_ business. Guitar_ (and FretboardWood_) are metamodel classes. The metamodel class and its attributes are used in Criteria queries to refer to the managed entity classes and their persistent state and relationships. Metamodel classes are typically generated by annotation processors either at development time or at runtime. A metamodel class is created with a trailing underscore. Hibernate Metamodel Generator is a popular annotation processor. The following is the autogenerated metamodel class for the Guitar @Entity:

// Guitar_.java stub
// ... package declaration and import statements

@Generated(value = "org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor")
@StaticMetamodel(Guitar.class)
public abstract class Guitar_ {

	public static volatile SingularAttribute<Guitar, Integer> serialNumber;
	public static volatile SingularAttribute<Guitar, BigDecimal> price;
	public static volatile SingularAttribute<Guitar, Model> model;
	public static volatile SingularAttribute<Guitar, BodyFinish> finish;
	public static volatile SingularAttribute<Guitar, Store> store;
	public static volatile SingularAttribute<Guitar, FretboardWood> fretboardWood;

	public static final String SERIAL_NUMBER = "serialNumber";
	public static final String PRICE = "price";
	public static final String MODEL = "model";
	public static final String FINISH = "finish";
	public static final String STORE = "store";
	public static final String FRETBOARD_WOOD = "fretboardWood";

}

Thanks to these generated classes, our criteria queries always have the correct attribute names and types. They can easily be updated, should they ever change.

Using Spring Data JPA Specifications

The last approach involves the declaration of specifications. Specification is a functional interface with the following signature:

jakarta.persistence.criteria.Predicate toPredicate(
        jakarta.persistence.criteria.Root<T> root,
        jakarta.persistence.criteria.CriteriaQuery<?> query,
        jakarta.persistence.criteria.CriteriaBuilder criteriaBuilder)

You typically write these as static methods in a Specs class like so:

// GuitarSpecs.java
// ... package declaration and import statements
public class GuitarSpecs {

    public static Specification<Guitar> noMapleFretboards() {
        return (root, query, builder) -> {
            Join<Guitar, FretboardWood> fretboardWood = root.join(Guitar_.FRETBOARD_WOOD);
            return builder.notEqual(fretboardWood.get(FretboardWood_.ID), FretboardWood.MAPLE);
        };
    }

    public static Specification<Guitar> from(Store store) {
        return (root, query, builder) ->
                builder.equal(root.get(Guitar_.STORE), store);
    }

    public static Specification<Guitar> limitPriceTo(BigDecimal value) {
        return (root, query, builder) ->
                builder.lessThanOrEqualTo(root.get(Guitar_.PRICE), value);
    }
}

Finally, we chain these specs with .or() & .and() (as per our requirements) into a single spec, which we then pass to an all-too-familiar findAll method:

// AppService.java stub
List<Guitar> getInventoryUsingSpecs(boolean showAllStores, int salesPersonId) {
    boolean isNewHire = salesPersonId == DAVE;

    Specification<Guitar> spec = GuitarSpecs.noMapleFretboards();

    if (!showAllStores) {
        Store roseville = storeRepository.getReferenceById(Store.ROSEVILLE);
        spec = spec.and(GuitarSpecs.from(roseville));
    }

    if (isNewHire) {
        spec = spec.and(GuitarSpecs.limitPriceTo(NEW_HIRE_PRICE_CAP));
    }

    return guitarRepository.findAll(spec);
}

Conclusion

JPQL queries are a perfectly valid JPA tool and are not going away any time soon (they’re well supported in Spring Data JPA with the @Query annotation). But a key aspect of being a professional is choosing the right tool for the job, and the benefits of using Criteria API/Specifications for complex querying are far too many to be ignored in favor of string mangling. Criteria API represents an incredibly valuable force multiplier that’s available to you the moment JPQL is.

Plain Sequences

This is the most straightforward way to produce primary key values. Sequences generate unique integers and can be incremented by an arbitrary number like 1, 20, -1, etc. Consider the following table:

CREATE TABLE student (
  id INTEGER,
  name VARCHAR(100) NOT NULL,
  CONSTRAINT pk_student PRIMARY KEY (id)
);

We could then create a sequence to generate valid data for our id primary key column:

CREATE SEQUENCE seq_student;
/* Postgres specific syntax (i.e. the nextval function).
Oracle's equivalent would be seq_student.NEXTVAL */
INSERT INTO student (id, name) VALUES (nextval('seq_student'), 'Victoria');
INSERT INTO student (id, name) VALUES (nextval('seq_student'), 'Manuel');

This approach works fine but assumes some sort of nomenclature is in place—you know which sequence belongs to the student table due to its name alone. Another developer might mistakenly use a different sequence, an ad hoc value, or even drop the sequence entirely (no errors will be thrown). Without any corresponding documentation there really is no way to tell at a glance how id values are produced, perhaps they’re managed in a different system altogether.

Attached Sequences

Auto incremental primary key columns are so common that Postgres offers a shorthand. We could redefine the student table like so:

CREATE TABLE student (
  id SERIAL, --shorthand type to create unique identifier columns 
  name VARCHAR(100) NOT NULL,
  CONSTRAINT pk_student PRIMARY KEY (id)
);

/* No need to explicitly define a sequence.
Later INSERT statements can omit the primary key column: */
INSERT INTO student (name) VALUES ('Victoria');
INSERT INTO student (name) VALUES ('Manuel');

--Deleting the table also removes the associated sequence:
DROP TABLE student;

In contrast, Oracle offers no shorthands and requires the declaration of a sequence beforehand, using the NEXTVAL function as the default value for the column:

CREATE SEQUENCE seq_student;
CREATE TABLE student (
  id INTEGER DEFAULT seq_student.NEXTVAL,
  name VARCHAR2(100) NOT NULL,
  CONSTRAINT pk_student PRIMARY KEY (id)
);

INSERT INTO student (name) VALUES ('Victoria');
INSERT INTO student (name) VALUES ('Manuel');

These last two examples make the table student depend on a certain sequence, which can’t be dropped on a whim. The table declaration itself makes it very clear how the primary key values are generated, and thus our intentions more evident.

Of course, other RDBMS vendors have their own unique ways of generating unique values (see what I did there?), such as MySQL’s AUTO_INCREMENT attribute, which also works in H2:

CREATE TABLE student (
  id INT AUTO_INCREMENT,
  name VARCHAR(100) NOT NULL,
  CONSTRAINT pk_student PRIMARY KEY (id)
);

INSERT INTO student (name) VALUES ('Maria');

It’s important to keep in mind that auto generated clauses do not necessarily create the primary key constraint automatically.

Identity Columns

Identity columns are the ultimate way to declare auto generated primary key columns, using good ol’ standard SQL (ISO/IEC 9075) and nothing else. Here’s what the student table could be rewritten as, using the identity clause:

CREATE TABLE student (
  id INTEGER GENERATED BY DEFAULT AS IDENTITY,
  name VARCHAR(100) NOT NULL,
  CONSTRAINT pk_student PRIMARY KEY (id)
);

INSERT INTO student (name) VALUES ('Paige');
SELECT id FROM student WHERE name = 'Paige';
--> 1
INSERT INTO student (id, name) values (1, 'Robert');
--> Constraint violation error

--No dangling sequences either:
DROP TABLE student; --purge (Oracle)

Customized Sequence Properties

Because identity columns have an implicit sequence attached to it, they can be tailored similarly to the CREATE SEQUENCE statement:

CREATE TABLE student (
  id INTEGER GENERATED ALWAYS AS IDENTITY (
    START WITH 25 INCREMENT BY 25 --Override default options
  ),
  name VARCHAR2(100) NOT NULL
);

INSERT INTO student (name) VALUES ('Ben');
INSERT INTO student (name) VALUES ('Wendy');

SELECT id FROM student WHERE name = 'Wendy';
--> 50

ALWAYS or BY DEFAULT?

The identity column clause has two different flavors: identifiers can be generated ALWAYS or BY DEFAULT. The former instructs the database to always generate a value, and will actually throw an error if you do try to insert one yourself:

CREATE TABLE test_error (
  id_col INTEGER GENERATED ALWAYS AS IDENTITY
);

INSERT INTO test_error (id_col) VALUES (1);
--> ORA-32795: cannot insert into a generated always identity column

Ultimately it all comes down to taste. Personally, I find the BY DEFAULT behaviour a bit more forgiving (say you need to change an ID for whatever reason).

ORM Support

Object–relational mapping providers have great support for identity columns out-of-the-box. In fact, it’s the default for primary key properties in Entity Framework Core. Here’s how we could map the student table to a JPA Entity, using GenerationType.IDENTITY:

package org.danielaguilar.samples;

import jakarta.persistence.*;

@Entity
public class Student {

	@Id
	@GeneratedValue(strategy = GenerationType.IDENTITY)
	private int id;
	
	private String name;
	
	// ...
}

Conclusion

Identity columns are a great and universal way to declare primary key columns for our tables. Because it’s part of the SQL standard, this particular syntax works with almost all the major RDBMS vendors, hopefully decreasing the cognitive load necessary when working on multiple systems.

Advancements in container technology have made it unbelievably easy to spin up a development database in mere seconds. Gone are the days of pre-packaged, resource-hogging, inflexible virtual machines; or installing databases locally for a particular project, setting the correct schema permissions, and dealing with platform-specific issues, as you spend the rest of your much productive day praying the hard drive never dies out; or —worse— having no alternative other than to share a single database with your entire development team.

We now have access to hundreds of official, actively maintained Docker images of our favorite databases, from Postgres to SQL Server. They’re all lighting fast and fully extensible, featuring sensible defaults (e.g. correct file system structure, proper user/group permissions), mappable ports, persistent volumes, among other great capabilities.

Containers help speed up the development process by providing consistent, predictable & easily reproducible environments to work with. It’s in this same spirit that today I bring you yet another tool you can add to your belt: Oracle’s Flashback Database.

What is Flashback Database?

Flashback Database is a neat feature of Oracle Database that lets you rewind your database to a defined point in time. Think of it as a ROLLBACK statement, but without the need of a transaction, and working at a much deeper level, as it deals with data files. What this means is that any new rows added to any table (or any new table added), sequences incremented, or modified stored procedures can be sent back in time to a pristine state. It’s flippin’ cool.

What are the use cases?

You may think this is a feature a DBA would me most concerned with, but think again!

I use flashbacks to rollback undesired changes on my local database, introduced by new features I’m working on. This is specially useful when working with a relatively complex (100+ objects) database.

Perhaps I accidentally corrupted a specific row with invalid (i.e. not according to the business logic) data; or I suddenly have to switch branches and don’t wanna be left with a bunch of test data, or modified column datatypes that I can’t ORM’d my classes to; or maybe there’s a painfully elaborate domain logic process I have to perform within the application multiple times to get the correct data to work with.

It’s a game of do and re-do. I can safely and confidently move my way around the database with a big undo button in my hand ready to be pressed at any time I need. This sort of flexibility, I believe, speeds up the development cycle considerably.

Getting Started

As it is the case with most of my articles, this is a tutorial with a hands-on approach. If you have Docker installed, you may follow along with me. I’ll be demonstrating how flashback database works using this sample project, which has all of the configuration and scripts you will need.

I’ll be working with release 19c, but this tutorial also applies to version 12c. There’s a caveat tho: flashback database is only available on Oracle Database Enterprise Edition.

Oracle provides official Dockerfiles that facilitate the installation and configuration of an Oracle Database. Head over to their GitHub repository, and follow the instructions to build a local oracle database image (SingleInstance).

Running the Sample Project

Once you have an Oracle Database image ready (in this case named oracle/database:19.3.0-ee), you can execute the init.sh script. This starts an Oracle Database container, automatically configures flashback database (which is not enabled by default), creates a pluggable database with a test user and a couple of tables, then finally creates a restore point. Here’s what we’ll be working with:

You can connect to the database using the user scott, password tiger. The hostname would be the IP address that has been assigned to your container, which you can find out what it is via docker inspect oracle-db. The port and service name correspond to 1521 and LOCALPDB respectively.

$ docker inspect oracle-db | grep IPAddress
            "SecondaryIPAddresses": null,
            "IPAddress": "172.17.0.2",
                    "IPAddress": "172.17.0.2",

Making Changes

You can query existing restore points with the following statement: SELECT * FROM V$RESTORE_POINT;. If you run the previous command, you’ll find out the BEFORE_FEATURE restore point exists, which means we can safely start doing some changes. The feature.sql script includes the following:

INSERT INTO guitar (brand_id, model) VALUES (2, 'Les Paul');
CREATE TABLE guitar_catalog (
    id NUMBER GENERATED AS IDENTITY,
    guitar_id NUMBER,
    quantity NUMBER,
    CONSTRAINT guitar_catalog_fk
        FOREIGN KEY (guitar_id) REFERENCES guitar (id)
);

We may now drop tables, insert hundreds of new rows, create sequences, you get the idea. Naturally, there’s so much data Oracle can hold about the new state of the database (10GB in this case, but it can be configured), so I wouldn’t recommend abusing this feature too much. Remember, this is a development database after all.

Performing the Flashback

To perform a flashback, we can connect directly to our database via RMAN (Recovery Manager), using OS authentication. Start by executing a shell in the running container:

$ docker exec -it oracle-db bash
$ export ORACLE_SID=ORCLCDB
$ export ORACLE_HOME=/opt/oracle/product/19c/dbhome_1
$ rman target /

At this point, it’s only a matter of closing the pluggable database (PDB), perform the actual flashback, and finally reopening the PDB (with the RESETLOGS option):

ALTER PLUGGABLE DATABASE LOCALPDB CLOSE IMMEDIATE;
FLASHBACK PLUGGABLE DATABASE LOCALPDB TO RESTORE POINT BEFORE_FEATURE;
ALTER PLUGGABLE DATABASE LOCALPDB OPEN RESETLOGS;

And that’s it! The flashback is now complete, and you can login with scott again to check the current state of the database. Everything should be how we initially started.

Conclusion

This isn’t by any means a guide to database flashbacks at all, far from it. This is a demonstration of a useful feature you can apply to your daily software development work. I obviously had to skim over so many details, (such as undoing a flashback using RECOVER), but hopefully you could get a general idea of what this is all about!

If you’d like to learn more, you can visit the official reference, which has a more in-depth explanation of what is going on, plus some other great examples.

The example I’ll be working on will be the classic client-server model, using IPv4. The server will be listening for messages (printing them out as they come) and react accordingly, while the client sends messages and outputs responses from the server. The server runs in a Docker container in its own network. You can find the example here.

The example is written in C. Most modern programming languages provide support for (the now called low-level) sockets, but what better way to learn other than using the original implementation?

The Basics

The original implementation of the TCP/IP stack for Unix-like systems appeared in 4.2BSD, it was later adopted as a POSIX standard. As I mentioned, it was written in C, and introduced the concept of the socket—an endpoint for communication between processes.

There are many domains of sockets (also known as families), but the 2 most popular you’ll encounter are UNIX domains and Internet protocols. While I’ll be discussing the Internet protocols family of sockets in this article, UNIX domain sockets are not that different. They’re used for efficient local communication (on the same machine). The Docker daemon, for instance, uses this type of socket.

Sockets also have types. I’ll be working with stream-type sockets (SOCK_STREAM), corresponding to a TCP socket.

The Telephone Analogy

A well-known way of explaining sockets is using the telephone analogy. In order to receive a call, you must first install a phone, have a phone number, hear it ring, and finally take the call. Generally, you do not need to know the caller’s number.

To make a phone call, the process is somewhat the same in that you still need a phone, but instead of passively listen for incoming calls, you dial a number instead, and wait for someone to answer.

Sockets work like telephones. On the server side, you create a socket(), bind() a local address to it, listen() for connections, and finally accept() one. On the client side, you create a socket() and connect() to an address.

Working with Addresses

While we can work with dot-decimal notation IP addresses (e.g. 192.168.1.110), ultimately they have to be converted to binary form (network byte order). Both bind() and connect() have a sockaddr argument, a struct that holds data about an address. You will see something like this in the client and server code:

struct sockaddr_in address;
struct in_addr ip;

inet_aton("192.168.1.110", &ip);
address.sin_addr = ip;
address.sin_port = htons(8080);
address.sin_family = AF_INET;

We can use the inet_aton() and htons() utilities to convert such values. Finally, we need to specify what kind of address we’re talking about. The address family for IPv4 Internet protocols is AF_INET.

Server Code

This server will implement a simple protocol consisting of two commands: HELLO and BYE. If the client sends a HELLO message, the server then replies with “HI”, while a BYE message instructs the server to shut down. All messages received must be sent to stdout.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// server.c stub
char buffer[12];
int data_socket;
int conn_socket = socket(AF_INET, SOCK_STREAM, 0);
bind(conn_socket, (const struct sockaddr *) &address,
     sizeof(struct sockaddr_in));
listen(conn_socket, 5);

for (;;) {
	data_socket = accept(conn_socket, NULL, NULL);
	read(data_socket, buffer, 12);
	buffer[11] = '\0';
	puts(buffer);

	if (strcmp(buffer, "HELLO") == 0) {
		strcpy(buffer, "HI\n");
		write(data_socket, buffer, 12);
	}

	close(data_socket);
	if (strcmp(buffer, "BYE") == 0) {
		break;
	}
}

close(conn_socket);

Assuming address has been correctly assigned, line 4 creates an IPv4 listening socket. I say listening because once we accept a connection, a new socket is created, so as to support multiple concurrent connections. Line 5 binds the previous socket to an address, while line 7 configures the socket to listen for up to 5 pending connections in a queue.

The main loop consists of accepting a new connection, reading 12 bytes from the socket, implement a HELLO protocol, and then close the data socket. If a BYE command is received, the listening socket is closed too.

If you’ve worked with file I/O in C before, you’ll notice the process is essentially the same. data_socket is a file descriptor and so the standard read() and write() operations work as they would with any other file.

Client Code

// client.c stub
char response[12];

int fd = socket(AF_INET, SOCK_STREAM, 0);
connect(fd, (const struct sockaddr *) &address,
        sizeof(struct sockaddr_in));

write(fd, "HELLO", 5);
read(fd, response, 12);
printf(response);
close(fd);

The client can be significantly smaller as it only has one task. Again, here I’m assuming address its been properly assigned. In this particular instance I am expected to received a “HI” response from the server.

Conclusion

I hope this explanation was clear. I tried to keep the code concise by removing includes, error handling noise and other off topic details, but I encourage you to download the full example and try it yourself.

A little bit of background before we get started. I was assigned a new project at work (Java web application running in a WAS), with one of the requirements being the ability to authenticate existing users in a directory service, specifically an LDAP server. While doing my research at the time, I found myself either digging through old forum posts, inspecting inherited and unmaintained code, or reading a whole spec in search for a particular detail. So I thought I’d write an article about it, with completeness being the main goal.

I’ll be working with OpenJDK 8, Spring Boot 2.3.0, Spring Security 5.3.2 and the Jetty Maven plugin, which spins up a servlet container ideal for development. A working sample of the following code can be found here.

Form Based Authentication

The first step is setting up the security configuration over at our deployment descriptor (i.e. web.xml). FORM based login just so happens to be our ideal authentication mechanism, users are presented with a login page where they enter their credentials. Under the hood, the action of the form is j_security_check, where we’ll be POSTing a j_username and j_password. The server then returns a cookie JSESSIONID used to validate any other requests that require authentication (and authorization, or access on the basis of roles). Here’s how it’s done:

<!-- web.xml excerpt -->
<login-config>
  <auth-method>FORM</auth-method>
  <realm-name>realm</realm-name>
  <form-login-config>
    <form-login-page>/login</form-login-page>
    <form-error-page>/login?error</form-error-page>
  </form-login-config>
</login-config>

The realm-name indicates the LDAP realm name. Users are stored there, and we really don’t care about the details. The realm name should be provided by the application server administrators.

An additional form-login-config is required, specifying the login and error page URLs, where the user will be automatically redirected when unauthenticated, or when the credentials don’t match, respectively.

Over at our login page, we would need an HTML form. The servlet spec offers an example of how that might look like:

<form method="POST" action="j_security_check">
  <input type="text" name="j_username">
  <input type="password" name="j_password" autocomplete="off">
</form>

Defining the Roles

One last piece of configuration we can specify in the deployment descriptor is the security-role element. We use it to define—well—security roles (with an optional description for each one):

<!-- web.xml excerpt -->
<security-role>
  <description>Application Administrator</description>
  <role-name>ROLE_ADMIN</role-name>
</security-role>

Do notice I added the ROLE_ prefix to the role name. If you’ve ever worked with Spring Security before, you know that’s a naming convention.

Spring Security Configuration

That’s it for the web.xml, Spring Security takes care of the rest. For this step I prefer the Java configuration over XML. It consists of overriding the configure method:

protected void configure(HttpSecurity http) throws Exception {
    http.authorizeRequests(requests -> requests
        .antMatchers("/admin/**").hasRole("ADMIN")
        .anyRequest().permitAll()
    );
    http.jee(jee -> jee.mappableAuthorities("ROLE_ADMIN"));
}

Here I’m securing the /admin/** route so only the ADMIN role can access it (the ROLE_ prefix is added automatically), while the rest is allowed to anyone. immediately after that is where we tell Spring Security to integrate with the Java EE container authentication (the docs refer to this scenario as pre-authentication), importing the previously defined roles via the mappableAuthorities method.

Spring Security is highly customizable, the documentation has all the classes that can be extended to modify the default behaviour, such as loading certain user information from a database (email address, full name, etc.) using a custom UserDetailsService.

The Results

Let’s do a couple of test requests to verify our authentication system is working. Jetty allows to configure a security realm in a properties file, which is handy for local development, you can learn more here. I have the following controller methods:

@GetMapping("/hello")
public String hello() {
    return "Hello";
}

@GetMapping("/admin/hello")
public String helloAdmin() {
    return "Hello, Admin";
}

$ curl localhost:8080/app/hello/
Hello

$ curl localhost:8080/app/admin/hello/ | python -m json.tool
{
    "timestamp": "2020-05-30T06:33:41.250+00:00",
    "status": 403,
    "error": "Forbidden",
    "message": "",
    "path": "/app/admin/hello"
}

$ curl -c - -d "j_username=admin&j_password=pass" \
localhost:8080/app/j_security_check/
# Output shortened for brevity
JSESSIONID node0gl4hg0zrigmg3v4ywapwo959.node0

$ curl -b "JSESSIONID=node0gl4hg0zrigmg3v4ywapwo959.node0" \
localhost:8080/app/admin/hello/
Hello, Admin
# Subsequent requests may 403'd as the cookie value has changed

Spring Security has its own JSON-formatted error messages, which are convenient if you’re working with JavaScript.

Conclusion

You can see just how little configuration Spring Security actually requires, but how much functionality you’re getting back! Plus, container authentication delegates the security to the application server, making it relatively easier to implement.

Setting the value of a <select> element it’s quite easy:

let selectEl = document.querySelector('select#favorite-food');
selectEl.value = 'pizza';

Yet there’s a particular UX detail that we might have overlooked: what if the value is not an existing option?

The Problem

Consider an instance where we have to set the value of a <select> programmatically. In my case, I had to preserve the user’s previously selected option right after updating the drop-down list with a new set of options.

The problem is when the option is not listed (maybe it’s no longer available):

The <select> is obviously left at an invalid state (its value is ""), which means existing validation mechanisms still work as intended. However, we’re left with an empty select, there’s no placeholder text to guide the user.

The Solution

Fortunately the HTMLSelectElement interface has a selectedIndex property with a value of -1 when no option is selected, which is exactly our case. We can leverage this property to perform a quick validation:

Funny headlines aside, this post is gonna be a small rant as to why I find cherry-picking particularly annoying when working with Gitflow.

Gitflow is a good idea! I’m just not a huge fan of its horrifying humorous results in the log, as opposed to a much linear history:

Now, if you couple that with the bad habit of cherry-picking hotfix or bug fix commits, things start to get a lot messier. So why exactly is cherry-pick a bad idea? Because it further obfuscates your commit history.

Consider the following example: I just committed a change on hotfix/issue658, and I need to apply it to both master and dev:

Suppose I cherry-pick the resulting commit to both of those branches:

It might look OK at first glance, but watch what happens when I try to update master to a new version:

We got duplicated commits! Git treats them as separate units because they each have different IDs (that’s what cherry-pick does, it creates a new commit each time), thus, my hotfix branch it’s not merged into any of my main branches. This commit history does not accurately reflect my original intent.

Contrast that to what a correct merge strategy of the previous example would look like:

I regard maintaining a reasonably sound commit history as important as writing good code, given how git can also be used as an auditing tool, believe me, it can save you a lot of trouble in the long run. Do yourself a favor an try to avoid cherry-picking as much as you can!

There are a couple different ways of doing it, but so far this is my preferred one. It involves 3 steps:

1. Download the binaries directly from Oracle’s website
2. Place the binaries in the appropriate directory
3. Set JAVA_HOME and PATH accordingly

Ok, let’s begin.

Step 1: Downloading the Binaries

Head over to Oracle’s website and download the JDK. Remember to verify the checksum!

Step 2: Choosing the Appropriate Directory

What directory is appropriate for a system-wide installation of Java? According to FHS opt/ fits just well. Go ahead and extract the contents of the downloaded archive there.

Step 3: Setting the Environment Variables

Where do we declare JAVA_HOME and modify our PATH? It can’t be in ~/.bashrc or ~/.profile as it’s single user only and limited to a CLI shell. What about a graphical shell?

I’ve found that the best location to set up environment variables is in /etc/profile.d. According to the Ubuntu Wiki:

Files with the .sh extension in the /etc/profile.d directory get executed whenever a bash login shell is entered (e.g. when logging in from the console or over ssh), as well as by the DisplayManager when the desktop session loads.

Which means the variables will be set in both CLI shells and graphical environments, which is exactly what we want!

Here’s what an /etc/profile.d/java.sh example might look like:

export JAVA_HOME=/opt/jdk1.8.0_161
PATH=$JAVA_HOME/bin:$PATH

That’s it! Log out and back in to apply the changes. As usual, run java -version to test if Java was installed correctly:

$ java -version
java version "1.8.0_161"
Java(TM) SE Runtime Environment (build 1.8.0_161-b12)
Java HotSpot(TM) 64-Bit Server VM (build 25.161-b12, mixed mode)

There you go, happy programming!

Most people keep them in sync via a git repository, usually GitHub, which is great because it encourages sharing. I like to look through those repositories to seek inspiration (I’m also just curious).

I used to keep them in sync using syncthing, but my current setup was limited to LAN only. I needed something that could work over the internet.

I must admit I was a bit skeptic about using a git repository because it meant creating a script to symlink the files, figuring out a way to handle different environments like macOS and Ubuntu, and manually transfer SSH keys.

But then I discovered YADM: Yet Another Dotfiles Manager, and I was blown away. It featured exactly everything I needed in a dotfiles manager:

• Git under the hood
• No symlinking required, as your $HOME is the working directory
• File encryption (via GnuPG)
• Alternate files based on the OS

With YADM, you only add the files you need synced, and because it’s a glorified git wrapper, all the git commands stay the same.

Perhaps my favorite feature is encryption, and it’s super easy to use. Simply create a ~/.yadm/encrypt file, and write some glob patterns matching the files you want encrypted so they’re not stored as plain text. For instance:

.config/secrets
.ssh/*
!.ssh/authorized_keys
!.ssh/known_hosts*

Then, encrypt the files with: yadm encrypt. This will create a bundle called ~/.yadm/files.gpg, which you can now add to the repo. If you’d like to decrypt the files, yadm decrypt does the job.

I highly recommend this tool, I think it’s an elegant way to handle dotfiles.

These two provide a somewhat similar functionality but are actually quite different fundamentally. According to the Dockerfile reference, CMD’s entire purpose is to provide defaults for an executing container, while ENTRYPOINT’s is being concerned with the configuration of said executing container.

That’s their main purpose. However, depending on the combination of this two instructions, we can achieve different use cases.

CMD

Let’s take a look at Debian Stretch Slim’s Dockerfile:

FROM scratch
ADD rootfs.tar.xz /
CMD ["bash"]

Notice how there’s no ENTRYPOINT. When only CMD is present, the default behaviour will be to execute whatever is specified by CMD, bash in this case.

So, when I docker run debian:stretch-slim, the container will run bash and exit.

Wouldn’t ENTRYPOINT achieve the same thing? Why do we need CMD for then? Well, CMD has a special property, something I like to call soft exec, which is basically the ability to override the command. Take a look:

$ docker run debian:stretch-slim echo Hello!
Hello!

The container executed echo Hello! instead of the default command.

ENTRYPOINT

Let’s contrast the previous behaviour with an ENTRYPOINT instruction. Using the following Dockerfile:

FROM debian:stretch-slim
ENTRYPOINT ["echo" "Hello,"]

I’m gonna build a entrypoint-test image and run it:

$ docker run entrypoint-test
Hello,

Okay, so far things look samey. But watch this!

$ docker run entrypoint-test World!
Hello, World!

I couldn’t override the command this time! Instead, the container used it as echo’s input. This is what I call the hard exec: ENTRYPOINT will always be executed, regardless.

ENTRYPOINT + CMD

As I mentioned, CMD provides default arguments to ENTRYPOINT. Consider the following Dockerfile:

FROM debian:stretch-slim
CMD ["World!"]
ENTRYPOINT ["echo", "Hello,"]

Having built it as entrypoint-cmd-test, let’s run it:

$ docker run entrypoint-cmd-test
Hello, World!

CMD provided the default World! argument to echo. What if we pass an argument of our own?

$ docker run entrypoint-cmd-test Daniel!
Hello, Daniel!

We have successfully overridden the default parameters!

Conclusion

Both CMD & ENTRYPOINT bring their own stuff to the table, but at the end of the day, like most things, it’s up to you to decide which use case fits your needs! I hope this has helped clear up the confusion!