1. Wie können wir Daten/Updates sicher bzw. transaktional zwischen den Services übergeben?
2. Wie schaffen wir es, dass die unterschiedlichen Services nicht auseinanderlaufen?

Das Outbound-Pattern kann uns hierbei helfen, dieses Problem zu lösen. Es handelt sich um eine bewährte Methode, um Datenkonsistenz und Transaktionen in verteilten Systemen zu gewährleisten.

Ereignisgesteuerte (Event Driven) Architekturen dienen keinem Selbstzweck. Häufig soll sie Problemen vorbeugen und uns helfen eine stabile Service Architektur zu entwickeln. Abseits vom „Happy Case“, was kann den wie und wo schief gehen; wie kann uns diese Architektur helfen?

Wir schauen uns drei typische Lösungsmethoden an:

1. Event Bus
2. Command Bus
3. Data Bus

• Transaktionen
• ACID
• Isolationslevel
• Locks

const ORDER_STATUS = {
  OPEN: 'Offen',
  ORDERED: 'Bestellt',
  CANCELED: 'Storniert'
} as const;

type OrderStatus = keyof typeof ORDER_STATUS;

function methodWithEnum(status: OrderStatus) {
    console.info(`${ORDER_STATUS[status]}: ${status}`);
}

methodWithEnum("OPEN");

In this way it is much easier to provide an enum including a potential mapping to a different value e.g. a display value.

This solution is usually considered being better, as long as enums aren’t supported by JavaScript natively.

Links

• https://www.typescriptlang.org/docs/handbook/enums.html
• https://www.typescriptlang.org/docs/handbook/enums.html#objects-vs-enums

Damit wird sichergestellt das dieser eine klare API und Funktion hat und der Nutzer einer Methode nicht überrascht wird, zB indem es zu einem unerwarteten Seiteneffekt führt. Beispiele:

• „readPersonById“ ändern zudem auch den Status in der DB, weil es den Zugriff protokolliert
• „formatDate“ vom DateFormatter führt zu einem Fehler, weil statisch auf eine Lokalisierungsdatei zugegriffen wird, die erst geladen werden muss, welche sich aber in einem anderen Modul befindet
• „readFile“ löscht auch die Datei nach dem einlesen

Sollte lesbar sein

Variablen und Methoden drücken das aus, für was sie stehen z.B.

• „Magic Numbers“ wurden als Konstanten definiert und sprechend benannt
• Komplizierte IF Prüfungen wurden als eigene benannte Funktionen extrahiert

dadurch sollte sich eine Art lesbarer Code ergeben.

Kommentare sollten weitgehend nicht notwendig sein

Durch die Verwendung von sprechenden Methoden- und Variablennamen sind weitere Kommentare nicht notwendig. Wenn überhaupt dann auf Klassen bzw. Public-Methoden ebene ein Verweis auf JIRA oder Confluence stehen, bzw. die Verantwortung eines Services abgegrenzt werden.

Code einer Methode sollte der Erwartung entsprechen

Ein Entwickler sollte beim lesen der Implementierung einer Methode möglichst nicht überrascht werden. Da er aufgrund des Methodennamen bereits rückschließen konnte wie die Methode aufgebaut ist, bzw. was diese macht.

Der Code sollte einfach zu verstehen sein

Jeder im Team sollte den Code schnell erfassen und ändern können, z.B. nach einem Jahr wenn man selbst die fachlichen Anforderungen weitergehen vergessen hat, warum der Code so ist.

Darf keine zirkulären Abhängigkeiten haben

Jedes Modul modifiziert nur seinen eigenen Status

Problem

Working with dates and a DB usually tends to create issues:

• Which type to use?
• Which type to save in the DB?
• How to handle time zones?
• How to avoid moving times?
• How to show the time in the correct time zone of the user?

Scenario

Our test entity

@Entity @Data
public class Person {
  @Id
  private Long id;
    
  private long longDate;
    
  private Instant instantDate;
    
  private LocalDateTime localDateTime;
    
  private OffsetDateTime offsetDateTime;
    
