August 15, 2025

JDK 25 - JEP 503: Remove the 32-bit x86 Port

Abstract

JDK 25 - JEP 503: Remove the 32-bit x86 Port. JEP 503 does not introduce any new language features. The JEP specifies Java will no longer support 32-bit hardware. The cost of maintaining a 32-bit port of Java is very costly with little benefit since 32-bit is no longer prevalent.

Pure Speculation

In 1996, the Nintendo 64 game console was released. This was the first big “64-bit” thing that I remember. As of this writing (2025), that was 29 years ago. So, maybe in the year 2054, There will be a JEP to remove support for the 64-bit x86 port in favor of continued development of the Quantum port (pure speculation)!

References

Shipilev, A. (2024, November 28). JEP 503: Remove the 32-bit x86 Port. https://openjdk.org/jeps/503.

JDK 25 - JEP 502: Stable Values (Preview)

Abstract

JDK 25 - JEP 502: Stable Values (Preview). This JEP introduces an API for stable values, which are objects that hold immutable data. Stable values are treated as constants by the JVM, enabling the same performance optimizations that are enabled by declaring a field final. Compared to final fields, however, stable values offer greater flexibility as to the timing of their initialization.

Disclaimer

This post is solely informative. Critically think before using any information presented. Learn from it but ultimately make your own decisions at your own risk.

Requirements

I did all of the work for this post using the following major technologies. You may be able to do the same thing with different technologies or versions, but no guarantees.

openjdk 25-ea 2025–09–16 (build 25-ea+27–3363)
NetBeans 25
Maven 3.9.6 (Bundled with NetBeans)
maven-compiler-plugin-3.14.0

Download

Visit my GitHub page https://github.com/mjremijan to see all of my open source projects. The code for this post is located at https://github.com/mjremijan/thoth-jdk25

Compile and Run

This is a preview API, disabled by default. To use this API in JDK 25, you must enable preview APIs:

Compile the program with javac --release 25 --enable-preview Main.java and run it with java --enable-preview Main
When using the source code launcher, run the program with java --enable-preview Main.java
When using jshell, start it with jshell --enable-preview

A Traditional Logger

A Logger object is a good example to introduce JEP 502: Stable Values. Ideally, creating a Logger object should have the following characteristics:

Created one time only
Created only when needed (lazy initialization)
Immutable
Optimization by the JVM (code in-lining, etc)

The traditional way to create a Logger is through a class-level final property. Listing 1 demonstrates this.

Listing 1 - Traditional Logger with Eager Initialization

package org.thoth.jdk25.jep502.main.traditional;

import java.util.logging.Logger;

public class TraditionalLoggerWithEagerInitialization {
  private static final Logger log
    = Logger.getLogger(TraditionalLoggerWithEagerInitialization.class.getName());
  
  public void service() {
      log.info("service() method start");
  }
}

This code is good, but it has eager initialization. The Logger object is created whether or not it is ever used. While creating this logger may be a fast operation, it is easy to imagine an expensive object creation composed of many different objects using external resources which either need to be created or connected to. It would be better if the initialization was on-demand (lazy). Listing 2 demonstrates this.

Listing 2 - Traditional Logger with Lazy Initialization

package org.thoth.jdk25.jep502.main.traditional;

import java.util.logging.Logger;

public class TraditionalLoggerWithLazyInitialization {
  private static Logger log;
  
  private static Logger getLog() {
    if (log == null) {
      log = Logger.getLogger(TraditionalLoggerWithLazyInitialization.class.getName()); 
    }
    return log;
  }
  
  public void service() {
      getLog().info("service() method start");
  }
}

This code implements lazy initialization, but introduces other problems. Threading is the first obvious issue. Threading potentially allows multiple loggers to be created. The possibility for multiple instances means the JVM cannot treat this object as immutable and thus cannot fully optimize its use. This may be addressed with synchronization, but mutli-threaded code is tricky to get right. This code also introduces a subtle NullPointerException issue because if the getLog() method is not used 100% of the time then it is possible the log property is null. Accessing the Logger through the getLog() method is not ideal.

Neither of these traditional ways of creating a Logger have all of the characteristics we want for initializing the object. The purpose of JEP 502 is to address these issues. Let’s start looking at JEP 502.

StableValue<M>

StableValue<M> has been introduced to the JVM in JEP 502: Stable Values (Preview). Its purpose is to:

Hold immutable data
Treated as constants by the JVM, enabling the same performance optimizations that are enabled by declaring a field final
Offer greater flexibility as to the timing of their initialization

The goal is to have the JVM handle the creation of these objects until they are needed. Since they are immutable, the JVM is able to optimize the bytecode for execution. Listing 3 shows the most basic use of StableValue.

Listing 3 - StableValue Logger

package org.thoth.jdk25.jep502.main.proposed;

import java.util.logging.Logger;

public class StableValueLogger {
  private final StableValue<Logger> logger = StableValue.of();

  Logger getLog() {
    return logger.orElseSet(() -> Logger.getLogger(StableValueLogger.class.getName()));
  }

  public void service() {
    getLog().info("service() method start");
  }
}

On line 6, see that the logger property is no longer a Logger instance but a StableValue<Logger> instance instead. The getLog() method calls the StableValue.orElseSet() method. The supplied lambda to this method knows how to create the Logger when needed. The orElseSet() method guarantees the lambda is evaluated only once even in a multi-threaded environment.

While using StableValue<Logger> results in a guaranteed single instance and thread safety, it unfortunately means accessing the Logger through the getLog() method to initialize the Logger object and return it. If getLog() is not used, there is no risk of a NullPointerException, but, using the StableValue API methods directly every time a Logger was needed would be very verbose and ugly. It would be more convenient if the logger property could be used more directly. This can be accomplished using a stable supplier. Listing 4 demonstrates this.

Listing 4 - Stable Supplier Logger

package org.thoth.jdk25.jep502.main.proposed;

import java.util.function.Supplier;
import java.util.logging.Logger;

public class StableSupplierLogger {
  private final Supplier<Logger> logger 
    = StableValue.supplier(() -> Logger.getLogger(StableSupplierLogger.class.getName()));

  public void service() {
    logger.get().info("service() method start");
  }
}

On line 7, see that the logger property is no longer a Logger instance but a Supplier<Logger> instance instead. The lambda passed to StableValue.supplier() is responsible for creating a Logger when evaluated.

On line 11, see that the Supplier.get() method is called. Similar to the orElseSet() method, the lambda is guaranteed to evaluate only once even in a multi-threaded environment. While using the Supplier.get() method is still an intermediary step needed to get the Logger, using this instance method is a better user experience than using a custom private getLog() method.

Summary

This has been a quick look into JEP 502: Stable Values (Preview). It is a new API, giving the JVM the ability to manage the creation of immutable objects. Having the JVM manage the creation of the objects conserves resources by creating objects only when needed and optimizes performance by treating them as final constant values. This is a preview feature so look for it to be finalized in a future release.

References

Minborg, P., Cimadamore, M. (2023, July 24). JEP 502: Stable Values (Preview). https://openjdk.org/jeps/502.

July 29, 2025

JDK 25 - JEP 470: PEM Encodings of Cryptographic Objects (Preview)

Abstract

JDK 25 - JEP 470: PEM Encodings of Cryptographic Objects (Preview). The Privacy-Enhanced Mail (PEM) format https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail defined by RFC 7468 https://www.rfc-editor.org/rfc/rfc7468 is a representation of cryptographic objects. This JEP adds encoding and decoding of the PEM format to Java.

Disclaimer

This post is solely informative. Critically think before using any information presented. Learn from it but ultimately make your own decisions at your own risk.

Requirements

I did all of the work for this post using the following major technologies. You may be able to do the same thing with different technologies or versions, but no guarantees.

openjdk 25-ea 2025–09–16 (build 25-ea+27–3363)
NetBeans 25
Maven 3.9.6 (Bundled with NetBeans)
maven-compiler-plugin-3.14.0

Download

Visit my GitHub page https://github.com/mjremijan to see all of my open source projects. The code for this post is located at https://github.com/mjremijan/thoth-jdk25

Compile and Run

This is a preview API, disabled by default. To use this API in JDK 25, you must enable preview APIs:

Compile the program with javac --release 25 --enable-preview Main.java and run it with java --enable-preview Main;
When using the source code launcher, run the program with java --enable-preview Main.java;
When using jshell, start it with jshell --enable-preview.

Java Generate public/private PEM files

Create a Java KeyPair and generate the public/private keys in PEM format.

Listing 1 - Java Generate Keys in PEM Format

package org.thoth.jdk25.jep470.main;

import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.security.PEMEncoder;
import java.security.SecureRandom;

/**
 */
public class MainInMemoryEncoding {

  public static void main(String[] args) throws Exception {
    System.out.printf("Hello JEP-470 In memory encoding!%n%n");
    
    System.out.printf("Create KeyPairGenerator for RSA%n");
    KeyPairGenerator generator 
      = KeyPairGenerator.getInstance("RSA");
    
    System.out.printf("Initialize KeyPairGenerator with a key size and SecureRandom%n");
    generator.initialize(2048, new SecureRandom());
    
    System.out.printf("Generate a KeyPair%n");
    KeyPair pair
      = generator.generateKeyPair();
    
    System.out.printf("Create PEMEncoder%n");
    PEMEncoder pe = PEMEncoder.of();
    
    System.out.printf("Encode private key to the PEM format%n");
    String privatePem = pe.encodeToString(pair.getPrivate());
    System.out.printf("%s%n", privatePem);
    
    System.out.printf("Encode public key to the PEM format%n");
    String publicPem = pe.encodeToString(pair.getPublic());
    System.out.printf("%s%n", publicPem);
  }
}

OpenSSL Generate public/private PEM files

Use the following Linux commands to generate public/private keys in PEM format saved to files.

Listing 2 - Generate 2048-bit RSA private key PEM file

openssl genrsa -out test-private.pem 2048

Listing 3 - Extract RSA public key PEM file

openssl rsa -in test-private.pem -out test-public.pem -pubout -outform PEM

Java read public OpenSSL PEM file

Read the test-public.pem file.

Listing 4 - Read test-public.pem

package org.thoth.jdk25.jep470.main;

import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.security.DEREncodable;
import java.security.PEMDecoder;
import java.security.PublicKey;

/**
 */
public class MainOpenSSLDecodingPublicFile {

  public static void main(String[] args) throws Exception {
    System.out.printf("Hello JEP-470! OpenSSL decoding public PEM file%n%n");
    
    System.out.printf("Read the OpenSSL test-public.pem file into a String%n");    
    InputStream is = MainOpenSSLDecodingPublicFile.class.getClassLoader().getResourceAsStream("test-public.pem");
    byte[] bytes = is.readAllBytes();
    String publicPem = new String(bytes, StandardCharsets.UTF_8);
    System.out.printf("%s%n", publicPem);
    
    System.out.printf("Create PEMDecoder%n");
    PEMDecoder pd = PEMDecoder.of();

    System.out.printf("Decode the OpenSSL test-public.pem file%n");
    DEREncodable derEncodable = pd.decode(publicPem);
    switch (derEncodable) {
      case PublicKey publicKey -> System.out.printf("Successfully decoded PublicKey!%n");  
      default -> System.out.printf("What is \"%s\"%n", derEncodable.getClass().getName());
    }      
  }
}

