DEV Community: Dara Olayebi

This Week I Learnt: Java's CompletableFuture

Dara Olayebi — Wed, 31 Jul 2024 19:18:43 +0000

This week, I'm diving into Java's CompletableFuture.

As a full-stack developer with a frontend background, dealing with asynchronous tasks is an inevitable part of my role – network requests, background computations, and the like. In Java, CompletableFuture is a powerful tool for handling these tasks while keeping the main thread responsive.

Completable futures are to Java what Promises are to JavaScript.

If you're familiar with JavaScript, it might help to grasp these concepts by making parallels between both languages. I like to think of CompletableFuture as Java's version of a Promise. It is a class that represents the eventual result of an asynchronous operation, whether that result is a success or failure. Introduced in Java 8 as part of the java.util.concurrent package, it's a powerful way of writing non-blocking code, with methods for chaining operations, and handling errors, similarly to Promises.

Here's a quick comparison of the two:

// JavaScript Promise
fetchFromServer()
    .then(data => processData(data))
    .then(result => updateUI(result))
    .catch(error => handleError(error));

// Java CompletableFuture
CompletableFuture.supplyAsync(() -> fetchDataFromServer())
    .thenApply(data -> processData(data))
    .thenAccept(result -> updateUI(result))
    .exceptionally(error -> handleError(error));

As illustrated above, CompletableFuture provides a similar, chainable syntax that allows for clean and readable asynchronous code.

Consider a scenario where you need to fetch a user's profile data and order history from two separate endpoints. You would want to avoid freezing the UI while waiting for these requests to complete. Here's how you would implement this using CompletableFuture:

CompletableFuture<User> profileFuture = CompletableFuture.supplyAsync(() -> {
    // Fetch user profile from a service
});

CompletableFuture<List<Order>> ordersFuture = CompletableFuture.supplyAsync(() -> {
    // Fetch user orders from another service
});

CompletableFuture<Void> combinedFuture = CompletableFuture.allOf(profileFuture, ordersFuture);

combinedFuture.thenRun(() -> {
    User user = userFuture.join(); 
    List<Order> orders = ordersFuture.join(); 
    displayUserData(user, orders); 
});

In this example, we trigger two asynchronous requests simultaneously and use allOf to wait for both to finish. Once they complete, we retrieve the results and update the UI accordingly, all without blocking the main thread.

Chaining & CompletionStage

CompletableFuture implements the CompletionStage interface, which provides the foundation for chaining operations. Each thenApply, thenAccept, and similar method returns another CompletionStage, allowing you to create complex asynchronous pipelines.

Similar to how we can chain promises in JavaScript when we have a sequence of asynchronous tasks to be performed one after another, we can chain tasks within a Completable Future in order to create a sequence of dependent asynchronous operations without falling into callback hell. Here's how we would do that:

CompletableFuture.supplyAsync(() -> "Hello")
    .thenApply(result -> result + ", CompletableFuture")
    .thenApply(result -> result + " in Java")
    .thenAccept(System.out::println);

Handling exceptions

Where we have .catch() on a Promise object, we have .exceptionally() on a Completable Future. This method handles exceptions that may occur during asynchronous processing:

CompletableFuture.supplyAsync(() -> {
    if (true) {
        throw new RuntimeException("Exception in CompletableFuture!");
    }
    return "No exception";
}).exceptionally(ex -> {
    System.out.println("Handled exception: " + ex);
    return "Recovered value";
}).thenAccept(System.out::println);

I hope this article gives you a good starting point to explore the CompletableFuture class further.

Helpful Links:

This Week I Learnt: gRPC & Protobuf

Dara Olayebi — Mon, 08 Apr 2024 21:43:31 +0000