  @Column(columnDefinition = "timestamptz") // we use here postgresql
  private OffsetDateTime offsetDateTimeZone;
}

Given

• We use the entity above
• We use a PostgreSQL DB
• Service instance 1 accesses the DB using the time zone GMZ / UTC
• Service instance 2 accesses the DB using the time zone GMZ + 1
• We have one or more users with direct DB access from their local computer using the time zone Europa/Berlin
• We have currently winter time as it is october

When

• Service instance 1 write a record into the DB

// Instance 1: GMT WRITE
Person(
  longDate           = 1507751058820, 
  instantDate        = 2017-10-11T19:44:18.820418Z, 
  localDateTime      = 2017-10-11T19:44:18.969400, 
  offsetDateTime     = 2017-10-11T19:44:18.969438Z, 
  offsetDateTimeZone = 2017-10-11T19:44:18.969455Z
)

Then

• Service Instance 2 reads the data

-- Instance 2: GMT+01:00 READ
Person(
  longDate           = 1507751058820, // correct
  instantDate        = 2017-10-11T18:44:18.820418Z, // wrong by one hour
  localDateTime      = 2017-10-11T19:44:18.969400,  // wrong by one hour as local time zone is +1
  offsetDateTime     = 2017-10-11T19:44:18.969438+01:00, // wrong by one hour too late
  offsetDateTimeZone = 2017-10-11T20:44:18.969455+01:00  // correct
)

• A user looks into the DB

Only the timestampz, number and instant column value looks okay. Storing an offset date into a type which doesn’t support the time zone leads here to an error.

Change the JDBC session to UTC

If the JDBC session is adjusted to use UTC instead of the JVM time zone using e.g. spring.jpa.properties.hibernate.jdbc.time_zone=UTC we end up with the following result:

// Instance 1: GMT WRITE
Person(
  longDate           = 1507751058820, 
  instantDate        = 2017-10-11T19:44:18.820418Z, 
  localDateTime      = 2017-10-11T19:44:18.969400, 
  offsetDateTime     = 2017-10-11T19:44:18.969438Z, 
  offsetDateTimeZone = 2017-10-11T19:44:18.969455Z
)
-- Instance 2: GMT+01:00 READ
Person(
  longDate           = 1507751058820, // correct
  instantDate        = 2017-10-11T19:44:18.820418Z, // now correct
  localDateTime      = 2017-10-11T20:44:18.969400,  // now also correct
  offsetDateTime     = 2017-10-11T20:44:18.969438+01:00, // now also correct
  offsetDateTimeZone = 2017-10-11T20:44:18.969455+01:00  // now also correct
)

Now all dates are okay, if all our instances really work with the same JDBC session time zone.

Avoid any time Zones in the business logic

Mathematically the time zone isn’t relevant assuming any date in the backend is saved and transferred as UTC date time with now time zone at all.

Save the date time as UTC long, which is anyway the simplest method to compare dates to each other. (Means as milliseconds, between the current time and midnight, January 1, 1970 UTC.)

class Pojo {
  String foo;
  long dateTimeInMs = System.currentTimeMillis();
  long dateTimeInS = Instant.now().getEpochSecond();
}

Even in the DB using a long / NUMBER has several advantages

• Any direct usage of the DB itself is hindered
• Date Time conversion by the JDBC driver is avoided
• A time zone cannot be introduced or assumed
• Clear also in external APIs using the Service
• The precision can be selected based on the domain, in most use cases seconds is enough

Instant in Java 8 or later

A valid alternative solution is to use Java Instant, which is in the end a wrapped UTC long and provides some further methods. It can be saved either as NUMBER or TIMESTAMP in the DB. But as soon as a real date type is used we have also to provide a time zone information in our JDBC URL e.g.:

• e.g. using serverTimezone=UTC
• or spring.jpa.properties.hibernate.jdbc.time_zone=UTC

OffsetDateTime

Many projects have chosen an offset date time type to avoid any issues with the time zone. The problem is, that it usually doesn’t address the issue if for some reason the time zone of your system changes.