Java read private OpenSSL PEM file

Read the test-private.pem file.

Listing 5 - Read test-private.pem

package org.thoth.jdk25.jep470.main;

import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.security.DEREncodable;
import java.security.PEMDecoder;
import java.security.PrivateKey;

/**
 */
public class MainOpenSSLDecodingPrivateFile {
    public static void main(String[] args) throws Exception {
     System.out.printf("Hello JEP-470! OpenSSL decoding private PEM file%n%n");
     
     System.out.printf("Read the OpenSSL test-private.pem file into a String%n");
     InputStream is = MainOpenSSLDecodingPrivateFile.class.getClassLoader().getResourceAsStream("test-private.pem");
     byte[] bytes = is.readAllBytes();
     String privatePem = new String(bytes, StandardCharsets.UTF_8);
     System.out.printf("%s%n", privatePem);

     System.out.printf("Create PEMDecoder%n");
     PEMDecoder pd = PEMDecoder.of();
     
     System.out.printf("Decode the OpenSSL test-private.pem file%n");
     DEREncodable derEncodable = pd.decode(privatePem);
     switch (derEncodable) {
      case PrivateKey privateKey -> System.out.printf("Successfully decoded PrivateKey!%n");    
      default -> System.out.printf("What is \"%s\"%n", derEncodable.getClass().getName());
     }
  }
}

Summary

JEP 470 add PEM encoding and decoding functionality to Java. In JDK 25, it is a preview feature so look for it to be finalized in a future release.

References

Scarpino, A. (2023, January 23). JEP 470: PEM Encodings of Cryptographic Objects (Preview). https://openjdk.org/jeps/470

May 07, 2025

Email Notes to OneNote with IFTTT

Abstract

Microsoft officially retired the me@onenote.com email feature on March 26, 2025. This service previously allowed users to forward emails directly into their OneNote notebooks by sending them to that address.

The decision to discontinue this feature was due to low usage and the availability of more integrated alternatives. Microsoft recommends using the “Send to OneNote” feature within Outlook, which allows users to send emails and meeting invitations directly to specific OneNote notebooks and sections.

Unfortunately, I am one of those “low usage” people. I relied quite heavily on the me@onenote.com email feature. Using the “Send to OneNote” feature within Outlook of course is not remotely the same thing and an attempt by Microsoft to force people to Outlook for email.

Fortunately, I found a very simple and easy solution: IFTTT

Disclaimer

This post is solely informative. Critically think before using any information presented. Learn from it but ultimately make your own decisions at your own risk.

Requirements

I did all of the work for this post using the following IFTTT Applets available as of May 7, 2025.

“Forward important emails to OneNote”

Add and Configure IFTTT Applet

Click the “Explore” button

Search for “Forward important emails to OneNote”. It is an IFTTT Applet that looks like this:

Figure 1 - IFTTT Applet

Click “Connect” to get started with configuring this applet.

Figure 2 - IFTTT Connect Button

Once it is connected, configure the OneNote part of the applet so a new note is created in the Notebook and Section you want. In the example below, New notes will be created in my “Process” notebook inside the “Collect” section.

Figure 3 - IFTTT OneNote Configuration

Once this is all done, send an email to “trigger@applet.ifttt.com” and emails will show up in OneNote.

Summary

Use IFTTT to fill in the gap with Microsoft ending support for me@onenote.com.

February 04, 2025

arch42 Stakeholders for Software

Abstract

arch42 has a section to document the stakeholders of the platform. Stakeholders have different roles and expectations when interacting with the platform’s architecture documentation. The purpose of this post to describe a few common roles and how they relate to each other.

Disclaimer

This post is solely informative. Critically think before using any information presented. Learn from it but ultimately make your own decisions at your own risk.

Requirements

A solution architect documenting the roles and expectations of stakeholders for the platform.

Roles

There are many people involved with the platform. Each person has a particular role and expectation with respect to the platform architecture and its documentation. People may have many roles. ChatGPT was initially prompted with “in software development if the analyst owns the what and the architect owns the how, what does the developer own?”. It was then prompted with the follow-ups “what does the tester own?” and “what does the user own?”. Responses were used to describe roles and expectations.

Owner. The owner is expected to provide the platform team decisions about (a) underlying business goals, (b) platform features and functional (business) requirements, and (c) platform architecture and non-functional (quality) requirements.

Analyst. The analyst is expected to provide the platform team with fully documented functional (business) requirements of the platform features in fulfillment of the underlying business goals. The analyst owns the “what” of the platform’s operation and maintains it in the architecture documentation.

Architect. The architect is expected to provide the platform team with fully documented non-functional (quality) requirements of the platform features in fulfillment of the underlying quality goals. The architect owns the “how” of the platform’s operation and maintains it in the architecture documentation.

Developer. The developer is expected to provide the platform team with an implementation of the platform in fulfillment of both the functional (business) and non-functional (quality) requirements specified by the analyst and architect respectively. The developer owns the “do” of the platform’s operation and references the architecture documentation.

Tester. The tester is expected to provide the platform team with quality assurance of the platform in fulfillment of both the functional (business) and non-functional (quality) requirements specified by the analyst and architect respectively. The tester owns the “validate” of the platform’s operation and references the architecture documentation.

User. The user is expected to provide the platform team with feedback on the platform. The user owns the “experience” of the platform’s operation with no direct use of the architecture documentation.

No list like this can be exhaustive, but, for most platforms this is a good list of roles to start with. Update the expectations or add new roles as appropriate for your platform.

Summary

That’s it, enjoy!

References

arc42 Documentation. (n.d.). https://docs.arc42.org/home/

ISO 25010. (n.d.). https://iso25000.com/index.php/en/iso-25000-standards/iso-25010

OpenAI. (2025). ChatGPT (Feb 04 version) [Large language model]. https://chatgpt.com/

arch42 Quality Goals for Software Architects

Abstract

arch42 has a section to document the quality goal decisions of your system or software product. arch42 references the ISO 25010. This a great standard reference for solution architects to focus on the non-functional requirements important to the stakeholders. The purpose of this post is to show the ISO 25010 standard characteristics and sub-characteristics.

Disclaimer

This post is solely informative. Critically think before using any information presented. Learn from it but ultimately make your own decisions at your own risk.

Requirements

A solution architect working with stakeholders to document the 3–5 most important quality goal characteristics for a system or software product.

ISO 25010

Visit ISO 25010 to read more about the characteristics and sub-characteristics for product quality. Table 1 provides a summary. In general, these are all of the “-ility” statements.

Table 1 - ISO 25010 Quality Characteristics

Functional Stability	Performance Efficiency	Compatibility	Interaction Capability	Reliability	Security	Maintainability	Flexibility	Safety
Functional Completeness Functional Correctness Funcational Appropriateness	Time Behavior Resource Utilization Capacity	Co-Existence Interoperability	Appropriateness Recognizability Learnability Operability User Error Protection User Engagement Inclusivity User Assistance Self-Descriptiveness	Faultlessness Availability Fault Tolerance Recoverability	Confidentiality Integrity Non-Repudiation Accountability Authenticity Resistance Compliance	Modularity Reusability Analysability Modifiability Testability	Adaptability Scalability Installability Replaceability	Operational Constraint Risk Identification Fail Safe Hazard Warning Safe Integration

When deciding the quality goals used to architect and evaluate the system or software product, they should be listed as both characteristics and sub-characteristics as shown in Table 1.

Summary

That’s it, enjoy!

References

arc42 Documentation. (n.d.). https://docs.arc42.org/home/

ISO 25010. (n.d.). https://iso25000.com/index.php/en/iso-25000-standards/iso-25010

January 14, 2025

Apache Derby Database Select-for-Update

Abstract

Select-for-update is an SQL feature which I used to use all the time, but it seems like it’s use has fallen out of favor. However, there are valid use cases for it.

My ferris-resiste project is an RSS to email system. The system keeps track of all RSS entries it encounters to prevent emailing duplicates. However, how long do you keep this history of RSS entries? RSS data isn’t 100% reliable, so the system has its own way of determining when to delete RSS entries. Each time an RSS entry is encountered, the date it’s encountered is saved in the database. If an RSS entry isn’t encountered, that date isn’t updated. Deleting RSS entries is then a simple query which use this last encountered date to delete entries older than 6 months. If the RSS feed hasn’t had that RSS entry for the past 6 months, it’s probably safe to assume the system will not encounter it again.

This is a perfect use case for a select-for-update SQL statement. The purpose of this post is to demonstrate how a select-for-update statement works for the Apache Derby database.

Disclaimer

This post is solely informative. Critically think before using any information presented. Learn from it but ultimately make your own decisions at your own risk.

Code

Listing 1 is Java code demonstrating select-for-update for Apache Derby.

Listing 1 - Java select for update code for Apache Derby

public Optional<RssHistory> find(String feedId, String entryId) {
  
  log.info(String.format("Find RSS entry history feedId=\"%s\", entryId=\"%s\"", feedId, entryId));
  
  Optional<RssHistory> retval
    = Optional.empty();

  StringBuilder sp = new StringBuilder();
  sp.append(" select ");
  sp.append("     feed_id, entry_id, published_on, last_found_on ");
  sp.append(" from ");
  sp.append("     rss_entry_history ");
  sp.append(" where ");
  sp.append("     feed_id=? ");
  sp.append("     and ");
  sp.append("     entry_id=? ");
  sp.append(" for update of ");
  sp.append("     last_found_on ");

  PreparedStatement stmt = null;
  ResultSet rs = null;
  try {
    stmt = conn.prepareUpdatableStatement(sp.toString());
    
    stmt.setString(1, feedId);
    stmt.setString(2, entryId);

    rs = stmt.executeQuery();
    if (rs.next()) {
      retval = Optional.of(
        new RssHistory(feedId, feedId, rs.getTimestamp("published_on").toInstant())
      );
      
      rs.updateDate(4, Date.valueOf(LocalDate.now()));
      rs.updateRow();
    }

  } catch (Throwable t) {
    throw new RuntimeException(
      String.format("Problem finding feed entry in history table feedId=\"%s\", entryId=\"%s\", sql=\"%s\""
        , feedId, entryId, sp.toString()
      ), t
    );
  } finally {
    conn.close(stmt, rs);
  }

  return retval;
}

Lines 17,18 These lines make this a select-for-update query. Line 18 specifies the last_found_on field is being updated.

Line 23 Uses the prepareUpdatableStatement() method to get a Statement object.

Line 34 Uses the updateDate() method to set the new value for the last_found_on field.

Line 35 Uses the updateRow() method to save the updated data to the database within the select-for-update and without having to execute a separate update statement.

Summary

That’s it. Pretty simple. I hope you enjoyed learning how to run a select-for-update SQL statement in Apache Derby.

October 03, 2024

Apache Derby Database Series

Abstract

This is my series on the Apache Derby Database. Move beyond its basics and use a great database for your applications.

Apache Derby Database Users and Permissions. Learn how to create users in Derby and assign them different roles and permissions. This is for security control compliance and to protect your data.
Multiple Derby Network Servers on the same Host. Learn how to run multiple, independent, remote Derby servers on different ports within the same server or VM.
Derby Database Backup. Learn how to regularly schedule backups of Derby to protect yourself against data disasters.
Apache Derby Database JVM Security Policy. Learn how to run Derby with a Java Security Manager policy to limit the JVM’s permissions and enhance runtime security.
Integration Testing with Maven and an In-Memory Derby Database. Learn how to use Derby in-memory for application integration tests. NOTE I said integration tests; never use any kind of database for unit tests.
Apache Derby Database Select-for-Update. Learn how to execute a select-for-update statement with Apache Derby with a Java code example.

