Gediminas Rimša

On complexity

Tue, 08 Jan 2019 08:00:00 +0000

“The biggest problem in the development and maintenance of large-scale software systems is complexity — large systems are hard to understand.” — Ben Moseley and Peter Marks

The ceiling of complexity

In the preface of the Domain-Driven Design book, Eric Evans mentions the ceiling of complexity in passing.

We can think about it as a natural limit of how complex a system can become before becoming intellectually unmanageable.

As we approach this limit, the system is more and more difficult to develop and maintain, causing us to expend huge resources or gamble on our changes not breaking anything.

Essence and accident

A useful mental model for thinking about complexity is dividing it into two kinds: essential and accidental.

Essential complexity is inherent in the problem being solved. In other words, it is the heart of software, a reflection of user expectations and intricacies of the real world, that we would still have to deal with even if we had complete knowledge, perfect tools and infrastructure.

Accidental complexity is then all other complexity.

Expressing some idea in a programming language adds some accidental complexity. So does using a library or framework. So does every line of code that can be simplified or removed, every workaround, every purely technical feature.

Complexity breeds complexity

What is worse, complexity breeds complexity.

Not being able to clearly understand the system makes us duplicate code, come up with poor designs and abstractions, or place them in suboptimal locations. Using outdated technology adds otherwise unnecessary constraints, limiting our options and forcing to use workarounds.

All of the above introduce further accidental complexity, compounding our difficulties.

The goal

It seems natural that our goal should be to eliminate as much accidental complexity as possible.

This way we can both make the system easier to understand and make more room for the essential.

However, why is then dealing with accidental rather than essential so much of what we do?

Simplicity is not easy

“I have made this letter longer than usual, only because I have not had the time to make it shorter.” — Blaise Pascal

The first solution is rarely the most simple, particularly if there is existing complexity, time pressure or we are new to the problem domain.

There is one important distinction - simple is not the same as easy.

Simple is the opposite of complex. Both of these words express complexity, which is objective and describes to what extent the parts (e.g. concepts and responsibilities) are intertwined or connected.
Easy is the opposite of difficult. Both of these words express effort, which is subjective, meaning something difficult for me might be easy for you.

Finding simple solutions and concise ways to express them might be difficult. It might require significant effort to reflect and iterate on the solution in order to untangle the complexity, identify and separate the concerns and express them clearly using fitting technology.

On the other hand, an easy solution that just works, might carry a lot of unnecessary complexity with it. We rarely consider that a familiar, available, succinctly described solution might make us end up worse than before.

So where does this leave us?

There is no easy way out of this, no silver bullet.

But we can be mindful of accidental complexity in our systems.

Once we learn to spot it, we can rally our peers to practice simplicity with us — both by trying to come up with better designs and writing cleaner, more expressive code.

Improving our collective skills makes simplicity easier to achieve, ultimately making it easier for us to cope with our systems.

Exploring this further

No silver bullet: Essence and accidents of software engineering - essay by Fred Brooks, 1986.
Out of the tar pit - a paper by Ben Moseley and Peter Marks, 2006.
Simple made easy - a talk by Rich Hickey, 2011.
Domain-driven design: Tackling complexity in the heart of software - a book by Eric Evans, 2003.

A hack to expose RESTful services via SOAP

Wed, 08 Feb 2017 07:12:47 +0000

Working in a corporation you sometimes face constraints that would seem strange and artificial to someone working in a small company. However, overcoming these constraints is both challenging and fun.

One of such cases is described below.

The challenge

We were building a new REST API. A good part of it was already done when we discovered a limitation in provided infrastructure: our Enterprise Service Bus (ESB) could only expose SOAP services.

REST support was promised to come soon, but we had to expose our functionality to the clients before that.

The easy solution would have been to build a throwaway SOAP API and ask our clients to upgrade to REST later. However, adding an unwelcome SOAP API did not feel right.

The solution

What felt right was solving this challenge in a generic way that would require almost no extra work on both service provider and service consumer sides.

The idea was to use SOAP messages for transferring request and response data, yet make them invisible to both service providers and consumers.

If direct access to a REST API looked like this:

Then this is the REST via SOAP solution:

How does it work?

Let’s say we have a REST API that allows its clients to create Greeting instances.

