DEV Community: Kyle Carter

Supporting Cross Node Interactive Queries In Kafka Streams

Kyle Carter — Mon, 21 Feb 2022 17:07:11 +0000

Kafka Streams is a powerful tool that adds a high-level abstraction on top of Kafka’s rock-solid infrastructure to enable building streaming applications. It has several features mainly grouped around two concepts, KStreams which represents an infinite stream of data, and KTables which represent a projection of a stream’s data. Even calling these two concepts different is not completely true due to the stream-table duality. While it is not required to have a perfect understanding of the stream-table duality to work with Kafka streams I do find having some level of understanding of it is useful when working with streams. Using these core building blocks of streams and tables (stored projections of stream data) many impressive things can be built. That said, working with infinite streams of data and with the limited query model of a KTable can be tricky and has a steep learning curve. Streams actually provides another way to query your data that follows a more comfortable pattern for many developers and one that adds the ability to query your stream state from outside a stream. This is where interactive queries can come into the picture.

At a high level, interactive queries allow a developer to query the state of a KTable (in reality the data store that backs the KTable) from outside the stream processing code. This allows ad-hoc key-value queries that are performant and, especially for developers new to stream processing code, much easier to understand than querying via a stream. That said, there are some major pitfalls to using interactive queries that may not be apparent when first using them. The pitfall that this post is going to focus on is that the data that a particular instance of a service can query is only a subset of all the data available. To understand why this is, let us briefly remind ourselves how Kafka Streams works and how KTables are populated.

Each KStream is backed by one or more topics each with one or more partitions. Outside of the case where you are only using one partition and/or you only have one instance of your streams application running at a time, different processes will be handling different slices of the data within the topic. One of the great capabilities of Kafka is that it handles this balancing of cooperating consumers automatically for you. As new instances come online they will be assigned one or more partitions that it will be in charge of processing. This allows you to scale out horizontally up to the number of partitions in your topic. This means each instance of the stream application will have its own view of the world. Records that exist on one node won’t exist on another node. This is great for scalability as no one instance needs to shoulder all the load. A simplified model of this can be seen here:

So how does this interact with interactive queries? The interactive query functionality allows an instance of the streams application to perform ad-hoc queries of the local state by key. If the partition that a specific key is assigned is the same partition that the current instance is assigned, all will work wonderfully as the data will be there in the local state store. However, if the key is assigned a partition that is not assigned to the querying instance then you are out of luck. The interactive streams documentation acknowledges this fact and leaves resolving it to the user with the hint that some kind of remote procedure call (RPC) method would likely need to be employed. While I understand that the library cannot solve all problems, not having an out-of-the-box solution for this leaves developers in a tough spot. What makes this particularly troublesome is developers may initially develop against a small data set with a topic that only has one partition and/or instance and thus not see this issue until they release it into a more production-like, horizontally-scaled environment. Of note, using streams to query a KTable does not have this issue because the stream will be co-partitioned with the KTable and thus will always be on the correct node to do the lookup.

This post strives to propose an idea of how we can account for this issue of data locality and allow any instance of a streams application to query any data. As a scaffold to discuss this solution I have developed a simple example application that loads up a topic with various records and then exposes a REST endpoint that allows someone to retrieve the information by key. There are a lot of interesting things even in this simple application but I will focus mainly on the parts of it that enable the cross node interactive query functionality.

The topology for our application is quite basic. Events come in on the “event-topic” are consumed into a stream then aggregated into a state store.

The first thing we need to handle is enabling each instance of our application to self-identify where it is being hosted and provide that information to the streams library so that it can provide that information to other nodes in the future. In this example application we have a simple configuration that gathers the current host information that looks like this:

The above is extremely simplistic and likely won’t work in many environments where hostnames are not as immediately available as in the above but the same concept can be used. At this point, we can use the above configuration in our streams configuration.

I have truncated much of the streams configuration here but left the two interesting things. The first is that, because we will be running two instances of this application locally, I changed the directory that state is stored so that multiple state stores can coexist on the same machine. This shouldn’t be required when using different servers but also shouldn’t hurt anything. The second is that we are telling Kafka Streams where our current service is hosted. The streams library will pass back this information later when we need to find out where a particular key is stored.
The high-level concept of how this system is going to work is that a request will come into our application, we will check with streams to determine if the queried key is stored on the local node or if it is on a remote node. If it is local we will query the state store locally and return the result. If the data is remote we will retrieve the host information about where it is stored and then make a HTTP call to that service which can do the same lookup which will now be local, return the result via the HTTP response, and then the original service can return the result as if it had it locally. To support this we have a few pieces of code.
The first piece of code that we need is a class that can hold all the pieces of information that are needed to determine if a remote call needs to be made and information needed to make the remote call.

A querying service then can call a method with the following signature to do the lookup:

The StoreInfo class is passed in as seen above as well as the key that will be queried and then a higher-order function to be used if the data is determined to be local to pull the data from the local store. The body of the above function is something like the following:

As discussed above this queries the metadata for a particular state store, retrieves its host info (the information we stored at configuration time), determines if it is local, if so it calls the higher-order function for processing passed in, if not it generates the body from the key, sets the right “Content-type” header, copies the authorization header from the current request to the outgoing request, generates the URL to query based on the metadata and information passed in, queries the remote service, and passes on an appropriate response.

The final chunk of code we will look at is what it looks like to call this service.

In reality, there is not much more code required compared to if we were only doing the local query which is nice. The InteractiveQueryService is also coded in such a way that it can handle various types of keys and responses.

Environment Setup

Let’s see how it works. To save ourselves some effort of setting up Kafka locally we will use Upstash as our Kafka service. Upstash is a Serverless Kafka offering where you pay per message you produce/consume. They have a free tier which is more than sufficient for this test and gives you a good idea of how the service works. To get ready to run the application you have two options. You can set up the cluster manually or use some additional code I added to the repo to create the needed infrastructure via the Upstash API. I’ll walk through both.

Manual Setup

After verifying your email address and logging into the console go to the Kafka section:

Press create cluster and fill out the information. There is no required setup as far as the cluster is concerned for this POC so give the cluster any name and choose the region closest to you.

Then you can create your first topic. Unfortunately (at least with the free tier) the credentials you get from Upstash don’t allow the application to create its own topics. This is safer for production but just requires a little more work for this POC. Create a topic with the following information, the rest of the defaults are fine.

Now we need to create another topic that will be used to back the state store inside of Kafka Streams.

Now we can go back to the “Details” tab and grab our configuration.

Copy those values and paste them over the existing values in the application.properties file in our repository. Make sure to prefix each of the keys with "kafka.".

Now you are ready to go.

Automated Setup

For the automated setup, we first need to create a “Management API Key” by going up to “Account” -> “Management API” -> “Create API Key”

Grab that value and the email address you signed up with and put them into the variables at the top of the ConfgureEnvironment.java class

Run that class and grab the output.

Finally, paste those values over the existing values in the application.properties file.