Disclaimer

This post is solely informative. Critically think before using any information presented. Learn from it but ultimately make your own decisions at your own risk.

Summary

That’s it. I hope you enjoy using Apache Derby!

March 11, 2023

Using PrismJS in Blogger for Code Highlighting

Abstract

For my blog, since I write mostly about technology and specifically software development, I needed a syntax highlighter for styling my source code examples.

I first started using SyntaxHighlighter to style source code. SyntaxHighligher works by add a class to a <pre> tag like this:

This worked well until I started writing my blog posts using Scrivener. With Scrivener, I write in Markdown and Scrivener compiles to HTML for me. The standard HTML to use for source code is a <pre> tag surrounding a <code> tag like this:

Unfortunately, SyntaxHighligher does not support this HTML so it no longer worked for me.

I then started using Highlight.js. This tool has been working well, but its styling is a little too simple. Plus I really wanted to start having line numbers added to my source code examples and Highlight.js does not support this.

It is time for another change. The purpose of this post is demonstrate how to incorporate the PrismJS syntax highlighting tool into Blogger.

Disclaimer

This post is solely informative. Critically think before using any information presented. Learn from it but ultimately make your own decisions at your own risk.

Requirements

I did all of the work for this post using the following major technologies. You may be able to do the same thing with different technologies or versions, but no guarantees.

Blogger
Scrivener 3
PrismJS 1.29

Download PrismJS

Visit the PrismJS download page: https://prismjs.com/download.html. On this page you are able to select the languages and plugins you want to include in your prism download. It is tempting to select everything, but, the reality is you will never use some of the languages listed. It only takes a few minutes to go through the language list and select the ones you use most often.

For PrismJS plugins, my primary reason for switching to PrismJS is the Line Numbers plugin. This is an important feature for me. I want to have line numbers added to my source code examples.

Another important plugin is the Autoloader plugin. If you try to style a language you have not previously included in your download, Autoloader will automatically get the styling for that language for you. This is good for occasional use. I would not rely on it all the time. If you start blogging about a new language regularly, re-download PrismJS with that language selected.

What is also nice about the PrismJS download page is that while you are selecting languages and plugins, the URL in your browser is automatically updated to reflect your selections. This means, once you are done selecting all the options you want, save the URL in your your favorite note-taking software (OneNote). Then all you need to do is click on the URL and you don’t have to go through selecting all your languages and plugins again. Very nice!

These are my selections: https://prismjs.com/download.html#themes=prism&languages=markup+css+clike+javascript+bash+http+java+javadoc+javadoclike+json+json5+plsql+python+regex+sql+typescript+yaml&plugins=line-numbers+autoloader

Host Your PrismJS Download on OneDrive

After you have downloaded the Prism JS and CSS files, the next thing you need to figure out is what to do with them. There are a couple options:

Cut and paste the contents inside your Blogger theme.
Host the JS and CSS files somewhere and update your Blogger template to use them.

Although option #2 is a bit more complicated, it is the better long-term option in my opinion. Blogger does not allow file uploads, so the files have to be hosted somewhere else. There are a number of different options where to host the files, but I chose to use my Microsoft OneDrive account to do this. I chose OneDrive because I already have an account, I use it all the time, and it is easy to use. Most online file upload system (Google Drive, etc.) allow you to get a read-only, permanent link to a file. That is exactly what we are going to to do.

I’m assuming you already know how to save a file on OneDrive, so I will start from there. Login to OneDrive with a web browser and navigate to the folder where you have the Prism JS and CSS files. As seen in Figure 1, you will need to click three times to generate the embedded code.

Select one of the files.
Click the “Embed” option.
Click the “Generate” button.

Figure 1 - Three Clicks to Generate Embedded Code

Figure 2 shows an embedded code example. You will notice it is an <iframe> tag with a src attribute (and a few others). We will be concentrating on the src attribute.

Figure 2 - The iframe Embedded Code

Let us take a look at the <iframe> tag a little more closely:

Extract the bolded URL like this:

https://onedrive.live.com/embed?cid=0C5144D8101C068D&resid=C5144D8101C068D%2127125&authkey=ADxgzT72UZ6zQQM

Then changed embed to download like this:

https://onedrive.live.com/download?cid=0C5144D8101C068D&resid=C5144D8101C068D%2127125&authkey=ADxgzT72UZ6zQQM

You will want to do this for both the JS file and the CSS file. When you are done you will have two URL values that look like this.

JS. https://onedrive.live.com/download?cid=0C5144D8101C068D&resid=C5144D8101C068D%2127124&authkey=AIhs3YZuWx_nl8k

CSS. https://onedrive.live.com/download?cid=0C5144D8101C068D&resid=C5144D8101C068D%2127125&authkey=ADxgzT72UZ6zQQM

These URL values are the direct links to your JS file and the CSS file. Test them by pasting the URL values into a browser. The browser should download the file without redirecting to OneDrive. If it does not download directly, something is not right and you should try again.

Now that we have the direct links to the hosted JS and CSS files, let us look at how we update the Blogger theme.

Blogger Theme Updates

Now that the Prism JS and CSS files are hosted on OneDrive and I have permanent URL values to retrieve them, I now need to update my Blogger theme to use these files. I will need to make two updates to the Blogger theme:

Include both the JS and CSS files.
Add the ‘line-numbers’ class to the <body> tag.

Let us take a look at how to do both.

Include both the JS and CSS files

The JS file gets included with a <script> tag and the CS file gets included with a <link> tag. Start by creating both of these tags and drop in the permanent URL values like this:

JS. <script src=‘https://onedrive.live.com/download?cid=0C5144D8101C068D&resid=C5144D8101C068D%2127124&authkey=AIhs3YZuWx_nl8k’ type=‘text/javascript’/>

CSS. <link href=‘https://onedrive.live.com/download?cid=0C5144D8101C068D&resid=C5144D8101C068D%2127125&authkey=ADxgzT72UZ6zQQM’ rel=‘stylesheet’/>

However, your not done yet! Normally this is all you need to do, but Blogger themes have a bit of a quirk. They seem to be saved as XML so the & characters in the URL values are a problem. To successfully save these tags to the Blogger theme, you need to escape the & characters with & like this:

JS. <script src=‘https://onedrive.live.com/download?cid=0C5144D8101C068D&resid=C5144D8101C068D%2127124&authkey=AIhs3YZuWx_nl8k’ type=‘text/javascript’/>

CSS. <link href=‘https://onedrive.live.com/download?cid=0C5144D8101C068D&resid=C5144D8101C068D%2127125&authkey=ADxgzT72UZ6zQQM’ rel=‘stylesheet’/>

These tags are now ready to be used in the Blogger theme.

Add the ‘line-numbers’ class to the <body> tag

Recall that one of the reasons I am switching to Prism is because it was important to me to have line numbers added to my source code examples. This is done by the Prism Line Numbers plugin. To use this plugin, you need to do is add the ‘line-numbers’ class to the <body> tag within the Blogger theme. It looks like this:

Now let us get these updates into the Blogger theme.

Updating the Blogger Theme

After you log into your blog, perform the following steps as shown in Figures 3 and 4:

Click “Theme” on the left
Click the down-pointing arrow
Select “Edit HTML”

Figure 3 - Blogger Theme Customization

Figure 4 - Blogger Edit HTML

Your are now looking at the HTML template of your blog’s theme. The Prism <script> and <link> tags you created above need to go somewhere within the opening and closing <head></head> tags so it looks like this:

<head>

</head>

The update to <body> is even easier. Just search the template for “<body” and update it to include the “line-numbers” class.

NOTE An HTML element can have multiple class values. The values are separated by a blank space. So note in the example below the blank space between loading and line-numbers.

That’s it! Save the file and you are good to go!

Examples

Let us take a look at a few source code syntax highlighting examples to make sure everything is working OK.

Listing 1 - Java

package org.prism.example;

public static final void main(String [] args) {
    System.out.println("Hello world!");
}

Listing 2 - JavaScript

const baseValue = prompt('Enter the base of a triangle: ');
const heightValue = prompt('Enter the height of a triangle: ');

// calculate the area
const areaValue = (baseValue * heightValue) / 2;

console.log(
  `The area of the triangle is ${areaValue}`
);

Listing 3 - TypeScript

class Employee {
    id: number;
    firstName: string;
    lastName: string;

    constructor(id: number, firstName: string, lastName: string) 
    {
        this.id = id;
        this.firstName = firstName;
        this.lastName = lastName;
    }

    getFullName() {
        return this.firstName + ' ' + this.lastName;
    }
}

// create Employee class object
let employee = new Employee(100, 'Rita', 'Red');
console.log(employee);
console.log(employee.getFullName());

Listing 4 - PL/SQL

DECLARE
  name VARCHAR2(50);
BEGIN
  name := 'Rita';
  DBMS_OUTPUT.PUT_LINE('Hello, ' || name);
END;


FOR i IN 1..10 LOOP
  DBMS_OUTPUT.PUT_LINE('i = ' || i);
END LOOP;

Listing 5 - XML

<Catalog>
	<CD>
		<Title>Empire Burlesque</Title>
		<Artist>Bob Dylan</Artist>
		<Country>USA</Country>
		<Company>Columbia</Company>
		<Price>10.90</Price>
		<Year>1985</Year>
	</CD>
	<CD>
		<Title>Greatest Hits</Title>
		<Artist>Dolly Parton</Artist>
		<Country>USA</Country>
		<Company>RCA</Company>
		<Price>9.90</Price>
		<Year>1982</Year>
	</CD>
</Catalog>

Listing 6 - HTML

<!DOCTYPE html>
<html>
<body>

<h1>My First Heading</h1>
<p>My first paragraph.</p>

</body>
</html>

Listing 7 - JSON

{
  "colors": [
    {
      "color": "red",
      "category": "hue",
      "type": "primary",
      "code": {
        "rgba": [255,0,0,1],
        "hex": "#FF0"
      }
    },
    {
      "color": "blue",
      "category": "hue",
      "type": "primary",
      "code": {
        "rgba": [0,0,255,1],
        "hex": "#00F"
      }
    },
    {
      "color": "yellow",
      "category": "hue",
      "type": "primary",
      "code": {
        "rgba": [255,255,0,1],
        "hex": "#FF0"
      }
    },
    {
      "color": "green",
      "category": "hue",
      "type": "secondary",
      "code": {
        "rgba": [0,255,0,1],
        "hex": "#0F0"
      }
    }
  ]
}

Summary

PrismJS is a nice syntax highlighter for source code examples. Using it with Blogger is a little work, but not too complicated.

Visit the PrismJS download page: https://prismjs.com/download.html and download what you will use most often.

Host the downloaded JS and CSS files on the technology of your choice. My example used OneDrive. You can also use Google Drive, GitLab, AWS, Azure, and I’m sure there are others.

Include the JS and CSS files in the Blogger theme by updating the template:

<head>

</head>