The client then sends a POST request with { "content" : "Hello!" } body to a remote /api/greetings endpoint.
REST Interceptor captures this outgoing HTTP request, transforms it into a SOAP request seen below and sends it to a remote SOAP Proxy for REST API (e.g. /soap-api).

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://g.rimsa.lt/rest-via-soap/" >
  <soapenv:Header />
  <soapenv:Body>
    <request method="POST" path="/api/greetings">
      { "content" : "Hello!" }
    </request>
  </soapenv:Body>
</soapenv:Envelope>

SOAP Proxy parses the incoming SOAP message, rebuilds the REST request and forwards it to the REST API.
REST API responds with HTTP status 200 and response body { "id" : 123 }.
SOAP Proxy wraps this response into a SOAP message:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://g.rimsa.lt/rest-via-soap/">
  <SOAP-ENV:Header/>
  <SOAP-ENV:Body>
    <response status="200">
      { "id" : 123 }
    </response>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

REST Interceptor unwraps it and the client receives a regular HTTP response with status 200 and { "id" : 123 } as the body, same as via a direct call to REST API.

The implementation

When this REST via SOAP idea was born, I set out to write a generic Servlet Filter to act as the SOAP Proxy for REST API.

It turned out well and you can now find the code in REST via SOAP project on GitHub.

However, as we ended up not needing it in the project we were doing at the time, it was not tested in a real-world setting and the REST Interceptor part remains to be implemented.

Hibernate: Multi-table update/delete handling strategies

Sat, 24 Dec 2016 15:20:47 +0000

If you ever used a hierarchical entity model with Hibernate, you might have noticed similar DDL statements being generated on application startup:

declare global temporary table session.HT_PARENT_1 (ID varchar(36) not null) not logged
declare global temporary table session.HT_CHILD_1 (ID varchar(36) not null) not logged
declare global temporary table session.HT_CHILD_2 (ID varchar(36) not null) not logged
...

What’s going on here? Let’s take a closer look.

Entity inheritance mapping

Consider the following entity hierarchy:

@Entity
@Table(name = "EMPLOYEE")
@Inheritance(strategy = InheritanceType.JOINED)
public abstract class Employee {
    @Id
    @Column(name = "ID", length = 36)
    protected UUID employeeId;
    // ...
}

@Entity
@Table(name = "EMPLOYEE_FULL_TIME")
public class FullTimeEmployee extends Employee {
    protected int salary;
    // ...
}

@Entity
@Table(name = "EMPLOYEE_PART_TIME")
public class PartTimeEmployee extends Employee {
    protected float hourlyWage;
    // ...
}

Because InheritanceType.JOINED is used, the entity hierarchy is mapped to the following database schema:

create table EMPLOYEE (ID varchar(36) not null, primary key (ID))
create table EMPLOYEE_FULL_TIME (ID varchar(36) not null, salary integer, primary key (ID))
create table EMPLOYEE_PART_TIME (ID varchar(36) not null, hourlyWage float, primary key (ID))
alter table EMPLOYEE_FULL_TIME add constraint FK_emp_id_ft foreign key (ID) references EMPLOYEE
alter table EMPLOYEE_PART_TIME add constraint FK_emp_id_pt foreign key (ID) references EMPLOYEE

A fairly straightforward mapping. But what happens once a bulk update or delete operation is executed?

Bulk updates and deletes

There are some challenges explained well in this Multi-table Bulk Operations post. The essence is that, for example, deleting a multi-table entity (like FullTimeEmployee) means:

Finding IDs for rows that need to be deleted and storing them somewhere
Deleting rows from multiple tables (in proper order!) by previously stored ID values

As you see, the IDs have to be stored somewhere. Let’s consider two approaches.

In-memory approach

An obvious approach is to keep the IDs around in application’s memory. The following SQL statements would have to be generated then:

select ID from EMPLOYEE_FULL_TIME where SALARY > 1000000;
delete from EMPLOYEE_FULL_TIME where ID IN ( [list of IDs] );
delete from EMPLOYEE where ID IN ( [list of IDs] );

However, the simplicity of this approach carries a performance penalty (transferring IDs over network, mapping them to/from Java objects, etc.).

Table-based approach

A more performant approach is to store the selected ID values on the database server itself. The generated SQL would be similar to this:

insert into ID_TABLE (
   select ID from EMPLOYEE_FULL_TIME where SALARY > 1000000
);
delete from EMPLOYEE_FULL_TIME where (ID) IN (select ID from ID_TABLE);
delete from EMPLOYEE where (ID) IN (select ID from ID_TABLE);

Note that as different entities could have different ID definitions, an equivalent of ID_TABLE needs to exist for each entity that is a part of any entity hierarchy. That could be a significant number of tables.

Let’s take a look at what Hibernate can do for us here.

Hibernate’s `MultiTableBulkIdStrategy` implementations

Hibernate has defined a generalized interface for handling multi-table bulk HQL operations called MultiTableBulkIdStrategy. Currently (Hibernate 5.2.6) ships with three implementations of this interface, all of them table-based:

GlobalTemporaryTableBulkIdStrategy - based on ANSI SQL’s definition of a “global temporary table”.
LocalTemporaryTableBulkIdStrategy - based on ANSI SQL’s definition of a “local temporary table” (local to each database session).
PersistentTableBulkIdStrategy - based on regular tables with an extra hib_sess_id column to segment rows from different Hibernate sessions.

The strategy to use is determined by hibernate.hql.bulk_id_strategy property, with Dialect#getDefaultMultiTableBulkIdStrategy used as a fallback.

Table-creation at startup

Both GlobalTemporaryTableBulkIdStrategy and PersistentTableBulkIdStrategy try to create the ID tables at startup and that is where the DDL statements mentioned in the beginning of the post come from.

It’s worth noting that any of these DDL statements that fail are just logged at DEBUG level and quietly ignored. That is, until a bulk update or delete operation is executed, at which point it would fail if the required table does not exist.

The point here is that failing to create the ID tables does not prevent application from starting and working, as long as:

No bulk update or delete operations are used, or
The ID tables are pre-created by other means (e.g. by a DBA having required authorizations).

There are also alternative implementations that might be useful in some circumstances.

Alternative implementations

Alternative strategy implementations discussed below might help you when:

DDL statements cannot be executed by your application
Bulk update/delete operations are actually used
Pre-creating ID tables is either difficult or impossible

When pre-creating ID tables is difficult

Assume there’s a way for you to get the ID tables created, either by doing some manual work or by involving other parties who can do it for you.

If your entity model is stable, you might just bite the bullet and do the work to create the ID tables once and for all. Afterwards you could forget about it and stick with using one of Hibernate’s standard strategies. However, if your model is constantly evolving, you might want to alleviate the pain of dealing with extra ID tables.

For this purpose I created a Single Global Temporary Table Bulk Id Strategy. It’s a slightly modified GlobalTemporaryTableBulkIdStrategy that uses a single shared global temporary table to store IDs for all entities, segmenting the rows by entity name held in an extra column.

The benefit of it is that you retain the advantages of the table-based approach, while also minimizing the overhead to create and manage tables for each entity.

The strategy was developed for a project where the same ID type and column name was used across all entities. Naturally, the same type and name was also used for the shared ID table too.

It should either work out-of-the-box or be easily extendable to support other cases (different types and/or names of single-column IDs, maybe even multi-column IDs), but you should verify it works for your circumstances.

When pre-creating ID tables is impossible

If there’s no way to create the ID tables at all, then any of the built-in table-based strategies are not an option. In this case you’d have to turn to the in-memory approach, which, to my surprise, is not implemented in Hibernate.

Luckily, there’s CTE Bulk Id Strategy.

The project includes tests on PostgreSQL, although when I tried it on DB2 and H2 databases a while ago, it did not work. Hence, minor alterations might once again be needed.

In place of a summary

The need for bulk update or delete operations (based on non-PK columns) on entity hierarchies is not a very common one, and Hibernate’s ID table-based strategies cover this need well in most environments.

However, when creation of ID tables is either problematic or not possible, one of existing alternative MultiTableBulkIdStrategy implementations could be used.

Or, as they say, you can always roll your own.

2017-07-18 Update

Hibernate 5.2.8 added a number of new Bulk-id strategies when you can’t use temporary tables.

These new strategies have only slight differences and a good starting point is to go with InlineIdsOrClauseBulkIdStrategy, which is supported by all major relational database systems.