Seeing the Code In Action

With our environment setup complete we can now test our application. Run the bootJar gradle task to build the jar and then, in two different terminal windows, navigate to the folder with the jar. We will then run the application with the following commands:

java -jar cross-node-iq-0.0.1-SNAPSHOT.jar
java -jar cross-node-iq-0.0.1-SNAPSHOT.jar --server.port=8081

After both nodes have come up and the logs have quieted down (indicating that rebalancing is complete) we are ready to query the application. You can choose to query either the node on 8080 or the one on 8081 since the whole point of this is it doesn’t matter which node is in charge or which key, it should work with either. For my test I will make the following request:

curl -i -H “Authorization:Bearer eyJhbGciOiJIUzI1NiJ9.eyJpZCI6MSwic3ViIjoidGVzdFVzZXIifQ.ZRq6TnZiBlkY1CDkkQP2RnTOMV58OxgC30W0u7AjTCg” localhost:8081/example/1

A lot of the above command is to manage the authentication. If you haven’t changed the authentication.jwt.secret from the application.properties file the above value should work for you too.

This gave me the following result:

Checking the logs of the node I queried we see it did not have the answer:

Checking the logs of the other node we see that it had it locally.

So it does indeed work. We can change the port number and query the one that has it locally and we see that it responds exactly the same. Looking at how long it takes to respond you can see some differences when it has to jump nodes and that will always have some effect but could be mitigated somewhat by keeping an open connection between nodes if that was desired.
As I have said above, there is a lot more to this application and some interesting concepts I think. Using Avro schemas without a schema registry, serializing/deserializing Avro for HTTP requests and response, simple authentication, etc. So do go ahead and jump in the code and see what there is to learn.

Repository Link

Conclusion

So where does this put us? With our new found ability to query across nodes are interactive queries ready to roll? Not so much. There are still other issues with interactive queries that must be accounted for, a major one being that during rebalances and hydration of state they are unusable. The above solution is also far from an end solution, it is merely the beginning of a much more feature-rich RPC framework that would be required if this was rolled out into a production environment. It does however show what is possible with a few good abstractions. This is also not the only way to solve this issue either, others have chosen to merely respond with basically a redirect when a client requests data that the current node does not have. All implementations have their tradeoffs and we need to know what we are optimizing for as we dive into these implementations. Even with its current limitations, interactive queries may be perfect for an application you are building, you just need to accept the failure modes that it has. If those failure modes are acceptable then interactive queries could be a great solution for interacting with the state within Kafka Streams in your application.

Effective Java: Consider Serialization Proxies Instead of Serialized Instances

Kyle Carter — Mon, 21 Feb 2022 16:28:01 +0000

Throughout all the recent items as we have discussed Java serialization, we have been discussing many of the challenges that come along with it. While on the surface it looks simple to implement, in reality, it is far from it. Due to the effectively hidden constructor provided by the serialization framework Serializable code is open to many potential issues that need to be protected against. Thankfully there is a pattern, called the serialization proxy pattern that can help us sidestep many of these issues.

One of the best parts of the serialization proxy pattern is that it is rather straightforward, especially compared to some of the alternatives. The first step is creating a private static nested class that holds all the necessary information to create your target object, this is your serialization proxy. This class will have a single constructor of the type of the enclosing class. This constructor simply copies the data from the parameter into its internal state, with no need for consistency checks or defensive copies. Now the serialization proxy and enclosing class need to add implements Serializable to their class signature. Let's look at an example of the serialization proxy that we would write for the Period class we have been discussing in recent items.

private static class SerializationProxy implements Serializable {
  private final Date start;
  private final Date end;

  SerializationProxy(Period period) {
    this.start = period.start;
    this.end = period.end;
  }

  // Any number will do here.
  private static final long serialVersionUID = 1234567890L
}

Our next step is to add a writeReplace method to the enclosing class. This method will look exactly like this in every implementation (assuming you call your private static serialization proxy SerializationProxy)

private Object writeReplace() {
  return new SerializationProxy(this);
}

When this method is on a class and it is serialized it causes the serialization system to return a SerializationProxy instance instead of an instance of the enclosing class. With this code in place that means that the serialization system will never create an instance of the enclosing class. To make sure no one tries to craft one maliciously we can add the following. (Again this code could be copied verbatim in a class implementing this pattern)

private void readObject(ObjectInputStream stream) throws InvalidObjectException {
  throw new InvalidObjectException("Proxy required");
}

The final step in the pattern is to provide a readResolve method in the SerializationProxy class that returns a logically equivalent instance of the enclosing class. The way it does this is by using only the enclosing class's public API. The benefit this provides is that it doesn't need to do anything special to protect the creation, all the protections can live within the enclosing class which it would already have to protect itself from "regular" API consumers. This is the benefit of this pattern, it doesn't use any "magic" constructors or capabilities, it simply forces the serialization framework to use the regular language primitives. In our example the readResolve function would be:

private Object readResolve() {
  return new Period(start, end);
}

Additional benefits this pattern provides to us above and beyond what the previously discussed patterns do is that the member variables in Period can once again be final which they always wanted to be to enforce immutability. The other huge benefit is the pattern is simple. A good proportion of it is simply copying and pasting the same code. That is to say, the effort you put in versus the benefit you get out with this pattern is great. The final additional benefit would be that the readObject method can return a different type of object than the originally serialized instance was. This benefit is taken advantage of by the EnumSet class in the core of the language. EnumSet uses the serialization proxy pattern to make for safer serialization and to allow for it to use the most efficient implementation (RegularEnumSet or JumboEnumSet) depending on how many types are in a particular enum.

There is always a cost to whatever we do though so what are the costs here? First, it is not usable with classes that are built to be extended. It is also not compatible with classes that can have circular references in their object graphs. Finally, it comes at a computational cost with measurements in the 14% slower range for using this pattern. All this being said, this pattern can be extremely useful to know. By taking some simple actions and accepting some potentially minimal drawbacks we can have far safer code.

With the end of this item, we have reached the end of the book Effective Java. There is a lot of insight that can be gleaned from this book and practicing its guidance. I know that I have learned a lot from the book about some lesser-known features of the language and some of the sharp edges I can watch out for in my day-to-day work. I hope you have gleaned some benefits too. I would like to do some more reviews like this in the future so be sure to subscribe for updates.

Effective Java: For Instance Control, Prefer Enum types to readResolve

Kyle Carter — Wed, 16 Feb 2022 14:06:48 +0000

In a previous section, we discussed different ways to make singleton objects in Java. One of the methods we discussed followed the following pattern:

public class Elvis {
  public static final Elvis INSTANCE = new Elvis();
  private Elvis() { ... }

  public void leaveTheBuilding() { ... }
}

By making the constructor private we prevent unexpected creations of the Elvis object. The problem with this pattern is that if you add implements Serializable to the class we open ourselves up for bypassing the private constructor. As has been mentioned in previous chapters, serialization effectively introduces a new, system-provided, constructor.