Add the “line-numbers” class to the <body> tag to support the Line Numbers plugin.

Save the template change, create a blog with source code examples, and that’s it!

Enjoy!

February 02, 2023

Creating, Signing, and Verifying JWT in Java

Abstract

You use JWTs don’t you? Everyone does, right? But do you know how to generate, sign, and verify them? The purpose of this post is to demonstrate how to code all these operations.

Disclaimer

This post is solely informative. Critically think before using any information presented. Learn from it but ultimately make your own decisions at your own risk.

Requirements

I did all of the work for this post using the following major technologies. You may be able to do the same thing with different technologies or versions, but no guarantees.

Java 11
Maven 3.8.6 (Bundled with NetBeans)

Download

Visit my GitHub page https://github.com/mjremijan to see all of my open source projects. The code for this post is located at: https://github.com/mjremijan/thoth-jwt

Introduction

A JWT is a simple three-part string of encoded characters - header, payload, signature - separated by 2 “.” characters.

xxxxx.yyyyy.zzzzz

JWT technology has been around for years. Read all about the JWT specification on the Introduction to JSON Web Tokens at https://jwt.io/introduction. This blog focuses on the Java code to create and verify JWT values. There are 2 examples:

JWT with Symmetric HMAC SHA256 Signature
JWT with Asymmetric RSA SHA256 Signature

Let’s take a look at them.

JWT with Symmetric HMAC SHA256 Signature

Listing 1 shows the code and Listing 2 shows example output.

Listing 1 - JWT with Symmetric HMAC SHA256 Signature

1. package org.thoth.jwt.main;
2. 
3. import java.util.Base64;
4. import javax.crypto.Mac;
5. import javax.crypto.spec.SecretKeySpec;
6. 
7. /**
8.  *
9.  * @author Michael Remijan mjremijan@yahoo.com @mjremijan
10.  */
11. public class SignatureWithSymmetricalHmacSha256Main 
12. {
13.     public static void main(String[] args) throws Exception 
14.     {
15.         // JWT HEADER
16.         //
17.         // This is the xxxxx of a JWT xxxxx.yyyyy.zzzzz
18.         //
19.         // Given the following JSON document, encode it
20.         // using Java as defined in the JWT specifications
21.         String header = "{\"alg\":\"HS256\",\"typ\": \"JWT\"}";
22.         String headerEncoded 
23.             = Base64.getUrlEncoder()
24.                     .withoutPadding()
25.                     .encodeToString(
26.                         header.getBytes()
27.                     );
28.         String headerDecoded
29.                 = new String(
30.                     Base64.getUrlDecoder().decode(headerEncoded)
31.                 );
32.         
33.         System.out.printf("Header Plain   : %s%n", header);
34.         System.out.printf("Header Encoded : %s%n", headerEncoded);
35.         System.out.printf("Header Decoded : %s%n", headerDecoded);
36.         
37.         
38.         // JWT PAYLOAD
39.         //
40.         // This is the yyyyy of a JWT xxxxx.yyyyy.zzzzz
41.         //
42.         // Given the following JSON document, encode it
43.         // using Java as defined in the JWT specifications
44.         String payload = "{\"sub\":\"TMJR00001\",\"name\":\"Michael J. Remijan\",\"exp\":61475608800,\"iss\":\"info@wstutorial.com\",\"groups\":[\"user\",\"admin\"]}";
45.         String payloadEncoded 
46.             = Base64.getUrlEncoder()
47.                     .withoutPadding()
48.                     .encodeToString(
49.                         payload.getBytes()
50.                     );
51.         
52.         String payloadDecoded
53.                 = new String(
54.                     Base64.getUrlDecoder().decode(payloadEncoded)
55.                 );
56.         
57.         System.out.printf("%n");
58.         System.out.printf("Payload Plain   : %s%n", payload);
59.         System.out.printf("Payload Encoded : %s%n", payloadEncoded);
60.         System.out.printf("Payload Decoded : %s%n", payloadDecoded);
61.         
62.     
63.         // SIGNATURE / VERIFY
64.         // This is the zzzzz of a JWT xxxxx.yyyyy.zzzzz
65.         //
66.         // Hash-based message authentication code(HMAC)
67.         // is a specific type of message authentication code 
68.         // (MAC) involving a cryptographic hash function and 
69.         // a secret cryptographic key. As with any MAC, it 
70.         // may be used to simultaneously verify both the data
71.         // integrity and authenticity of a message.
72.         // 
73.         // A cryptographic hash function (CHF) is any function 
74.         // that can be used to map data of arbitrary size to 
75.         // a fixed-size number of n bits that has special 
76.         // properties desirable for a cryptographic application.
77.         //
78.         // For this example, the process will use the SHA256
79.         // cryptographic hash function and a secret key
80.         // to generate a signatureCreatedFromThisData (hash) of the JWT data.
81.         // This signatureCreatedFromThisData can then be used to verify the
82.         // JWT data has not been tampered.
83.         //
84.         // Typically the secret key is only available on the 
85.         // Authentication Server. The key is used to create the 
86.         // signatureCreatedFromThisData for the JWT. Clients will typically make 
87.         // an authentication request (HTTPS) to the Authentication
88.         // server to verify a JWT. Clients cannot verify a JWT 
89.         // themselves because they do not have access to the
90.         // secret key. However, if a Client is 100% trusted,
91.         // The secret key can be shared with the Client so
92.         // that the Client can do its own verification. 
93.         // WARNING: This means the Client will also be able 
94.         // to make new JWTs, which can be dangerous.
95.         String algorithm  = "HmacSHA256";
96.         String secret = "thisismysupersecretkeywhichshouldonlybeontheauthenticationserver";
97.         SecretKeySpec key = new SecretKeySpec(secret.getBytes(), algorithm);
98.         Mac mac = Mac.getInstance(algorithm);
99.         mac.init(key);
100.         String signatureCreatedFromThisData 
101.             = headerEncoded + "." + payloadEncoded;
102.         String signatureEncoded 
103.             = Base64.getUrlEncoder()
104.                     .withoutPadding()
105.                     .encodeToString(mac.doFinal(
106.                             signatureCreatedFromThisData.getBytes()
107.                         )
108.                     );
109.         
110.         System.out.printf("%n");
111.         System.out.printf("Signature Algorithm : %s%n", algorithm);
112.         System.out.printf("Signature Secret    : %s%n", secret);
113.         System.out.printf("Signaure Encoded    :%s%n", signatureEncoded);
114.     }
115. }
116.

Listing 2 - HMAC Example Output

Header Plain   : {"alg":"HS256","typ": "JWT"}
Header Encoded : eyJhbGciOiJIUzI1NiIsInR5cCI6ICJKV1QifQ
Header Decoded : {"alg":"HS256","typ": "JWT"}

Payload Plain   : {"sub":"TMJR00001","name":"Michael J. Remijan","exp":61475608800,"iss":"info@wstutorial.com","groups":["user","admin"]}
Payload Encoded : eyJzdWIiOiJUTUpSMDAwMDEiLCJuYW1lIjoiTWljaGFlbCBKLiBSZW1pamFuIiwiZXhwIjo2MTQ3NTYwODgwMCwiaXNzIjoiaW5mb0B3c3R1dG9yaWFsLmNvbSIsImdyb3VwcyI6WyJ1c2VyIiwiYWRtaW4iXX0
Payload Decoded : {"sub":"TMJR00001","name":"Michael J. Remijan","exp":61475608800,"iss":"info@wstutorial.com","groups":["user","admin"]}

Signature Algorithm : HmacSHA256
Signature Secret    : thisismysupersecretkeywhichshouldonlybeontheauthenticationserver
Signaure Encoded    :Xi6kVafrGX18FQIkNZuVJVBbmGbmEzI8cM-5G02S32A

Line #21 of Listing 1 starts the creation of the JWT header. This is the xxxxx part of a xxxxx.yyyyy.zzzzz JWT. As you can see, the code is simple. Use Base64.getUrlEncoder().withoutPadding() for encoding and Base64.getUrlDecoder() for decoding.

NOTE Make sure to use the **.withoutPadding()** encoder. If not, trailing “=” characters will be added by the encoder to make the encoded string the necessary length. These trailing “=” are not allowed by the JWT specification so if you have them, other JWT decoders won’t be able to decode your JWT properly.

Line #44 of Listing 1 starts the creation of the JWT payload, typically user information, but in theory can be anything. This is the yyyyy part of a xxxxx.yyyyy.zzzzz JWT. As you can see, the code is simple. Use Base64.getUrlEncoder().withoutPadding() for encoding and Base64.getUrlDecoder() for decoding. See NOTE above about using the .withoutPadding() encoder.

Line #95 of Listing 1 starts the creation of the JWT signature. This is the zzzzz part of a xxxxx.yyyyy.zzzzz JWT. Listing 1 is an example of using the "alg":"HS256" aka HmacSHA256 algorithm. This is a single-key, symmetric algorithm which relies on a user-generated secret value as seen on line #96. This secret typically is stored outside the application in some kind of configuration system (file, git, database, etc.). Staring with line #102, you see how the MAC is used to finish the hash and the Base64.getUrlEncoder().withoutPadding() is used to encode the hash.

You’ll notice that after signing, there is no more code in Listing 1. Where’s the code showing how to verify a JWT? Well with a single-key, symmetric algorithm like HmacSHA256, the signing and verifying steps are exactly the same. To verify, the signature needs to be generated again and compared with the zzzzz part of a xxxxx.yyyyy.zzzzz JWT.

That’s it for JWT with Symmetric HMAC SHA256 Signature.

JWT with Asymmetric RSA SHA256 Signature

Listing 3 shows the code and Listing 4 shows example output.

Listing 3 - JWT with Asymmetric RSA SHA256 Signature