Running save and load in different Time zones

Avoid Local Date Time

Local date time tends to surprise the people each time, even if it states, that the e.g. LocalDate represents a date without a time zone, same applies to LocalDateTime, it uses behind the scenes the system time zone:

    public static LocalDate now() {
        return now(Clock.systemDefaultZone());
    }

    public static LocalDateTime now() {
        return now(Clock.systemDefaultZone());
    }

Which leads to the problem, that we have a time which was build using a time zone which is lost as soon as we have only the object. The value depends on the OS time zone which leads to interesting problems in a hosted server environment. Imagine e.g. that one node of the cluster has a different time zone because of some configuration issue in the infrastructure.

Having just the following simple test let us review the results, take in mind that my local time zone would be GMT+2 but currently we have wintertime, GMT+1.

    @ParameterizedTest
    @ValueSource(strings = {"", "GMT+1", "GMT+6"})
    void test(String timeZone) {
        if (timeZone.length() != 0) {
            TimeZone.setDefault(TimeZone.getTimeZone(timeZone));
        }
        System.out.println(java.util.TimeZone.getDefault());
        System.out.println("Instant:        " + Instant.now());
        System.out.println("LocalDateTime:  " + LocalDateTime.now());
        System.out.println("OffsetDateTime: " + OffsetDateTime.now());
    }

Already this very simple example generates here with LocalDateTime three different results. Even if the offset looks correct.

ZoneInfo[id="Europe/Berlin",offset=3600000,dstSavings=3600000,useDaylight=true,transitions=143,lastRule=java.util.SimpleTimeZone[id=Europe/Berlin,offset=3600000,dstSavings=3600000,useDaylight=true,startYear=0,startMode=2,startMonth=2,startDay=-1,startDayOfWeek=1,startTime=3600000,startTimeMode=2,endMode=2,endMonth=9,endDay=-1,endDayOfWeek=1,endTime=3600000,endTimeMode=2]]
Instant:        2017-10-10T09:54:45.370020Z
LocalDateTime:  2017-10-10T11:54:45.379338
OffsetDateTime: 2017-10-10T11:54:45.380626+02:00
ZoneInfo[id="GMT+01:00",offset=3600000,dstSavings=0,useDaylight=false,transitions=0,lastRule=null]
Instant:        2017-10-10T09:54:45.394314Z
LocalDateTime:  2017-10-10T10:54:45.394416
OffsetDateTime: 2021-10-10T10:54:45.394455+01:00
ZoneInfo[id="GMT+06:00",offset=21600000,dstSavings=0,useDaylight=false,transitions=0,lastRule=null]
Instant:        2017-10-10T09:54:45.397258Z
LocalDateTime:  2017-10-10T15:54:45.397353
OffsetDateTime: 2017-10-10T15:54:45.397406+06:00
ZoneInfo[id="GMT",offset=0,dstSavings=0,useDaylight=false,transitions=0,lastRule=null]
Instant:        2017-10-10T09:54:45.399973Z
LocalDateTime:  2017-10-10T09:54:45.400040
OffsetDateTime: 2017-10-10T09:54:45.400076Z

If the code base is already based on local date times and a refactoring isn’t possible the following actions could be applied to reduce the risk of moving dates and times:

• Check the current time zone in production, as all dates may require an update
• Change all dates to UTC/ GMT+0 in the DB
• Apply a fixed time zone to the JVM: -Duser.timezone=UTC
• Apply a fixed time zone in the JDBC URL (since hibernate 5.2 a hibernate property is available)
• Verify that the date isn’t displayed to the user, or a time zone conversion is applied

Links

• https://docs.oracle.com/javase/9/troubleshoot/time-zone-settings-jre.htm

The module pattern is one of the most known and used. It helps us to create private variables or better to avoid side effects in a larger JS application between the different JS files we load or frameworks we use.

The problem

Overall the problem is that in JavaScript everything is more or less public. Currently, most frameworks register their name in the Global space, also known as the window Object. You know them as angular or just $ or maybe even as Y.

Imagine the following code (jsBin):