The built-in functionality to handle this issue and to take back some control of the instances produced by a class is the readResolve function. This function allows the substitution of another instance in place of the one created by readObject. If your class defines a readResolve function with the proper signature it will be invoked after the readObject function. The reference returned by this method will then be returned in place of the newly created object. In common usage, no reference to the newly created object is retained and thus it can be garbage collected.

Using this functionality to sure up our above Elvis class could end up looking something like the following:

private Object readResolve() {
  return INSTANCE;
}

This ends up being pretty straightforward in this case, rather than do anything with the newly created object we simply return our one true Elvis instance. Since no data from the serialization is used we can, and should declare all instance fields as transient. If you have instance fields that are object reference types then you must declare them transient to avoid a possible attack where an attacker could get a hold of the deserialized object before it is garbage collected and thus can keep it around resulting in your singleton no longer being a singleton.

The particular steps of this attack aren't strictly necessary to understand. Interested readers are encouraged to read the source material. Suffice to say it is possible by creating a "stealer" class that causes a circular dependency with the deserialized object and thus avoiding garbage collection can be made. While not a likely attack, it is better to be safe than sorry.

While declaring all fields as transient is one method of avoiding this issue, there are other ways to accomplish it as well. Another pattern from our previous singleton chapter used a single-element enum type to facilitate the singleton. This puts much of the singleton safety semantics on the JVM to perform and releases you from that burden. Our example as an enum type would be:

public enum Elvis {
  INSTANCE;

  private String[] favoriteSongs = { "Hound Dog", "Heartbreak Hotel" }
  public void printFavorites() {
    System.out.println(Arrays.toString(favoriteSongs));
  }
}

readResolve still may be necessary even with the above pattern when the instances of a class are not known at compile time.

Another thing to note when using the readResolve function is the visibility of the method. If your class is final then readResolve should be private. If your class is non-final you have more options. If you make it private it will not do any instance control for subclasses. If it is package-private it will only apply to subclasses that live in the same package. Finally, if you make it protected or public and a subclass doesn't override it any deserialization of the class will create an instance of the super class, not the subclass, which will likely cause a ClassCastException.

In summary, the use of enum type singletons should be preferred whenever possible when trying to enforce instance control on a serializable class. If it is not possible to use the enum pattern then careful consideration needs to be taken when writing the class's readResolve method. You should make sure that all the class's instance fields are either primitive or marked transient to protect against potential attacks against your instance control mechanism.

Effective Java: Write readObject Methods Defensively

Kyle Carter — Tue, 01 Feb 2022 20:40:31 +0000

In a previous item, a date range class was discussed. It includes Date fields and is careful to avoid breaking its invariants of its start date needing to come before its end date. The way that it accomplishes that is via careful coding of its constructor as well as its accessors. Let's refresh our familiarity with this class:

public final class Period {
  private final Date start;
  private final Date end;

  public Period(Date start, Date end) {
    if (start.compareTo(end) > 0) {
      throw new IllegalArgumentException("Start is after end");
    }
    this.start = start;
    this.end = end;
  }

  public Date start() {
    return start;
  }

  public Date end() {
    return end;
  }
}

Now let's consider if the need arose to make this class Serializable. Thinking back to our previous item of discussion about the physical and logical models of our classes, it is reasonable to come to the conclusion that we can use this same form as the serialized form. Because of this, we may be tempted to simply throw implements Serializable on the class and call it good. Unfortunately, this would open our class up to not keeping its invariants.

As we have discussed before, Java's default serialization system effectively creates a new hidden constructor for our class. In our existing implementation of the Period class the constructor is very critical to facilitating the safety of our class invariants. The effectively new constructor that exists with serialization does not have these same checks that protect our invariants so we must provide additional code to keep our internal data safe.

The way that Java facilitates our taking ownership of the construction of our object during deserialization is via the readObject method. This method takes a byte stream as its sole parameter and populates the state of an object. Usually, the byte stream that is consumed by this method will have been generated by serializing a normally constructed (and thus invariant keeping) instance of the object. However, since it is simply a stream of bytes, we can never be sure where those bytes came from and whether we can trust the source. We thus could be presented with an artificially created byte stream that does not meet our invariants and thus we can end up with an object that shouldn't be possible to create.

With this new consideration in mind we may attempt to resolve the issue by adding a method such as:

private void readObject(ObjectInputStream inputStream)
                  throws IOException, ClassNotFoundException {
  inputStream.defaultReadObject();

  if (start.compareTo(end) > 0) {
    throw new InvalidObjectException(start + " after " + end);
  }
}

While the spirit of the above is reasonable it is not enough. For the same reason that the original blog post was written (making defensive copies) this implementation opens itself up for being passed a byte stream that preserves the invariants of the class initially but then, since the reference could be modified by code outside of the class, the invariants could be broken by simply changing the value outside the class.

To solve this problem we must remember to always defensively copy any field that contains an object reference when using serialization. We thus can extend our above solution as follows to make it safe:

private void readObject(ObjectInputStream inputStream)
                  throws IOException, ClassNotFoundException {
  inputStream.defaultReadObject();

  start = new Date(start.getTime());
  end = new Date(end.getTime());

  if (start.compareTo(end) > 0) {
    throw new InvalidObjectException(start + " after " + end);
  }
}

In this version, we do our defensive copy and then do our validity check. This allows us to have full control of the variables when we do the check. We, unfortunately, do need to remove the final modifier on the member variables for this to work but that is the price we pay for safe deserialization.

The test that you can perform to determine if the default deserialization method will work is, would you be comfortable having a constructor on your class that simply took in the member variables and saved the state without any further validation? If so, then you are likely safe using the default deserialization method as far as defensive copying goes, if not, you should take steps to protect yourself from these possible issues.

The final item of consideration is that of making sure not to call overridable methods from the readObject method. This is the same caution that applies to constructors (because readObject is effectively a constructor) and for the same reason. If you call overridable methods from the readObject method you are open to having those methods called before the whole state of the object is initialized which can lead to issues.

In summary, it is best to remember that when using serialization you are effectively creating a new public constructor for your class. If you wouldn't be comfortable with having such a public constructor for your class, implement the readObject method and make sure that it takes care of the state in a defensive manner. The byte streams that your readObject method is passed should be handled as if they didn't come from a trusted source (because it may not have). If an entire object graph must be validated after being deserialized you can use the ObjectInputValidation interface (not discussed in this item).

Effective Java: Consider Using a Custom Serialized Form

Kyle Carter — Fri, 21 Jan 2022 22:01:08 +0000

As discussed in our previous post, the serialized form of an object is part of its API. This means that it is something that we should respect for some time going forward and that if we break it, we will be causing an unnecessary burden to the users of our code. This being the case, we should take great care in determining what structure the serialized version of our classes take. That is what this post focuses on.