1. package org.thoth.jwt.main;
2. 
3. import java.security.KeyPair;
4. import java.security.KeyPairGenerator;
5. import java.security.PrivateKey;
6. import java.security.PublicKey;
7. import java.security.Signature;
8. import java.util.Base64;
9. 
10. /**
11.  *
12.  * @author Michael Remijan mjremijan@yahoo.com @mjremijan
13.  */
14. public class SignatureWithAsymmetricalRsaSha256Main 
15. {
16.     public static void main(String[] args) throws Exception 
17.     {
18.         // JWT HEADER
19.         //
20.         // This is the xxxxx of a JWT xxxxx.yyyyy.zzzzz
21.         //
22.         // Given the following JSON document, encode it
23.         // using Java as defined in the JWT specifications
24.         String header = "{\"alg\":\"RS256\",\"typ\": \"JWT\"}";
25.         String headerEncoded 
26.             = Base64.getUrlEncoder()
27.                     .withoutPadding()
28.                     .encodeToString(
29.                         header.getBytes()
30.                     );
31.         String headerDecoded
32.                 = new String(
33.                     Base64.getUrlDecoder().decode(headerEncoded)
34.                 );
35.         
36.         System.out.printf("Header Plain   : %s%n", header);
37.         System.out.printf("Header Encoded : %s%n", headerEncoded);
38.         System.out.printf("Header Decoded : %s%n", headerDecoded);
39.         
40.         
41.         // JWT PAYLOAD
42.         //
43.         // This is the yyyyy of a JWT xxxxx.yyyyy.zzzzz
44.         //
45.         // Given the following JSON document, encode it
46.         // using Java as defined in the JWT specifications
47.         String payload = "{\"sub\":\"TMJR00001\",\"name\":\"Michael J. Remijan\",\"exp\":61475608800,\"iss\":\"info@wstutorial.com\",\"groups\":[\"user\",\"admin\"]}";
48.         String payloadEncoded 
49.             = Base64.getUrlEncoder()
50.                     .withoutPadding()
51.                     .encodeToString(
52.                         payload.getBytes()
53.                     );
54.         
55.         String payloadDecoded
56.                 = new String(
57.                     Base64.getUrlDecoder().decode(payloadEncoded)
58.                 );
59.         
60.         System.out.printf("%n");
61.         System.out.printf("Payload Plain   : %s%n", payload);
62.         System.out.printf("Payload Encoded : %s%n", payloadEncoded);
63.         System.out.printf("Payload Decoded : %s%n", payloadDecoded);
64.         
65.     
66.         // SIGNATURE
67.         //
68.         // This is the zzzzz of a JWT xxxxx.yyyyy.zzzzz
69.         //
70.         // RSA (Rivest--Shamir--Adleman) is a public-key cryptosystem 
71.         // that is widely used for secure data transmission.
72.         // In a public-key cryptosystem, the public key is used for
73.         // encryption and the private key is used for decryption. The
74.         // private key is also used for creating digital signatures
75.         // of data and the public key is used for verifying the
76.         // digital signature.
77.         //
78.         // A cryptographic hash function (CHF) is any function 
79.         // that can be used to map data of arbitrary size to 
80.         // a fixed-size number of n bits that has special 
81.         // properties desirable for a cryptographic application.
82.         //
83.         // For this example, the process will use the SHA256
84.         // cryptographic hash function along with a public/private
85.         // keypair and the RSA encryption algorithm to generate
86.         // a signature for the JWT.
87.         //
88.         // The private key is used for creating the signature.
89.         //
90.         KeyPairGenerator keyGenerator = KeyPairGenerator.getInstance("RSA");
91.         keyGenerator.initialize(1024);
92.         KeyPair kp = keyGenerator.genKeyPair();
93.         PublicKey publicKey = (PublicKey) kp.getPublic();
94.         PrivateKey privateKey = (PrivateKey) kp.getPrivate();
95.         String algorithm = "SHA256withRSA";
96.         String signatureCreatedFromThisData 
97.             = headerEncoded + "." + payloadEncoded;
98.         
99.         Signature privateSignature 
100.             = Signature.getInstance(algorithm);
101.         privateSignature.initSign(privateKey);
102.         
103.         System.out.printf("%n");
104.         System.out.printf("Algorithm    : %s%n", algorithm);
105.         System.out.printf("Public Key   : %s%n", Base64.getEncoder().encodeToString(publicKey.getEncoded()));
106.         System.out.printf("Private Key  : %s%n", Base64.getEncoder().encodeToString(privateKey.getEncoded()));
107.         
108.         privateSignature.update(signatureCreatedFromThisData.getBytes());
109.         String signatureEncoded 
110.                 = Base64.getUrlEncoder()
111.                         .withoutPadding()
112.                         .encodeToString(
113.                             privateSignature.sign()
114.                         );
115.         System.out.printf("%n");
116.         System.out.printf("Signaure Encoded         : %s%n", signatureEncoded);
117.         
118.         // VERIFY
119.         // This is the zzzzz of a JWT xxxxx.yyyyy.zzzzz
120.         //
121.         // The public key is used for verifying the signature.
122.         //
123.         // Becuase the public key is used for creating a signature,
124.         // it safe to distribute the public key to Clients so 
125.         // that Clients can verify the JWT signature without
126.         // having to ask the Authentication Server for verification
127.         //
128.         
129.         Signature publicSignature = Signature.getInstance(algorithm);
130.         publicSignature.initVerify(publicKey);
131.         publicSignature.update(signatureCreatedFromThisData.getBytes());
132.         boolean verified = publicSignature.verify(
133.             Base64.getUrlDecoder().decode(signatureEncoded)
134.         );
135.         System.out.printf("Signature Verified (t/f) : %b%n", verified);
136.     }
137. }
138.

Listing 4 - RSA Example Output

Header Plain   : {"alg":"RS256","typ": "JWT"}
Header Encoded : eyJhbGciOiJSUzI1NiIsInR5cCI6ICJKV1QifQ
Header Decoded : {"alg":"RS256","typ": "JWT"}

Payload Plain   : {"sub":"TMJR00001","name":"Michael J. Remijan","exp":61475608800,"iss":"info@wstutorial.com","groups":["user","admin"]}
Payload Encoded : eyJzdWIiOiJUTUpSMDAwMDEiLCJuYW1lIjoiTWljaGFlbCBKLiBSZW1pamFuIiwiZXhwIjo2MTQ3NTYwODgwMCwiaXNzIjoiaW5mb0B3c3R1dG9yaWFsLmNvbSIsImdyb3VwcyI6WyJ1c2VyIiwiYWRtaW4iXX0
Payload Decoded : {"sub":"TMJR00001","name":"Michael J. Remijan","exp":61475608800,"iss":"info@wstutorial.com","groups":["user","admin"]}

Algorithm    : SHA256withRSA
Public Key   : MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDRxw6Ncvsx0/kDYKwA6pLwn3hSbRdYFBOv1aiBomF7lPfOPfqaTgN2yPN6hErlLAP2d+94ig4uXv7MROXlsn8n7jdr2g5yo/kC92RJwALpffzBlWh29hEadiznWp2u0b0h++Cn4HJejfJpZOek6wurBL/7K2Y2TELOg8eg1uipEwIDAQAB
Private Key  : MIICdwIBADANBgkqhkiG9w0BAQEFAASCAmEwggJdAgEAAoGBANHHDo1y+zHT+QNgrADqkvCfeFJtF1gUE6/VqIGiYXuU9849+ppOA3bI83qESuUsA/Z373iKDi5e/sxE5eWyfyfuN2vaDnKj+QL3ZEnAAul9/MGVaHb2ERp2LOdana7RvSH74Kfgcl6N8mlk56TrC6sEv/srZjZMQs6Dx6DW6KkTAgMBAAECgYBqVyPzZGQeADxtD+ZhmIfgXpaaAh8hURwhuIdxH6WXBg8Qh66v5fgvkPKMGt/0iHmByY6lZiaGLzWuywZXiEKYSl6tpK8WtiY+gyYxOVgFckAKzjBJ4GYb6YvPI5p5/qDFqN/9Ca4vDn9URFEIRSBIc1it8TWzze8x2Ljd4vu54QJBAOmlSJ/m4dHJMzLnyM6Y1x/e2fqm48DbfV3m+jDjyR7YrTwcVoZSC17B1z4J7W+/Ea7N61UWRRvelvC4c8OKkEkCQQDl2StC7vbKCsnDAFyDjUADq7p2aE+vVH7v7ZUjHhsTXMF8TFMgfkxl5cH58nDNq1Yo82SKGvMeRnmBYHeHlqZ7AkBP1Ur4YBJ+9QmKdkpV1UGEQUgn7ghaKGUwxbBtLhfVc2HV7TTfVn9OFFuwdgHsMdQf73peq2pXuHnIrK3ZfaoJAkEAh0nXg/NCAdRtw8C/s5L9feujujRVyt6SRMj0ApKi3ze2j2Ihf7u3XjbpgSRprzVNZpc0s3F/bm+O708HrCBJZwJBANPeVhBizgqPZOiQxLRxpNN2+EvEfs8js7YFRwB45orM/+9yVelNojEKxcHT7zS6j59dTlwvbGp6LVrKCrwtwLw=

Signaure Encoded         : HO4FLrLDt4ObECVWRiUGIGUimU1M70Y9aILT5op0UkV-kbEx8AqjCsLTh-Y1zOAisvFmuH5LYRw1wQyncQ5uEUWJYcoeldr-1_uFlpD2LqUy-QZfng8e6pxXOopL8Of_OcNEOqRijmI_dob8Gf0UnT7GQWpGTl32cIuuIFDeRHo
Signature Verified (t/f) : true

Line #24 of Listing 3 starts the creation of the JWT header. This is the xxxxx part of a xxxxx.yyyyy.zzzzz JWT. As you can see, the code is simple. Use Base64.getUrlEncoder().withoutPadding() for encoding and Base64.getUrlDecoder() for decoding.

NOTE Make sure to use the **.withoutPadding()** encoder. If not, trailing “=” characters will be added by the encoder to make the encoded string the necessary length. These trailing “=” are not allowed by the JWT specification so if you have them, other JWT decoders won’t be able to decode your JWT properly.

Line #47 of Listing 3 starts the creation of the JWT payload, typically user information, but in theory can be anything. This is the yyyyy part of a xxxxx.yyyyy.zzzzz JWT. As you can see, the code is simple. Use Base64.getUrlEncoder().withoutPadding() for encoding and Base64.getUrlDecoder() for decoding. See NOTE above about using the .withoutPadding() encoder.

Line #90 of Listing 3 starts the creation of the JWT signature. This is the zzzzz part of a xxxxx.yyyyy.zzzzz JWT. Listing 3 is an example of using the "alg":"RS256" aka SHA256withRSA algorithm. This is a two-key, asymmetric algorithm which relies on a public/private keypair created on Line #92. A Signature object is created on line #99 and it is initialized with the private key. Staring with line #108, see how the Signature is used to create a signature and the Base64.getUrlEncoder().withoutPadding() is used to encode the signature.

NOTE The public/private keypair will need to be generated outside the application and kept in some kind of configuration store (file, git, database, etc.). This is an exercise left up to you.

Line #129 of Listing 3 starts the verify process. A Client may verify a JWT it receives from an Authentication server to guard against tampering while in transit. To verify a JWT created using an asymmetric RSA SHA256 signature, the Client will need the public key. This typically is not a problem since public keys are designed to be giving away. Line #132 demonstrates the call to .verify().

That’s it for JWT with Asymmetric RSA SHA256 Signature.

Summary

Most of this blog is the code. Review the code, top to bottom, it is not overly complicated. But now you know how to create and verify JWT values using both a Symmetric HMAC SHA256 Signature and an Asymmetric RSA SHA256 Signature.

Enjoy!

References

Introduction to JSON Web Tokens. (n.d.). JWT. https://jwt.io/introduction.

Debugger. (n.d.). JWT. https://jwt.io/#debugger-io

Alx. (2017, December). Create jwt in java using Public key rsa. https://wstutorial.com/misc/jwt-java-public-key-rsa.html

Base64 withoutPadding Encoding of string or byte array (Java8). (n.d.). MakeInJava Tutorials. https://makeinjava.com/base64-withoutpadding-encoding-string-byte-array-java8/

Poulsen, Søren. (n.d.). Calculate HMAC-Sha256 with Java. https://sorenpoulsen.com/calculate-hmac-sha256-with-java

Dommerholt, Niels. (2016, December 28). Example of RSA generation, sign, verify, encryption, decryption and keystores in Java. https://gist.github.com/nielsutrecht/855f3bef0cf559d8d23e94e2aecd4ede1

HMAC. (2023, January 1). Wikipedia. https://en.wikipedia.org/wiki/HMAC

Cryptographic hash function. (2023, January 10). Wikipedia. https://en.wikipedia.org/wiki/Cryptographic_hash_function