// first JS file
var CLASS_NAME = "A1";
function A1() {}
A1.prototype.sayHallo = function() {
  $('#out').html(CLASS_NAME + ": says hallo!");
};

// second class in a different JS file
var CLASS_NAME = "B1";
function B1() {}
B1.prototype.sayHallo = function() {
  $('#out').html(CLASS_NAME + ": says hallo!");
};

// some code
$('#cmdA1').click(function() {
  new A1().sayHallo();
});
$('#cmdB1').click(function() {
  new B1().sayHallo();
});

It doesn’t matter which button you press the result will always be B1 because we have overwritten the value in CLASS_NAME in the second part.

Even if this sample is somehow of course constructed, this problem can easily happen in a larger JS application. We must take this into account an protect ourself.

The solution

The solution is pretty straight forward. We just wrap our class definition into an anonymous function. This does not only protect us but it allows us to create really private variables in JS which can’t be overwritten from outside — we can protect the access to them with functions.

jsBin again

// first JS file
MyGlobal = {};
(function($) {
  var CLASS_NAME = "A1";
  function A1() {}
  A1.prototype.sayHallo = function() {
    $('#out').html(CLASS_NAME + ": says hallo!");
  };
  MyGlobal.A1 = A1;
})(window.$); // pass any global scope

// second class in a different JS file
(function($) {
  var CLASS_NAME = "B1";
  function B1() {}
  B1.prototype.sayHallo = function() {
    $('#out').html(CLASS_NAME + ": says hallo!");
  };
  MyGlobal.B1 = B1;
})(window.$);

// some code
$('#cmdA1').click(function() {
  new MyGlobal.A1().sayHallo();
});
$('#cmdB1').click(function() {
  new MyGlobal.B1().sayHallo();
});

What have we learned?

• In JavaScript, the best practice is to wrap our code into anonymous functions
• Define one global scope variable which we use to register all our classes (here MyGlobal)
• Anonymous function also allow us to create private/ protected variables

What is it?

Strong IDs are simply wrapped primitive or simple types into classes. Just remember what we did in Java before the Enum come around. We had just Strings or Numbers in the code which we used to assign well known values to specific objects. In some projects these Strings has already been wrapped into classes. Now with Enums this is mostly obsolete. But for Ids we can still apply this pattern.

Imagine the following classes:

class Office {
  String id;
  String name;
}

class Person {
  String id;
  String name;
}
// we could use any string we want, even the ID from the office
interface PersonService {
  Person getById(String id);
}

Both classes have an id, simply just as a String. Keeping just these ids in hand you cannot tell if it is a Person Id or the Office Id. To make it more obvious we could change the code too:

final class OfficeId {
  String value;
}
class Office {
  OfficeId id;
  String name;
}

final class PersonId {
  String value;
}
class Person {
  PersonId id;
  String name;
}
// we can now use the real type, compile time save
interface PersonService {
   Person getById(PersonId id);
}

If you now have either the OfficeId or PersonId in hand, you cannot accidentally mix them up. You exactly know what you have and what it identifies.

Usually the ID classes are not mutable too.

Advantages

In larger projects you have many classes, it is easier to understand and keep different IDs in method signatures. That we use the right type in generic lists or method calls can be ensured now during compile time.

Also nice we can easyer change the type of ID, e.g. from String to Long or to a composite type.

If we move this sample to REST where we usually want to return a URI as an identifier to an object this pattern even gets more attractive. If we assume our IDs have been initially just simple Longs wrapped into a Strong ID we could change the value it a String and create URI / String which we return to the clients.

Disadvantages

Well no pro without a contra. Having strong ids in the system makes the handling sometimes awkward. E.g. if you serialize this to JSON you get:

// with strong ID
{ id: {value: "abc"}, name: "Main Office"}

// without strong id, or what you usually want
{ id: "abc", name: "Main Office"}

Furthermore Hibernate nor simple bean serializer/ deserializer can handle well immutable classes. Overall we would need to add additional code to handle that. e.g. Hibernate custom types etc.

Github JPA example