A particular object can be thought of in two different ways, that of its physical representation and that of its logical representation. The physical representation of an object is that of the members and pieces of its internal structure, this is what acts as the state of a particular object. The logical representation of an object serves as a representation of an object conceptually, as a human would think of it. Rather than focussing on the nuts and bolts of how it is put together, it is focussed on the meaningful components. This may not make total sense right now but with a few examples, I think it can be a beneficial model to use.

The default serialized form of an object, that is the serialized version of a regular object used within the program and not the serialized version of an object specifically created for serialization, is likely an appropriate serialization to use if the physical and logical representation of an object is identical. For example, the following class's physical and logical representation are the same:

public class Name implements Serializable {
  /**
  * Family Name. Must be non-null.
  * @serial 
  */
  private final String familyName;

  /**
  * Given Name. Must be non-null.
  * @serial 
  */
  private final String givenName;

  /**
  * Middle Name. May be null.
  * @serial 
  */
  private final String middleName;

  // rest omitted.
}

Logically speaking a name is made up of these components and since the object physically represents them the same way this class could be serialized as-is. You will notice that even though the above members are private they still include a JavaDoc comment. This is because they are part of the serialized form of the class and therefore are part of the API. We put the @serial tag to tell JavaDoc to include this on the special page of the documentation for serialization.

Even when the default serialized form is appropriate for a particular class we still may need to implement the readObject method to protect invariants like the non-nullability of firstName and lastName above. This will be discussed further in future posts.

Now let's look at a class where the logical and the physical representations do not match. This class serves as a container for String objects (let's ignore that using a collection of type String would be far superior to this for a moment)

public final class StringList implements Serializable {
  private int size = 0;
  private Entry head = null;

  private static class Entry implements Serializable {
    String data;
    Entry next;
    Entry previous;
  }

  // Remainder omitted.
}

From the logical side, this class represents a collection of strings. From the physical side, this class is a doubly-linked list of entries. These two don't match. Since the default serialized form mirrors the physical form of an object it will end up representing each item individually and all connections both backward and forwards.

Using the default serialized form when the physical and logical representation of an object don't match can lead to a couple of issues:

It ties your class's exported API to the current implementation of the class. This greatly reduces the extensibility of your class.
It consumes unnecessary space in its serialized form. In our above example, this would be the unnecessary links between each entry.
It consumes unnecessary time when serializing and deserializing.
It can cause stack overflows. Because of the recursive traversal of the objects in the graph when serializing this can lead to stack overflows. Serializing our above StringList having an instance with between 1,000 and 1,800 elements led to a StackOverflowException. The size wasn't even consistent when the error was thrown due to internal differences in the runtime executions.

Let's consider a reasonable serialized form for our StringList example. All we need is maybe an integer detailing the size of the list and then the entries themselves. This would much closer match our logical model of what this class does. Here is what that may look like now with readObject and writeObject implemented to create our custom serialized form.

public final class StringList implements Serializable {
  private transient int size = 0;
  private transient Entry head = null;

  // No longer serializable.
  private static class Entry {
    String data;
    Entry next;
    Entry previous;
  }

  public void add(String newString) {
    // Omitted.
  }