Hash function. (2023, February 1). Wikipedia. https://en.wikipedia.org/wiki/Hash_function

December 08, 2022

Automatically Delete Emails in Outlook Based on Age

Abstract

Do you get a lot of email notifications? I’m particularity thinking of daily notifications from your system which you largely ignore but still fill up your mailbox. This post is a short tutorial on how you can use the AutoArchive feature in Outlook to automatically delete these emails yet keep some recent emails for review.

Disclaimer

This post is solely informative. Critically think before using any information presented. Learn from it but ultimately make your own decisions at your own risk.

Requirements

I did all of the work for this post using the following major technologies. You may be able to do the same thing with different technologies or versions, but no guarantees.

Outlook from Microsoft 365

Introduction

My inbox fills up with “monitoring” emails which are sent by multiple servers every day. Do I review all these emails every day? Nope. Most times I don’t look at them for weeks, the emails build up into the hundreds, and when I do finally review them, I’m only interested in the latest ones. To help manage this, I configured the Outlook AutoArchive feature to automatically delete old emails I’m no longer interested in. Doing this is very easy.

Folder properties

First, right click on the folder (I’m sure you have already created a rule that moves the emails to a certain folder which you’ve been ignoring) and select properties as shown in figure 1.

Figure 1 - Folder Properties

AutoArchive Configuration

Next, select the AutoArchive tab and configure it the way you want. As you can see in figure 2, I have my folder configured to permanently delete emails which are older than 1 week.

Figure 2 - AutoArchive Configuration

Summary

That’s it. Very simple. Enjoy!

November 17, 2022

Pragmatic Strategy for Deconstructing a Monolith into Microservices

Abstract

This article is a result of more than a year of research and study (2019–2020) into the microservice design pattern, domain driven design (DDD), feature driven design (FDD), hexagonal (ports and adapters) architecture, and event storming. I started studying just microservices but was quickly lead to the other topics because they all seemed to have a synergy with each other. I gained a lot of knowledge during my studies, but was disappointed this knowledge was mostly theoretical. Practical questions like, “What is a domain?” or “How do I deconstruct my monolith?” were hand-waved with the answer, “It depends”. As a software architect, I felt I needed to be able to give better answers.

The purpose of this article is to make an attempt to combine all of these theoretical patterns, designs, and architectures with the ultimate goal of creating a pragmatic strategy for deconstructing a monolith into microservices. By pragmatic, I mean an actual step-by-step guide that is realistic and actionable that will get you from monolith to microservices.

Disclaimer

This post is solely informative. Critically think before using any information presented. Learn from it but ultimately make your own decisions at your own risk.

This post also assumes you are not Google, Facebook, Uber, Spotify, etc, who necessarily have solution patterns which are largely not applicable to most everyday applications.

Why a Strategy?

You might be asking yourself, “A pragmatic strategy for deconstructing a monolith? A step-by-step guide that is realistic and actionable?”

IMPOSSIBLE!

I bet that is what you are thinking. After all, “You don’t know MY monolith!”

That is true. I do not know YOUR monolith, but I know MONOLITHS. I also know that no strategy will ever be 100%. But what if the strategy is 90%? Or even 75%? Personally, I would rather start with some kind of strategy instead of no strategy at all.

Why is a pragmatic strategy for deconstructing a monolith needed? Why not just start coding and see what happens? Let us take a look at a few thoughts about doing this.

First, consider well-known architect Grady Booch’s comments about agile and architecture. Agile (typically scrum) is all the rage and with agile you throw away documentation and design in favor of code, code, code! The common thought is that agile will eventually get you to a good architecture. This is just not true. We all know it is not true, but we continue to do it anyway. Why? Because of the hope that agile may get you a good architecture by accident. What does Grady Booch have to say about this? “Don’t count on it!…A good architecture is intentional and must be thought out and planned by an experienced architect” (Booch, youtube, 2016). The bottom line is this: If your strategy for deconstructing your monolith is to code, code, code and wing it, then good luck!

Next, are the ever-present time and budget questions that must be answered, but how do you answer them? Managers ask, “How long will it take?”, which really translates into, “How much will it cost?” About this, Grady Booch says, if it doesn’t cost much to change, it is design, otherwise it is architecture. (Booch, youtube, 2016). Designing solutions in an existing monolith is cheap (Mas Ruiz, dev.to, 2019). Completely rewriting the monolith as microservices is not cheap. But how much “is not cheap”? To answer this question you will need to know roughly how many microservices you are going to need. Knowing this will allow you to estimate lots of other costs associated with developing, building, and running microservices. How are you going to figure how many microservices you need? To do that, you need some kind of pragmatic strategy for deconstructing a monolith. It will not be perfect, but it will get you started with making a reasonable estimate.

Finally, software architects just have to do better! The microservice design pattern is big on concepts, ideas and technology, but small on strategy. In much of my research, DDD and microservices go hand in hand as a “way to do it”. But, consider this very common DDD question: “What are the bounded contexts of my application?” A software architect may respond, “It depends” or “They will eventually emerge”. We must have better answers. We must have some kind of pragmatic strategy which enables us to answer questions like these.

The Strategy

My pragmatic strategy for deconstructing a monolith into microservices consists of five realistic and actionable steps:

Step 1. Define “Microservice”

Step 2. Deconstruct the Monolith by Features

Step 3. Understand Bounded Context

Step 4. Define Domains

Step 5. Embrace The Hexagon

That is it. Only five steps! Simple, huh? Let the endless debate begin! Well before it begins, let us at least walk through the steps.

Step 1. Define “Microservice”

What is a microservice? This is a loaded question! It needs to be answered before moving forward though. The answer is extremely important because your understanding of what a microservice is will influence how you decide to implement them. For example, if you think of a microservice as a layer of your current layered architecture (account data), then you will end up building a distributed monolith. If you think of a microservice as remote methods or utilities (pattern match this data), you will end up building a Death Star. So defining “microservice” is critical.

Of all the definitions I have seen, the one I like the best was re-published on DZone from Maruti Techlabs’s. Figure 1 shows the definition (Makadia, dzone, 2020).

Figure 1 - Techlab’s Microservice Best Practices

From figure 1, I derive my definition for “microservice”:

A microservice is a stand-alone, self-contained product that carries out a single important business feature.

This definition is my starting point for my pragmatic strategy. I specifically use the words “product” and “feature” for reasons you will discover as you continue reading. Stating that a microservice is something that is responsible for providing a business feature implies that it is something more than just a layer, method or utility.

A microservice is more than just a layer of your current architecture. Yes, a layer of your code handles account data, but this by itself is not a complete business feature. It may be something needed to implement a feature, but it is not a stand-alone, self-contained product by itself.

A microservice is more than just a method or utility of your current code base. Yes, there is some wonderful code to parse and pattern match data, but, this is not a stand-alone, self-contained business feature by itself either.

So a microservice is a stand-alone, self-contained product that carries out a single important business feature. This definition is not only clear and concise, but it also lines up perfectly with the well-known characteristics of microservices. Figure 2 shows these characteristics (Ma, medium, 2018).

Figure 2 - Characteristics of Microservices

Let us see how these characteristics line up with my microservice definition.

Single purpose is building a product which carries out a single important business feature, not twenty different things.
Loose coupling is the degree of interdependence between software modules (Pagade, 2021). Being stand-alone means not needing a dozen other things (other microservices) up and running in order to work successfully.
High cohesion is the degree to which the elements inside a module belong together (Pagade, 2021). Being self-contained means that in one place (typically a single source code repository or project) you find everything you need to update when the business feature requires a change.

Although this is a great definition for microservice, there is still more work to do. This definition depends on knowing what the important business features are. Do you know what they are for you monolith? Next, we will take a look at how to really determine what the business features are of your monolith.

Step 2. Deconstruct the Monolith by Features

Now that we have defined a microservice as a stand-alone, self-contained product that carries out a single important business feature, how do you determine your monolith’s business features? Answering this question is the very heart of deconstructing the monolith.

To help answer this question, I turn to the blog To Domain Driven Design by Kevin Mas Ruiz. In his blog, he discusses how important it is to stop thinking of your code as a single application (monolith) but instead to think of it as a platform of independent products. He writes, “…we need to think [of] our business as a business platform: we don’t have a product, we have a set of products. Those products are a set of features that apply to a persona.” (Mas Ruiz, dev.to, 2019).

Did you see the word feature? This is promising because we are trying to figure out some way of generating a list of business features of the monolith.

To further illustrate how to think about your application as a platform of independent products instead of a monolith, Mas Ruiz writes, “For example, based on this pattern, we can define our shopping platform like in the following diagram:”

Figure 3 - Shopping Platform

In figure 3 above, Mas Ruiz uses the green stickies to represent what he calls a product of the shopping platform. Since each product contains one or more features, the green stickies also represent the features of the shopping platform.

What is interesting about Mas Ruiz using green stickies is that green stickies are also used in Event Storming (you starting to see the synergy of these concepts?). In Event Storming, green stickies represent a view (Brandolini, 2018). A view is typically a webpage, but it can represent any kind of user interface of an application. Mas Ruiz uses green stickies to represent a product/feature of the platform and Brandolini uses green stickies to represent a user interface of an application. Combining these ideas together leads to the following:

green stickie == business feature == webpage

This equivalency is important because it hints at a way to determine your monolith’s business features. Try this…

Login to your monolith. As you click through it, create a list of every webpage with its name/title/description. Supplement with a screenshot if you want. Continue until you have visited every webpage of your monolith. Once you are done…

Congratulations! You have just finished deconstructing your monolith into microservices.

WAIT!

WHAT?

You probably think I have lost my mind. Maybe. Remember my pragmatic strategy started with a definition for microservice. Let us revisit the definition.

A microservice is a stand-alone, self-contained product that carries out a single important business feature.

In a monolith, each webpage is (typically) created for a specific reason. In other words, each webpage carries out a single important business feature. Therefore, we can extend the equivalency above to include microservice:

green stickie == business feature == webpage == microservice

This equivalency basically means a monolith can be deconstructed into microservices by simply implementing each webpage as its own stand-alone, self-contained product. I can already hear you screaming objections! That is OK. I understand that deconstructing a monolith so each webpage becomes its own product will immediately raise a LOT of objections. However, as Mas Ruiz has suggested, we need to stop thinking of our application as a single solution (monolith) and instead think of the application as a platform of independent products which all work together to provide a solution. I hope that my reasoning for deconstructing a monolith so each page becomes a product of the platform solution has some validity.

Remember, my purpose is to attempt to create a pragmatic strategy for deconstructing a monolith. No strategy will EVER be 100%, and that is OK. Starting with some strategy is always better than starting with no strategy at all. May it be the case that multiple webpages are group together into a microservice? Of course! But for a strategy, you need to start somewhere.

If you are still with me, congratulations! I know it is not easy and you are probably hesitant. Now that you know each webpage of your monolith will become a microservice, the next thing we want to look at is how this relates to DDD bounded contexts.

Step 3. Understand Bounded Context

Domain Driven Design is…interesting to say the least. Lots of theory, little practice. I want to discuss DDD as part of my pragmatic strategy because if you research “how to implement microservices”, you will find suggestions that DDD bounded contexts can be used to define a microservice. The idea is that if you know what a “bounded context” is, then you know how to define - and therefore implement - a microservice. At least that is the theory.