After a (very) long hiatus, I'm back with a writing series I'm calling "This Week I Learnt". Just over a year ago, I started a new job and it has been the most exciting and most challenging experience of my career. Exciting because I'm contributing to a product I love with a brilliant team. Challenging because imposter syndrome reared its ugly head and I spent months working to overcome daily feelings of self-doubt. I was also transitioning into a full stack role with a purely frontend engineering background, so that made everything a little more difficult.

In my first few months, I was learning so much so quickly as I began to work with large, complex systems. I became exposed to system architecture and design concepts as well as advanced software tooling, a lot of which I'd had very little previous practical experience with. This led me to the idea of a writing series - breaking down some of these concepts as frequently as I can in a way that's easy to understand.

So, here goes the first one!

This Week I Learnt how gRPC (General Remote Procedure Call) and protocol buffers work.

To understand gRPC, it helps to first understand what RPC is. A remote procedure call is a type of communication that allows computer programs to execute code on a remote server as if they were local function calls. In slightly simpler terms, RPC allows developers to make function calls on remote machines or services. It is particularly useful for distributed systems where components are spread across multiple nodes or servers. gRPC is an open-source API implementation of the RPC model. It was built by Google in 2016 and is now widely used by a lot of companies with large systems. It has multiple benefits over the traditional REST/SOAP API approach, one major one being its performance.

APIs rely on a communication protocol to determine how to send and receive data. A communication protocol in a nutshell is a set of rules that determine how data is sent over the internet and other networks. HTTP, for example, is the most widely used protocol today, used to send data between clients and servers on the web. File Transfer Protocol (FTP) is another example, and is used to transfer files between computers etc. gRPC relies on the HTTP/2 protocol (which is an upgraded version of HTTP).

Image credit: Imperva

In addition, APIs also need to follow a specific data format for communication between clients and servers. REST APIs send and receive data as JSON or XML objects. gRPC APIs on the other hand use Protocol Buffers (or protobuf). These are .proto files containing messages and a service definition that define the methods of the service and each request and response type. Below is a protobuf file example - it defines a UserInfo service that allows consumers to get a user's profile information and update a user's email:

// Specifies the proto version
syntax = "proto3";


// Request and response for fetching a user's profile
message GetUserProfileRequest {
    string user_id = 1;
}

message GetUserProfileResponse {
    string user_id = 1;
    string email = 2;
    int64 phone = 3;
    string avatar_url = 4;
    repeated string followers = 5; 
}

// Request and response for updating a user's email
message UpdateUserEmailRequest {
    string user_id = 1;
    string new_email = 2;
}

message UpdateUserEmailResponse {
    // You can also define enums in these files
    enum ResponseStatus {
        SUCCESS = 0;
        ERROR = 1;
    }

    ResponseStatus response = 1;
}


// API service definition which lists the two API methods and their corresponding request and response
service UserInfo {
    rpc GetUserProfile (GetUserProfileRequest) returns (GetUserProfileResponse)
    rpc UpdateUserEmail (UpdateUserEmailRequest) returns (UpdateUserEmailResponse)
}

You can have several proto files in your codebase, each one containing a different service and message definitions.

Once proto files have been defined, they need to be compiled to translate them into code that can be understood and used by various programming languages. For example, consuming a REST API in a JavaScript application can be done via the native fetch() method or some web client library like Axios. In the gRPC world, we need a way for the data structures defined in the proto files to become readable code. This is done by the protobuf compiler (protoc). It takes in the proto files as its input, and outputs a bunch of stub code made up of classes and objects that represent your service. The compiler supports multiple programming languages (Java, Python, C++ etc), so can generate stub code in the language you will be using to consume the API.

The image below is a workflow of the processes required to consume a gRPC API:

Image credit: IONOS Digital Guide

Once compiling is done, clients can then begin to interact with the API using the methods generated.

Helpful Links:

A checklist for prioritising web accessibility

Dara Olayebi — Fri, 09 Sep 2022 18:45:55 +0000