  /**
  * Serialize this {@code StringList} instance.
  * 
  * @serailData The size of the list is emitted ({@code int}), followed by all of its elements (each is a {@code String}).
  private void writeObject(ObjectOutputStream outputStream) throws IOException {
    outputStream.defaultWriteObject();
    outputStream.writeInt(size);

    for (Entry entry = head; entry != null; entry = entry.next) {
      outputStream.writeObject(e.data);
    }
  }

  private void readObject(ObjectInputStream inputStream) throws IOException, ClassNotFoundException {
    inputStream.defaultReadObject();
    int numElements = inputStream.readInt();

    for (int i=0; i < numElements; i++) {
      add((String) inputStream.readObject());
    }
  }

  // Remainder omitted.
}

This is undoubtedly more code, but it is worth the cost. The first thing that both readObject and writeObject do is invoke their defaultRead/WriteObject method. Even though all the fields of this class are marked transient we still need to invoke these. This will allow adding non-transient fields in a future release and still maintain backward compatibility. If an object is serialized in a new version with non-transient field and then deserialized in an older version where they weren't there they would simply be ignored. If we didn't take this step the serialization would fail with StreamCorrupttedException.

Again we see JavaDoc on a private method detailing how the serialization form of this object will take form. The @serialData tag marks this as something that should show up on the page for serialization of the documentation.

Let's consider the performance difference between this new custom serialized form and the old default form. Considering StringList instances with an average String length of 10 characters the new form takes half as much space when serialized. It is also twice as fast in the tests of it. Finally, there are no longer stack overflows no matter the size of the list.

Even though our StringList example is bad it at least is mostly usable with its default serialization. That is not always the case. Consider the case of a hash table. Its physical representation is a sequence of hash buckets containing key-value pairs. The bucket a particular item falls in is a function of its hash. This hash is not, in general, guaranteed to be the same from implementation to implementation. Therefore, not only is it less than ideal, it could be broken by simply serializing and then deserializing an object of that class.

No matter what form you take for your serialized data every field of an object not marked transient will be serialized when the defaultWriteObject method is invoked. This means that every field that can be marked transient should be. This includes derived fields, generated fields, cache value fields, or fields pointing to something specific to that one run (for example a native filehandle). Before a field should be marked as non-transient you should be able to convince yourself it is part of the logical model of the class. Do note that fields marked as transient will be initialized to their default value when the class is created via deserialization.

Another thing to keep in mind is that if you are creating a thread-safe class you should also synchronize the writeObject method, even if you aren't using a custom serialized form. This can look something like the following:

private synchronized void writeObject(ObjectOutputStream outputStream) throws IOException {
  outputStream.defaultWriteObject();
}

In addition, no matter what form our class takes we should also explicitly set the serial version UID for serializable classes we write. This helps prevent the serial version UID from becoming an invalid source of incompatibility. It has the bonus of providing a small performance benefit as it avoids the process that must happen at runtime where the UID would need to get generated if it wasn't provided. It doesn't matter what value we set this variable to, just pick any random long value. Then when you modify your class in such a way it is no longer compatible simply increment the value.

In summary, when using Java's built-in serialization consider whether the default serialized form of a class is appropriate. You can determine if it is appropriate by determining if its logical and physical representations are the same. Serialized forms of your class are every bit as much a part of your class's public API as its methods and thus should be given just as much consideration and planning.

Effective Java: Implement Serializable With Great Caution

Kyle Carter — Tue, 18 Jan 2022 22:49:38 +0000

In the last topic, we covered why we should avoid using the built-in serialization framework in Java. A big part of that serialization system is the _Serializable _ interface. This interface indicates some of the magic promised by Java's serialization. Simply add this interface (which requires no methods to be implemented) and all of a sudden you have serialization. Unfortunately, this is not the case, while that enables serialization there are many concerns related to serialization that the developer of the program must keep in mind. This post covers some of those concerns.

A major cost of implementing the Serializable interface is the loss of encapsulation of internal data structure and thus a decrease in flexibility. Once you implement the Serializable interface the output of the serialization is part of your code's API and thus must not be changed without care. A potential way to minimize this risk would be to create a custom serialized form of your data (an idea that will be discussed in a future item). If you don't take this mitigating action though, by default, all of your private and package-private fields become part of the API.

If you do change the internal structure of your class and then someone tries to use the new code to read an old object byte stream they will be presented with failures. There are specific ways to try to account for internal changes by using ObjectOutputStream.putFields and ObjectOutputStream.readField but these are far from a clean solution. Thus, if you are going to use Java serialization then you need to carefully design a serialized form of the class that you are ready to support for the long term.

An example of the limitations on the evolution of a class imposed by serialization is stream unique identifiers, also known as serial version UIDs. Each serializable class has a unique identifier to specify the serializable version that it is. This can be manually set by declaring a static final long field of the name serialVersionUID. If you don't specify one one will be generated for you at runtime by applying a cryptographic hash (SHA-1) to the structure of your class. This will mean that it will have a consistent value as long as you don't change anything about the structure of the class. This means names of the class, interfaces it implements, most member variables, and even synthetic members generated by the compiler all affect this unique identifier. So even if you made a change that shouldn't affect the serialization of the class you still could be presented with an InvalidClassException at runtime when trying to use it.

Another major cost of implementing Serializable is that it increases the likelihood of bugs and security holes. This is covered fairly extensively in the last topic from this book. A lot of this concern comes down to a backdoor being generated for your classes to be created from. Because there is this hidden constructor it is easy to forget that you must validate the invariants of your class even in this case.

Yet another burden of serializability is the increased testing burden when making changes to the class. If you want a robust program you don't only need to verify that the business logic is sound, that previous bugs haven't regressed, and that your code is performant, but you also need to verify that the serializability is still sound. You can again mitigate some of this burden if you use a custom serializable form and if you minimize the number of versions of your class that can exist in the wild but the burden is still there.

Sometimes implementing Serializable can not be avoided. This should not be taken lightly though. Whether it is because a class is participating in a framework that needs object transmission or persistence or if the class is participating as a component of another Serializable class it can have its uses. When the decision to implement the interface is undertaken it is then our responsibility to do it safely. Within the core language, it has historically been that value classes such as BigInteger and Instant implement as well as collections implement serializable. However, classes that represent active executing items such as Thread and Thread Pools have not.

Serializable should rarely be implemented by classes designed for inheritance as well as new interfaces should rarely extend Serializable. If you do one of the above you will be putting a heavy burden on the future users of your classes and interfaces. You may need to violate this rule if your class or interface's sole purpose is to participate in a framework that requires serializability. Some examples from the core library are Throwable and Component. Throwable requires serializability because it is enabling exceptions to be passed via RMI. Component implements it so that GUIs can be sent, saved, and restored (even though this ability was rarely used).

If you choose to implement a class that is built for extensibility as well as is serializable there are a few items to be aware of. If ther are any invariants that must be kept for your fields then you must ensure that no subclass overrides the finalize method. You can do this by overriding it yourself and marking it as final. If you don't you leave your class open to a finalizer attack. Also, if you have invariants of fields that would be violated if they were reset to their default values then you must add a readObjectNoData method:

private void readObjectNoDAta() throws InvalidObjectException {
  throw new InvalidObjectException("Stream data required");
}

This method was added in Java 4 to account for the edge case where a serializable superclass was added to an existing class.

When deciding to not implement Serializable on a class built for extensibility you need to also consider if a subclass would reasonably need to implement Serializable. This is because deserializing requires the superclass to have an accessible parameterless constructor. If there is no such constructor, subclasses must follow other patterns to succeed.

Finally, inner (non-static) classes should not implement Serializable. The way these are implemented is using synthetic fields that store references to its enclosing instance and to store values of the local variables from the enclosing scope. The way that these are defined is ill-defined and thus should be avoided. Static member classes, however, don't have this issue.

In summary, correctly implementing the Serializable interface is full of pitfalls. Unless you have a high level of control of your environment where versioning and data inputs are constrained you will be in an uphill battle. This only gets more challenging when also introducing inheritance.

Effective Java: Prefer Alternatives To Java Serialization

Kyle Carter — Tue, 04 Jan 2022 15:29:59 +0000

Java's built-in serialization has been part of the language since 1997, just two years after its inception. Even from the beginning of its life as part of the language it has been known to be risky. While the goal was well-intended, that of distributing objects with little effort, in hindsight it is largely agreed that it was not worth the costs in correctness, performance, security, and maintenance.

There are countless examples throughout the history of the Java language where Java's built-in serialization has caused issues. One such example was a ransomware attack on the San Francisco Metropolitan Transit Agency Municipal Railway that shut down the entire fare collection system for two days in 2016.

A core problem with Java serialization is that it aims to be so broad that it makes the attack surface extremely large. Object graphs are deserialized by the readObject method on the ObjectInputStream class. This effectively serves as a magic constructor that can instantiate an object of basically any type as long as it implements the Serializable interface.

There are basically no classes that aren't part of the serialization attack surface. JVM classes, third-party classes, and the classes from the application itself are all possible targets. Even if your code doesn't use Java serialization explicitly it may still be using serialization under the hood. This is because there are major parts of the Java platform such as RMI (Remote Method Invocation), JMX (Java Management Extension), and JMS (Java Messaging System) that are built on top of the serialization that Java offers. Deserialization of untrusted sources via these systems can lead to remote code execution, denial-of-service attacks, and other issues.

Attackers and security researchers alike are always in search of new classes that they can exploit via serialization. Many times it is via the chaining of these exploits that the actual exploit is performed. That is exactly what happened with the railway system mentioned above.

Even without these chains of exploits we can run into serialization issues with even basic looking code. Attackers will often look for ways they can provide a small amount of code and get a disporportiate amount of computation performed in search of a denial-of-service attack. This is often refered to as a deserialization bomb. Let us look at one example:

static byte[] bomb() {
  Set<Object> root = new HashSet<>();
  Set<Object> s1 = root;
  Set<Object> s2 = new HashSet<>();
  for (int i=0; i<100; i++) {
    Set<Object> t1 = new HashSet<>();
    Set<Object> t2 = new HashSet<>();
    t1.add("foo");
    s1.add(t1);
    s1.add(t2);
    s2.add(t1);
    s2.add(t2);
    s1 = t1;
    s2 = t2;
  }

  return serialize(root);
}

This code creates an object graph of 201 HashSet instances each with 3 or fewer object references. The whole graph only takes up 5,744 bytes but is impossible to deserialize. This is because deserializing a HashSet requires computing the hash codes of all of its elements. The two elements of the root HashSet themselves have two more hash sets all the way down the 100 levels. This causes the hashCode function to be called 2^100 times. The extra frustrating part of this is that, other than the code not completing, there is no indication of a problem.

So I think we have sufficiently demonstrated that Java's built-in serialization has many pitfalls. What are we to do? The best way to solve this problem is to avoid it entirely. There is no good reason to use Java serialization in any new code you write today. Instead, you should use some other form of data transfer. These systems have the bonus of being cross-platform. These representations have the benefit of being much simpler and having a much smaller scope than Java serialization. This allows it to be much safer as they are usually focused solely on data. Some examples of these formats are JSON, Protocol Buffers (Protobuf), and Avro. While Protocol Buffers and Avro also can facilitate schema verification as well as have extensions for remote procedure call systems (RPC) they are still much simpler than Java serialization is when it comes to simply transfering state.

If you however are working on a legacy system that is already using serialization there are still some things you can do to mitigate your risks. First would be to only deserialize trusted data. The official secure coding guidelines for Java say "Deserialization of untrusted data is inherently dangerous and should be avoided" in large, bold, red letters. This is the only guideline given such extreme focus thus we shouldn't ignore it. Another tool you can use is the java.io.ObjectInputFilter class added in Java 9 (and also backported). This allows more control over what types of objects can and can't be deserialized in our system. You can choose to accept only certain types (an allowed list) or not accept certain types (a disallow list). If at all possible you should use a allow list as this gives the most control over what is accepted. A disallow list, while still useful, only can protect you from known issues, not the new ones just being discovered.

There is still a lot of Java code that uses serialization in use today. That being the case we should understand the complexities and issues it can introduce. We should also use whatever tools we have available to limit our exposure to these issues and the blast radius that they have. In general, if you can avoid Java serialization, avoid it. In new systems don't introduce Java serialization at all. Use modern data interchange formats instead to transfer data across systems.

Effective Java: Don't Depend on the Thread Scheduler

Kyle Carter — Thu, 16 Dec 2021 17:26:49 +0000

Even on modern systems that have many CPU cores and thus can be concurrently executing multiple threads, they are likely no match for the number of threads in a runnable state on a system. For this reason, we have the thread scheduler which determines which threads will run and for how long. Implementations of thread schedulers strive for equality in how they treat threads but their exact semantics vary from implementation to implementation. This being the case, relying on the particular semantics of a thread scheduler is not wise and can lead to unexpected behavior on different systems and non-portable code.

A good plan for having a robust, responsive application is to aim for the number of runnable threads to be, on average, the number of cores your system has. Of note, this is aimed at runnable threads and not simply threads that exist. Runnable threads are threads that are ready to do work and that are not in a waiting state. Threads in a waiting state are easier for the thread scheduler to reason about because they aren't requesting to be run therefore they won't be scheduled. That's not to say there is no cost to having waiting threads but those aren't being discussed in this topic because they aren't related to the thread scheduler.

The simple rule of thumb is that any runnable threads should be doing useful work and not simply running to keep themselves scheduled. Threads should also keep their work short (but not too short thus spending all of its time in dispatching overhead). At its core, this means your threads should not be busy-waiting. While busy-waiting can be an advanced technique that can be used in some specific circumstances they are rare and likely not what you are wanting. Busy waiting just wastes CPU cycles while not progressing the work of the application. Let us look at an example of an extremely poor CountdownLatch implementation.

public class BadCountDownLatch {
  private int count;

  public BadCountDownLatch(int count) {
    if (count < 0) {
      throw new IllegalArgumentException(count + " < 0");
    }
    this.count = count;
  }

  public void await() {
    while (true) {
      synchronized(this) {
        if (count == 0) {
          return;
        }
      }
    }
  }

  public synchronized void countDown() {
    if (count !=0) {
      count--;
    }
  }
}

This implementation underperforms the built-in implementation by 10x when 1,000 threads are waiting on the latch. While at first glance this implementation may look like something that wouldn't be written, it comes up much more than it should.

When presented with an application that has issues due to thread scheduling one might be tempted to "fix" the issue by calling Thread.yield on the problematic thread. Even if this works in your case it is not guaranteed to work in other cases. There are no testable semantics to the yield function. A much better reaction to this issue would be to restructure your application to correctly handle the concurrent runnable threads it has.

Another technique that you may be tempted to use is Thread priorities. These again don't have testable semantics and have different implementations on different systems and JVMs and thus should not be used to attempt to fix issues.

Summing this topic up, do not rely on the thread scheduling algorithm of your JVM to provide correctness to your application. This includes relying on Thread.yield and thread priorities. Instead, strive to keep the number of runnable threads to around the number of executable processes your system can run concurrently.

Effective Java: Use Lazy Initialization Judiciously

Kyle Carter — Wed, 08 Dec 2021 15:02:09 +0000

Lazy initialization is the pattern of putting off the creation of an object or process until it is needed. The idea behind this pattern is that you may never need the object and thus you saved the initialization costs. The main reason that lazy initialization is used is as an optimization. The other use that lazy initialization has is breaking tricky circular dependencies in your code.

As discussed in a previous item going down the path of optimizations is often fraught with peril and we can sometimes even decrease performance in the search of performance improvements. As with all optimizations, we should test out and confirm that we will truly see the improvements we are after. With lazy initialization, this will largely rely on how often we can completely avoid initialization of the object and how expensive that initialization is. Of note though, bringing in lazy initialization, especially in the presence of multiple threads, can introduce a new level of complexity which might not be worth its cost. For these reasons, unless presented with hard evidence to the contrary, you should use eager instantiation in almost all cases.

Let's say that we have determined that lazy instantiation is required, let's look at a few patterns of how to accomplish it. The first method can be used when trying to break a circular dependency since it is the simplest:

private FieldType field;

private synchronized FieldType getField() {
  if (field == null) {
    field = computeFieldValue();
  }
  return field;
}

This ends up being fairly simple. Within a synchronized method, determine if the field is initialized, if it isn't, initialize it, if it is, just return it. The synchronized keyword allows us to use this method with concurrent threads at the cost of some performance. This same pattern can be used with a static field by simply marking the field as static and the function as static.

The next pattern we can use is useful when we need to lazily initialize a static field with a pattern called lazy initialization holder class idiom. This idiom uses the guarantee that a class will not be initialized until it is used.

private static class FieldHolder {
  static final FieldType field = computeFieldValue();
}

private static FieldType getField() {
  return FieldHolder.field;
}

This is quite a beautiful pattern. On the first call to the getField method, the object reads FieldHolder.field at which point the class will be initialized. This idiom doesn't require any explicit synchronization as that will be provided only on the initialization of the class and only does a field access which means it's going to be extremely performant as well.

The next use case we may find ourselves in is needing to do lazy initialization for performance reasons on an instance field. In this case, we should look at the double-check idiom. This pattern avoids the cost of synchronization once the field is initialized with the trade-off that we need to check the field twice. It first checks the field to determine if it should look into initializing the field. If it appears it needs initialization then it obtains the lock and then double checks that initialization is still required. Because there is no locking once initialized the field must be marked as volatile.

private volatile FieldType field;

private FieldType getField() {
  FieldType result = field;
  if (result == null) {
    synchronized(this) {
      if (field == null) {
        field = result = computeFieldValue();
      }
    }
  }
  return result;
}

The code is a bit convoluted, to be honest, but via that convolution there are benefits. The need for the local result variable may seem unclear. The purpose of this local variable is to ensure that in the common case (the case where the field is initialized) it is only read once. While not necessary it can improve performance. In the case where a field can tolerate repeated initialization, we can instead use the single-check idiom. As the name suggests, this pattern drops one of the checks to simplify the code at the cost of possible multiple initializations.

private volatile FieldType field;

private FieldType getField() {
  FieldType result = field;
  if (result == null) {
    field = result = computeFieldValue();
  }
  return result.
}

The final variant that can be considered is if we are OK with up to a reinitialization per thread and the field is of a primitive type (except long and double) we can forgo the volatile keyword. On some architectures that can lead to greater performance.

There are many complications when trying to tackle lazy initialization. If at all possible we should avoid it. That said if after testing it is confirmed it will be of benefit, lazy initialization can be useful for improving performance or breaking a circular dependency. There are proven methods we can use presented above that balance safety and performance even in a concurrent environment.

Effective Java: Document Thread Safety

Kyle Carter — Thu, 02 Dec 2021 01:18:09 +0000

Users of classes you write need to know how they behave. One of the attributes of your class that a user needs to know is whether the class is thread-safe or not. Outside of this documentation a user of the class needs to guess about the class's thread-safety. This can lead either to excessive synchronization or insufficient synchronization which can lead to invariant issues.

It is important to know that thread-safety is not black and white. There are levels of thread safety.

Immutable objects - Since there is no mutable data inside of an immutable object they are inherently thread-safe. Examples of immutable objects are: String, Long, and BigInteger
Unconditionally thread-safe objects - These objects are thread-safe in all usages. This can make them simple to use as all operations on the object can be considered thread-safe and we don't need to account for the differences between methods. Examples of unconditionally thread-safe objects are AtomicLong and ConcurrentHashMap.
Conditionally thread-safe objects - These objects include both thread-safe and thread-unsafe functions depending on what part of the object you are interacting with. These objects need great documentation to help the users of the objects to know where external synchronization may be required. An example of this would be the Collections.synchronized wrappers that synchronize much of interactions with the object but do require external synchronization of iterators returned.
Not thread-safe objects - The objects contain mutable data and make no effort at synchronization. If a user of one of these objects would like to use it in a concurrent way they must bring their own synchronization. There are many, many examples of these types of objects such as ArrayList and HashMap.
Thread-hostile - These objects are often not implemented this way on purpose and are unsafe to use even if you perform perfect external synchronization. The most common way this can occur is through the unsafe interaction with static values.

As noted above, documenting a conditionally thread-safe class requires care. You must not only indicate that the class is not completely thread-safe but what locks must be obtained to make its non-thread-safe methods thread-safe. For example, let's look at the documentation for Collections.synchronizedMap:

It is imperative that the user manually synchronize on the returned map when iterating over any of its collection views:

  Map m = Collections.synchronizedMap(new HashMap());
      ...
  Set s = m.keySet();  // Needn't be in synchronized block
      ...
  synchronized (m) {  // Synchronizing on m, not s!
      Iterator i = s.iterator(); // Must be in synchronized block
      while (i.hasNext())
          foo(i.next());
  }

Failure to follow this advice may result in non-deterministic behavior.

Thread-safety documentation usually belongs in the class level documentation but if a specific method has special concerns the documentation can also live there. Documenting the thread-safety of static factories (like in the Collections.synchronizedMap example above) is also a good idea.

When a class uses a publicly accessible lock it can initially feel like it is enabling clients of the class more control. However, this flexibility can come at the cost. This is because it is incompatible with high-performance internal concurrent controls such as those used in ConcurrentHashMap. It also opens yourself up for a client holding the lock for a long time either accidentally or intentionally. In either case, it can lead to serious problems.

Alternatively, we can use a private lock object in our synchronized methods.

private final Object lock = new Object();

public void bar() {
  synchronized(lock) {
    ...
  }
}

There are a few things we can learn from this example. By marking the object as private we protect ourselves from someone external to our class holding the object for too long. We also mark it as final protecting ourselves from accidentally reassigning it and from subclasses changing it as well. Even when using locks from the java.util.concurrent.locks package we should always make them final.

As convenient and beneficial as this private lock pattern is, we can only use this method when writing unconditionally thread-safe objects. When writing a conditionally thread-safe object we are unable to do this because we have to provide the user of the class a handle to hold a lock when doing operations on the non-thread-safe parts of the object.

Thread-safety can be a tricky problem within an application. It becomes much more difficult when the classes we are using haven't documented what level of thread-safety they have implemented. There is no right or wrong level of thread-safety, different types of behavior can lend themselves to different levels of thread-safety. No matter the level we can document their status. Remember to make all your lock objects final and when possible also private. By following these guidelines we can mitigate some of the difficulty out of working in a concurrent environment.

Effective Java: Prefer Concurrency Utilities Over wait and notify

Kyle Carter — Fri, 19 Nov 2021 16:15:31 +0000

At the core of each Object in the Java language there are three methods, wait, notify, and notifyAll. These methods allow you low-level concurrency control options. Up until Java 5, this was the go-to option for facilitating concurrency control. However, since the release of Java 5 (in 2004) there are now higher-level tools that can be used that are much easier and less error-prone. This being the case, in new code, we should be using exclusively these provided concurrency utilities.

The java.util.concurrent provides three different kinds of utilities. The first is the Executor framework discussed in a previous item, concurrent collections implementations, and synchronizers.

The concurrent collections provided by the Java language are high-performance concurrent implementation of the common collection interfaces (List, Queue, and `Map). These collections bring their own concurrency controls and thus don't need (and shouldn't be) externally synchronized. At times these collections provide lock-free implementations of functions and the fact that the user of the collection doesn't need to know how the implementation works is great.

Because these concurrent collections sometimes need to do multiple actions (because they are state-dependent) atomically they provide functions to facilitate this. These methods can be extremely useful so in Java 8 many of these functions were provided on the main Collection interfaces. One example of this is putIfAbsent(key, value). We could use this functionality to develop a Strin.intern implementation.

`
private static final ConcurrentMap map = new ConcurrentHashMap<>();

public static String intern(String s) {
String previousValue = map.putIfAbsent(s, s);
return previousValue == null ? s : previousValue;
}
`

This is pretty efficient and concise but we can make it even more performant but using the knowledge that get operations are optimized in ConcurrentHashMap and write the following:

public static String intern(String s) { String result = map.get(s); if (result == null) { result = map.putIfAbsent(s, s); if (result == null) { result = s; } } return result; }

This new implementation is actually faster than the built-in intern function (although it doesn't take into account some of the memory management jobs that the built-in intern function must perform).

These built-in concurrent capable collections effectively obsolete the built-in synchronizing collection operations (Collections.synchronizedMap etc). Simply replacing one of these usages with its concurrent counterpart is likely a great performance benefit. These concurrent collections are even used internally by the concurrent package to facilitate its work like the BlockingQueue's usage in ThreadPoolExecutor as discussed in the previous item.

Another type of concurrent utility provided by the java.util.concurrent package is synchronizers. These are objects that allow one thread to wait on another thread. Although this is a fairly basic concept it can be used powerfully. The most common synchronizers are the CountdownLatch and the Semaphore but there are also more advanced synchronizers like the CyclicBarrier, Exchanger, and Phaser.

Let's look a little more into CountdownLatch. This class serves as a single-use barrier that allows threads to wait on one another before proceeding. The class takes an int in its constructor of the number of times its countdown method must be invoked before it unblocks the threads waiting on it. Using this class let's build a simple timer function that has all threads initialize, wait until all are ready, start processing, and then stop and determine how long the process took.

`
public static long time(Executor executor, int concurrency, Runnable action) {
CountDownLatch ready = new CountDownLatch(concurrency);
CountDownLatch start = new CountDownLatch(1);
CountDownLatch done = new CountDownLatch(concurrency);

for(int i=0; i executor.execute(() -> {
ready.countDown();
try {
start.await();
action.run()
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
} finally {
done.countdown();
}
});
}

ready.await();
long startNanos = System.nanoTime();
start.countDown();
done.await();
return System.nanoTime() - startNanos();
}
`

In this example we use three different CountdownLatchs which can get a little muddy but it does keep things pretty separated. We have the ready latch that each thread checks in with and the main thread is waiting on. Once all threads check in the main thread starts the timer and triggers the start latch which all the worker threads have been waiting on. All the worker threads do their work and then check-in when finished via the done latch. The main thread is waiting on the done latch to open and then marks the finished processing time.

Let's consider a few other things about this example. What would happen if we passed in a concurrency count that didn't match the number of threads? If it was too few we would end up prematurely starting our time and finishing our timer. If it was higher than our thread count then we would be deadlocked in what is known as a thread starvation deadlock. You will also notice that we catch the InterruptedException. By convention whenever this exception type is caught we should call Thread.currentThread().interrupt() to signal to the owner of the thread that the thread has been interrupted and allow it to handle that in whatever way seems fit. Finally, you will notice the usage of System.nanoTime() vs something like System.currentTimeMillis(). This is because it is more accurate and because it is unaffected by the system's real-time clock. It is also of note that, unless the Runnable represents a significant amount of work, this function won't return very interesting work. This is because even System.nanonTime() is not accurate enough for microbenchmarking. It is for this reason that tools like JMH exist for this specific purpose.

This only begins to cover the utilities provided by the concurrent utilities built into the core language. Feel free to dig deeper into these utilities.

Even though there are better methods out there than using wait and notify directly we may need to maintain code that does use these functions. The wait method is, as the name suggests, used to make a thread wait for some condition. It must be invoked in a synchronized region that locks the on the method it is invoked. The colloquial usage looks like this:

synchronized(obj) { while(<condition does not hold) { obj.wait(); } // perform action now that condition holds. }

Things of note, we need to always call wait within a loop checking that the condition we are waiting for is true. If the condition we are waiting for is true and the notify or notifyAll method is called before the wait method is called there is no guarantee the thread will ever wake up. By putting the check in a loop we ensure safety. If the thread moves past the wait before the condition holds we lose the protection of our invariant. There are several ways that a thread can be woken up when the condition it is waiting for is not true.

Another thread could have also been notified and taken the lock.
Another thread could have invoked notify incorrectly.
The invoking thread could have triggered notify too early before it was actually ready.
In rare circumstances, a waiting thread can be woken up even without a notify call.

One topic that comes up when discussing wait and notify is whether to use notify or notifyAll. As a reminder notify wakes up one waiting thread and notifyAll wakes up all waiting threads. Waking up all waiting threads is a safe, conservative choice. It will always guarantee you will wake up all threads that need to be awakened. You actually may be waking up more threads than you need to, but if you are properly checking on condition before proceeding after waiting, these additional threads that were woken up will simply go back to waiting. Using only notify could lead to a bit of an optimization but in the long run, it's not likely worth it.

Simply put, wait and notify rarely need to be used in new code. By using modern concurrent utilities we can have much simpler code, safer code, and likely more performant. If we do find ourselves maintaining code that does use wait and notify we should be careful we are using the functionality correctly. Always check before proceeding, loop if the condition isn't met, and prefer notifyAll over notify.

Effective Java: Prefer Executors, Tasks, and Streams to Threads

Kyle Carter — Sat, 13 Nov 2021 01:29:02 +0000

Eventually, it seems that every developer will be presented with a problem that requires some kind of work queue. These work queues can be used to store a collection of tasks to be worked in some order and move on. Although the concept of these work queues may be simple, actually developing one of these in a safe, performant manner can be tricky and error-prone. Thankfully we have a solution built right into the Java language.

Within the java.util.concurrent package we have the Executor Framework which is a flexible framework based on separating the work to be performed, a task, from the unit of execution, the executor. Let's look at a very simple use of the Executor framework:

ExecutorService executor = Executors.newSingleThreadExecutor();

executor.execute(runnable);

executor.shutdown();

The steps usually follow that model above: create the right type of executor for what you are trying to accomplish, add work to it, then shut it down (don't forget that last part as your JVM likely won't shut down in that case).

This simplest case is not all you can do. You can wait for a task to finish, you can wait for any or all of a group of tasks to finish, you can wait for the executor to finish, you can retrieve the results of your asynchronous tasks, you can run particular tasks on a schedule, and more.

In the above example, we used a single-threaded executor, in case you need more threads than that you can use a different factory method and configure what you need. Changing from using one thread or multiple, the rest of the code will stay the same. There are a number of options and which one is going to be best is going to be based on how busy it's going to be, what kind of work it will be doing, and what environment you are running in. In short, there isn't a one size fits all solution. Take a look at what your options are and choose which one fits your use case the best.

One of the things the executor framework allows you to do is to avoid working directly with Threads. Threads are fairly error-prone to work directly with so having this abstraction layer on top of them can greatly simplify working with them and make it much safer. The executor interface takes two different types of tasks that are fairly closely related. The first is a Runnable, this is a task that doesn't have a return value, and then you have a Callable which can have a return value and can throw an arbitrary exception.

From Java 7 onwards the Executor framework has also extended to support fork-join tasks. These are a special kind of job where a particular piece of work is split between a number of executors that can steal work from each other in order to stay busy. One of the more recent enhancements to the Java language, parallel streams, is built on the fork-join pool that the executor framework provides. This makes it a little easier to work with but still comes with its own caveats and pitfalls.

There is a lot one could dig into when considering all that the executor service can do but even this simple introduction I hope can raise awareness of it so that when you may be tempted to reach for a Thread you can instead look deeper into this framework.