Let us start by defining a DDD bounded context.

A bounded context is a boundary inside of which lives multiple components of a software model. A component has a specific meaning and behavior within the boundary. Behavior within a bounded context is idempotent and/or ACID. A component with the same name - but with different meaning and behavior - must exist in its own boundary. (Vernon, 2016, p. 327)

Given this definition for a DDD bounded context, recall Step #2 of my pragmatic strategy that I made this radically controversial equivalency:

business feature == webpage == microservice

This equivalency basically means a monolith can be deconstructed into microservices by simply implementing each webpage as its own stand-alone, self-contained product. Now let us propose that a DDD bounded context also defines a microservice. If this is true, it would mean bounded context can be added to the equivalency like this:

webpage == business feature == microservice == bounded context

However, is this equivalency true? Can bounded context just be thrown in there? The answer is Yes. Let us break down the definition of bounded context to see why.

A bounded context contains software model components that have very specific meaning inside that bounded context. In the DDD world, this specific meaning is how you create a ubiquitous language (UL). UL is the most important concept in DDD. Everything in DDD is built on UL. UL is intended to define exact meanings for words so that when you use those words everyone understands what you are talking about. Let me illustrate with an example.

Suppose you get the following request from a security auditor: “Please provide a list of all the log files on the server”.

WAIT A MINUTE!

A server can have dozens of different log files for dozens of different services running on the server. Plus, there are lots of different servers performing different tasks all throughout your environment. So what log files is the security auditor looking for? For what services? For what servers? These questions demonstrate the need for a UL within a context. The problem is not with the auditor’s request. The problem is that for the context of the request - security audit - the meanings of the words “server” and “log file” have not been adequately defined. In order to respond to the auditor’s request, the team must first get a meeting with the auditor, ask a bunch of questions, and determine what exactly the auditor means by “server” and “log files”. At the meeting, the team learns the auditor is interested in remote SSH connections to the VM running the database. Now the words “server” and “log files” have a very specific meanings. A UL for the context - security audit - has been established so everyone can understand each other when the words “server” and “log files” are used.

Now suppose there is a production problem with the application. In order to troubleshoot, the team starts a conversation about getting the “log files on the server”. Does the team confuse this conversation with the security audit conversation? No, of course not! But why not? After all, the same words, “server” and “log files”, are being used. The team does not get confused because there are two different contexts: security audit and production problem. Within each context, “server” and “log files” have specific and different meanings. Bringing this back to DDD, “security audit” and “production problem” are bounded contexts and “server” and “log files” are software model components.

Now that we have a better understanding of bounded context, how does it relate to my pragmatic strategy? To answer this question, let us look at a common data-related objection to my strategy. The objection goes something like this:

20 different webpages of the monolith use policy data, so they should all be in the same microservice, right? But if I put 20 webpages in the same microservice, that gets me right back to building a monolith. So I think I will need to extract policy as its own microservice. But policy is not a stand-alone, self-contained business feature by itself, so if I extract it on its own then I will start to have tight coupling between microservices. Oh boy!

Mas Ruiz addresses this objection when discussing cross-product modules. He gives the illustration shown in figure 4. The “1 click purchase” feature seems to need the same data as the “Purchase” feature (Mas Ruiz, dev.to, 2019). If that is the case, then it would seem both features should collapse together instead of being independent. But before doing that, Mas Ruiz says to dig deeper.

Figure 4 - Cross-Product Modules

Mas Ruiz uses the word “modules” to describe the orange boxes in figure 4. These orange boxes represent the data needed for both “1 click purchase” and “Purchase”. Notice the words in the orange boxes are identical!

NOTE Do not get these orange boxes mixed up with Event Storming orange stickies. In this case, there is no similarity between the two.

BUT WAIT!

We have seen this identical word problem before when breaking down the definition of bounded context…remember the “server” and “log files” example above? Yes, in figure 4, the words “buyers”, “books”, “stock”, and “shipment” are used for both the “1 click purchase” feature and the “Purchase” feature. But Mas Ruiz’s point is if you dig deeper into them you will discover the views of the data for each feature will be different. So within the “1 click purchase” feature, “books” has one meaning and in the “Purchase” context, “books” has a different meaning. This is the whole point of DDD bounded contexts.

If you think about it, this should not be surprising. Each webpage is created to carry out a specific business feature. Each business feature has a different (if somewhat subtle) view of the data and operations on the data. In fact, if the view and operations were exactly the same, you would have multiple pages performing the exact same business feature!

NOTE This is not outside the realm of possibility. Over time, you will lose both the development and business teams that first created the application. Knowledge is lost, so features may be forgotten and re-implemented.

So is this equivalency true?

webpage == business feature == microservice == bounded context

The answer is yes! A webpage is created to perform some specific business feature. Within the context of this business feature, the view and operations on the data has a very specific meaning which does not exist on any other webpage. Therefore, it can and should be implemented as a stand-alone, self-contained product as my microservice definition suggests.

NOTE If you think back to the 2000 year time frame when service-oriented architecture (SOA) was all the rage, you can now understand why that concept failed so miserably. SOA set out to be the one-definition-to-rule-them-all so to speak. If you needed policy information, SOA tried to centrally define “Policy” for the ENTIRE organization. DDD bounded contexts tell us you just can not do that!

BUT WAIT!

Without a doubt, different webpages will need to use similar, but not identical, data. If each webpage is its own microservice and is developed as a stand-alone, self-contained, independently-deployable product, how does each microservice get the data it needs?

Great question! For possible answers, go to Micoservices.io and on the homepage search for “data management”. On Micoservices.io, Chris Richardson documents a number of different strategies for how to handle data and databases. Spoiler alert, it is not easy! This is especially true when considering ACID requirements of business operations. I specifically say “business operations” here instead of transactions because the requirement should be that when the button is clicked, everything gets done. It does not matter if it is transactional or not, just as long as everything gets done.

My recommendation for data management is the shared database pattern (Richardson, n.d., Pattern: Shared database). For implementation, keep microservices isolated to a database schema created just for that microservice. The data in the schema is handled in various ways including:

TABLE. Data is owned by that schema (microservice).
VIEW & MATERIALIZED VIEW. Read-only sharing of data from other schemas (microservices).
TRIGGER Read-only copies of data from other schemas (microservices).

Handling data is a very, very complicated topic unto itself. For microservices, the one-database-per-microservice diagram is what everyone loves to see and therefore what everyone strives to implement. But, given its massive complications, is it worth it? (Richardson, n.d. Virtual bootcamp:…). Like my post disclaimer says, unless you are Google, Facebook, Uber, etc., probably not! I highly recommend you research data strategies on your own.

Step 4. Define Domains

The next thing to do in this pragmatic strategy is to define domains. For DDD, Defining domains would seem to be a very important because, after all, it is in the name: Domain Driven Design. I think the bounded context is a much more important DDD concept, but domains have value too.

Despite the word “domain” being part of the name Domain Driven Design, a domain is actually one of the most confusing and least explained concepts of DDD. In Domain-Driven Design Distilled, Vernon does not give a definition of domain. The best we get is a discussion about something called a core domain.

“When compared with all the software your organization uses, a Core Domain is a software model that ranks among the most important, because it is a means to achieve greatness. A Core Domain is developed to distinguish your organization competitively from all others. At the very least it addresses a major line of business. Your organization can’t excel at everything and shouldn’t even try. So you choose wisely what should be part of your Core Domain and what should not. This is the primary value proposition of DDD, and you want to invest appropriately by committing your best resources to a Core Domain.” (Vernon, 2016, pg. 13).

This really does not define domain. It gets even more confusing because in addition to domains there are also subdomains. The words “domain” and “subdomain” seem to be used interchangeably adding even more confusion. For example, Vernon lists three types of subdomains:

Types of Subdomains

Core Domain

Supporting Subdomain

Generic Subdomain (Vernon, 2016, pg. 46)

Now wait just a minute. “Core Domain” is a type of subdomain? That does not make any sense. “Core Domain” should be a domain right? It is in the name! So why is it listed as a type of subdomain? If it is a type of subdomain, then why is it not called “Core Subdomain”? If this is not confusing enough, an attempt is made to establish a relationship between domain/subdomain and bounded context. You can imagine how well this goes.

For my pragmatic strategy, I ignore all of the DDD book treatments of domain and subdomain because they just do not work or make any sense.

My definition of domain:

A domain is a high-level, one- or two-word description that can be used to logically group together the stand-alone, self-contained products that carry out the important business features of the application platform.

That is it. Very simple. Here are examples of domains I have encountered a lot:

Reporting
Configuration
Administration
Health Check
Performance

Get the idea? If your application gets a lot of data from 3rd parties, you may have a Data Processing domain. If your application converts files into different formats, you may have a Converter domain. If your application processes orders, you may have an Order Processing domain.

An application should have a relatively few number of domains meaning that all of the features of the application should logically fit into relatively few categories. If you find yourself writing down dozens of different domains, then either one of two things are happening.

Your monolith is big hodgepodge of a lot of different responsibilities. This is very telling!
What you are writing down is not high-level enough. If you have ABC File Import, XYZ File Processing, and 123 Data Validation as domains, all three of these can probably be assigned to a Data Processing domain.

Try this. Remember that list of webpages from Step #2 of my pragmatic strategy? For each one, assign it a one- or two-word, high-level category. Do this for every line of the list.

Congratulations! You just assigned a domain to every product of your application platform!

NOW WHAT?

There is some value in assigning domains. Domains can help make return on investment (ROI) decisions. Take the Reporting domain for example. Would it be better for the software developers to code custom reports into the application? Or, would it be better to purchase a reporting tool and allow users to create whatever reports they want? This is an ROI decision. If the primary purpose of your application is reporting on extremely complicated data, then it is best for the software developers to code them. If the primary purpose of your application is something else, then buying a reporting tool to free up developers' time might be a better ROI. If you find yourself writing down dozens of different domains, that may indicate you application is performing a lot of unrelated business functions and maybe some of them are the responsibility of other teams? Or maybe new teams need to be formed? Again, ROI decisions for the organization.

Overall, the domain concept is not difficult as long as you avoid the DDD book treatments and stick with my definition.

Step 5. Embrace the Hexagon

The final step of my pragmatic strategy is to embrace the Hexagon. What in the world does this mean?

If you go through Steps 1–4, you will get a good idea of what your application will look like - on paper - rewritten from monolith to microservices. The paper can be used for project planning, budgeting, time estimates, event storming, and lots of other things. However, what you do not have yet is code. Remember, “A good architecture is intentional and must be thought out and planned by an experienced architect” (Booch, youtube, 2016). Now that you have done this, software developers will eventually need to start writing code. The Hexagon will help make sure code is organized properly.

Figure 5 - O’Reilly Plan First Code Later Sticker

Alistair Cockburn documented the hexagonal (ports and adapters) architecture in a work published in 2005. Cockburn stated the intent of the architecture is to “Allow an application to equally be driven by users, programs, automated test or batch scripts, and to be developed and tested in isolation from its eventual run-time devices and databases.” (Cockburn, 2005). The hexagonal layers of the architecture allows code to be organized and written to adhere to the intent of the architecture. Figure 6 gives an overview of the layers.

Figure 6 - Hexagonal Architecture Layers