In the spirit of being transparent, I haven't always prioritised accessibility. This is not to say that I've deliberately built applications to be inaccessible, but rather, that it was often an afterthought - something I needed to "tackle" at the end. Because of this mindset, I didn't spend enough time making sure all parts of the user interface were accessible. Over time, I have realised how important it is to make it a natural part of my development process from the jump.

In a nutshell, accessibility on the web refers to the ability for everyone to successfully perceive, operate, understand and access a website or web application. People with disabilities use assistive technologies - screen readers, screen magnifiers, Braille displays, voice control, to name a few - to access the web.

Different categories of disabilities (source: Microsoft's inclusive design kit)

Before diving in, we'll go behind the scenes a little bit. When a browser loads a webpage, a couple of things happen. One of those things is the creation of what is called the Accessibility Tree - the browser takes the DOM tree and transforms it into a version that assistive technologies can understand. The Accessibility Tree consists of the name, role, value and state (along with other properties) of elements on a webpage. Technologies such as screen readers will refer to this tree to relay information to its users.

Chrome's Accessibility Tree (within Developer tools) showing the accessibility data for a button on the page

To ensure website developers stick to accessibility rules, the WCAG (Web Content Accessibility Guidelines) were introduced many years ago. This article highlights some of these guidelines in a checklist format that can be easily followed during the development process.

✔️ Are you using semantic HTML?

By default, HTML is accessible. However, the more elaborate a website becomes - as is the case nowadays - the greater the need to ensure that it remains accessible. Using semantic HTML sets the foundation.

Semantic elements (header, footer, main, aside, article, button, nav, menu cite, em, to name a few) introduce meaning to a webpage which means that assistive technologies are able to establish landmark regions and identify what the layout and sections of the page are.

As I read somewhere, "developing semantic websites solves more than 50% of the most common accessibility issues."

Semantic vs Non-semantic code

In some cases, there might be no semantic element in existence for what needs to be achieved - for example, building a dropdown menu - and the alternative would be to create a custom element. This has the potential to affect accessibility which is where ARIA comes in (discussed later on).

More on semantics: HTML semantics cheat sheet.

✔️ Does every element have a name?

Just as people are addressed by name, so are web elements when it comes to accessibility. The name of an element (also called "accessible name") is one of the values that screen readers will announce to users as they navigate a website.

Elements get their default accessible names from different sources:

Image names come from the alt attribute.
Button names come from the button's text contents (or from the alt value of an enclosing image, if one exists).
Table names come from the title attribute.
Form input names come from the placeholder, associated label or title attribute.

Here are some examples of three web elements followed by a screenshot of the MacOS screen reader announcement of each element:

<button class="button">Settings</button>

Screen reader announcement for a button

<a href="/settings/labels">Manage Labels</a>

Screen reader announcement for a link

<form role="search">
   <label for="q">Search:</label>
   <input type="text" id="q" name="q" />
</form>

Screen reader announcement for a form with a search field

Sometimes, an element needs to be explicitly given its accessible name. Here are two example scenarios:

A "Read more" link that requires additional context for visually impaired users
Icon buttons that have no text

ARIA to the rescue!

If you scroll up to the screenshot of Chrome's Accessibility Tree at the beginning of the article, you'll notice the section titled "ARIA attributes".

ARIA (Accessible Rich Internet Applications) is a set of roles, states and properties that can be added to an element to specify how it should behave.

The aria-label attribute will override an element's accessible name.

<button class="button" aria-label="Shopping Cart">
  <svg>
     ...
  </svg>
</button>

<button aria-label="Read more about the blog post on global travel">
   Read more
</button>

Key things to note:

All images should have an alt attribute.
- If the image is purely decorative (e.g. a question mark icon next to a Help button or a magnifying glass icon within a search input), the alt text should be an empty string (this prevents screen readers from announcing a redundant element).
- If the image is not redundant and serves a purpose, the alt text should describe exactly what the image is or in some cases, what the image does.
All HTML form inputs should have an associated descriptive label to enhance accessibility.

So it's pretty obvious that an element with no name could affect a user's experience. Examining the Accessibility Tree to make sure elements have proper naming will increase the amount of context screen readers provide to users.

More on accessible names: What's in a name?

✔️ Are headings in hierarchical order?

Some assistive technology users prefer to navigate a page using headings, especially on sites that have a lot of content, for example Wikipedia. Headings should have the correct hierarchy (i.e. <h3> must come before <h4>) to give users a sense of how the page content is structured.

Headings should also be as succinct and as descriptive as possible to properly illustrate the content they introduce.

WCAG says: The heading elements should be organized in descending order without skipping a level, meaning that an h4 should only come after an h3. Skipping heading levels will cause screen reader users to wonder if content is missing.

It can be tempting to order headings by size and not by level. In such cases, CSS utility classes can be used to make elements appear visually smaller or bigger regardless of their heading level.

More on headings hierarchy: Accessible heading structure

✔️ Does your content have a logical tab order and visible focus indicators?

Not all users make use of a mouse or a trackpad. Some have to rely on the keyboard, while others choose to. Regardless, ensuring that this group of users can successfully navigate a webpage should be a priority.

HTML elements are either presentational (div, span, section, article) or interactive (a, button, input, select, textarea). By default, interactive elements are focusable. A keyboard user will click the tab key to jump from one focusable element to the next.

The order in which users tab through the page is based on the order of the DOM, and the order of the DOM is based on the order of the HTML markup. Therefore, it is important to prioritise how you write your code as it will determine how keyboard users navigate your site. For example, if your UI is supposed to display article content to the left and the article heading to the right, your HTML should be written in the normal order with the article heading appearing first and the article content second. CSS can then be used to adjust the visual appearance of the page.

The page tab order can also be altered using tabindex - this attribute determines where an element will fall in the tab flow. The default tabindex value of interactive elements is 0. An element given a value of -1 will be removed from the tab flow, while an element given a value of 1 will take precedence over other elements. The latter should be avoided as it could affect the user's navigation flow on the page.

<div tabindex="1">I will be focused before all other elements</div>

<div tabindex="0">I am the default</div>

<div tabindex="-1">I will never be in focus</div>

Key things to note:

Make sure any element that the user needs to interact with, particularly custom controls like a dropdown menu, have a tabindex value of 0. Otherwise, a keyboard user will never be able to access it.
If an element is visually hidden but may be interacted with at some point by the user (e.g. a pop-up modal), it should be set to display: none or visibility: hidden to prevent focus until it becomes visible.
If an element is visually hidden and will never involve any interaction from the user, it should be given a tabindex value of -1 to remove it from the focus flow entirely.
When used for interactive controls, non-semantic elements are inaccessible via the keyboard (e.g. using a <div> to create a button) and will require some Javascript to be written to be made accessible. Semantic elements on the other hand have built-in keyboard accessibility.

So how does a keyboard user know what element is in focus while they tab through the page?

As Sara Soueidan wrote:

A keyboard user’s cursor equivalent is the focus indicator.

Removing the browsers default focus indicator (using outline: none) without replacing it with another one makes a site inaccessible. Today, in addition to :focus, most browsers support the :focus-visible pseudo-class which will be applied when an element is in focus and the user's input is a keyboard.

The focus indicator is displayed on the "Paid Courses" menu item via a keyboard

Here's how to use :focus-visible from MDN's docs:

.button {
  margin: 10px;
  border: 2px solid darkgray;
  border-radius: 4px;
}

.button:focus-visible {
  /* Draw the focus when :focus-visible is supported */
  outline: 3px solid deepskyblue;
  outline-offset: 3px;
}

@supports not selector(:focus-visible) {
  .button.with-fallback:focus {
    /* Fallback for browsers without :focus-visible support */
    outline: 3px solid deepskyblue;
    outline-offset: 3px;
  }
}

✔️ Are you using ARIA attributes appropriately?

As we saw above, ARIA lets you modify the way an element is presented to assistive technologies.

You can use ARIA to define the role of an element e.g. role="dialog", or set its state e.g. aria-checked="true". You can also use it to make custom controls accessible. For example, if you choose to create a checkbox instead of using HTML's native checkbox element, you would need to add ARIA states and properties to make your checkbox usable and accessible.

As useful as ARIA is however, it is not always required. Semantic markup should always be used where possible.

✔️ Are you choosing colours carefully?

Very often, when it comes to colours, I have prioritised aesthetics over accessibility without realising it, neglecting a large group of people in the process.

With more awareness comes more consideration for users who are blind or have low vision. This means prioritising the following:

Making sure all text has the right amount of contrast with its background. WCAG expects a website's background to text contrast ratio to be at least 4.5:1.

Chrome's colour contrast tool which shows selected colours pass (left) and fail (right) contrast ratio check

Including text alternatives to depict different coloured interactive states. For example, error, success or warning states.
Using focus indicators that have enough contrast with the surrounding element or background.
Although this is unrelated to colour, it's important to also take into account other UI elements like font sizes, line heights and letter spacing, and consider how well content can be perceived on a website.

More on colour: Here's why you should never use pure black for text or backgrounds.

✔️ Are you letting users know when dynamic content changes?

Imagine a visually impaired user sending messages on a website's customer service chat widget but not being made aware whenever they receive a response?

If you have any time sensitive notifications on your website that are vital to a user's experience, you should explore using aria-live. This attribute can be added to any element and allows website developers determine how screen readers should notify users about changes on a webpage.

aria-live="off": No announcements will be made ("off" is the default).
aria-live="polite": Announcements will be made only after a user has completed a process i.e. the user will not be interrupted.
aria-live="assertive": The user will be interrupted so the announcement can be made.

Web accessibility is a much broader topic than this article covers. However, as I started to prioritise it in all the ways mentioned above, it led to a major shift in my perspective, motivated me to re-evaluate the way I build user interfaces, and is ultimately making me a more thoughtful developer.

Helpful resources:

Everything I learnt building my first DApp - a frontend perspective

Dara Olayebi — Fri, 08 Apr 2022 15:51:49 +0000

This article is a walkthrough of my process and learnings building a DApp using React, WAGMI & ethers.js.

I was recently given a task at work to build the client side of a DApp (decentralised application). I watched a number of tutorials but still had a hard time figuring out why I needed certain libraries / services and more importantly, how to put all the various pieces together. If you’re trying to figure this out too, then keep reading!

The frontend of a DApp is built very similarly to a traditional web application (using a mix of HTML, CSS & JavaScript), but instead of interacting with a database via an API, you’re interacting directly with the blockchain via a smart contract (a program written to execute a set of instructions). In order to be fully decentralised, DApps are also often hosted on peer-to-peer (P2P) networks instead of centralised hosting servers. Here's a summary:

Traditional web application: Client → API → Database
Decentralised application: Client → Smart Contract → Blockchain

Here's how it went!

Setting up the DApp

After initialising a new React project, the first thing I did was to install a package that will enable communication with the blockchain. Two of the most widely-used Javascript libraries for this are Web3.js and Ethers.js. I did some digging to understand how they work under the hood.

The blockchain is made up of many nodes, each of which stores a copy of the data on the blockchain. To read or write any of this data, my application needed to be able to communicate with one of these nodes. These libraries provide developers with access to various modules (with methods and properties) for interacting with a local or remote Ethereum node. For example:

ethers.Wallet is used to connect to an Ethereum wallet.
ethers.Contract is used to interact with a smart contract on the Ethereum blockchain.

Both libraries will allow you to achieve the same things. However, if you’re unsure about which one to use, this article does a good comparison study.

I also needed a crypto wallet. A wallet acts as a login / gateway to a DApp. In traditional web applications, users are prompted to sign in with an email address and a password. In the decentralised world, DApps need to be given permission to access a user's wallet in order to enable certain functionality (more on this later). I installed Metamask which is one of the most popular wallet solutions, and is accessible via a Chrome extension or a mobile app.

Once I had both ethers.js and Metamask installed, I was good to go.

Interacting with the smart contract

I had what I needed to communicate with the blockchain. Next, I needed to figure out how to interact with the "middleman" - the smart contract.

Connecting to a smart contract requires you to have:

The contract address
The contract ABI
A provider and/or a signer

The contract address is the address of the contract on the blockchain. The ABI (Application Binary Interface) is a file that contains a breakdown of each function in the contract along with its input parameters (if any), expected output and data types, in JSON format. Both of these can be found on Etherscan, a blockchain explorer for Ethereum that allows you to view smart contracts (plus much more).

Providers and signers are essential parts of a DApp. A smart contract can consist of both read and write functions. To read data from a smart contract, you require a provider. To write data (i.e. perform transactions that will change the state of the data on the blockchain), you require a signer. To do both, you require a signer that has a provider.

A provider provides (pun intended) a link to an Ethereum node that your application will communicate with. There are multiple third party services that offer node providers so you don't have to run your own local node. Some of them are Infura, Metamask (uses Infura under the hood), Quicknode and Alchemy.

I got started with Infura, created an account and got a Project ID in a few minutes. I was able to create a provider using the built-in Infura provider option on Ethers.js:

const provider = new ethers.providers.InfuraProvider('rinkeby', INFURA_PROJECT_ID);

Signers on the other hand are essentially an abstraction of the user's wallet address. If you are performing any write operation to the blockchain, you will need to sign the transaction (i.e. prove that you are who you are).

Finally, I created a contract instance that will be used across the application, passing in the contract address, ABI and signer.

const contract = new ethers.Contract(CONTRACT_ADDRESS, CONTRACT_ABI, provider or signer);

With this done, I could call any smart contract function like this:

const result = await contract.functionName();

Handling the wallet connection

The final bit was to figure out how to handle connecting the DApp to a wallet.

In addition to Metamask, my application was to provide users with two other wallet connector options.

Fortunately, there are several packages that remove the need to write code for each connector separately. I used WAGMI which is a React hooks library built on top of ethers.js. WAGMI does a lot more than just handle wallets. It uses over 20 different hooks to abstract a lot of the ethers.js functionality.

This guide on their website explains in detail how to configure wallets. I found it really easy to integrate. Other similar libraries include web3-react and web3-modal.

One important thing to note: Wallets come with a number of networks you can select from.

There is the main network (Ethereum mainnet) which is for production purposes and multiple test networks (Ethereum testnets) that replicate the Ethereum production environment and are used to develop and test smart contracts. Each testnet has its own properties and supports a specific set of clients.

It's also important to make sure that your wallet is on the same network your smart contract is deployed on - in my case, Rinkeby - otherwise, requests will fail. I used WAGMI's useNetwork hook to flag when the user is on the wrong network.

Other things worth mentioning:

To fund your wallet with test tokens (particularly to test write functions as they incur gas fees), you will need to use a faucet - a website that distributes small amounts of crypto for free in exchange for performing certain actions. I used Rinkeby's faucet and got some test ETH within minutes. However, other options are Chainlink's faucet and MyCrypto.
It's extremely important to pass each contract function the correct data in the expected data type. Otherwise, you might end up paying an exorbitant amount in gas fees due to an input error. Thankfully, Metamask warns you when your transaction is likely to fail.
If your application needs to display a list of tokens (with their meta information, current prices etc), I would recommend Coingecko's API which is what I used.

Helpful resources:

Please feel free to reach out if you have any questions, comments or notice any errors.

Also, here’s to finally publishing my first article! 🥂