Hexagonal Architecture is a huge topic all by itself. I encourage you to research it more on you own. Here is a high-level summary, describing the purpose of each layer.

UI

The UI is not actually one of the layers, it is everything outside of the hexagon. It is called UI because it is common for some kind of user interface to want to interact with your application. However, as shown in figure 6, there are lots of other ways of interacting with your application, such as HTTP, JMS, SMTP, and SFTP. Each interaction has a unique protocol it uses to communicate with your application. When communication does occur, it happens with the outer most hexagon layer, the framework layer.

Framework Layer

The Framework layer is responsible for:

Accepting a raw driver request through some communication protocol.
Converting a raw request into an application specific request, then sending this application specific request down to the next layer, the Application layer.
Converting the application specific response into a raw driver response and sending the response back through the communication protocol.

Typically the Framework layer is the smallest of the layers since raw driver requests are simply converted and passed to the application layer for handling. The Framework layer does not contain any business code. The Framework layer communicates with the Application layer through an application primary port. This is simply a fancy way of saying an instance of an Application layer class is injected into an instance of a Framework layer class.

A Spring @RestController is a perfect example of a Framework layer class. Its primary responsibility is to accept a raw HTTP protocol request, do something with it, then send a raw HTTP protocol response back. The “do something with it” part is handled by an Application layer class that gets created and injected into the @RestController by Spring. Next, we will look at these Application layer classes in more detail.

Application Layer

The Application layer is the hardest layer to understand because of its unique position between the Framework layer and the Domain layer. The Application layer is responsible for:

Converting an application specific request into an orchestration of domain operations performed by the Domain layer.
Providing the Domain layer concrete implementations of the exit points out of the Domain layer.
Converting the domain response into an application specific response, sending the response back up to the Framework layer.

Let us take a look at each of these responsibilities in more detail.

First, the Application layer takes an application specific request and converts it into an orchestration of domain operations performed by the Domain layer. Like the Framework layer, the Application layer does not contain any business code. But the Application layer does know what Domain layer operations need to be executed to fulfill the application specific request. The Application layer communicates with the Domain layer through a domain primary port. This is simply a fancy way of saying an instance of a Domain layer class is injected into an instance of an Application layer class.

Second, the Application layer is responsible for providing the Domain layer with concrete implementations of the exit points out of Domain layer. What are exit points? Well, at some point, the code in the Domain layer is going to need to communicate with the outside world. Databases are the most well known example of this kind of communication. Other examples are message brokers, email, and files. Suppose code in the Domain layer needs to retrieve and store data. This is an exit point. Though the Domain layer needs to retrieve and store data, it does not need to know how the data is retrieved and stored. Because it does not need to know the how, those operations are defined by interfaces only. It is then the responsibility of the Application layer to provide concrete implementations of these interfaces so that when a dependency injection engine (CDI, Spring, etc.) wires everything together, the data is retrieved and stored in a manner that best suites the application. The interfaces in the Domain layer are the domain secondary ports and the classes in the Application layer that implement these interfaces are the application secondary adapters.

Third, any responses from the Domain layer are converted into an application specific response and passed back up to the Framework layer. Remember the Framework layer then takes this application specific response and converts it into a raw driver response and sends the response back through the communication protocol.

Domain Layer

Finally is the inner most layer, the Domain layer. This is the most important layer because it is finally in this layer where all of the business code is located. The Framework layer and Application layer have specific responsibilities, but are basically pass throughs to the Domain layer.

Being protected by the other layers makes the code in the Domain layer very easily reusable. The code has no knowledge of the HTTP protocol or how to talk to a database. So as your application evolves, the code in the Domain layer should easily evolve with it. And that is what you want. For example, suppose you are changing from an N-Tier architecture based on Struts to a microservice architecture based on Angular and Spring boot. The Domain layer, with all the business code, should not care. It should be equally reusable in both applications. If the architecture change reveals the need for code in the Domain layer, the code in the Domain layer was not created correctly. Similarly, if the application’s architecture further evolves into use cloud-native services (like AWS Lambda), again, the Domain layer, with all the business code, should be reusable without any changes. This is a tall order and takes discipline on the software development team to achieve. Knowing the responsibilities of each hexagon layer helps achieve it.

Being protected by the other layers makes the code in the Domain layer very easily testable. Because interfaces are used to define exit point operations, unit test frameworks need only to mock these interfaces with suitable responses for each test. If unit tests require the startup of a complex testing runtime to simulate a database or other external resources, the unit tests are wrong. Keep the focus on testing the business code, not simulating a runtime environment. If unit tests are written this way, it fulfills the primary intent of the hexagonal architecture, which is to “Allow an application to equally be driven by users, programs, automated test or batch scripts, and to be developed and tested in isolation from its eventual run-time devices and databases.” (Cockburn, 2005).

This was a very quick and very high-level review of hexagonal architecture. Again, I encourage you to research it more on your own. Now that you understand the purpose of each layer, we can translate this into code.

Code

When the team starts coding, the first thing to do is create a source code repository for each microservice. Remember, a microservice is a stand-alone, self-contained product that carries out a single important business feature, so the code for a microservice should exist in its own source code repository. Suppose you need to code the ABC Reconciliation Report business feature. Create a source code repository with the following name:

abc-reconciliation-report

Now that you have a repository, what do you put in it? Follow The Hexagon and create projects based on the layers. Physically these are file system folders created inside the repository. Logically these folders are referred to by different names depending on the technology you are using. If you are using Java and Maven, you may refer to these folders as modules of a multi-module Maven project. If you are using C#, you may refer to these folders as projects of a solution. For simplicity, I will refer to them as projects. What you name the projects identifies the layer of The Hexagon the code is for and also declares the intent of the code. For example, you may have projects which look like this:

abc-reconciliation-report
    /api
    /jms
    /application
    /domain
    /ui

/api A hexagon Framework layer module containing REST endpoints. Provides a way the outside world may interact with the domain. Responsible for translating HTTP(S) requests into application layer objects for processing.

/jms A hexagon Framework layer module containing messaging (JMS) listeners. Provides a way the outside world may interact with the domain. Responsible for translating raw JMS messages into application layer objects for processing.

NOTE You may be asking, “Why not name the project ‘framework’ and put all Framework layer code in one project?” Recall from figure 6, There may be many different UI components that want to communicate with your application and each component may use a different protocol for communication. You want to separate the protocol handlers into different projects. So a project for handling HTTP REST communication should be separate from the project handling JMS message communication. Following The Hexagon, each project can re-use the code from the Application and Domain layers.

/application A hexagon Application layer module containing domain orchestration and domain implementations. These implementations provide a way the domain may interact with the outside world (exit points).

/domain A hexagon Domain layer containing the important business code. This layer should have no knowledge of the Framework or Application layer code. It should be easily testable without any external runtime environments and easily reusable as Framework or Application layer code evolves.

/ui A UI compoent. Responsible for translating user input into HTTP(S) - typically - to interact with /api for requests.

As you can tell by the the names and responsibilities of these projects, everything for the abc-reconciliation-report is contained in a single repository. This really helps the code adhere to the characteristics of a microservice. Let us revisit these characteristics (Ma, medium, 2018) and see how well code code matches up.

Single purpose. The name of the repository is abc-reconciliation-report. I think that pretty much defines its purpose. If the code is doing anything other than this, the software developers got the code wrong.
Loose coupling. Hopefully, the Application layer code which implements the Domain layer exit points keeps coupling loose. If not, the software developers got the code wrong.
High cohesion. If you need to make a change to the ABC Reconciliation Report, it should be clear that this repository is the only place you need to go. If not, the software developers got the code wrong.

Summary

That is it! As a software architect, you can use steps 1–4 of my pragmatic strategy to plan the architectural shift from monolith to microservices. As a software developer, you can use step 5 to organize the source code repositories and the contents of each repository and get coding!

It has been a journey, right? Here is a summary.

I wanted to learn how to deconstruct a monolith into microservices. To learn this, I studied microservice design pattern, domain driven design (DDD), feature driven design (FDD), hexagonal (ports and adapters) architecture, and event storming. After a year, I learned a lot of theory but little practice. So I decided to create my own pragmatic strategy for deconstructing a monolith into microservices; A step-by-step guide that is realistic and actionable.

My strategy is implemented with five steps:

Step 1. Define “Microservice” A microservice is a stand-alone, self-contained product that carries out a single important business feature.

Step 2. Deconstruct the Monolith by Features

business feature == webpage == microservice.

Click through your monolith and create a list of every webpage. Congratulations! You have just finished deconstructing your monolith into microservices

Step 3. Understand Bounded Context

webpage == business feature == microservice == bounded context.

A webpage defines a bounded context because the data and behavior on that webpage is unique and not found on other webpages.

Step 4. Define Domains A domain is a high-level, one- or two-word description that can be used to logically group together the stand-alone, self-contained products that carry out the important business features of the application platform (microservices). Go get the list of all the webpages of your application. For each line, write down a one- or two-word, high-level description of the product. You have just assigned a domain to every product of your application platform. Use domains to make ROI decisions.

Step 5. Embrace The Hexagon Use the concepts from hexagonal architecture to organize the source code repositories and the contents of each repository so that software developers know which code goes in which projects so code with similar responsibilities stay together in the same layer.

That is it. Get started. Have fun. Remember no strategy is 100%, so be pragmatic, but also be flexible.

References

Booch, Grady. (2016, June 30). SATURN 2016 Keynote: Architecting The Unknown with Grady Booch [VIDEO]. https://www.youtube.com/watch?v=RJ3v5cSNcB8&t=2685s.

Makadia, Mitul. (2020, February, 26). Break a Monolith to Microservices — 12 Best Practices and Design Principles. https://dzone.com/articles/break-a-monolith-to-microservices-12-best-practice.

Mas Ruiz, Kevin. (2019, December 2). To Domain Driven Design. https://dev.to/kmruiz/to-domain-driven-design-6ao.

Brandolini, Alberto. (2018, November 7). 50,000 Orange Stickies Later - Alberto Brandolini - GOTO 2018. https://www.youtube.com/watch?v=NGXl1D-KwRI&ab_channel=GOTOConferences.

Ma, Xiao. (2018, October 17). Microservice Architecture at Medium. https://medium.engineering/microservice-architecture-at-medium-9c33805eb74f.

Fowler, Martin (2011, July 14). CQRS. https://martinfowler.com/bliki/CQRS.html.

Cockburn, Alistair. (2005, April 01). Hexagonal architecture. alistair.cockburn.us. https://alistair.cockburn.us/hexagonal-architecture/.

Vernon, Vaughn. (2016). Domain-Driven Design Distilled. Addison-Wesley

Richardson, Chris. (n.d.). Microservice Architecture. Microservices.io. https://microservices.io/.

Richardson, Chris. (n.d.). Pattern: Shared database. https://microservices.io/patterns/data/shared-database.html.

Richardson, Chris (n.d.). Virtual bootcamp: Distributed data patterns in a Microservice architecture. https://www.chrisrichardson.net/virtual-bootcamp-distributed-data-management.html.

Pagade, Ganesh. (2021, May 25). Difference Between Cohesion and Coupling. https://www.baeldung.com/cs/cohesion-vs-coupling.

Cockburn, Alistair. (2005, January 4). Hexagonal architecture. https://alistair.cockburn.us/hexagonal-architecture/.