Creating API for Invoice Generator Using C# and Minimal APIs

2025-07-02T00:00:00+00:00

In this blog post, we will explore how to create a robust invoice generator API using .NET 9 and minimal APIs, with a focus on integrating it with an existing Vue frontend whose implementation we covered in a previous blog post.

We will use the minimal APIs framework to create a RESTful API that can be easily used by our Vue application. Minimal APIs require less boilerplate code and configuration compared to traditional controller-based approaches. It is suited for smaller APIs, microservices, or serverless functions. You can learn more about choosing between controller-based APIs and minimal APIs here.

Prerequisites

Before going further into the code, we should make sure to have the following tools and technologies installed:

.NET 9 (the latest version of the .NET runtime)

Additionally, we already have an existing Vue frontend implementation that lacks API connectivity from our previous post. We will guide you through the process of integrating the Invoice Generator API with Vue application.

Setting up the Project

We will use the dotnet command to create a new .NET 9 project and set up the minimal APIs framework using the steps below:

Create a new .NET Core Web API project using the following command:

dotnet new webapi -n invoice-generator-api

Navigate to the newly created project directory:

cd invoice-generator-api

Open the Program.cs file which should look like below.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast =  Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast");

app.Run();

record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

We will also add the following packages for Swagger UI, Entity Framework, and the Entity Framework Core provider for PostgreSQL.

dotnet add package Microsoft.Extensions.ApiDescription.Server
dotnet add package Swashbuckle.AspNetCore.SwaggerUi
dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL
dotnet add package Microsoft.EntityFrameworkCore.Design

Setting up the Swagger UI

Update Program.cs and configure Swagger UI to point to the OpenAPI JSON file.

 if (app.Environment.IsDevelopment())
 {
     app.MapOpenApi();
+    app.UseSwaggerUI(config =>
+    {
+        config.SwaggerEndpoint("/openapi/v1.json", "v1");
+    });
 }

 app.UseHttpsRedirection();

Once the application is running using dotnet run, you can access Swagger UI at http://localhost:<PORT>/swagger on your browser, which should look like below.

Setting up the Database Context with Entity Framework

Create a file, InvoiceDbContext.cs, in the root of the project and add the following code.

using Microsoft.EntityFrameworkCore;

public class InvoiceDbContext : DbContext
{
    public InvoiceDbContext(DbContextOptions<InvoiceDbContext> options)
     : base(options)
    {

    }
}

Update the Program.cs file to include the configuration for connecting to the PostgreSQL database using Entity Framework.

+using Microsoft.EntityFrameworkCore;
+
 var builder = WebApplication.CreateBuilder(args);

+builder.Services.AddDbContext<InvoiceDbContext>(options =>
+    options.UseNpgsql(builder.Configuration.GetConnectionString("InvoiceDbcontext")));
+
+

Add the connection string InvoiceDbcontext in the appsettings.json file as shown below:

       "Microsoft.AspNetCore": "Warning"
     }
   },
-  "AllowedHosts": "*"
+  "AllowedHosts": "*",
+  "ConnectionStrings": {
+    "InvoiceDbcontext": "Host=<HOSTNAME>;Port=<PORT>;Database=<DATABASE>;Username=<USERNAME>;Password=<PASSWORD>;"
+  }
 }

Designing the Invoice Generator API

The next step is to design the API endpoints required for invoice generation. We will need the following endpoints:

GET /api/invoice — Get list of invoices
POST /api/invoice — Create a new invoice
GET /api/invoice/{id} — Get an invoice using ID
PUT /api/invoice/{id} — Update an invoice using ID
DELETE /api/invoice/{id} — Soft delete an invoice using ID
PUT /api/invoice/{id}/upload-logo — upload logo to saved invoice using ID
DELETE /api/invoice/{invoiceId}/detail/{id} — Soft delete invoice line item using line item ID and invoice ID

We will also need data models and entities to represent invoices and invoice line items. Let’s create the following classes in the model folder:

public class Base
{
    public int Id { get; set; }
    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
    public DateTime? ModifiedAt { get; set; }
    public bool IsDeleted { get; set; } = false;
    public DateTime? DeletedAt { get; set; }
}

public class Invoice : Base
{
    public string? Name { get; set; }
    public string? logo { get; set; }
    public string? Number { get; set; }
    public string? PONumber { get; set; }
    public virtual List<InvoiceItem> InvoiceItems { get; set; } = new();
    public UsageAmount? DiscountAmount { get; set; }
    public UsageAmount? TaxAmount { get; set; }
    public UsageAmount? ShippingAmount { get; set; }
    public decimal TotalAmount { get; set; }
    public decimal PaidAmount { get; set; }
    public string? Sender { get; set; }
    public string? Buyer { get; set; }
    public Status? Status { get; set; }
    public string? Notes { get; set; }
    public string? Terms { get; set; }
    public DateTime? Date { get; set; }
    public DateTime? DueDate { get; set; }
    public bool SentToBuyer { get; set; } = false;
}

public class InvoiceItem : Base
{
    public string Description { get; set; } = string.Empty;
    public int Quantity { get; set; }
    public decimal Rate { get; set; }
    public decimal Amount { get => this.Quantity * this.Rate; }
}

public class UsageAmount : Base
{
    public bool IsUsed { get; set; } = false;
    public bool IsPercentage { get; set; } = false;
    public decimal Value { get; set; } = 0;
}

Will will now use these classes to create tables in the database and then define a DBSet for each class in our InvoiceDbContext.cs.

 public InvoiceDbContext(DbContextOptions<InvoiceDbContext> options)
  : base(options)
 {

 }
+    public DbSet<Invoice> Invoices => Set<Invoice>();
+    public DbSet<InvoiceItem> InvoiceItems => Set<InvoiceItem>();
+    public DbSet<UsageAmount> UsageAmounts => Set<UsageAmount>();
 }

Since we will be using the soft delete feature in our API, we will use Global Query Filters to filter out the deleted records from our table. So, we configure the query filters in OnModelCreating using the HasQueryFilter API in InvoiceDbContext.cs. After which, the file should look like below.

 public InvoiceDbContext(DbContextOptions<InvoiceDbContext> options)
  : base(options)
 {

 }
+    protected override void OnModelCreating(ModelBuilder modelBuilder)
+    {
+        modelBuilder.Entity<Invoice>().HasQueryFilter(p => !p.IsDeleted);
+        modelBuilder.Entity<InvoiceItem>().HasQueryFilter(p => !p.IsDeleted);
+        modelBuilder.Entity<UsageAmount>().HasQueryFilter(p => !p.IsDeleted);
+    }
+
+    public DbSet<Invoice> Invoices => Set<Invoice>();
+    public DbSet<InvoiceItem> InvoiceItems => Set<InvoiceItem>();
+    public DbSet<UsageAmount> UsageAmounts => Set<UsageAmount>();
 }

Creating and running database migrations

We have defined models for our data models, but we need to create a database and tables for them. We can do this using Entity Framework tool dotnet ef. On the command prompt, in the root path of project, run the following command:

dotnet ef migrations add "create table and columns"

This command will create migration files in the Migrations folder. We can run this migration using the following command:

dotnet ef database update

Implementing API Endpoints

Now that we have designed the API endpoints and data models, let’s implement them using minimal APIs. We will create a new endpoints folder and add an InvoiceEndpoints.cs file in it. This file will contain the implementation for the Invoice API endpoints.

// InvoiceEndopints.cs

using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Hosting.Internal;

public static class InvoiceEndpoints
{
    public static List<Invoice> Invoices = new();
    public static RouteGroupBuilder MapInvoiceEndpoints(this RouteGroupBuilder group)
    {
      // Return list of invoices
        group.MapGet("/", async (InvoiceDbContext db) =>
        {
            return await db.Invoices.Include(x => x.InvoiceItems).ToListAsync();
        })
            .WithSummary("Get list of invoices");

        // Return an existing invoice
        group.MapGet("/{id}", async (int id, InvoiceDbContext db) =>
        {
            return await db.Invoices.Include(x => x.InvoiceItems).FirstOrDefaultAsync(x => x.Id == id)
            is Invoice invoice
                ? Results.Ok(invoice)
                : Results.NotFound();
        })
            .WithSummary("Get an invoice using id");

        // Create an invoice
        group.MapPost("/", async (Invoice invoice, InvoiceDbContext db) =>
        {
            invoice.DueDate = invoice.DueDate.HasValue ? invoice.DueDate.Value.ToUniversalTime() : null;
            invoice.Date = invoice.Date.HasValue ? invoice.Date.Value.ToUniversalTime() : null;
            db.Invoices.Add(invoice);
            await db.SaveChangesAsync();
            return Results.Created($"/api/invoice/{invoice.Id}", invoice);
        })
            .WithSummary("Create a new invoice");

        // Create a new line item for an existing invoice
        group.MapPost("/{id}/items", async (int id, List<InvoiceItem> invoiceItems, InvoiceDbContext db) =>
        {
            if (await db.Invoices.FindAsync(id)
            is not Invoice invoice)
            {
                return Results.NotFound();
            }
            invoice.InvoiceItems.AddRange(invoiceItems);
            await db.SaveChangesAsync();
            return Results.Created($"/api/invoice/{invoice.Id}", invoice);
        })
            .WithSummary("Create new line items for invoice");

        // Update an existing invoice
        group.MapPut("/{id}", async (int id, Invoice inputInvoice, InvoiceDbContext db) =>
        {
            var invoice = await db.Invoices.AsNoTracking().FirstOrDefaultAsync(x => x.Id == id);

            if (invoice is null) return Results.NotFound();

            invoice.Id = id;
            db.Invoices.Update(inputInvoice);
            await db.SaveChangesAsync();
            return Results.NoContent();
        })
            .WithSummary("Update invoice");

        // Upload invoice logo image file for an existing invoice
        group.MapPut("/{id}/upload-logo", async (int id, IFormFile uploadImageFile, InvoiceDbContext db) =>
        {
            var invoice = await db.Invoices.AsNoTracking().FirstOrDefaultAsync(x => x.Id == id);

            if (invoice is null) return Results.NotFound();

            if (uploadImageFile == null)
            {
                throw new ArgumentNullException(nameof(uploadImageFile));
            }

            var contentPath = Environment.CurrentDirectory;
            var uploadPath = Path.Combine("Uploads", id.ToString());
            var rootPath = Path.Combine(contentPath, uploadPath);

            if (!Directory.Exists(rootPath))
            {
                Directory.CreateDirectory(rootPath);
            }
            string[] allowedFileExtensions = [".jpg", ".jpeg", ".png"];
            var ext = Path.GetExtension(uploadImageFile.FileName);
            if (!allowedFileExtensions.Contains(ext))
            {
                throw new ArgumentException($"Please upload only .jpg, .jpeg, and .png images.");
            }

            // generate a unique filename
            var fileName = $"{Guid.NewGuid().ToString()}{ext}";
            var fileNameWithPath = Path.Combine(uploadPath, fileName);
            var rootPathWithFileName = Path.Combine(rootPath, fileName);
            using var stream = new FileStream(rootPathWithFileName, FileMode.Create);
            await uploadImageFile.CopyToAsync(stream);

            invoice.logo = fileNameWithPath;
            db.Update(invoice);
            await db.SaveChangesAsync();
            return Results.NoContent();
          })
          .DisableAntiforgery()
          .WithSummary("upload logo");

        // soft delete an invoice
        group.MapDelete("/{id}", async (int id, InvoiceDbContext db) =>
        {
            if (await db.Invoices.FindAsync(id) is Invoice todo)
            {
                todo.IsDeleted = true;
                todo.DeletedAt = DateTime.Now.ToUniversalTime();
                await db.SaveChangesAsync();
                return Results.NoContent();
            }
            return Results.NotFound();
        })
            .WithSummary("Soft delete an invoice");

        return group;
    }
}

Then we will also implement InvoiceDetailEndpoint.cs. We will only define a delete endpoint for soft deleting the line items. We created this also to demonstrate how to use multiple files in the Program.cs to map the endpoints to a certain URL.

// InvoiceDetailEndpoint.cs

public static class InvoiceDetailEndpoints
{
    public static RouteGroupBuilder MapInvoiceDetailEndpoints(this RouteGroupBuilder group)
    {
        group.MapDelete("/{id}", async (int id, InvoiceDbContext db) =>
        {
            if (await db.InvoiceItems.FindAsync(id) is InvoiceItem invoiceItem)
            {
                invoiceItem.IsDeleted = true;
                invoiceItem.DeletedAt = DateTime.Now.ToUniversalTime();
                await db.SaveChangesAsync();
                return Results.NoContent();
            }
            return Results.NotFound();
        }).WithSummary("Soft delete invoice line item");

        return group;
    }
}

Similar to how traditional controller APIs are separated in their own files, we now have the implementation for the endpoints in two files. We will now register and map the endpoints to a preferred URL using MapGroup in the Program.cs file.

 // Program.cs

+var root = app.MapGroup("api");
+var invoice = root.MapGroup("invoice").MapInvoiceEndpoints();
+var invoiceDetail = root.MapGroup("invoice/{invoiceId}/detail").MapInvoiceDetailEndpoints();
+
 app.Run();

We also need to add a config to expose the Uploads folder so the images can be loaded from the running API server. Also, make sure to create the Uploads folder before running the application, otherwise the application wouldn’t run.

 // Program.cs

 var invoice = root.MapGroup("invoice").MapInvoiceEndpoints();
 var invoiceDetail = root.MapGroup("invoice/{invoiceId}/detail").MapInvoiceDetailEndpoints();

+app.UseStaticFiles(new StaticFileOptions
+{
+    FileProvider = new PhysicalFileProvider(
+        Path.Combine(builder.Environment.ContentRootPath, "Uploads")),
+    RequestPath = "/Uploads"
+});
+
 app.Run();

Adding CORS for development

While working locally we usually run the frontend application and the API application in different ports, so CORS is required for the frontend application to access the API. To enable CORS in development mode, we can add the following code snippet to our Program.cs file:

 // Program.cs

 using Microsoft.EntityFrameworkCore;
 using Microsoft.Extensions.FileProviders;

 var builder = WebApplication.CreateBuilder(args);
+var MyAllowSpecificOrigins = "_myAllowSpecificOrigins";
+builder.Services.AddCors(options =>
+{
+    options.AddPolicy(name: MyAllowSpecificOrigins,
+                      policy =>
+                      {
+                          policy.AllowAnyOrigin();
+                          policy.AllowAnyHeader();
+                          policy.AllowAnyMethod();
+                      });
+});

 builder.Services.AddDbContext<InvoiceDbContext>(options =>
     options.UseNpgsql(builder.Configuration.GetConnectionString("InvoiceDbcontext")));

 app.MapGet("/weatherforecast", () =>
 var root = app.MapGroup("api");
 var invoice = root.MapGroup("invoice").MapInvoiceEndpoints();
 var invoiceDetail = root.MapGroup("invoice/{invoiceId}/detail").MapInvoiceDetailEndpoints();

+app.UseCors(MyAllowSpecificOrigins);
 app.UseStaticFiles(new StaticFileOptions
 {
     FileProvider = new PhysicalFileProvider(

Now, we can start the application and test our API. When we go to /swagger, we can see our API endpoints.

The source code for the API is available on GitHub.

Integrating with Vue 3 Application

We already created a Vue 3 application in the previous blog. Now, we will integrate our API with the Vue application.

To integrate the Invoice Generator API with our Vue 3 application, we will need to configure API calls from the frontend to interact with the API. We will follow the following steps:

Install the axios package in our Vue 3 project:

npm install axios

Create a new file called index.ts in the services folder of our Vue 3 project and add the following code. Also, add .env file with key VITE_API_URL and value of the API URL:

// services/index.ts

import axios from 'axios'
export default axios.create({
    baseURL: import.meta.env.VITE_API_URL,
    timeout: 5000,
});

# .env
VITE_API_URL=https://localhost:7041/api/
VITE_BACKEND_URL=https://localhost:7041/

Create a new file called invoiceService.ts in the services folder of your Vue 3 project. Add the methods that calls the API endpoints:

import { Invoice, InvoiceItem } from "../types/index.type"
import axios from "./"

export default {
    getInvoices: async () => {
        return await axios.get('invoice')
    },
    getInvoice: async (id) => {
        return await axios.get(`invoice/${id}`)
    },
    saveInvoice: async (data: Invoice) => {
        return await axios.post('invoice', data)
    },
    deleteInvoice: async (id: number) => {
        return await axios.delete(`invoice/${id}`)
    },
    updateInvoice: async (id: number, data: Invoice) => {
        return await axios.put(`invoice/${id}`, data)
    },
    uploadLogo: async (invoiceId, file) => {
        const formData = new FormData();
        formData.append("imageFile", file);
        return axios.put(`invoice/${invoiceId}/upload-logo`, formData, { headers: { "Content-Type": "multipart/form-data" } });
    },
    addLineItem: async (id: number, data: InvoiceItem) => {
        return await axios.post(`invoice/${id}/detail/`, data);
    },
    updateLineItem: async (id: number, lineId: number, data: InvoiceItem) => {
        return await axios.put(`invoice/${id}/detail/${lineId}`, data)
    },
    deleteLineItem: async (id: number, lineId: number) => {
        return await axios.delete(`invoice/${id}/detail/${lineId}`)
    },
}

We will use invoiceService.ts to make API calls in our application. Normally, the API calls are usually made from Vue 3 components, but in this case we will use it to make API calls from our composable useInvoiceStorage.ts where all the business logic related to invoice are handled. Below are the code changes done to integrate the API calls from invoiceService.ts.

 // composables/useInvoiceStorage.ts

 import { useStorage } from '@vueuse/core'
-import { reactive } from 'vue';
+import { computed, ref } from 'vue';
 import { Invoice, InvoiceStore } from '../types/index.type';
+import invoiceService from '../services/invoiceService';

 const storage = useStorage<InvoiceStore>('invoice-store', {
-    currentInvoiceNumber: 10000,
-    invoices: {}
+    currentInvoiceNumber: "10000",
 }, localStorage);

+const state = ref({
+    ...storage.value,
+    invoices: {},
+});
 export default function useState() {
-    const state = reactive(storage);

     function saveInvoice(invoice: Invoice) {
         state.value.invoices[invoice.number] = { ...invoice };
-        state.value.currentInvoiceNumber = invoice.number + 1;
+        state.value.currentInvoiceNumber = `${+invoice.number + 1}`;
+        invoiceService.saveInvoice(invoice);
     }

-    function updateInvoice(invoice: Invoice) {
+    function updateInvoice(id: number, invoice: Invoice) {
         state.value.invoices[invoice.number] = { ...invoice };
+        invoiceService.updateInvoice(id, invoice);
     }

-    function deleteInvoice(invoiceId: number) {
+    async function deleteInvoice(invoiceId: number) {
         // delete state.value.invoices[invoiceId];
+        await invoiceService.deleteInvoice(invoiceId);
         state.value.invoices = Object.keys(state.value.invoices).filter(x => x != invoiceId.toString()).reduce((acc, curr) => {
             return {
                 ...acc,
@@ -40,15 +45,33 @@ export default function useState() {
         })
             .map(x => ({ ...state.value.invoices[x] }))

+
+    }
+
+    async function fetchInvoices() {
+        const result = await invoiceService.getInvoices();
+        state.value.invoices = result.data.reduce((acc, curr) => {
+            return { ...acc, [curr.id]: curr }
+        }, {})
+    }
+    async function fetchInvoice(id) {
+        const result = await invoiceService.getInvoice(id);
+        console.log(result);
+        state.value.invoices[result.data.id] = result.data;
+        console.log(state.value.invoices);
+        return result.data;
     }
     return {
         // variables
         storage: state,
+        invoices: computed(() => state.value.invoices),

         // methods
         saveInvoice,
         updateInvoice,
         deleteInvoice,
-        findInvoices
+        findInvoices,
+        fetchInvoices,
+        fetchInvoice
     }
 }

The above fetchInvoices method is then used by Invoices.vue to fetch the invoices. Similarly, all other endpoints are used in the application for CRUD operations.

The source code for the Vue app is available on GitHub.

Deployment

To deploy our API to Azure App Service, we can follow the documentation provided by Microsoft here.

Conclusion

In this blog post, we explored how to create a robust invoice generator API using .NET 9 and minimal APIs. We designed the API endpoints, implemented them using minimal APIs, and integrated the API with an existing Vue 3 application. This approach allowed us to leverage the power of minimal APIs while maintaining a clean and modular codebase.

How to Migrate from Struts 2 to Struts 6

2025-04-17T00:00:00+00:00

With the introduction of Struts 6, developers are provided enhanced features, security improvements, and modern practices that align with contemporary Java development. If you’re currently using Struts 2, migrating to Struts 6 is a worthwhile endeavor that can future-proof your application.

Also, since Struts 2.5.x reached its end of life, there won’t be any security updates for this version. This guide will walk you through the key differences between Struts 2 and Struts 6, including some significant changes in Struts 6 with practical configuration and code examples.

Getting Ready for Migration from Struts 2 to Struts 6

Starting from Struts 6.0.0 the framework requires Java 8 at minimum. So, if you are running a Struts 2.x environment on an old version of Java, it needs to be upgraded to Java 8 at least. Check out the Struts 6.0.0 version notes for a list of changes.

Config and Code Changes

Servlet API Dependency

Struts 6.0.0 requires Servlet API 3.1 or newer and won’t work with the older versions. The Maven dependency that you can use for this is below:

<dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <version>3.1.0</version>
    <scope>provided</scope>
</dependency>

Deprecated Sitegraph Plugin Removed

Support for the sitegraph plugin, which was already deprecated, has now been removed entirely.

Velocity Plugin

Velocity support has been moved into a dedicated plugin. To continue using the Velocity plugin in your Struts application, you can extend the Struts config package definition, adding velocity-default in struts.xml as in the below example:

<package name="mystrutsapp" extends="struts-default, velocity-default">
  ...
</package>

DTD of struts.xml

The proper DTD (Document Type Definition) header of struts.xml should be updated as below:

<!DOCTYPE struts PUBLIC
    "-//Apache Software Foundation//DTD Struts Configuration 6.0//EN"
    "https://struts.apache.org/dtds/struts-6.0.dtd">

Class Changes

There are some class changes you might need to consider.

com.opensymphony.xwork2.config.providers.XmlConfigurationProvider was made abstract. You should now use org.apache.struts2.config.StrutsXmlConfigurationProvider instead.
com.opensymphony.xwork2.conversion.TypeConversionException was replaced byorg.apache.struts2.conversion.TypeConversionException.
com.opensymphony.xwork2.XWorkException was replaced by org.apache.struts2.StrutsException.

Constant Changes

Xwork config constants like devMode were already deprecated and replaced with new constants like struts.devMode. In Struts 6.0.0, the deprecated constants were completely removed. Also, new constants struts.i18n.search.defaultbundles.first and struts.ui.escapeHtmlBody were introduced.

OGNL

Starting from Struts 6.0.0 OGNL expression length is limited to 256 characters by default as longer expressions can be considered harmful. However, the limit can be changed by adjusting the struts.ognl.expressionMaxLength constant in struts.xml.

Static method access is not possible using OGNL expressions like @com.mypack.MyClass@MyStaticMethod(). This usage should be converted to alternative approaches such as Value Stack access through Action methods:

// MyAction.java
public class MyAction extends ActionSupport {

    public String getMyData() {
        return MyStaticClass.getMyStaticData();
    }

    public String execute() {
        return SUCCESS;
    }
}

// MyClass.java
public class MyStaticClass {
    public static String getMyStaticData() {
        return "Data from static method";
    }
}

In your JSP you can access the data using an OGNL expression:

<s:property value="myData" />

HTML Escaping

Struts 6 uses a newer FreeMarker version with auto-escaping enabled by default, affecting how output is rendered. You should avoid manual escaping (e.g., ?html) in FreeMarker templates when migrating to Struts 6.

Struts 2 manual escaping:

${user.name?html}

Struts 6 auto-escaping happens by default, so no ?html escape is necessary:

${user.name}

Tiles Support

Until version 6.3.0, Struts 2 and Struts 6 had been supporting Tiles through Apache Tiles. The Apache Tiles project has been retired and is not updated anymore. The Struts team incorporated the Apache Tiles codebase into Struts and essentially added built-in support for Tiles starting with Struts version 6.3.0 through the new Tiles Plugin.

If you are using Maven you can use the following dependency to setup the Tiles plugin in Struts 6.x:

<dependency>
  <groupId>org.apache.struts</groupId>
  <artifactId>struts2-tiles-plugin</artifactId>
  <version>${version.tiles}</version>
</dependency>

And then register the Tile listener in your web.xml:

<listener>
  <listener-class>org.apache.struts2.tiles.StrutsTilesListener</listener-class>
</listener>

Conclusion

Migrating from Struts 2 to Struts 6 involves several significant changes due to updates in the framework’s architecture, dependencies, and requirements. Struts 6 (starting with version 6.0.0) introduces modernizations to align with newer Java versions, servlet specifications, and security practices.

Learning Vue 3 composables by creating an invoice generator

2025-01-06T00:00:00+00:00

The latest major version of Vue, Vue 3, has new features that are not present in Vue 2, such as Teleport, Suspense, and support for multiple root elements per template. Vue 3 provides smaller bundle sizes, better performance, better scalability, and better TypeScript IDE support.

What are Vue 3 composables?

Writing repetitive code can be a real pain in the frontend development realm. We can use Vue 3 composables to encapsulate and reuse stateful logic in our components. In this blog post, we will look at how we can use composables to reuse business logic by building an invoice generator.

An invoice generator, simply said, is an application that creates and manages invoices. We will focus on creating Vue 3 composables to properly separate business logic while reusing it across different features.

Core functionalities for invoice generator

Adding, editing, and removing invoices and items
Calculating totals with discounts, taxes, and shipping
Generating PDF invoices

To implement these functionalities, we’ll focus on:

Creating composables to handle business logic
Reusing this logic across features and components

Prerequisites

Basic understanding of:

Vue 3 and Composition API
JavaScript/TypeScript fundamentals

Tools:

Node.js and npm installed
Vite
Tailwind CSS (optional)

Setting up the project

First, initialize the Vue 3 project:

$ npm create vite@latest ep-invoice-generator
Need to install the following packages:
create-vite@6.0.1
Ok to proceed? (y) y
√ Select a framework: » Vue
√ Select a variant: » TypeScript

Scaffolding project in G:\PersonalWork\blog\ep-invoice-generator...

Done. Now run:

  cd ep-invoice-generator
  npm install
  npm run dev

Create folders for the project structure:

src/components/ for adding UI components
src/composables/ for adding composables
src/router/ for adding Vue Router routes
src/types/ for adding type definitions
src/views/ for adding pages to render based on Vue Router routes

Create first composable for invoice: `useInvoice`

The composable is named useInvoice.ts and it will serve the following purposes:

Handle data for invoice and invoice items
Add methods for adding, editing, and removing invoice items
Calculate totals automatically using item’s rate and amount as well as discount, tax, and shipping
Reset invoice

Define interfaces for `Invoice` and `InvoiceItem`

export interface InvoiceItem {
    id: number,
    description: string,
    rate: number,
    quantity: number,
}

export interface Invoice {
    logo: string,
    name: string,
    number: number,
    ponumber: string,
    date: string,
    duedate: string,
    sender: string,
    buyer: string,
    items: InvoiceItem[];
    notes: string,
    terms: string,
    discount: {
        isUsed: boolean,
        isPercentage: boolean,
        value: number,
    },
    tax: {
        isUsed: boolean,
        isPercentage: boolean,
        value: number,
    },
    shipping: {
        isUsed: boolean,
        value: number,
    },
    total: number,
    paid: number,

    sentToContact: boolean,
    status: Status,
}

First we make an Invoice object to create and edit an invoice. The code state.storage.value.currentInvoiceNumber gets the current invoice number to use for the new invoice, we will learn more about it later.

We return the object containing the required data and methods that can be used by any single-file component (SFC). We will see the implementation of computed properties and methods in the next section.

export function useInvoice(invoiceId?: number) {

    const invoice = reactive<Invoice>({
        logo: "",
        name: "",
        number: state.storage.value.currentInvoiceNumber,
        ponumber: "",
        date: format(date, "yyyy-MM-dd"),
        duedate: "",
        sender: "",
        buyer: "",
        items: [
            {
                id: 1,
                description: "",
                rate: 0,
                quantity: 0,
            },
        ],
        notes: "",
        terms: "",
        discount: {
            isUsed: false,
            isPercentage: false,
            value: 0,
        },
        tax: {
            isUsed: false,
            isPercentage: false,
            value: 0,
        },
        shipping: {
            isUsed: false,
            value: 0,
        },
        total: 0,
        paid: 0,
        sentToContact: false,
        status: Status.Draft,
    });

    const subtotal = computed(() => ...)
    const afterDiscount = computed(() => ...)
    const afterTax = computed(() => ...)
    const afterShipping = computed(() => ...)
    const total = computed(() => ...)
    const balance = computed(() => ...);

    const updateLineItem = (value: InvoiceItem, index: number) => ...);
    const addLineItem = () => ...)
    const removeLineItem = (index) => ...)

    return {
        // data helpers
        invoice,
        subtotal,
        afterDiscount,
        afterTax,
        afterShipping,
        total,
        balance,

        // Methods
        addLineItem,
        updateLineItem,
        removeLineItem,
    }
}

Adding business logic

Now we implement the business logic for various methods — adding an invoice item, updating an invoice item, etc. — as well as calculating the various dynamic amounts.

The following methods add an invoice item to the invoice as a line item, which can be rendered on the UI. Then, the user can update the line item’s rate and quantity, which calls updateLineItem to update the invoice item data.

/**
 * Add a line item to the invoice line items array
 */
const addLineItem = () => {
    invoice.items.push({
        id: invoice.items.length + 1,
        description: "",
        rate: 0,
        quantity: 0,
    });
};

/**
 * @param {invoice line item} value
 * @param {index of invoice line item} index
 * @returns
 */
const updateLineItem = (value: InvoiceItem, index: number) => (invoice.items[index] = { ...value });

/**
 * Remove items from invoice items array
 * @param {*} index index of item to remove
 */
const removeLineItem = (index) => {
    invoice.items.splice(index, 1);
};

Based on the invoice item data, we then calculate:

subtotal
subtotal after discount, if available
subtotal after tax, if available
subtotal after shipping, if available

Moreover, discount and tax can be stored as an amount or as a percentage value, so we update the logic to evaluate discount and tax based on the type of the entered values and calculate the subtotal. We can also include a previously overpaid amount and calculate the balance at the end of the calculations.

// useInvoice.ts
const subtotal = computed(() =>
    invoice.items.reduce((prev, acc) => prev + acc.rate * acc.quantity, 0)
);

/**
 * Compute total value after applying discount
 * based on `discount` percentage or value and `subtotal` value
 */
const afterDiscount = computed(() => {
    if (invoice.discount.isUsed) {
        if (invoice.discount.isPercentage) {
            return subtotal.value - (subtotal.value * invoice.discount.value) / 100;
        } else {
            return subtotal.value - invoice.discount.value;
        }
    }
    return subtotal.value;
});

/**
 * Compute total value after applying tax
 * based on `tax` percentage or value and `afterDiscount` value
 */
const afterTax = computed(() => {
    if (invoice.tax.isUsed) {
        if (invoice.tax.isPercentage) {
            return (
                afterDiscount.value + (afterDiscount.value * invoice.tax.value) / 100
            );
        } else {
            return afterDiscount.value + invoice.tax.value;
        }
    }
    return afterDiscount.value;
});

/**
 * Compute total value after applying shipping
 * based on `shipping` value and `afterTax` value
 */
const afterShipping = computed(() => {
    if (invoice.shipping.isUsed) {
        return afterTax.value + invoice.shipping.value;
    }
    return afterTax.value;
});

const total = computed(() => {
    return afterShipping.value;
});

// later if we track the payment done for the clients, we can easily
// come up with the balance based on the payment and invoices
const balance = computed(() => total.value - invoice.paid);

Rendering the invoice with composable functions

We create the InvoiceGenerator.vue SFC, utilizing the useInvoice composable we created. We use the <script setup> syntax for importing and using the composable. <script setup> help us use Composition API inside SFCs instead of the Options API. Using the <script setup> syntax removes boilerplate code while providing the ability to declare props, emitted events, and many more advantages.

<!-- InvoiceGenerator.vue-->
<script setup>
import { useInvoice } from "../composables/useInvoice";

const {
  // data
  invoice,

  // computed / read only
  subtotal,
  total,
  balance,

  // methods
  addLineItem,
  updateLineItem,
  removeLineItem,
  resetInvoice
} = useInvoice(
</script>

I have already defined the LineItems.vue component, where we render the line items which have text boxes to enter description, rate, and amount. The totals for each item are calculated using the computed property. Let’s see an example showing how we can use it with invoice items:

Use items prop to render the invoice items
Emit update-item event when any value for an invoice line item changes
Emit add-item when user adds a new line item
Emit close when user removes a line item

<LineItems
    :items="invoice.items"
    @update-item="updateLineItem"
    @close="removeLineItem"
    @add-item="addLineItem"
    />

Similarly, we use invoice.discount, invoice.tax, and invoice.shipping properties from the composable in a text box where the user can enter the value and type of the value. All of them have helper properties named isUsed and isPercentage, which we use to make the input box user-friendly. The CustomInput, CustomToggleSwitch and WithLabel are three custom components that are already created and they can be used as follows:

<WithLabel label="Discount">
    <CustomInput
        v-model.number="invoice.discount.value"
        is-used
        label="Discount"
        toggle
        :currency="!invoice.discount.isPercentage"
        @close="invoice.discount.isUsed = false"
    >
        <CustomToggleSwitch
        v-model="invoice.discount.isPercentage"
        :for-value="'invoice-discount'"
        />
    </CustomInput>
</WithLabel>

<WithLabel label="Tax">
    <CustomInput
        v-model.number="invoice.tax.value"
        is-used
        label="Tax"
        toggle
        :currency="!invoice.tax.isPercentage"
        @close="invoice.tax.isUsed = false"
    >
        <CustomToggleSwitch
        v-model="invoice.tax.isPercentage"
        :for-value="'invoice-tax'"
        />
    </CustomInput>
</WithLabel>

<WithLabel label="Shipping">
    <CustomInput
        v-model.number="invoice.shipping.value"
        label="Shipping"
        is-used
        currency
        @close="invoice.shipping.isUsed = false"
    >
    </CustomInput>
</WithLabel>

All other properties can also be rendered, but we would like some input fields, like PO Number, Invoice Date, and Amount Paid to be rendered differently. Using custom components like CustomInput and CustomToggleSwitch can help us get more control of the visual and functional aspects of the UI component.

<WithLabel label="PO Number">
    <CustomInput
    v-model="invoice.ponumber"
    label="PO Number"
    type="text"
    />
</WithLabel>

<WithLabel label="Date">
    <CustomInput
    v-model="invoice.date"
    label="Date"
    type="date"
    />
</WithLabel>

<WithLabel label="Amount Paid">
    <CustomInput
    v-model.number="invoice.paid"
    label="Amount Paid"
    currency
    />
</WithLabel>

Create a second composable for using localStorage to save and retrieve invoice data

The useInvoice composable only gives us the invoice data along with computed properties, but now we have to save it somewhere so we can use it later. We can use localStorage to save the invoices. VueUse is a very good library that has a collection of Vue composition utilities that can be used with Vue 2 as well as Vue 3.

For accessing localStorage reactively, we will use a composable from VueUse called useStorage, which uses localStorage by default. We will define saveInvoice, updateInvoice, deleteInvoice, and findInvoices methods that use the reactive variable from useStorage to perform the required operations.

We will create another composable called useInvoiceStorage.ts, where we initialize our storage using useStorage, which also stores the current invoice number.

// useInvoiceStorage.ts

const storage = useStorage<InvoiceStore>('invoice-store', {
    currentInvoiceNumber: 10000,
    invoices: {}
}, localStorage);

Then we define and implement the methods discussed above for saving, updating, deleting, and finding invoices. The update of the current invoice number happens in the saveInvoice method.

// useInvoiceStorage.ts

export default function useState() {
    const state = reactive(storage);

    function saveInvoice(invoice: Invoice) {
        state.value.invoices[invoice.number] = { ...invoice };
        state.value.currentInvoiceNumber = invoice.number + 1;
    }

    function updateInvoice(invoice: Invoice) {
        state.value.invoices[invoice.number] = { ...invoice };
    }

    function deleteInvoice(invoiceId: number) {
        state.value.invoices = Object.keys(state.value.invoices)
            .filter(x => x != invoiceId.toString())
            .reduce((acc, curr) => {
                return {
                    ...acc,
                    [curr]: state.value.invoices[curr]
                }
            }, {})
    }

    function findInvoices(searchText: string) {
        searchText = searchText.toLowerCase();
        return Object.keys(state.value.invoices).filter(x => {
            const invoice = state.value.invoices[x];
            return invoice.number.toString().indexOf(searchText) > -1
                || invoice.buyer.toString().toLowerCase().indexOf(searchText) > - 1
                || invoice.date.toString().toLowerCase().indexOf(searchText) > - 1
                || invoice.total.toString().indexOf(searchText) > - 1
        })
            .map(x => ({ ...state.value.invoices[x] }))

    }
    return {
        // variables
        storage: state,

        // methods
        saveInvoice,
        updateInvoice,
        deleteInvoice,
        findInvoices
    }
}

Now, we can use data and methods from the useInvoiceStorage composable to show the latest invoice number as well as save, update, delete, and find invoices. The composable useInvoice also uses useInvoiceStorage to set the current invoice number for the new invoice. Whenever a user creates a new invoice, the current invoice number is automatically assigned to the invoice obtained from the useInvoiceStorage composable.

Moreover, the useInvoice composable is updated to support the new invoice and edit invoice features. Support for editing an invoice is achieved by passing invoiceId to the useInvoice composable, the invoiceId is then checked in the storage returned by useInvoiceStorage, if the invoice exists, the useInvoice composable returns the correct invoice data from storage.

The following code checks for the invoice in the storage:

// If the invoice is already in storage, use it
if (invoiceId) {
    const invoiceToUse = state.storage.value.invoices[invoiceId];
    if (invoiceToUse) Object.assign(invoice, invoiceToUse);
}

Printing Invoice

For printing invoices, we can simply use print styles from Tailwind CSS to style the elements that we want to print. A simple example is the CustomButton component in the source code. We don’t want to show any buttons on the PDF, so we use the Tailwind CSS style print:hidden to hide the buttons on the print view. We then need to call the method below on the invoice page to print the current page.

const print = () => window.print();

Bonus: create a third composable for showing dashboard data

The dashboard is important for looking at the high-level data and is crucial to any application. So, we add a new composable called useDashboardData.ts that will give us the total invoice amount, total paid amount, total due amount, and total drafted amount. It can be further expanded to include any other business logic as well. We will again use the useInvoiceStorage composable to get the list of invoices.

// useDashboardData.ts
import useState from "./useInvoiceStorage";
import { Status } from "../types/index.type";

export function useDashboardData() {
    const state = useState();

    const totalInvoiceAmount = computed(() => {
        const invoices = state.storage.value.invoices;
        const amount = Object.keys(invoices).reduce((acc, item) => acc + invoices[item].total, 0);
        return amount.toFixed(2)
    })

    const totalPaid = computed(() => {
        const invoices = state.storage.value.invoices;
        const amount = Object.keys(invoices).reduce((acc, item) => {
            if (invoices[item].status === Status.Paid) {
                return acc + invoices[item].total
            }
            return acc;
        }, 0);
        return amount.toFixed(2);
    })

    const totalDue = computed(() => {
        const invoices = state.storage.value.invoices;
        const amount = Object.keys(invoices).reduce((acc, item) => {
            if (invoices[item].status === Status.Overdue) {
                return acc + invoices[item].total
            }
            return acc;
        }, 0);
        return amount.toFixed(2);
    })

    const totalDrafted = computed(() => {
        const invoices = state.storage.value.invoices;
        const amount = Object.keys(invoices).reduce((acc, item) => {
            if (invoices[item].status === Status.Draft) {
                return acc + invoices[item].total
            }
            return acc;
        }, 0);
        return amount.toFixed(2);
    })

    return {
        // variables
        totalInvoiceAmount,
        totalPaid,
        totalDue,
        totalDrafted
    }
}

After that we create the Dashboard.vue component to use data from useDashboardData.ts and display the data on the dashboard. We can keep adding business logic to useDashboardData.ts to display data on the dashboard, and we can use it elsewhere to support other business logic.

<!-- Dashboard.vue -->
<template>
    <section class="max-w-[1800px] mx-auto">
        <div class="grid grid-cols-4 gap-x-4 mt-4">
            <Card>
                <template #header>Total Amount</template>
                <span>${{ totalInvoiceAmount }}</span>
                <template #footer></template>
            </Card>
            <Card>
                <template #header>Paid Amount</template>
                <span>${{ totalPaid }}</span>
                <template #footer></template>
            </Card>
            <Card>
                <template #header>Due Amount</template>
                <span>${{ totalDue }}</span>
                <template #footer></template>
            </Card>
            <Card>
                <template #header>Drafted Amount</template>
                <span>${{ totalDrafted }}</span>
                <template #footer></template>
            </Card>
        </div>
        <Invoices />
    </section>
</template>

<script setup lang="ts">
import Card from '../components/shared/Card.vue';
import { useDashboardData } from '../composables/useDashboardData';
import Invoices from './Invoices.vue';

const { totalInvoiceAmount, totalPaid, totalDue, totalDrafted } = useDashboardData();
</script>

The source code is available at GitHub.

An application demo is also available.

Next Steps

Use a REST API for saving the invoices to the database
Use Pinia to store the retrieved invoices so we can easily use the invoices
Add a composable to switch between different types of templates for printing PDFs

Conclusion

We learned about Vue 3 composables and how to use Composition API to create composables. We saw how composable functions are a game changer for building complex, maintainable, and scalable applications by encapsulating the business logic, organizing the code, and making it reusable. It helps to simplify the process and boost productivity.

Migration from Struts 1 to Struts 2

2024-10-04T00:00:00+00:00

Apache Struts is an open source web framework. Struts 1 was first released in 2000 and its latest version (1.3.10) was released in December 2008, marking the EOL of Struts 1. So Struts 1 is an ancient, dead version. Organizations still using it need to move away from Struts 1.

Apache adapted the WebWork framework as Struts 2. Its architecture significantly differs from that of Struts 1. There are key points and obvious differences provided by Apache to cover a migration plan from Struts 1 to Struts 2.

The market share of Apache Struts is around 0.01%, which gives relatively lower relevance to Apache Struts. However, there are companies still using Apache Struts 1 in their legacy applications, which may not be counted in market share statistics.

A Comparison of Struts 1 and Struts 2

Struts 1 and Struts 2 differ significantly in their approach to handling web requests. Struts 1 follows a more rigid structure where Action classes must extend an abstract base class, limiting flexibility. In contrast, Struts 2 is more dynamic, allowing Action classes to implement interfaces or even function as simple POJOs, enhancing adaptability. Struts 2 also includes the ActionSupport class, which implements commonly used interfaces, making development easier and more versatile.

The threading model in Struts 1 is based on a singleton pattern, meaning only one instance of an Action class exists to handle all requests, which requires careful management of thread safety. Struts 2, on the other hand, creates a new Action object for every request, which eliminates concerns about thread safety.

When it comes to servlet dependency, Struts 1 is tightly coupled with the servlet API, requiring Actions to work directly with HttpServletRequest and HttpServletResponse. Struts 2 decouples the Action from the servlet container, using simple maps to represent the context. This allows for easier testing and more modular code. Struts 2 still offers the flexibility to access the request and response objects when necessary, but often through other architectural patterns that minimize the need for direct servlet interaction.

Testing Struts 1 applications is challenging due to its tight coupling with the servlet API. External libraries like Struts TestCase are often required to mock servlet objects for testing purposes. Struts 2 makes testing far more straightforward by supporting dependency injection and allowing Action classes to be tested in isolation, without needing complex mocks.

Input handling in Struts 1 revolves around ActionForm objects, which must extend a base class which often leads to redundancy. Struts 2 simplifies this by using Action properties directly, eliminating the need for separate ActionForm objects. Additionally, Struts 2 supports complex object types for input and output, allowing domain specific objects to be used.

In terms of expression languages, Struts 1 integrates with JSTL, which provides basic object graph traversal but lacks robust support for collections. Struts 2 uses OGNL (Object Graph Notation Language), offering more advanced and flexible expression capabilities, giving developers more control over data handling in views.

Binding values into views is handled differently as well. Struts 1 uses standard JSP mechanisms, while Struts 2 introduces the ValueStack, a system that decouples the view from the object being rendered. This allows for a greater degree of reuse and flexibility, especially when dealing with varying property types across different objects.

Type conversion in Struts 1 is handled by Commons-Beanutils, which operates on a per-class basis. This can be limiting as it doesn’t allow for instance-level customization. Struts 2 improves on this by utilizing OGNL for type conversion, offering built-in converters for common types while also providing a flexible system for adding custom converters.

Lastly, the control over action execution is much more granular in Struts 2. While Struts 1 uses a single request processor per module, Struts 2 introduces Interceptor Stacks, allowing developers to define different lifecycles for individual Actions. This customization helps tailor the flow of execution to fit specific application requirements.

Actions are central components in both Struts 1 and 2 and play a major role in the architectures of both Struts versions. Struts 2 offers a more modern, flexible, and test-friendly framework, improving upon Struts 1’s limitations by embracing POJO actions, better type conversion, enhanced validation, and a decoupled threading model. These changes make Struts 2 more adaptable and easier to maintain, particularly for complex web applications.

You can see more about request processing flow in Struts 2 in this InfoQ article.

Migration

Dependencies

Add the Struts 2.0 Jars to the existing Struts 1.3 application. The latest Jar files can be downloaded from the Apache Struts download page. Alternatively, you can download the Jar files for any of the previous versions from the archive.

Request handling

Configure Struts 2 to handle requests with the *.action extension, differently from Struts 1, which uses the *.do extension.

Configure web application

The web application is enabled in the web.xml configuration file. There are a few changes to this file needed for Struts 2. Dispatcher configuration is done by simply renaming the configuration tags from <servlet> and <servlet-mapping> to <filter> and <filter-mapping>.

A very basic web.xml configuration for Struts 1 would look like:

<servlet>
    <servlet-name>action</servlet-name>
    <servlet-class>org.apache.struts.action.ActionServlet</servlet-class>
    <init-param>
        <param-name>config</param-name>
        <param-value>/WEB-INF/struts-config.xml</param-value>
    </init-param>
    <load-on-startup>2</load-on-startup>
</servlet>

<servlet-mapping>
    <servlet-name>action</servlet-name>
    <url-pattern>*.do</url-pattern>
</servlet-mapping>

The corresponding conversion to Struts 2 would look like:

<filter>
    <filter-name>webwork</filter-name>
    <filter-class>org.apache.struts.action2.dispatcher.FilterDispatcher</filter-class>
</filter>

<filter-mapping>
    <filter-name>webwork</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

Migrating actions

A general structure of a Struts 1 action class is below.

public class CustomAction extends Action {
    public ActionForward execute(
        ActionMapping mapping,
        ActionForm form,
        HttpServletRequest request,
        HttpServletResponse response) throws Exception {
        // add logic
        return (mapping.findForward("success"));
    }
}

Struts 1 actions are singletons and extend the base Action class. Alternatively, DispatchAction can be used instead of the base class. In either case, the execute method is the entry point to an Action class. Actions have to be thread-safe and hence all the necessary variables should be handled in method scope. Finally, the execute method returns an ActionForward response.

On the other hand, in Struts 2 a basic action class structure would look like this:

public class MyAction extends ActionSupport {
   public String execute() throws Exception {
        // add logic
        return "success";
   }
}

A Struts 2 action class will usually (but not necessarily) extend ActionSupport. The usual entry point is again the execute method—however, this method has no parameters. In Struts 2 action classes are not singletons. Instead an instance of the action class is created for each request, so class scope variables can be used safely, alleviating many thread-safety concerns in Struts 1 actions. Struts 2 will inject a HttpServletRequest for the current request into actions implementing the ServletRequestAware interface, allowing you access to the underlying request object.

Action Configuration

In Struts 1 applications, action configurations are made in struts-config.xml located in the WEB-INF directory. Struts 1 applications need to configure actions and action form beans in this configuration file.

<struts-config>

     <form-beans>
         <form-bean name="myForm" type="com.endpoint.blog.struts.MyForm"/>
         ...
     </form-beans>

    <global-forwards>
       <forward name="home" path="/home.do" redirect="true" />
       <forward name="projects" path="/myactionProcess.do?dispatch=myDispatch" redirect="true"/>
       ...
   </global-forwards>

   <action-mappings>
       <action path="/myPackage/add" type="org.apache.struts.actions.ForwardAction" />
       ...
   </action-mappings>

 </struts-config>

Struts 2 configuration involves a package wrapper around the action definitions.

<struts>
  <package name="myPackage" extends="struts-default">
      <action name="add" >
          <result>/myPackage/add.jsp</result>
        </action>
        ...
    </package>
 </struts>

However, in Struts 2, actions can be defined in a more general way using Struts conventions:

<struts>
  <constant name="struts.action.extension" value="ep"/>
    <constant name="struts.convention.action.packages" value="com.endpoint.blog.actions.*"/>
    ...
</struts>

In this article we covered migrating the most basic components from Struts 1 to Struts 2 and compared several features between each version. Complete configuration and code migration from Struts 1 to Struts 2 can be done gradually, involving actions, interceptors, tags, and many other details. Not completely straightforward, but the patterns and convention changes adopted in Struts 2 become clearer as you dive in.

Introduction to Nuxt3 and Rendering Modes

2024-07-12T00:00:00+00:00

Nuxt is a free and open-source framework which helps us build performant full-stack web applications and websites with Vue.js. Nuxt is built on top of Vue, so it is also called a meta-framework. Nuxt uses conventional style directory structure to streamline repetitive tasks and allow developers to focus on more important operational tasks. The configuration file can be used to customize the default behaviors.

Nuxt3 features

File-based routing. Nuxt generates routes based on the Vue files and folder structure within the pages/ directory. For example, if we have a pages/contact.vue file, Nuxt will generate a corresponding route at /contact. It also supports dynamic routing: pages/product/[sku].vue includes the route /product/APPLE, giving the [sku].vue single-file component access to the value APPLE.
Auto-imports. Components, composables, and helper functions have their respective directories which can be used across the project without importing them. This feature enhances the developer experience by removing the long list of imports. Nuxt also supports automatic importing of Vue APIs. It can be configured to import third-party packages using the nuxt.config file. Auto import can also be disabled using nuxt.config.
Server-side rendering. Nuxt has built-in server-side rendering (SSR) support, without having to configure the server. It has benefits such as loading pages quickly, improved search engine optimization, caching, and many more. We will talk more about other rendering methods later.
Data-fetching utilities. Nuxt provides composables to handle SSR-compatible data fetching as well as different strategies.
TypeScript support. Nuxt3 fully supports TypeScript.
Modules. Nuxt provides a module system to extend the framework core and simplify integrations.

Rendering Modes

The process of interpreting JavaScript code to convert Vue components to HTML elements is called rendering. This can happen both in the browser and the server. Nuxt supports the following rendering modes and we will discuss them more in detail:

1. Universal Rendering (SSR + CSR)

This is the default rendering mode which provides a great user experience, good performance, and optimized search engine indexing. The rendering mode can be switched by changing the ssr value in nuxt.config.

In this mode, the server returns a fully rendered HTML page to the browser on request. Nuxt runs the Vue code in the server, which produces HTML content. Users get the content of web application which can be displayed in browser.

After the page is loaded from the server, the browser loads the JS code to make content interactive and dynamic. The browser re-interprets the Vue code to enable interactivity. This process of making a page interactive in the browser is called “hydration”.

Universal rendering provides quick page load times while preserving the benefits of client-side rendering. It enhances SEO because HTML content is already present for crawling.

Pros:

Performance. Browsers display static content faster, hence users can see the page content almost immediately. Nuxt also preserves the interactivity of the web application using hydration.
SEO. Web crawlers can index the page’s content easily as universal rendering delivers the entire HTML content of the page to the browser.

Cons:

Development constraints. Some APIs don’t work in both the browser and the server; for example, the window object is only available in the browser, so it can’t be accessed on the server. It can be time consuming to write code that runs on both sides. Nuxt does provide guidelines and variables to help with this.
Cost. Unlike hosting static files, universal rendering requires a server to generate the full HTML content. Using a server adds cost.

2. Client-Side Rendering (CSR)

A traditional Vue application loads the JavaScript code on the browser first, then interprets the code to generate the HTML elements and interface.

Pros:

Development speed. Writing client-side-only code improves development speed as we don’t have to worry about supporting server-side compatibility.
Cheaper. The code can be hosted on a simple web server without the need for a application server, and can run in the browser, reducing the server-side cost.
Offline. Once the JavaScript has been sent to the client, the code only runs in the browser. This means the web application can keep working even if there is no internet.

Cons:

Performance. Because the browser has to first download files and then run JavaScript files to generate the HTML document, the page can be slow to load initially. This depends on the network download speed as well as the performance of the user’s device for executing the JS code. This negatively affect page load times and user experience.
SEO. Crawlers takes more time indexing and updating the content delivered. Based on the above performance drawback, the crawler may not wait until the interface is fully rendered, and will report slower load speeds.

Client-side rendering is the preferred choice for heavy interactive web applications such as SaaS and back-office applications that don’t require indexing.

Enabling client-side only rendering with Nuxt can be done by updating nuxt.config:

export default defineNuxtConfig({
  ssr: false
})

3. Hybrid Rendering

Hybrid rendering allows different caching rules per route using Route Rules which can dictate the server response for each new request.

Without hybrid rendering all the routes/pages of the application use the same rendering mode—either universal or client-side.

With hybrid rendering, some pages which have static content can be generated at build time while pages which have dynamic content (e.g. dashboard or orders pages) can be generated client-side.

Nuxt3 provides a way to support hybrid rendering using routeRules in nuxt.config:

export default defineNuxtConfig({
  routeRules: {
    '/': { prerender: true }, // Pre-render or SSG
    '/country': { ssr: false }, // CSR (SPA)
    '/university': { ssr: false }, // CSR (SPA)
    '/isr/country': { isr: true }, // ISR without TTL
    '/isr/university': { isr: 60 }, // ISR with TTL
    '/swr/country': { swr: true }, // SWR without TTL
    '/swr/university': { swr: 60 }, // SWR with TTL
    '/prerender/country': { prerender: true }, // Pre-render or SSG
    '/prerender/university': { prerender: true }, // Pre-render or SSG
  }
)

Routes can have various properties such as:

ssr. This is used to disable or enable server-side rendering for the given route. It can be used to make SPA app like dashboard and orders page for serving dynamic content with ssr: false.
swr. SWR means state-while-revalidate. This is a caching technique which enables the server to provide cached data for a configurable Time to live (TTL). We can define a time value in seconds, which is used to set TTL, or just pass true, which sets the TTL with maximum age. Without TTL, the response is cached until there is change in the content. With TTL, the response is cached until the TTL expires. The response of the page upon first request is generated and cached.
isr. This stands for “incremental static regeneration.” It is similar to swr, with the main difference being that the response is cached on the CDN. It can also be configured with TTL and without TTL.
prerender. This generates pages based on routes at build time and serves them as static pages.

There are many more properties that we can use to define how each route will act.

I’ve created a demo app showing hybrid rendering. This app shows list of countries and universities with details pages.

The /country and /university routes are defined as single-page applications (SPA—this means they use client-side rendering). We can see that the time on the server and the time on the client are almost same, with the difference being hydration time.
The /prerender/country and /prerender/university routes are defined as prerendered or static-site generated (SSG), which means the pages are generated at build time. The server time shows the time when the build was run to generate the pages, and does not change.
The /prerender/country/{countries starting from a to m} routes are defined as prerendered, which means the countries whose name starts with a to m are generated at build time. We can browse any of the prerendered country pages, like /prerender/country/Canada, where we see that the server times are build times. However, if we browse a country page which isn’t prerendered, like /prerender/country/Nigeria, we see that server times are the same as browser times.
The /isr/country, /isr/country/**, /swr/country/**, and /swr/country routes are defined as ISR and SWR respectively, with the maximum TTL set. These pages will serve cached content until the response changes.
The /isr/university, /isr/university/**, /swr/university/** and /swr/university routes are defined as ISR and SWR with a TTL of 120 seconds. This means that when first browsed, the pages will serve the initial response and cache it for 2 minutes.

You can see the code for the demo app on GitHub.

I wrote the same app twice, with Hotwire and Blazor Server — here’s what I learned

2023-05-27T00:00:00+00:00

There’s been a very interesting movement that has emerged recently in the world of frontend web development: a rise of little-to-no-JavaScript frontend frameworks.

The promise here is that we would be able to develop web applications with rich interactive capabilities without the need to write a whole lot of JavaScript. As such, these new approaches present themselves as alternatives to the likes of Vue, React, Angular, etc.

Two recent technologies that try to fulfill this promise come from two of the most prolific web application development frameworks of today: Blazor, built on .NET, and Hotwire, built on Ruby on Rails.

Now, I love my JS frameworks as much as the next guy, but these new technologies are intriguing. So I decided to build the same application twice, with Hotwire and with Blazor. I learned a few things along the way that I would like to share in this blog post.

Note that there is a table of contents at the end of this post.

What this article is

I want to present some of my findings when working with these two technologies. I also want to discuss how they work and how they feel. How they are similar and how they are different. How they take different routes to arrive at their ultimately similar destinations. Maybe offer some pros and cons.

This post assumes sufficient familiarity with C#, ASP.NET, Ruby, Ruby on Rails and the current state of the art of web development. I won’t assume any familiarity with either Blazor or Hotwire, but this is not a tutorial for either, so I won’t explain in detail how to fully build apps with these technologies.

So who am I writing this for? Essentially, for anybody who is curious about these technologies and is interested in understanding the big picture of what they are about, how they compare to each other, and building their next project with one of them. So, this article is intended to serve more as an introduction to both, a starting point for a conversation to help you make a decision on what’s best for you and your team.

Spoiler alert: Both are great and you can’t go wrong with either. It all comes down to your team’s preferences and past experience.

One final thing worth noting is that I’m focusing this article on “Blazor Server” specifically. I’ll be using the word “Blazor” moving forward, for short. Blazor as a framework has three variants: Blazor Server, Blazor WebAssembly and Blazor Hybrid. You can learn more about them here.

Most of the examples that I’ll use in this post come from a couple of demo apps that I built in order to get my feet wet with these technologies. You can find both of them in GitHub. Here’s the Blazor one and here’s the Hotwire one. You can study both the source code and the commit history, which I tried my best to keep neatly organized. They are both functionally identical, and based on this excellent Hotwire tutorial.

An overview of Blazor

When it comes to how they are designed and the developer experience they offer, these two are very different. Let’s go over some of the key details of Blazor and then we’ll do the same with Hotwire. With that, the differences between them will become apparent.

The first thing we have to understand about Blazor is that it is a component framework, very much like Vue or React. So, with Blazor, applications are broken up into composable modules called “Razor/Blazor components” that are essentially independent pieces of GUI bundled with their corresponding logic. Each component has three parts to it:

HTML-like markup that describes the layout and UI elements to be rendered,
C# logic that defines the behavior of the component, like what actions to take when users interact with GUI elements, and
CSS for styling the GUI elements.

For example here’s a simple a Blazor component that allows displaying, editing, and deleting a particular type of record called “Quote”. Don’t worry about the details too much; we’ll go over some of them next. For now, I just want us to get a sense of what Blazor components look like:

@using Microsoft.EntityFrameworkCore

@inject IDbContextFactory<QuoteEditorBlazor.Data.QuoteEditorContext> dbContextFactory

@if (isEditing)
{
    <QuoteEditorBlazor.Shared.Quotes.Edit
        QuoteToEdit="QuoteToShow"
        OnCancel="HideEditForm"
    />
}
else
{
    <div class="quote">
        <a href="quotes/@QuoteToShow.ID">@QuoteToShow.Name</a>
        <div class="quote__actions">
            <a class="btn btn--light" @onclick="DeleteQuote">Delete</a>
            <a class="btn btn--light" @onclick="ShowEditForm">Edit</a>
        </div>
    </div>
}

@code {
    [Parameter]
    public QuoteEditorBlazor.Models.Quote QuoteToShow { get; set; }

    [Parameter]
    public EventCallback OnQuoteDeleted { get; set; }

    bool isEditing = false;

    void ShowEditForm()
    {
        isEditing = true;
    }

    void HideEditForm()
    {
        isEditing = false;
    }

    void DeleteQuote()
    {
        using var context = dbContextFactory.CreateDbContext();
        context.Quotes.Remove(QuoteToShow);
        context.SaveChanges();
        OnQuoteDeleted.InvokeAsync();
    }
}

You can see that we have some C# in the file (enclosed in a @code block) with some event handlers and parameters. We also have some markup written with a mixture of HTML and C#. This markup has conditionals, wires up click event handlers, renders data from a given record, renders another component, etc. That markup is really just Razor, a templating language that has been widely used in ASP.NET for a good while now. And we also have some top-level statements like @using and @inject for including classes and objects that the component can use.

As far as CSS goes, here’s how it works: Suppose these are the contents of a file called Example.razor. The CSS for it would have to be defined in an Example.razor.css file sitting right next to it. Syntax-wise, this would just be a plain old CSS file. One cool thing to mention about it, though, is that the CSS within it is visible only to the component. So there’s no risk of conflicting rules between components.

If you’re familiar with modern frontend web development and have used frameworks like Vue or React, this should look very familiar to you. In fact, I would venture to say this is one of Blazor’s most attractive points. If you come from that background, and know .NET, it’s not that big of a leap to get into Blazor. The development experience is very similar as its design shares many concepts with modern JS frameworks; they operate under a very similar mental model.

Of course, C# is not JavaScript and .NET is not a browser. So there are many differences when it comes to the nitty-gritty mechanics of things. So a thorough understanding of the .NET framework and its libraries is also important for mastering Blazor. Which, depending on your team’s background, may be a point in favor or against.

How Blazor works under the hood

As you can probably gather from the previous discussion, Blazor takes control of the entire GUI of the application and puts up a firm layer of abstraction over traditional native web technologies. All notion of JavaScript or code executing on a browser environment is greatly de-emphasized. In fact, most of Blazor executes in the server.

Essentially, all the code that you actually write executes on the server side. When a user begins using the app, a two-way, persistent SignalR connection is established between the browser and server. Whenever the client requests a page, the server renders it and sends it through the connection to the client browser, where there’s a component that interprets and displays it. Likewise, whenever the user interacts with some UI element, like clicking a button or a link, the action is sent to the server via this SignalR connection for it to be processed. If changes to the GUI are necessary, the server calculates them and sends them back to the user’s browser, where they will be interpreted and used to re-render the screen with the new state.

Microsoft’s official documentation has an excellent diagram that helps explain the process:

So, even though there is client side code running and browser DOM being manipulated, this is all happening under the hood. The developer doesn’t need to be concerned with that and can just focus on authoring C# code, for the most part.

This approach has a few implications worth noting. One is that this means higher load on the server compared to more traditional web applications. This is mainly because there needs to be a connection always open between clients and the server, by design. Classic HTTP is purely stateless, and connections are typically opened and closed multiple times throughout a user’s session, as they interact with the web app. Not so for Blazor, where this SignalR connection (most likely via WebSockets) is always alive. So, for scalability concerns, we need to keep in mind that the more concurrent users our app has, the more resources the server will consume, even if the users are somewhat idle.

An abstraction over the request/response cycle

A key element of Blazor is that it abstracts developers from the classic HTTP request/response model. With Blazor, one seldom has to consider that aspect, as all interactions between client and server are managed via the framework itself through the persistent connection we discussed in the last couple of paragraphs. To the developer, there’s no real separation between the two. This is a big departure from classic MVC-like frameworks where things like endpoints, actions, and controllers are front and center. Such concepts are simply not in play on Blazor apps. The idea is to make them feel more like desktop apps: fully integrated, monolithic, simple packages of GUI and functionality.

This could become a double-edged sword as, in general, it is always important to have a clear understanding of the underlying technologies that support the application stack you’re working with. That is, the web is still there, even if you can’t see it. But as long as you’re cognizant of that, this approach can have great advantages too.

For example, thanks to this approach, there’s no need to employ the classic SPA pattern of developing applications in two halves: 1. a backend Web API for domain logic written in some backend programming language, and 2. a frontend application written in JavaScript that implements the user experience and communicates with the backend over HTTP.

Blazor attempts to offer a simpler solution from a developer’s perspective, where everything lives in the same execution environment so there’s no need for inter-process communication over HTTP. The example Blazor component from before demonstrates such a case. Notice how this link has an event handler registered to its click event:

<a @onclick="DeleteQuote">Delete</a>

That DeleteQuote event handler, simply defined as the method below, directly leverages the DbContext to issue the delete command to the underlying database:

void DeleteQuote()
{
    using var context = dbContextFactory.CreateDbContext();
    context.Quotes.Remove(QuoteToShow);
    context.SaveChanges();
}

Pretty simple.

However, this flexibility also requires great discipline from the development team. It falls upon us not to clutter the GUI code with all manner of extraneous things like database calls and domain or application logic that have nothing to do with user interface concerns. The traditional two-halves pattern for SPAs has this separation between domain and GUI logic baked in by necessity. Blazor allows us to break free from it, but that does not mean that the separation is not useful or even necessary. For a small example like this, this works just fine, but for larger applications, a more modularized design should be considered as well. Maybe the introduction of abstractions like repositories or domain services? At the end of the day, the core software design principles still need to be applied.

How Blazor supports common frontend framework features

Something else to consider, which I touched on before, is that Blazor is built on top of .NET. That means that a solid understanding of .NET concepts is all but a necessity in order to be effective with Blazor. Most of the features that are now traditional and expected in frontend JavaScript frameworks exist in Blazor, and they are implemented using age-old .NET concepts. If your team has solid .NET experience, this is a blessing. If not, then Blazor requires a larger investment, one that could be overwhelming depending on your time constraints.

Here are a few examples of how Blazor implements classic frontend framework features:

Handling DOM events

We already saw how event handlers work: they are defined as regular C# methods. The way they are registered to respond to events is via attributes in the GUI elements like @onclick or @onchange. All traditional DOM events are available. Like this:

<a @onclick="DeleteQuote">Delete</a>

Including other Blazor components

We also saw how to render components from within other components. All it takes is adding the component to the template as if it was any other GUI element/HTML tag. The tag itself is the name of the component, which sometimes needs to be fully qualified. We saw an example before:

<QuoteEditorBlazor.Shared.Quotes.Edit
    QuoteToEdit="QuoteToShow"
    OnCancel="HideEditForm"
/>

The fully qualified component name is QuoteEditorBlazor.Shared.Quotes.Edit in this case, and that’s how we reference it. If we were to include the namespace with an @using statement (like @using QuoteEditorBlazor.Shared.Quotes near the top of the file) then we would be able to invoke the component just by its name of Edit.

Passing parameters to components

That previous snippet also demonstrates how to pass parameters to components. In this case, we have two: QuoteToEdit which is an object, and OnCancel which is a custom event. As you can see, parameters are passed as if they were HTML element attributes. In the case of QuoteToEdit, we’re passing it QuoteToShow, which is a C# Property defined in the @code section of the component:

public QuoteEditorBlazor.Models.Quote QuoteToShow { get; set; }

In order for the receiving component to be able to accept the parameter, it needs to define a property itself of the same type, annotated with the Parameter attribute. In this case, the QuoteEditorBlazor.Shared.Quotes.Edit component defines it like this:

[Parameter]
public QuoteEditorBlazor.Models.Quote QuoteToEdit { get; set; }

Notice how the name of the property is the same name used for the “HTML attribute” that was used in markup to pass the parameter to the component:

QuoteToEdit="QuoteToShow"

In this case, the expected parameter is of type QuoteEditorBlazor.Models.Quote.

Defining, handling and triggering custom component events

The other parameter, which is a custom event, accepts a method. It looks like this in the receiving component:

[Parameter]
public EventCallback OnCancel { get; set; }

Again, this is a Property annotated with the Parameter Attribute. The only difference is that the type of this one is EventCallback. That’s what allows it to accept a method. Then, inside the receiving component, the event can be triggered with code like this:

OnCancel.InvokeAsync();

This will execute whatever method the parent component has registered as a handler for this custom event. In this case, that would be our HideEditForm method.

Handling component lifecycle events

Other than DOM and custom events, much like in other frontend frameworks, Blazor components also offer ways of hooking up to their own internal lifecycle events. OnInitialized is one of the most important ones, which runs when the component is first starting up. To hook into it and run some code when it happens, all a Blazor component has to do is implement it as a method override within its code section. Something like this:

protected override void OnInitialized()
{
    // Do something here.
}

There’s more to learn about component lifecycle and the official documentation does a good job in explaining it.

Templates

Like we discussed before, Blazor also offers a rich templating syntax via Razor, which is also a hallmark of modern frontend frameworks. We have conditional rendering, support for loops, interpolation of data, model binding, etc.

Routing

Routing is also included in Blazor and the way that it works is with the @page directive that’s used on top of components like this:

@page "/quotes"

Not all components will use these, only those that correspond to whole pages. Most components will be used as portions of pages and as such, would not include these. A @page statement like the above will make the component that includes it accessible via an URL like http://mydomain.com/quotes. In other words, at the root of the site.

These routes also support parameters, which can be defined like this:

@page "/quotes/{quoteId:int}"

A component with this directive will be accessible through URLs like http://mydomain.com/quotes/123. The code in the component can access the route parameter quoteId by defining it as a Property with the matching type, annotated with the Parameter attribute. Like this:

[Parameter]
public int QuoteId { get; set; }.

State management

Global application state management à la Vuex or Redux is also available in Blazor. The cool thing about how this is implemented in Blazor is that there is no need for any additional library or special components. A global app store can be a simple C# object that’s configured to have a lifetime that spans that of the user’s session. Here’s an example of a class that’s used to store global flash messages:

namespace QuoteEditorBlazor.AppState;

public class FlashStore
{
    public List<string> Messages { get; private set; } = new List<string>();

    public event Action? MessagesChanged;

    public async void AddMessage(string message)
    {
        Messages.Add(message);
        MessagesChanged?.Invoke();

        await Task.Delay(TimeSpan.FromSeconds(5));

        Messages.Remove(message);
        MessagesChanged?.Invoke();
    }
}

Like I said: a plain and simple C# class. It offers a method for displaying a message for a few seconds. It does this by storing the given message into an internal variable and then, after a little while, it gets removed. It also offers a MessagesChanged event that other components can subscribe to which is triggered as messages are added and removed.

The lifetime of the instance is controlled via its dependency injection configuration. In our Program.cs, it would be configured like this:

builder.Services.AddScoped<FlashStore>();

Like I mentioned before, Blazor apps establish a persistent connection for the user throughout their session. This means that the instance of the app that is running on the server is also persistent. So, if we add FlashStore as a scoped service, one single instance of it will also persist throughout the session. That’s why we can rely on its internal variables to store global application state.

You can learn more about state management in Blazor here.

Then, you could have a component that renders those messages that looks like this:

@using QuoteEditorBlazor.AppState

@inject FlashStore flashStore

@implements IDisposable

<div class="flash">
    @foreach (var message in flashStore.Messages)
    {
        <div class="flash__message">
            @message
        </div>
    }
</div>

@code {
    protected override void OnInitialized()
    {
        flashStore.MessagesChanged += StateHasChanged;
    }

    public void Dispose()
    {
        flashStore.MessagesChanged -= StateHasChanged;
    }
}

Very simple too. This Blazor component uses a loop to render all the messages. There are a couple of interesting things about this one. First, the component gets access to the instance of the FlashStore class via the @inject directive near the top of the file. That’s how the flashStore variable is made available for the component to use both in C# code and in the template.

The second interesting element is how this component registers its StateHasChanged method to the MessagesChanged event defined in FlashStore. As you recall, FlashStore will trigger MessagesChanged every time messages are added or removed. By registering StateHasChanged to that event, we make sure that the component re-renders every time the messages list changes; which in turn ensures that the most current messages are always rendered. Kind of a neat trick.

And as you might expect, any piece of code throughout the app can submit new messages to FlashStore by getting hold of the global instance via dependency injection and then calling:

flashStore.AddMessage("Here's a flash message!");

Interoperability with JavaScript

For all the nice abstractions that Blazor presents us with, the reality is that sometimes we actually do have to break through them. In the case of JavaScript, this happens when, for example, we need access to some native browser feature, or when we need to integrate with some library for some widget or other type of capability. In Blazor, this is certainly possible.

There are many details to consider when it comes to JavaScript interoperability in Blazor. Check out the official documentation to learn what all is possible. For our purposes here though, it’s enough to know that calls from .NET to JS and vice versa are supported.

The most basic example of calling JS code from .NET code looks like the following. If we have a JS function like this:

window.showMessagefromServer = (message) => {
    alert(`The server says: ${message}`);
    return "The client says thanks!";
};

Such a method can be invoked from a Blazor component like this:

string interopResult = await js.InvokeAsync<string>("showMessagefromServer", "Have a nice day!");

The Blazor component that runs this code would have to inject an instance of IJSRuntime into the js variable with a statement like @inject IJSRuntime js. A key thing to note is that the JavaScript method needs to be attached to the window object in order for it to be accessible.

Like I said, the other way around also works: JavaScript code is able to call .NET logic defined in a server-side Blazor component. Here’s a simple example for us to get an idea of how it feels. We can have a method that looks like this on a Blazor component:

[JSInvokable]
public static Task<string> getMessageFromServer()
{
    return Task.FromResult("Have a nice day!");
}

This method is public and static. It is also possible to invoke non-static instance methods, but the setup is a little more complicated, and this is enough for our purposes here. Other than that, as you can see, the method needs to be annotated with the JSInvokable attribute and return a type of Task.

Here’s some JavaScript that calls this method:

window.returnArrayAsync = () => {
    DotNet.invokeMethodAsync('{YOUR APP ASSEMBLY NAME}', 'getMessageFromServer')
        .then(data => {
            alert(`I asked the server and it says: ${data}`);
        });
};

There are a few noteworthy things here. First we have the DotNet.invokeMethodAsync function which Blazor makes available to us in JavaScript land. That’s what we use to invoke .NET server side code. Next, the function needs to be given the assembly name of our app as well as the name of the method to invoke within the Blazor component. This is the one that was annotated with JSInvokable. Finally, the function itself is asynchronous and thus returns a promise.

An overview of Hotwire

Hotwire makes a promise similar to Blazor’s. However, the way it goes about it couldn’t be more different.

Hotwire is much simpler and more minimalistic than Blazor. Whereas in Blazor we let the framework take total control of the GUI, just like we do with other popular frontend frameworks, Hotwire feels more like a natural evolution of traditional pre-JavaScript-heavy web development. We still have controllers and views, we still render pages on the server, and we still work in tandem with HTTP’s request/response model.

What Hotwire gives us, if we were to boil it down to a single sentence, is a way to refresh only portions of our pages as a result of user interactions. That is, we’re not forced to reload the entire page, as is the case with non-JavaScript web applications. For example, in Hotwire we have the ability to submit a form or click a link and, as a result of that, only update a particular message, picture, or section.

ASP.NET veterans will find this awfully familiar. That’s because all the way back in version 3.5, ASP.NET AJAX offered a very similar feature: partial page updates with the UpdatePanel component. Indeed, Hotwire presents a very similar concept; only greatly improved and modernized.

When it comes to actual coding, Hotwire’s footprint is minimal. It augments traditional Ruby on Rails controllers and views to produce the desired effect of page refreshes that are partial and targeted. Let’s walk through an example and you’ll see how we can start with a regular looking Rails app and then, through minor adjustments, we end up with a more richly interactive experience.

Imagine we are beginning to develop support for CRUDing a particular type of record called “Quote”, and we have these files:

### app/controllers/quotes_controller.rb
class QuotesController < ApplicationController
  def index
  end

  def new
    @quote = Quote.new
  end
end

<!-- app/views/quotes/index.html.erb -->
<main class="container">
  <div class="header">
    <h1>Quotes</h1>
    <%= link_to "New quote", new_quote_path %>
  </div>
</main>

<!-- app/views/quotes/new.html.erb -->
<main class="container">
  <%= link_to "Back to quotes", quotes_path %>

  <div class="header">
    <h1>New quote</h1>
  </div>

  <%= render "form", quote: @quote %>
</main>

<!-- app/views/quotes/_form.html.erb -->
<%= simple_form_for quote do |f| %>
  <% if quote.errors.any? %>
    <div class="error-message">
      <%= quote.errors.full_messages.to_sentence.capitalize %>
    </div>
  <% end %>

  <%= f.input :name %>
  <%= f.submit %>
<% end %>

This sample is using the simple_form gem, which you can learn more about here.

If you’re familiar with Rails, then you understand what’s happening here. We have a simple index page with a heading and a link to another page. That other page contains a form to create new Quote records. It also contains a link to go back to the index page.

Partial page updates with Turbo Frames

As they are right now, these files would produce a traditional web application user experience. When links are clicked, the whole screen will be reloaded to show the page that the clicked link points to. But what if we wanted, for example, to have the new record creation form appear out of nowhere within the same index page, without a full page reload? Here’s what that would look like with Hotwire:

 <!-- app/views/quotes/index.html.erb -->
 <main class="container">
   <div class="header">
     <h1>Quotes</h1>
     <%= link_to "New quote",
                 new_quote_path,
+                data: { turbo_frame: dom_id(Quote.new) } %>
   </div>

+  <%= turbo_frame_tag Quote.new %>
 </main>

 <!-- app/views/quotes/new.html.erb -->
 <main class="container">
   <%= link_to sanitize("&larr; Back to quotes"), quotes_path %>

   <div class="header">
     <h1>New quote</h1>
   </div>

+  <%= turbo_frame_tag Quote.new do %>
     <%= render "form", quote: @quote %>
+  <% end %>
 </main>

Remember that these examples are taken from a fully working application. Feel free to read through the source code to have a more complete understanding of the context within which these files exist.

And that’s really all it takes. Let’s go over it. With these changes, whenever a user clicks on the “New quote” link, instead of the browser triggering the usual GET request to then reload the screen and show the creation page, Hotwire’s frontend component captures the click event and makes the request itself via XHR. The server then receives this request normally and routes it to the new action in the quotes controller. All that action does is render the new.html.erb template and send that back to the client as a response.

When the Hotwire frontend component receives this, it notices that some of the response is enclosed in a turbo_frame_tag whose ID is that of an empty new Quote object. Now, because the link that the user clicked also had the ID of an empty new Quote object as its data-turbo_frame attribute, Hotwire looks for a turbo_frame_tag with the same ID in the page that’s currently being shown an replaces its contents with the contents from the similarly named turbo_frame_tag from the incoming response.

With that, you’ve seen in action some of the key elements that make Hotwire work. First of all we have the turbo_frame_tag helper, which produces a so-called “Turbo Frame”. Turbo Frames are the main building block that we use for partial page updates. Turbo Frames essentially say: “This section of the page is allowed to be dynamically updated without a full page refresh.” In an app that uses Hotwire, whenever you’re in a page that includes a Turbo Frame, if a request is made (whether it be navigation or form submission), and if the resulting response includes within it another Turbo Frame with the same ID, then Hotwire will notice the match and update the current page’s Turbo Frame with the contents of the Turbo Frame from the response.

Looking back at the code, you can see how we achieved this. We added an empty Turbo Frame on the index page, right below the link to the creation page. We also wrapped the form from the creation page in a similarly named Turbo Frame. Finally, we added the data-turbo_frame attribute to the link in the index page to tell Hotwire that it should kick in for this link and target that specific Turbo Frame. If the link was inside the Turbo Frame, we would not have to do this. Since it is outside, Hotwire needs the little hint that says: “Treat this link as if it was inside this Turbo Frame.”

I feel like this is at the same time a little awkward to wrap your head around and deceptively simple. When compared to Blazor, which builds upon tried and true concepts (as far as the developer experience goes at least), Hotwire almost seems alien, with a much more unusual style. But all in all, one can’t deny just how clean and simple all of this looks, in that “Rails magic” kind of way. And once it clicks, you can begin to see a world of possibilities opening up. The Hotwire developers managed to identify and extract a general design pattern of web application interactions, one that can be leveraged to produce a lot of varying rich interactive user experiences.

One neat aspect worth noting is that, if the user were to disable JavaScript, the app would still fully work. It would gracefully degrade. This is a direct consequence of Hotwire’s paradigm of adding minimal features on top of the existing traditional Rails programming model.

Imperative rendering with Turbo Streams

Let’s consider another example now. This time we’ll see another key component of Hotwire in action which is called Turbo Streams.

Turbo Streams helps solve the problem that emerges when the declarative style of pure Turbo Frames is not enough to obtain the fine grained control and behavior that we need. In these cases, the server needs to issue specific commands to the frontend on how to update the GUI. Via Turbo Streams, we can achieve just that. Coding-wise, these look like regular Rails view templates, albeit with some funky syntax thanks to the Turbo Stream helpers.

In our example, we’ll add a list of quotes in the index page, right below the link and the form. We’ll also complete our quote creation implementation so that we’re actually able to submit the form. As a result of that, we want the GUI to be updated so that the form goes away and the newly created quote is shown in the list. These last two are the things that we’ll use Turbo Streams for. Of course, these updates to the page will be done without a full page refresh.

Let’s start by adding a list of quotes on the index page.

In the controller, we query the database for all the quote records and store them in a variable that the view can later access.

 ### app/controllers/quotes_controller.rb
 class QuotesController < ApplicationController
   def index
+    @quotes = Quote.all
   end

   def new
     @quote = Quote.new
   end
 end

In the index view template, we render the collection of records.

 <!-- app/views/quotes/index.html.erb -->
 <main class="container">
   <div class="header">
     <h1>Quotes</h1>
     <%= link_to "New quote",
                 new_quote_path,
                 data: { turbo_frame: dom_id(Quote.new) } %>
   </div>

   <%= turbo_frame_tag Quote.new %>

+  <%= render @quotes %>
 </main>

Now we need to define a “_quote” partial view so that render statement we added on the index view can work automagically.

<!-- app/views/quotes/_quote.html.erb -->
<div class="quote">
  <%= quote.name %>
</div>

With this, the render @quotes statement will loop through all the records in @quotes and render this partial view for each on of them. This template is very simple. All it does is render the name of the quote.

Now let’s add an action that can accept quote creation form submissions:

 ### app/controllers/quotes_controller.rb
 class QuotesController < ApplicationController
   def index
     @quotes = Quote.all
   end

   def new
     @quote = Quote.new
   end
+
+  def create
+    @quote = Quote.new(quote_params)
+
+    if @quote.save
+      redirect_to quotes_path, notice: "Quote was successfully created."
+    else
+      render :new
+    end
+  end
+
+  def quote_params
+    params.require(:quote).permit(:name)
+  end
 end

A typical Rails recipe for a record creation endpoint. It takes the parameters coming from the request and uses them to create a new record via the Quote Active Record model. If successful, it redirects to the index page; if not, it renders the creation page again (via the new action). The new.html.erb view template has some logic to render error messages when they are present so those are going to show up when that page is rendered as a result of unsuccessful calls to this create endpoint.

At this point, we’re able to view all the quotes on record and create new ones. Now here are the changes to Hotwire-ify this scenario.

First we wrap the list of quotes with a Turbo Frame named “quotes”:

 <!-- app/views/quotes/index.html.erb -->
 <main class="container">
   <div class="header">
     <h1>Quotes</h1>
     <%= link_to "New quote",
                 new_quote_path,
                 data: { turbo_frame: dom_id(Quote.new) } %>
   </div>

   <%= turbo_frame_tag Quote.new %>

+  <%= turbo_frame_tag "quotes" do %>
     <%= render @quotes %>
+  <% end %>
 </main>

Next, we employ Turbo Streams. Like I said, Turbo Streams materialize themselves in code as if they were view templates. So, a new file is added that looks like this:

<!-- app/views/quotes/create.turbo_stream.erb -->
<%= turbo_stream.prepend "quotes", partial: "quotes/quote", locals: { quote: @quote } %>
<%= turbo_stream.update Quote.new, "" %>

It sort of looks like a couple of imperative statements, does it not? The first line instructs Hotwire to prepend, in the "quotes" Turbo Frame, a new render of the app/views/quotes/_quote.html.erb partial view, while passing it the @quote object as a parameter. The second line updates the Quote.new Turbo Frame to be empty. When we remember that the "quotes" Turbo Frame is the one that contains the list of records and the Quote.new Turbo Frame is the one that contains the new quote creation form, this starts to make sense. This Turbo Streams view is making the newly created quote appear in the list; and at the same time, it is making the form disappear. From a user’s perspective, this all takes place after submitting the creation form. So the user experience makes complete sense. All that with no full page refresh.

And finally, the controller action needs to make use of this new view template like so:

 ### app/controllers/quotes_controller.rb

 def create
   @quote = Quote.new(quote_params)

   if @quote.save
-    redirect_to quotes_path, notice: "Quote was successfully created."
+    respond_to do |format|
+      format.html { redirect_to quotes_path, notice: "Quote was successfully created." }
+      format.turbo_stream
+    end
   else
     render :new, status: :unprocessable_entity
   end
 end

This is yet another familiar Rails pattern. This is how we specify different response formats, whether it be HTML, JSON, XML. Now, thanks to Hotwire, we can also specify Turbo Streams. This is one of the great aspects about Hotwire: it seamlessly integrates with Rails’ existing features and concepts.

Anyway, in this case, we invoke format.turbo_stream within the block passed to respond_to and that makes it so the app/views/quotes/create.turbo_stream.erb view template is included in this action’s response. Hotwire’s frontend component sees this coming as part of the response and acts accordingly, updating the GUI how it’s been specified.

Adding JavaScript with Stimulus

The final piece of the Hotwire puzzle is Stimulus, which allows us to integrate JavaScript functionality in a neat way. Stimulus is a very simple JavaScript framework, it does not take control of the entire UI. In fact, it does not render any HTML at all. Stimulus essentially offers a nice way of wiring up JS behavior to existing markup. Let’s look at a quick example of how it could hypothetically be used for showing a confirmation popup before deleting a record.

The JavaScript logic lives inside so-called “Stimulus controllers”. For our example, it could look something like this:

// app/javascript/controllers/confirmations_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  confirm() {
    if (confirm("Are you sure you want to delete this record?")) {
      // Carry on with the operation...
    }
  }
}

And now, the idea is to wire up this code so that it runs when the hypothetical delete button is clicked. Here’s what that button could like:

<button
  data-controller="confirmations"
  data-action="click->confirmations#confirm"
>
  Delete
</button>

Pretty self-explanatory. We specify the name of the controller to use via the data-controller attribute. We also specify, via data-action, what method to invoke within that controller as a result of which DOM event, click in this case.

And that’s basically all it takes to sprinkle some JavaScript on Hotwire apps. Stimulus does offer a few more useful features, which you can read more about in the official documentation. But for us for now, it’s enough to know that it exists, and what’s the main idea behind it.

So as you can hopefully see, Hotwire is much smaller in scope to Blazor. And yet, it allows us to do just the same: highly interactive applications with little to no JavaScript. This ought to make a lot of Rails developers happy.

A final comparison

I was initially thinking about ending this blog post with a flowchart of sorts to explain the process of deciding which of these two technologies you should use. But really, the decision is very simple: If your team is comfortable with .NET, use Blazor. If your team is comfortable with Ruby on Rails, use Hotwire. It’s obvious, so I won’t claim to have made a great discovery here.

The only thing to add is that if your team is familiar with modern frontend web development framework concepts, you’ll be even better served by Blazor and you’ll hit the ground running. If not, then even for seasoned .NET people, there will be a decent learning curve, but not steep enough to be deterred. Moreover, if your team has no modern frontend development experience at all, then Hotwire is a godsend; thanks to its “augment classic backend-heavy web app development” style.

With that said, let’s close out with a summary of main aspects of both technologies and how they compare to each other.

Overall, Hotwire is much simpler than Blazor. While Blazor is a full-fledged GUI component framework, Hotwire’s approach is more like an augmentation of classic non-JavaScript web development patterns. That said, Hotwire’s style is more unusual than Blazor’s, so if your team is already familiar with modern frontend web development, Blazor can be a great fit.

While both frameworks try to offer enough functionality to allow the development of rich interactive experiences without the need to write any JavaScript, the reality is that sometimes JavaScript does need to be written. Both technologies offer ways to make this happen. And while both are perfectly workable, Blazor’s solution is a bit more clunky than Hotwire’s.

When it comes to classic web technologies like HTTP’s request/response cycle and the separation between server and client, Blazor’s style offers a big deviation from them. It greatly de-emphasizes them and presents instead a completely different programming model, one more akin to desktop application development. The concepts of request, response, client, and server seem to vanish. Not so for Hotwire, which builds upon these classic technologies in a way where they still need to be considered and are in fact in the spotlight. While Blazor attempts to do away with these, Hotwire embraces them.

In Blazor, client events are sent to the server, the server renders the DOM updates and sends them to the client for updates. This happens via the persistent SignalR/WebSockets connection.

Hotwire, on the other hand, intercepts client events and sends classic HTTP requests (via AJAX/XHR) to the server. The server then executes the requests and sends back the responses to the client which carries out the necessary operations, generally speaking, updating sections of the page that’s already being displayed.

That means that at the end of the day, both frameworks do the rendering on the server side and send the rendered markup over the wire to the clients. But in Blazor, the client and server have a persistent connection, while Hotwire’s connections come and go as normal HTTP requests and responses.

A neat aspect of Hotwire’s programming model is that it allows an incremental approach to web development where you can start developing the app like you would a traditional, non-reactive, non-JS app, then augment it with a little code to give it SPA capabilities.

And that’s all for now! I for one am glad to see these types of technologies emerge. While there are many teams out there that are already effective and productive with the current landscape of frontend web development, these two are very interesting and seem capable in their own right.

Besides, having alternatives is never a bad thing. Depending mainly on your previous experience, these could be a great fit for projects new and old. It’s great to know that both .NET and Rails include these types of offerings and that they work pretty well.

Vue 3 is out with exciting new features

2020-12-08T00:00:00+00:00

Photo courtesy of NASA

Vue 3 was officially released on September 18, 2020 with improved performance and some exciting new features.

Composition API

The Composition API is one of the most significant changes. It helps with logically grouping related fragments of components. In Vue 2, we used the Options API to pass various options during component configuration:

// src/components/ProductList.vue
<template>
  <div class="child">
    <h3>Vue2</h3>
    <div>
      <div class="add-product">
        <h2>Add Product</h2>
        <div>Name: <input name="name" v-model="newProduct.name" /></div>
        <div>Price: <input name="name" v-model="newProduct.price" /></div>
        <button @click="addProduct">Add</button>
      </div>
      <div class="search-product">
        <h2>Search Product</h2>
        <input name="name" v-model="filterText" placeholder="Start typing to search" />
      </div>
    </div>
    <div class="list-product">
    <h1>Product List</h1>
    <ul>
      <li v-for="product in filteredProducts" :key="product">{{product.name}}:{{product.price}}</li>
    </ul>
    </div>
  </div>
</template>

<script>
export default {
  data() {
    return {
      newProduct: {name: '', price: 0.00},
      productList: [
        {name: 'Milk', price: 2},
        {name: 'Carrot', price: 12},
        {name: 'Sugar', price: 8},
        {name: 'Cheese', price: 20}
        ],
      filterText: ''
    }
  },
  methods: {
    addProduct: function(){
      this.productList.push({...this.newProduct})
    }
  },
  computed: {
    filteredProducts: function () {
      if(this.filterText.trim().length > 0){
        return this.productList.filter(p => p.name.toLowerCase().indexOf(this.filterText.toLowerCase())>-1)
      }
      return this.productList;
    }
  }
}
</script>

This component’s functions have several responsibilities, and as the code grows more functions with different responsibilities will be needed, making it more difficult to understand and implement new changes. Moreover, the related parts of code are scattered throughout each component’s options (data, computed, methods).

The new Composition API enables us to organize related code. setup is a new component option in Vue 3, acting as the entry point for the Composition API. setup is executed before the component is created, and after the props are resolved, which means this cannot be accessed inside setup, but props and context can.

The following code uses the Composition API to recreate the earlier ProductList example component.

// src/components/ProductList3.vue
<template>
  <div class="child">
    <h3>Vue3 Composition API</h3>
    <div>
      <div class="add-product">
        <h2>Add Product</h2>
        <div>Name: <input name="name" v-model="newProduct.name" /></div>
        <div>Price: <input name="name" v-model="newProduct.price" /></div>
        <button @click="addProductToList">Add</button>
      </div>
      <div class="search-product">
        <h2>Search Product</h2>
        <input name="name" v-model="filterText" placeholder="Start typing to search" />
      </div>
    </div>
    <div class="list-product">
      <h1>Product List</h1>
      <ul>
        <li v-for="product in filteredProducts" :key="product">{{product.name}}:{{product.price}}</li>
      </ul>
    </div>
  </div>
</template>

<script>
import useProducts from '@/composables/useProducts'
import useProductNameSearch from '@/composables/useProductNameSearch'
import { ref } from 'vue'

export default {
  setup () {
    const newProduct = ref({name: '', price: 0.00})
    const { products, addProduct } = useProducts();
    const { filterText, filteredProducts } = useProductNameSearch(products)

    return {
      newProduct,
      addProduct,
      filterText,
      filteredProducts
    }
  },

  methods: {
    addProductToList: function(){
      // process product data before adding to list
      this.addProduct({...this.newProduct})
    }
  },
}
</script>

// src/composables/useProducts.js
import { ref } from "vue";

export default function userProducts(){
  const products = ref([
    {name: 'Milk', price: 2},
    {name: 'Carrot', price: 12},
    {name: 'Sugar', price: 8},
    {name: 'Cheese', price: 20}
  ]);

  const addProduct = (product) => products.value.push(product);

  return {
    products,
    addProduct
  }
}

// src/composables/useProductNameSearch.js
import { computed, ref } from "vue";

export default function useProductNameSearch(products){
  const filterText = ref('');

  const filteredProducts = computed(()=>{
    if(filterText.value.trim().length > 0){
      return products.value.filter(p => p.name.toLowerCase().indexOf(filterText.value.toLowerCase())>-1)
    }
    return products.value;
  })

  return {
    filterText,
    filteredProducts
  }
}

The two functions using the Composition API are now in two separate files, imported by our ProductList component. Similarly, we can add more functions with isolated responsibility in different files and use them in our component. This will the make code easier to understand and to make changes to the component.

Take a look at the demo and source code if you like.

Summary

setup() is the entry point for composition API and can be used as a standalone composition function in a separate file. To learn more about setup check out the Vue 3 docs.
ref can be used to make a variable reactive, and .value is used to access its value inside the setup function.
computed properties can be created using the function imported from Vue. .value should also be used here to access the value of computed properties.

There are more options, like lifecycle hooks, watch, and toRefs, which we don’t use in the above code.

Lifecycle hooks can be used in setup by prefixing with on. For example, mounted becomes onMounted. Visit the docs to learn about all of the lifecycle hooks.
To setup watch and know more about it read the docs.
toRefs is another option which helps make props which are passed to the setup function reactive. To learn more visit the docs.

Teleport

Teleport is another interesting feature which helps in making our HTML structure cleaner and more logical. Previously when we wanted to use a global modal or a notification/alert, it required deeply nested code. With teleport, the placing of components in the required location is easier. Let’s take a look:

The screenshot below shows the rendered DOM (without teleport code), where the Vue app is inserted into the DOM in div#app.
Now we are going to add <div id="destination"></div> just above the Vue application. This div is highlighted in the screenshot below. Notice that the div we added is outside of the Vue application.
Now in the Vue component we will add <teleport to="#destination">Teleported outside Vue App component</teleport>. This code uses the to prop to pass a reference of which element to use as parent instead of the Vue app.
After adding the teleport code, we can see that its contents, “Teleported outside Vue App component”, are rendered in HTML outside the Vue app. Normally, it would be rendered in its place in the app (the red region) but due to teleport it’s rendered in the teleport destination (the green region).
We can see in the browser that the teleported code is at the top of the page rather than within the Vue app.

With teleport we can render a piece of HTML code anywhere in the DOM tree. Teleported code will render with the Vue component and even update with it when props change. Note that the destination should be outside the component tree.

Fragments

In Vue 2, multi-root components were not supported, so multiple components needed to be wrapped in a single <div>. But in Vue 3, having multi-root components is possible.

Vue 2:

<!-- Layout.vue -->
<template>
  <div>
    <header>...</header>
    <main>...</main>
    <footer>...</footer>
  </div>
</template>

Vue 3:

<!-- Layout.vue -->
<template>
  <header>...</header>
  <main>...</main>
  <footer>...</footer>
</template>

Emits component option

In Vue 2, props for a component are declared in props option, making it easy to see which props are being used. But for custom events, we had to search the whole component to see what events are used. Now, custom events can be declared just like props via the emits option. Since this option accepts object notation, validators for arguments can be defined similar to validators in the props option.

Below you can see that we are passing custom events from the parent component to the child component and using the emits option to declare the custom event in the child component.

// src/App.vue
<template>
  <div class="parent">
    <product-list />
    <product-list-3 @update-inventory="addToInventory"/>
  </div>

  <div id="inventory">
    <span v-show="inventory.length === 0">Inventory is empty.</span>
  <div v-show="inventory.length > 0">
    <h3>Inventory</h3>
    <ul>
      <li v-for="item in inventory" :key="item.name">{{item.name}}: {{item.price}}</li>
    </ul>
      Total: ${{inventory.reduce((acc,product)=>acc=acc+(+product.price),0)}}
  </div>
  </div>

  <teleport to="#destination">Teleported outside Vue App component</teleport>
</template>

<script>
import ProductList from "./components/ProductList.vue";
import ProductList3 from "./components/ProductList3.vue";

export default {
  name: "App",
  components: {
    ProductList,
    ProductList3
  },
  data(){
    return {
      inventory: []
    }
  },
  methods: {
    addToInventory(products){
      this.inventory = [...this.inventory, ...products];
    }
  }
};
</script>

// src/components/ProductList3.vue
<template>
  . . .
    <div class="list-product">
      <h1>Product List</h1>
      <button @click="updateInventory()">Update Inventory</button>
      <ul>
        <li v-for="product in filteredProducts" :key="product">
          {{ product.name }}:{{ product.price }}
        </li>
      </ul>
    </div>
  . . .
</template>

<script>
import useProducts from "@/composables/useProducts";
import useProductNameSearch from "@/composables/useProductNameSearch";
import { ref } from "vue";
import ChildComponent from "./ChildComponent.vue";

export default {
  components: { ChildComponent },

  emits: ["update-inventory"],

  . . .

  methods: {
    . . .
    updateInventory: function() {
      this.$emit("update-inventory", [...this.filteredProducts]);
      this.emptyProducts();
    }
    . . .
  }
};
</script>

Some breaking changes from Vue 2

New method in the Global API, createApp. Calling this returns the app instance which can be used to mount the root instance.

Vue 2:

import Vue from 'vue'
import App from './App.vue'

Vue.config.productionTip = false

new Vue({
  render: h => h(App),
}).$mount('#app')

Vue 3:

import { createApp } from 'vue'
import App from './App.vue'

createApp(App).mount('#app')

Global API methods like nextTick, set, observable and others are now restructured with tree-shaking support.

Vue 2:

import Vue from 'vue'

Vue.nextTick(() => {
  // something DOM-related
})

Vue 3:

import { nextTick } from 'vue'

nextTick(() => {
  // something DOM-related
})

Here is a list of more breaking changes.

Many Vue libraries are yet to implement the changes that would work with Vue 3. For example, we use Vuetify in various client projects and this is not supported in Vue 3 as of writing this blog. There is a roadmap planned for Vue 3 support in Vuetify, with the alpha release in Q4 2020 and target release in summer 2021.

For information about migrating Vue 2 projects check out the migration guide.

Svelte: A compiled JavaScript front-end framework

2020-12-02T00:00:00+00:00

It seems like JavaScript frameworks are a dime a dozen these days. In the JavaScript world, there are frameworks and libraries for almost every task that you can imagine, and there is much overlap. In the front-end web development area though, there are three who reign supreme: Angular, React, and Vue.js. Whether you’re building single-page apps or traditional web apps with some front-end zest, you can’t go wrong with any of these three.

Recently though, I discovered a new player in this field that promises to offer a similar developer experience to existing frameworks with great performance gains. Its name is Svelte, and it achieves this promise in a very interesting way: it’s a compiler.

This is a novel approach to the front-end web development problem. While traditional front-end frameworks are libraries with runtime components that get loaded and executed in the browser, Svelte itself only runs at development/build time, on your development machine. Svelte takes the JavaScript components that we write, compiles them into pure, lean JavaScript and emits only that to the browser. No big library, or runtime, or interpretation of components ever happens in the browser. It doesn’t do any of this, and yet still offers a robust component framework with all the features that you might expect like reactivity, templating capabilities, scoped CSS, data binding, etc.

If we can truly get much better performance while maintaining a familiar developer experience when compared to more traditional frameworks (or improving it in some cases), that sounds like we get to have our cake and eat it too.

After learning all that, I decided to take a closer look at Svelte and see how it works, how it’s similar to and different from other frameworks, and what new features it brings to the table. In this blog post, I’ll discuss some of my most interesting findings.

Simple components

In Svelte, the concept and mechanics of components are similar to those of other frameworks. Components encapsulate the HTML, CSS, and JavaScript of a given portion of our applications in a reusable manner. Svelte components look very similar to plain old HTML files, minimal fluff. Here’s what a “hello world” example could look like as a Svelte component:

<h1>{ message }!</h1>
<p>{ author }</a>

<script>
  export let author;
  let message = "Hello World";
</script>

<style>
  h1 {
    color: royalblue;
  }
</style>

Very simple, refreshing even. This content would live inside a *.svelte file which is what Svelte components should be named. As you can see, the <style> and <script> tags contain just plain old CSS and JavaScript, respectively. export let author is how we declare component props. That is, values that are supplied as parameters by the component that’s parent to this one, or, if this was the top most component, by the client code that initializes the Svelte application.

The rest of the file, the view template, is also plain HTML with some curly brace goodness injected by Svelte that allows us to render the results from JavaScript expressions. In this case, we are just rendering the message and author variable that we defined in the <script> portion of our component.

Now, Svelte has a lot of features, so it does add some syntax to spice up HTML templates and it also uses some unconventional JavaScript to express some constructs. Nothing too revolutionary though, as we’ll see later.

It’s easy to set up

In front-end web development, we spend most of the time authoring components like these, so we’ll talk more about them later. In order for the components to do anything, though, we need that compilation step that I mentioned earlier. That means setting up a new Svelte project in our development environment. Luckily for us, Svelte makes this easy.

All you need is to install Node.js so that you have npm and npx available and can run this:

npx degit sveltejs/template my-svelte-project

This will use the Svelte project template hosted here to get you up and running quickly with a working application and build pipeline.

cd into the my-svelte-project directory that was just created and run npm install to install all dependencies needed by the app. Then, run npm run dev and that should start a development web server that you can reach with your browser via “localhost:5000”. You’ll be greeted by this:

Feel free to explore the app files. You’ll see there’s an App.svelte file that has our sole app component. It contains some HTML, CSS, and JS. main.js is particularly interesting for us at this point because it shows us how a Svelte app is initiated.

import App from './App.svelte';

const app = new App({
  target: document.body,
  props: {
    name: 'world'
  }
});

export default app;

This should be very familiar if you’re used to the likes of Vue. Here, we import the App.svelte file and instantiate the JavaScript component contained within by passing it its target (that is, where in the DOM it is going to be mounted) and some props.

Notice how we import the component file directly and no Svelte library. We don’t need it because our app does not need Svelte to run. It only needs Svelte to build. Svelte, after all, is a compiler. It’s not a runtime dependency, but rather, a build time one.

You can learn more about the parameters that Svelte components expect in the official documentation.

Another interesting aspect of setting up a Svelte app is that it uses Rollup as a module bundler by default. You can confirm this by looking at the my-svelte-project/rollup.config.js file that was created. If you prefer Webpack, Svelte also supports it. All you need to do to build with Webpack instead of Rollup is use this command when creating your app:

npx degit sveltejs/template-webpack svelte-app

This is just using the project template hosted on GitHub and it will build out a Webpack-based application functionally identical to the one we’ve just created. You will see that such projects include a webpack.config.js file instead of rollup.config.js.

The templating capabilities are powerful

When it comes to templating, Svelte has everything that you would expect from a modern JavaScript front-end framework and then some. You’ve got your basics like interpolation and flow control, but there are also some more advanced features that look to be very useful. Here’s an example component that demonstrate some of the most common capabilities:

<script>
  let title = 'Trying out some Svelte features';
  let itsAllJustJavaScript = "It's all just JavaScript";
  let youCanAlsoUseHtml = 'You can also use <b><em>HTML</em></b>';
  let showThis = true;
  let things = ['a thing', 'another thing', 'a thingy'];
  let complicatedThings = [
    {id: 1, what: 'car', why: 'it can go fast'},
    {id: 2, what: 'plane', why: 'it can fly'},
    {id: 3, what: 'submarine', why: 'it can go underwater'}
  ];
</script>

<main>
  <!-- We can use any variable that's declared in <script> -->
  <h1>{title}</h1>

  <!-- We can use any valid JavaScript expression and its return value will be
    rendered.-->
  <p>{itsAllJustJavaScript.toUpperCase()}</p>

  <!-- Svelte will make sure to sanitize text so that no HTML is rendered by
    mistake... -->
  <p>{youCanAlsoUseHtml}</p>

  <!-- ...unless you explicitly tell it not to by using @html -->
  <p>{@html youCanAlsoUseHtml}</p>

  <!-- Conditional logic works as you would expect. -->
  {#if showThis}
    <p>Showing this</p>
  <!-- There's also {:else if ...} if you need it. -->
  {:else}
    <p>And not that</p>
  {/if}

  <!-- It can iterate over an array. -->
  <h2>Things</h2>
  <ul>
    {#each things as thing}
      <li>{thing}</li>
    {/each}
  </ul>

  <!-- It can also iterate over an array of objects and use their fields. -->
  <h2>Complicated things</h2>
  <ul>
    {#each complicatedThings as thing}
      <li>{thing.id}: a {thing.what} is complicated because {thing.why}</li>
    {/each}  
  </ul>
</main>

There’s a more advanced feature that I think can prove very useful. Svelte supports rendering of templates based on promises. Here’s an example demonstrating how easy it is to implement a very common pattern on front-end development: displaying a loading message while we fetch some information via an HTTP request:

<script>
  // First, we define our promise and capture it in a variable.
  let url = 'https://vpic.nhtsa.dot.gov/api/vehicles/getmodelsformake/subaru?format=json'
  let promiseToGetSubarus = fetch(url).then(response => {
    if (response.ok) {
      return response.json();
    } else {
      throw new Error("Something went wrong ☹️");
    }
  });
</script>

<main>
  <!-- Then, in the template, we await the promise and show a loading message
    in the meantime. -->
  {#await promiseToGetSubarus}
    <p>loading Subarus...</p>
  <!-- When the promise resolves, we can render the result. The "data"
    variable here captures what our promise resolves with, in this case,
    it's "response.json()", like we defined in our JavaScript code. -->
  {:then data}
    <p>Message: {data['Message']}</p>

    <h2>Subaru Models</h2>
    <ul>
      {#each data['Results'] as model}
        <li>{model['Model_Name']}</li>
      {/each}
    </ul>
  <!-- We can also do some error handling in case our request fails. -->
  {:catch error}
    <p style="color: red">{error.message}</p>
  {/await}
</main>

This is a pretty neat feature. It embraces the modern JavaScript concept of promises and has the potential of reducing a good amount of boilerplate and, as a consequence, make our components easier to read.

Reactivity is built in, and leverages a quirky JavaScript feature

Svelte also checks the reactivity box, and it does so in some interesting ways.

First of all, any value that you include in a template is fully reactive. So, to take an example from Svelte’s own documentation, this works as you’d expect:

<script>
  // Here's our variable.
  let count = 0;

  // Here's a function that updates our "count" variable.
  function handleClick() {
    count += 1;
  }
</script>

<!-- This is how we tell Svelte to respond to the click event on this button by
  calling the handleClick function. -->
<button on:click={handleClick}>
  <!-- We use the count variable to render some markup here. It is reactive by
    default. That means that the view will be updated automatically
    every time the value changes. That is, every time the button is clicked. -->
  Clicked {count} {count === 1 ? 'time' : 'times'}
</button>

Try it out in Svelte’s official tutorial.

There’s also support for computed values. That is, values that are derived from other values and reactively change whenever the values they depend on are changed. Svelte solves this problem with so called reactive declarations. They look like this:

$: evenness = count % 2 == 0 ? 'even' : 'odd';

In the context of our count example, we could use it with something like this:

<script>
  let count = 0;

  // Here's a reactive declaration. It gets recalculated every time "count"
  // changes. That is, every time the button is clicked. 
  $: evenness = count % 2 == 0 ? 'even' : 'odd';

  function handleClick() {
    count += 1;
  }
</script>

<button on:click={handleClick}>
  Clicked {count} {count === 1 ? 'time' : 'times'}
</button>

<!-- And as expected, this portion of the view also gets updated when "evenness"
  changes. -->
<p>
  Evenness of count: {evenness}
</p>

The fist time I saw this $: syntax I thought it was weird, and it kind of is. However, it’s actually valid JavaScript. This is just a label (as explained in MDN). The Svelte magic comes into play when it finds a label like this one. The compiler looks at the statement to the right of the label and does what it needs to do in order to make it reactive.

Svelte can also reactively run arbitrary code. Pretty much any statement can be run reactively. For example, all of these work:

// This gets executed every time "evenness" changes.
$: console.log("The evenness changed to: " + evenness);

// This gets executed every time "evenness" or "count" changes.
$: {
  console.log("The evenness changed to: " + evenness);
  console.log("The count is: " + count)
}

// This gets executed every time "count" changes.
$: if (count >= 10) {
  alert("count is dangerously high!");
}

You can go low level

Svelte offers various mechanisms for going low level and directly handling the DOM. One such method is the “this” binding. With it, we can take a given HTML element and have Svelte assign a reference to it into a variable of our choosing. Here’s how it works:

<script>
  // First, we need to import the "onMount" function which allows us to
  // execute some code when the Svelte component is fully mounted into the DOM
  // and ready to use.
  import { onMount } from 'svelte';

  // Here we define this variable which we will use to capture a reference to
  // one of our DOM elements.
  let myDiv;

  // The "myDiv" variable is initialized when the component is mounted. So any
  // code that uses it needs to be inside an "onMount" callback. The variable
  // contains a reference to our div element defined below.
  onMount(() => {
    console.log("Here's a reference to some div: ", myDiv);
    myDiv.innerText = "The component has been mounted";
  });
</script>

<!-- Using this 'bind:this="{div}"' binding, we tell Svelte to store a reference
  to the DOM element represented by this div into the myDiv variable. -->
<div bind:this="{myDiv}">
  This is some text that will go away.
</div>

The only thing to keep in mind is that we should only use the myDiv variable inside the onMount life cycle hook (more info here). This is the only way to make sure that the variable is correctly initialized, since it will be undefined before the component is mounted.

Another mechanism to perform low level DOM operations is via “actions” and the “use” directive. This is a more robust and reusable alternative to the “this” binding in that it allows us to define a separate function to augment a given DOM element with custom functionality and interact with the rest of the Svelte app ecosystem via firing events. Here’s an example illustrating the most unnecessarily roundabout way of making a div clickable using the DOM API directly:

<script>
  // This function encapsulates all direct DOM manipulations. It receives a
  // "node" parameter which contains a reference to the DOM element that had
  // the "use" directive called on it with this "customClickable" as a
  // parameter. This function could have been defined in a separate file and
  // imported here for easy reusability.
  function customClickable(node) {
    function handleOnClick(event) {
      // We have full access to the DOM element. We can use members like
      // "id" or "dispatchEvent".
      console.log(`dispatching ${node.id}'s customclick event`);
      // Here we dispatch a custom event named "customclick" with some
      // arbitrary parameters.
      node.dispatchEvent(new CustomEvent('customclick', {
        detail: { x: event.clientX, y: event.clientY }
      }));
    }

    // Here we directly use the DOM API to set up an event handler for our
    // "node".
    node.addEventListener('click', handleOnClick);

    // We should return an object with a "destroy" method to be called by
    // Svelte when the component is unmounted. In this case, all we do is
    // remove the event listener that we added above.
    return {
      destroy() {
        node.removeEventListener('click', handleOnClick);
      }
    };
  }

  // This function gets passed the custom event data, just as
  // "customClickable" defines it when it calls "dispatchEvent" on the "node".
  function logCoordinates(event) {
    console.log("Div clicked in ", {
      x: event.detail.x, y: event.detail.y
    });
  }
</script>

<!-- When defining our custom clickable div, we use the "use:customClickable"
  directive to tell Svelte to call the "customClickable" function and pass it
  the div's underlying DOM element. "customClickable" in turn augments the div
  so that it can dispatch a new type of event: "customclick". Then, using
  Svelte's usual event handling mechanisms, we set the element up so that when
  the div dispatches the "customclick" event, "logCoordinates" gets executed.
-->
<div
  id="my_custom_clickable_div"
  style="border: 1px solid blue; padding: 10px; cursor: pointer;"
  use:customClickable
  on:customclick={logCoordinates}
>
  Click here and see what happens.
</div>

Again, this example is doing something completely unnecessary because divs are already clickable. For a more complex example you can study this one from Svelte’s official documentation.

And that’s it for now. These are the features that called my attention as I dove into Svelte for the first time. Of course, Svelte offers many other features that I didn’t discuss here like:

Two-way data binding for input elements in forms and even between components.
Handling and dispatching DOM and custom events to keep the flow of data through the component hierarchy clean and obvious.
Transitions and Animations which in Svelte are built in, first-class citizens.
Component composition: traditional nesting and via slots.
Global application state management à la Vuex or Redux.
A full-stack application framework in the form of Sapper.

These are features that other frameworks also include and Svelte offers similar implementations, with its own particular flavor. I just wanted to mention them so you know they are there. To learn more, I’d encourage you to work through the excellent official tutorial.

When talking about features, Svelte has one advantage in that it has more freedom than traditional frameworks to add a lot of functionality. They have this freedom because more features don’t mean any additional overhead (in space or performance) for those who don’t use them. Svelte is a compiler, so it has the ability to produce a bundle which includes only the features that are being used in your app. In other words, the framework can grow and not have to deal with the constraints of traditional library-based frameworks. The future seems bright.

All in all, I think Svelte is a great contender. It offers all the features that put it right up there with the big guys. It also promises a great uplift in performance when compared to said big guys. As a cherry on top, it offers a great developer/code authoring experience which is familiar and also arguably better than existing frameworks. I for one am looking forward to seeing how the project evolves and matures and what cool things people make with it. And of course, also trying it out in some projects of my own.

Creating a Messaging App Using Spring for Apache Kafka, Part 3

2020-05-21T00:00:00+00:00

Photo by Pascal Debrunner on Unsplash

This article is part of a series. The GitHub repository with code examples can be found here.

In this article we’ll create the persistence and cache models and repositories. We’re also going to create our PostgreSQL database and the basic schema that we’re going to map to the persistence model.

Persistence

Database

We are going to keep the persistence model as simple as possible so we can focus on the overall functionality. Let’s first create our PostgreSQL database and schema. Here is the list of tables that we’re going to create:

users: will hold the users who are registered to use this messaging service.
access_token: will hold the unique authentication tokens per session. We’re not going to implement an authentication and authorization server specifically in this series but rather will generate a simple token and store it in this table.
contacts: will hold relationships of existing users.
messages: will hold messages sent to users.

Let’s create our tables:

CREATE TABLE kafkamessaging.users (
    user_id BIGSERIAL PRIMARY KEY,
    fname VARCHAR(32) NOT NULL,
    lname VARCHAR(32) NOT NULL,
    mobile VARCHAR(32) NOT NULL,
    created_at DATE NOT NULL
);

CREATE TABLE kafkamessaging.access_token (
    token_id BIGSERIAL PRIMARY KEY,    
    token VARCHAR(256) NOT NULL,
    user_id BIGINT NOT NULL REFERENCES kafkamessaging.users(user_id),
    created_at DATE NOT NULL
);

CREATE TABLE kafkamessaging.contacts (
    contact_id BIGSERIAL PRIMARY KEY,
    user_id BIGINT NOT NULL REFERENCES kafkamessaging.users(user_id),
    contact_user_id BIGINT NOT NULL REFERENCES kafkamessaging.users(user_id),
);

CREATE TABLE kafkamessaging.messages (
    message_id BIGSERIAL PRIMARY KEY,
    from_user_id BIGINT NOT NULL REFERENCES kafkamessaging.users(user_id),
    to_user_id BIGINT NOT NULL REFERENCES kafkamessaging.users(user_id),
    message VARCHAR(512) NOT NULL,
    sent_at DATE NOT NULL
);

Model

Before creating the models we’ll add another dependency called Lombok in pom.xml as shown below. Lombok provides very helpful annotations which automatically create getters, setters and many other parts of a class.

    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
    </dependency>

So here are the persistent model classes of the corresponding tables we created in the database. Notice the Lombok and javax.persistence annotations in the model classes:

User

package com.endpoint.SpringKafkaMessaging.persistent.model;

import java.io.Serializable;
import java.util.Date;
import java.util.Set;

import javax.persistence.CascadeType;
import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.FetchType;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.OneToMany;
import javax.persistence.Table;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

@Entity
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Table(name="users")
public class User implements Serializable {

    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    @Column(name="user_id")
    private Long userId;

    @Column
    private String fname;

    @Column
    private String lname;

    @Column
    private String mobile;
    
    @Column(name="created_at")
    private Date createdAt;
    
    @OneToMany(mappedBy = "User", fetch = FetchType.EAGER,
            cascade = CascadeType.ALL)
    private Set<Contact> contacts;

}

AccessToken

package com.endpoint.SpringKafkaMessaging.persistent.model;

import java.io.Serializable;
import java.util.Date;
import java.util.Map;
import java.util.UUID;

import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.Table;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

@Entity
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Table(name="access_token")
public class AccessToken implements Serializable {

    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    private Long token_id;
    
    @Column(name="token")
    private String token;

    @Column(name="user_id")
    private Long userId;

    @Column(name="created_at")
    private Date createdAt;

}

Contact

package com.endpoint.SpringKafkaMessaging.persistent.model;

import java.io.Serializable;

import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.FetchType;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.JoinColumn;
import javax.persistence.ManyToOne;
import javax.persistence.Table;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

@Entity
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Table(name="contacts")
public class Contact implements Serializable {
    
    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    @Column(name="contact_id")
    private Long contactId;
    
    @Column(name="user_id")
    private Long userId;

    @Column(name="contact_user_id")
    private Long contactUserId;
    
    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "user_id", nullable = false)
    private User user;
}

Message

package com.endpoint.SpringKafkaMessaging.persistent.model;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.io.Serializable;
import java.util.Date;

import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.Table;

@Entity
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Table(name="messages")
public class Message implements Serializable {

    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    @Column(name="message_id")
    private String messageId;

    @Column(name="from_user_id")
    private Long fromUserId;

    @Column(name="to_user_id")
    private Long toUserId;

    @Column(name="message")
    private String message;
    
    @Column(name="sent_at")
    private Date sentAt;

}

Note also that we didn’t use underscores in the class field names for the corresponding table field names like userId for user_id.

We’re going to use Spring’s CrudRepository interface to create our data repositories. CrudRepository can use keywords to automatically create logic using the given interface method names. Underscores are reserved characters, and even though you can still escape using double underscore in the CrudRepository method names, it doesn’t look good. I chose to use camel case, which also complies with Java convention.

Repository

Now let’s add the corresponding persistent repositories for each data model:

UserRepository

package com.endpoint.SpringKafkaMessaging.persistent.repository;

import java.util.List;

import org.springframework.data.repository.CrudRepository;
import org.springframework.stereotype.Repository;

import com.endpoint.SpringKafkaMessaging.persistent.model.User;

@Repository
public interface UserRepository extends CrudRepository<User, Long> {

    List<User> findAll();

    User findByUserId(Long userId);
    
    User findByMobile(String mobile);
    
    User findByFname(String fname);
    
    User findByLname(String lname);

    void deleteById(Long userId);

}

ContactRepository

package com.endpoint.SpringKafkaMessaging.persistent.repository;

import java.util.List;

import org.springframework.data.repository.CrudRepository;
import org.springframework.stereotype.Repository;

import com.endpoint.SpringKafkaMessaging.persistent.model.Contact;

@Repository
public interface ContactRepository extends CrudRepository<Contact, Long> {

    List<Contact> findAllByUserId(Long userId);
    
    Contact findByContactUserId(Long contactUserId);

    void deleteByContactUserId(Long contactUserId);
}

AccessTokenRepository

package com.endpoint.SpringKafkaMessaging.persistent.repository;
import org.springframework.data.repository.CrudRepository;
import org.springframework.stereotype.Repository;

import com.endpoint.SpringKafkaMessaging.persistent.model.AccessToken;

@Repository
public interface AccessTokenRepository extends CrudRepository<AccessToken, Long> {

    AccessToken findByUserId(Long userId);

    void deleteByUserId(Long userId);

}

MessageRepository

package com.endpoint.SpringKafkaMessaging.persistent.repository;

import org.springframework.data.repository.CrudRepository;
import org.springframework.stereotype.Repository;

import com.endpoint.SpringKafkaMessaging.persistent.model.Message;
@Repository
public interface MessageRepository extends CrudRepository<Message, Long> {
    
}

Cache

We’re not going to integrate the cache environment as Spring persistent data, so we won’t be using the CrudRepository implementation for the cache repository. Instead, let’s create the cache repository interface and create an implementation of it. Caching is going to be used for quick activation and authentication responses. To achieve this we’re going to store and query simple key-value pairs with Redis.

Repository

CacheRepository

package com.endpoint.SpringKafkaMessaging.cache.respository;

public interface CacheRepository {

    void putAccessToken(String token, String userId);
    
    String getUserIdByAccessToken(String token);

    void putActivationCode(String mobile, String activationCode);
    
    String queryMobileActivationCode(String mobile, String activationCode);
}

Since the business logic of this interface is not automatically created by Spring Boot, we need to create our own logic in Spring’s @Service like below.

CacheRepositoryImpl

package com.endpoint.SpringKafkaMessaging.cache.respository;

import org.springframework.stereotype.Service;

import com.endpoint.SpringKafkaMessaging.cache.JedisFactory;

import redis.clients.jedis.Jedis;

@Service
public class CacheRepositoryImpl implements CacheRepository {

    @Override
    public void putAccessToken(String token, String userId) {

        try (Jedis jedis = JedisFactory.getConnection()) {

            jedis.set(token, userId);

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    @Override
    public String getUserIdByAccessToken(String token) {

        try (Jedis jedis = JedisFactory.getConnection()) {

            return jedis.get(token);

        } catch (Exception e) {
            e.printStackTrace();
        }

        return null;
    }

    @Override
    public void putActivationCode(String mobile, String activationCode) {

        try (Jedis jedis = JedisFactory.getConnection()) {

            jedis.hset(mobile, String.valueOf(activationCode), "");
            jedis.expire(mobile, 15 * 60);

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    @Override
    public String queryMobileActivationCode(String mobile, String code) {

        try (Jedis jedis = JedisFactory.getConnection()) {

            return jedis.hget(mobile, code);
        } catch (Exception e) {
            e.printStackTrace();
        }

        return null;
    }
}

Activation and Authentication

Activation is a one-time process to activate a mobile number for our messaging service client. After an activation our simple authentication service will provide an access token to messaging client, and this access token will be used for future client logins. To achieve these simple processes let’s create our authentication service interface.

AuthService

package com.endpoint.SpringKafkaMessaging.auth;

public interface AuthService {
    void putAccessToken(String code, Long userId);

    void loginWithAccessToken(String mobile, String code);
}

AuthServiceImpl

package com.endpoint.SpringKafkaMessaging.auth;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import com.endpoint.SpringKafkaMessaging.cache.respository.CacheRepository;
import com.endpoint.SpringKafkaMessaging.persistent.model.AccessToken;
import com.endpoint.SpringKafkaMessaging.persistent.repository.AccessTokenRepository;

import java.util.Calendar;

@Service
public class AuthServiceImpl implements AuthService {

    @Autowired
    CacheRepository cacheRepository;

    @Autowired
    AccessTokenRepository accessTokenRepository;

    @Override
    public void putAccessToken(String token, Long userId) {

        // store token in the cache
        cacheRepository.putAccessToken(token, String.valueOf(userId));

        // store token in the persistence
        AccessToken accessToken = AccessToken.builder()
                                    .token(token)
                                    .userId(userId)
                                    .createdAt(Calendar.getInstance().getTime())
                                    .build();
        accessTokenRepository.save(accessToken);
    }

    @Override
    public void loginWithAccessToken(String mobile, String code) {
        // TODO
    }
}

We won’t implement a complex auth server here.

Let’s look at the draft form of the authentication controller below. The authentication controller here simulates the mobile number activation and one time login with the activation code and provides a unique access token to client. To achieve this I defined activation request and response models.

ActivationRequest

package com.endpoint.SpringKafkaMessaging.auth.controller;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

@Builder
@Data
@AllArgsConstructor
@NoArgsConstructor
public class ActivationRequest {
    
    private String mobile;
    
}

ActivationResponse

package com.endpoint.SpringKafkaMessaging.auth.controller;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

@Builder
@Data
@AllArgsConstructor
@NoArgsConstructor
public class ActivationResponse {
    
    private String mobile;
    
    private String activationCode;
    
}

LoginRequest

package com.endpoint.SpringKafkaMessaging.auth.controller;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

@Builder
@Data
@AllArgsConstructor
@NoArgsConstructor
public class LoginRequest {
    
    private String mobile;
    
    private String activationCode;
    
}

AuthController

package com.endpoint.SpringKafkaMessaging.auth.controller;

import javax.validation.Valid;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import com.endpoint.SpringKafkaMessaging.auth.AuthService;
import com.endpoint.SpringKafkaMessaging.cache.respository.CacheRepository;
import com.endpoint.SpringKafkaMessaging.persistent.model.User;
import com.endpoint.SpringKafkaMessaging.persistent.repository.UserRepository;
@RestController
@RequestMapping("/api/auth")
public class AuthController {

    @Autowired
    UserRepository userRepository;

    @Autowired
    AuthService authService;

    @Autowired
    CacheRepository cacheRepository;
    
    @RequestMapping(value = "/getcode", method = RequestMethod.POST, consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public ResponseEntity<Object> getCode(@Valid @RequestBody ActivationRequest activationRequest) {
        
        // TODO
        
        return null;
    }
    
    @RequestMapping(value = "/login", method = RequestMethod.POST, consumes = MediaType.APPLICATION_JSON_UTF8_VALUE, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public ResponseEntity<String> login(@RequestBody LoginRequest loginRequest) {
        
        // TODO
        
        return null;
    }
}

In the next chapter, we’ll shape and complete the authentication service and controller and add message sender and receiver services. We’ll also configure and enable Spring WebSocket.

In the final chapter, we’ll create a simple web app interface as a messaging client to test our spring-kafka messaging application.

Creating a Messaging App Using Spring for Apache Kafka, Part 2

2020-04-29T00:00:00+00:00

This article is part of a series. The GitHub repository with code examples can be found here.

In this part I’ll walk through Kafka’s servers and processes, the basics of spring-kafka producers and consumers, persistence, and caching configurations.

Kafka Servers

Kafka uses Apache ZooKeeper as the distributed coordination server. You can download the Apache Kafka with ZooKeeper bundle here.

When you download and untar the Kafka bundle Kafka’s console scripts can be found in the bin directory. To enable Kafka connectivity and prepare the Kafka configuration let’s start the Kafka servers and see how to create Kafka topics and test console producers and consumers.

ZooKeeper

To start ZooKeeper with the default properties run the following command:

bin/zookeeper-server-start.sh config/zookeeper.properties

Kafka Server

A single Kafka server with the default properties can be started with following command:

bin/kafka-server-start.sh config/server.properties

Kafka Topics

Creating Kafka Topics

Let’s create a test Kafka topic:

bin/kafka-topics.sh --create --zookeeper localhost:2181 --replication-factor 1 --partitions 1 --topic myTestTopic

List Topics

To list all previously created Kafka topics:

bin/kafka-topics.sh --list --bootstrap-server localhost:9092

Start a Producer

To start a console producer run the following command and send some messages from console:

bin/kafka-console-producer.sh --broker-list localhost:9092 --topic myTestTopic
> This is a message
> This is another message

Start a Consumer

bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic myTestTopic --from-beginning

When you run the consumer on the console with the from-beginning parameter you’ll see all the messages sent previously shown in the console.

Here we ran Kafka as a single server. You’ll need to optimize and scale the Kafka clusters for production and large-scale distributed systems. So far, we’ve become familiar with some Kafka components but for further Kafka configuration you can refer to the corresponding tutorials.

spring-kafka Configuration

Consumer Configuration

In the Spring Boot project let’s put the lines below in the application.properties to configure the Spring Kafka consumer:

#Consumer
spring.kafka.consumer.bootstrap-servers=localhost:9092
spring.kafka.consumer.group-id=foo
spring.kafka.consumer.auto-offset-reset=earliest
spring.kafka.consumer.key-deserializer=org.apache.kafka.common.serialization.StringDeserializer
spring.kafka.consumer.value-deserializer=org.apache.kafka.common.serialization.StringDeserializer

A simple Kafka consumer is defined as a Spring @KafkaListener annotated method like this:

@Configuration
public class MyKafkaConsumer {

    @KafkaListener(topics = "myTestTopic")
    public void listenTopic(ConsumerRecord<String, String> kafkaMessage) {
        System.out.print(String.format("Received a message: %s", kafkaMessage.value()));
    }

}

We are going to define different Kafka consumer methods listening to different topics for different purposes in our messaging app.

Producer Configuration

For producer configuration let’s add the following lines in the application.properties in our Spring Kafka project.

#Producer
spring.kafka.producer.bootstrap-servers=localhost:9092
spring.kafka.producer.key-serializer=org.apache.kafka.common.serialization.StringSerializer
spring.kafka.producer.value-serializer=org.apache.kafka.common.serialization.StringSerializer

A very simple Kafka producer could be configured like below. Spring KafkaTemplate provides a producer model and methods for sending messages to specified Kafka topics.

@Configuration
public class MyKafkaProducer {

    @Autowired
    private KafkaTemplate<String, String> kafkaTemplate;

    public void sendMessage(String topic, String message) {
        System.out.println(String.format("Message is being sent to topic %s", topic));
        kafkaTemplate.send(topic, message);
    }

}

So far we have configured Kafka in a Spring Boot project and seen simple consumer and producer examples. Before going further with Kafka configuration, let’s configure the persistence and cache repositories.

Persistence Configuration

As I mentioned in the first part of this blog series, I’m going to use PostgreSQL as a persistence environment and Spring data configuration will be like below in the application.properties:

spring.datasource.url=jdbc:postgresql://localhost:5432/epmessagingdb
spring.datasource.username=epmessaging
spring.datasource.password=epmessagingdb_password
spring.datasource.driver-class-name=org.postgresql.Driver
spring.datasource.configuration.maximum-pool-size=30
spring.jpa.database-platform=PostgreSQL
# The SQL dialect makes Hibernate generate better SQL for the chosen database
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
# Hibernate ddl auto (create, create-drop, validate, update)
spring.jpa.hibernate.ddl-auto=none

In the properties we set the spring.jpa.hibernate.ddl-auto Spring JPA property to none to avoid Hibernate populating the schema automatically. In some cases it can be useful to allow auto-population. We leave the base configuration here for now as it is, in the next part we’ll create our Spring Data models in the project.

Caching Configuration

I also mentioned that we’re going to use Redis as the cache environment. Redis is developed using C and a very fast in-memory cache.

Let’s put the following lines in application.properties to enable Redis configuration in our Spring Kafka project.

cache.redis.host=localhost
cache.redis.port=6379
cache.redis.timeout=5000
cache.redis.password=

Redis Pooling Factory

We’re going to use Jedis as the Redis client in our project. So let’s create a Jedis pooling factory class in our project called JedisFactory like below:

package com.endpoint.SpringKafkaMessaging.cache;

import org.springframework.beans.factory.annotation.Value;
import redis.clients.jedis.Jedis;
import redis.clients.jedis.JedisPool;
import redis.clients.jedis.JedisPoolConfig;

public class JedisFactory {

    @Value("${cache.redis.host}")
    private static String host;

    @Value("${cache.redis.port}")
    private static Integer port;

    @Value("${cache.redis.timeout}")
    private static Integer timeout;

    @Value("${cache.redis.password}")
    private static String password;

    // hide the constructor
    private JedisFactory() {

    }

    private static JedisPool jedisPool;

    static {
        JedisPoolConfig poolConfig = new JedisPoolConfig();
        poolConfig.setMaxTotal(128);

        jedisPool = new JedisPool(
            poolConfig,
            host,
            port,
            timeout,
            password
        );
    }

    public static Jedis getConnection() {
        return jedisPool.getResource();
    }
}

We’ll create a persistence model, repository, controllers, and a cache repository in the next part of this blog series.

Creating a Messaging App Using Spring for Apache Kafka, Part 1

2020-04-08T00:00:00+00:00

Photo by Click and Learn Photography at Unsplash

This article is part of a series. The GitHub repository with code examples can be found here.

Spring is a popular Java application framework. Apache Kafka is a fault-tolerant, fast, and horizontally scalable distributed stream-message broker. Spring for Apache Kafka applies the overall concepts of Spring to Java applications based on Kafka.

Since Kafka can establish a fast and fault-tolerant stream data pipeline it can be used as an orchestrator. In this article I’ll explain how to create a spring-kafka project, add dependencies and use Kafka to create a messaging app.

Initialize Spring project

Spring projects can be built from scratch using Spring Initializr. I like to keep the default options. Most Spring projects use Maven. I set the group id as com.endpoint and the artifact as SpringKafkaMessaging which makes the base package name com.endpoint.SpringKafkaMessaging.

When we are done with the initial project setup we press the “GENERATE” button to download an empty Spring Boot project in a zip file. You can then use your favorite IDE to open and start developing your project. I prefer Eclipse for Java projects. Here’s what it looks like when I open the project up:

I won’t address detailed configuration or adding dependencies of Spring and Maven projects in this post. If you are not familiar with Spring and Maven, I recommend that you have a look at the Spring documentation first.

Design and architecture

Before adding the dependencies, including Kafka, we need to make a high-level design of this simple project and figure out how to proceed with development. Messaging apps seem simple at first glance but the architecture behind them can be quite complex.

There are different kinds of technology stacks you can choose from. Which base protocol we choose (XMPP, SIP, or WebSocket) depends on what our app’s aim is. Sometimes multiple protocols can be used and interconnected to provide more features; XMPP is mostly used for chatting, SIP is designed for VoIP and media transfer. We’ll use WebSocket to communicate with Kafka over TCP.

By understanding the architectural model of Kafka, you’ll get an understanding of how Kafka is going to maintain most of the backend processes.

Kafka, as I mentioned previously, is horizontally scalable, and Kafka clusters can grow to span several data sources. Message producers and message consumers (all client messaging apps are both producers and consumers) produce and consume messages through Kafka topics.

So, taking into account the principles for designing the architecture of such a client–server-based messaging app, here are the components and their communication directions:

Kafka Cluster
Spring Boot REST API, which will handle user authentication and login
Persistence (here I chose PostgreSQL)
Cache (Redis) for fast read-write cache operations
WebSocket for messaging app clients

spring-kafka dependencies

After creating a model and components let’s add our dependencies to the pom.xml file to finish creating our project. Below we add spring-boot-starter, spring-boot-starter-web, spring-kafka, spring-boot-starter-jdbc, and redis.clients:jedis for the corresponding REST, Kafka, Persistent (JDBC), and Redis components.

<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>
  </dependency>

  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>

  <dependency>
    <groupId>org.springframework.kafka</groupId>
    <artifactId>spring-kafka</artifactId>
  </dependency>

  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jdbc</artifactId>
  </dependency>

  <dependency>
    <groupId>redis.clients</groupId>
    <artifactId>jedis</artifactId>
  </dependency>

  <dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
  </dependency>

  <dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
  </dependency>

  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
    <exclusions>
      <exclusion>
        <groupId>org.junit.vintage</groupId>
        <artifactId>junit-vintage-engine</artifactId>
      </exclusion>
    </exclusions>
  </dependency>

  <dependency>
      <groupId>org.springframework.kafka</groupId>
      <artifactId>spring-kafka-test</artifactId>
      <scope>test</scope>
  </dependency>
</dependencies>

Continued in Part 2!

Serialization and Deserialization Issues in Spring REST

2020-03-17T00:00:00+00:00

Photo by Annie Spratt

Spring Boot projects primarily use the JSON library Jackson to serialize and deserialize objects. It is especially useful that Jackson automatically serializes objects returned from REST APIs and deserializes complex type parameters like @RequestBody.

In a Spring Boot project the automatically registered MappingJackson2HttpMessageConverter is usually enough and makes JSON conversions simple, but this may have some issues which need custom configuration. Let’s go over a few good practices for them.

Configuring a Custom Jackson ObjectMapper

In Spring REST projects a custom implementation of MappingJackson2HttpMessageConverter helps to create the custom ObjectMapper, as seen below. Whatever custom implementation you need to add to the custom ObjectMapper can be handled by this custom converter:

public class CustomHttpMessageConverter extends MappingJackson2HttpMessageConverter {

    private ObjectMapper initCustomObjectMapper() {
        ObjectMapper customObjectMapper = new ObjectMapper();
        return customObjectMapper;
    }

    // ...
}

Additionally, some MappingJackson2HttpMessageConverter methods, such as writeInternal, can be useful to override in certain cases. I’ll give a few examples in this article.

In Spring Boot you also need to register a custom MappingJackson2HttpMessageConverter like below:

@Bean
MappingJackson2HttpMessageConverter mappingJackson2HttpMessageConverter() {
    return new CustomHttpMessageConverter();
}

Serialization

Pretty-printing

Pretty-printing in Jackson is disabled by default. By enabling SerializationFeature.INDENT_OUTPUT in the ObjectMapper configuration pretty-print output is enabled (as in the example below). Normally a custom ObjectMapper is not necessary for setting the pretty-print configuration. In some cases, however, like one case of mine in a recent customer project, this configuration might be necessary.

For example, passing a URL parameter can enable pretty-printing. In this case having a custom ObjectMapper with pretty-print enabled and keeping the default ObjectMapper of MappingJackson2HttpMessageConverter as is could be a better option.

public class CustomHttpMessageConverter extends MappingJackson2HttpMessageConverter {

    private ObjectMapper initiatePrettyObjectMapper() {
        ObjectMapper customObjectMapper = new ObjectMapper();
        customObjectMapper.configure(SerializationFeature.INDENT_OUTPUT, true);

        // additional indentation for arrays
        DefaultPrettyPrinter pp = new DefaultPrettyPrinter();
        pp.indentArraysWith(new DefaultIndenter());
        customObjectMapper.setDefaultPrettyPrinter(pp);

        return customObjectMapper;
    }

}

Conditionally Filtering the Fields

When serializing a response object you may need to include or ignore one or more fields depending on their values. Let’s assume a model class UserResponse like below.

Notice that we used @JsonIgnore which is completely discarding the annotated field from serialization. Conditional filtering is different and it can be done using SimpleBeanPropertyFilter objects set to the filter provider of the ObjectMapper objects. Also notice that @JsonFilter annotation is used for UserResponse which points to which filter will be used by ObjectMapper during the serialization.

@JsonFilter("userCodeFilter")
public class UserResponse {

    public Integer userId;
    public String username;
    public Integer code;

    @JsonIgnore
    public String status;

}

Here we add a filter called userCodeFilter—like the one we added to the custom ObjectMapper of CustomHttpMessageConverter—which will include the UserResponse class’s code field in the serialization if its value is greater than 0. You can add multiple filters to ObjectMapper for different models.

public class CustomHttpMessageConverter extends MappingJackson2HttpMessageConverter {

    private ObjectMapper initiatePrettyObjectMapper() {
        ObjectMapper customObjectMapper = new ObjectMapper();
        customObjectMapper.configure(SerializationFeature.INDENT_OUTPUT, true);

        // additional indentation for arrays
        DefaultPrettyPrinter pp = new DefaultPrettyPrinter();
        pp.indentArraysWith(new DefaultIndenter());
        customObjectMapper.setDefaultPrettyPrinter(pp);

        PropertyFilter userCodeFilter = new SimpleBeanPropertyFilter() {
            @Override
            public void serializeAsField(Object pojo, JsonGenerator jgen, SerializerProvider provider, PropertyWriter writer)
                    throws Exception {
                if (include(writer)) {
                    if (!writer.getName().equals("code")) {
                        writer.serializeAsField(pojo, jgen, provider);
                        return;
                    }
                    int intValue = ((UserResponse) pojo).code;
                    if (intValue > 0) {
                        writer.serializeAsField(pojo, jgen, provider);
                    }
                } else if (!jgen.canOmitFields()) {
                    writer.serializeAsOmittedField(pojo, jgen, provider);
                }
            }

            @Override
            protected boolean include(BeanPropertyWriter writer) {
                return true;
            }

            @Override
            protected boolean include(PropertyWriter writer) {
                return true;
            }
        };

        FilterProvider filters = new SimpleFilterProvider().addFilter("userCodeFilter", userCodeFilter);
        customObjectMapper.setFilterProvider(filters);

        return customObjectMapper;
    }

}

Deserialization

JSON String Parse Error Handling in Spring Boot

This one is a little tricky. Deserialization of a JSON @RequestParam object can cause parsing errors if the JSON object is not well-formed. The errors thrown in Jackson’s deserialization level just before it’s pushed to Spring Boot occur at that level, so Spring Boot doesn’t catch these errors.

Deserialization of Jackson maps JSON to POJOs and finally returns the expected Java class object. If the JSON is not well-formed, parsing cannot be done and MappingJackson2HttpMessageConverter internally throws a parsing error. Since this exception is not caught by Spring Boot and no object is returned, the REST controller would be unresponsive, having a badly-formed JSON payload.

Here we can override the internal read method of MappingJackson2HttpMessageConverter, hack the ReadJavaType with a customReadJavaType method, and make it return an internal error when the deserialization fails to parse the JSON input, rather than throwing an exception which is not seen or handled by Spring Boot.

@Override
public Object read(Type type, @Nullable Class<?> contextClass, HttpInputMessage inputMessage)
        throws IOException, HttpMessageNotReadableException {

    objectMapper.enable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);

    JavaType javaType = getJavaType(type, contextClass);
    return customReadJavaType(javaType, inputMessage);
}

private Object customReadJavaType(JavaType javaType, HttpInputMessage inputMessage) throws IOException {
    try {
        if (inputMessage instanceof MappingJacksonInputMessage) {
            Class<?> deserializationView = ((MappingJacksonInputMessage) inputMessage).getDeserializationView();
            if (deserializationView != null) {
                return this.objectMapper.readerWithView(deserializationView).forType(javaType).
                        readValue(inputMessage.getBody());
            }
        }
        return this.objectMapper.readValue(inputMessage.getBody(), javaType);
    }
    catch (InvalidDefinitionException ex) {
        //throw new HttpMessageConversionException("Type definition error: " + ex.getType(), ex);
        return "Type definition error";
    }
    catch (JsonProcessingException ex) {
        //throw new HttpMessageNotReadableException("JSON parse error: " + ex.getOriginalMessage(), ex, inputMessage);
        return "JSON parse error";
    }
}

This way you can return errors occurring at the deserialization level to Spring Boot, which expects a deserialized object but gets a String value which can be caught and translated into a ControllerAdvice handled exception. This also makes it easier to catch JSON parsing errors without using any third party JSON libraries like Gson.

Enhancing Your Sites with Vue.js

2017-12-26T00:00:00+00:00

Framework Fatigue

When developers consider and evaluate front-end frameworks they often think in terms of writing or rewriting their entire project in Framework X. “Should we use Vue, React, Preact?” or “I heard about Sapper the other day, has anyone tried that?” The running joke response (back-end developers especially love this one) is to the effect of: “If we wait a couple weeks there will be ten more choices!”

All joking aside, frameworks like Vue and React offer many great benefits and can be incrementally adopted to enhance existing sites. There is no need to rewrite your entire project as a Single Page Application to take advantage of what frameworks like Vue offer. I have taken this approach on a couple of my projects recently and been very happy with the results.

Start Small

One of the benefits of using a framework in this way is that you’re not forced to adopt its entire toolchain and specific workflow immediately, such as using ES6/2015, webpack, and Babel right off the bat. I simply loaded the minified, minimal version of Vue I needed on my page and I was off to the races.

If you are familiar with Angular, Vue has a similar concept of custom directives. I used this to build a small countdown timer directive for a customer who wanted to dynamically display the time left before promotions ended. By offloading the DOM updates and rendering to Vue, I was able to create a useful feature very quickly with lean and readable JavaScript code.

Here’s what the widget I delivered to the client looked like:

<countdown-timer start="{start date/time}" end="{end date/time}" />

They were able to drop this snippet onto their pages and use multiple instances of the widget on their product listing page with ease.

Wishlist Pagination

For another project I needed to display wishlists in the cart, below the items the customer had previously added. The wishlist feature is very popular and used by a large number of customers. Many customers have dozens (some hundreds!) of products in their wishlist at any given time.

For this project I was already using gulp to handle the front-end automation so I simply added Vue and vuejs-paginate to the project config and loaded those scripts asynchronously on the cart page. The vuejs-paginate plugin has a simple API that emitted the pagination related events I could tap into.

With a small Vue template and less than 100 lines of code I was able to create a dynamic and very responsive (read: fast!) pagination feature without any DOM manipulation code (e.g. updates, insertions, deletions, etc.).

With Vue (React and friends as well) you simply manage the state of your application (wishlist items in this case) and let the framework handle the rendering step. Give it a try—I think you’ll like it!

Surviving the Framework Hype Cycle (MWRC 2016)

2016-08-31T00:00:00+00:00

Back in March, I attended MountainWest RubyConf with my co-workers Phunk and Phin. Shortly thereafter, Phin wrote about a couple of his favorite talks: Writing a Test Framework from Scratch and How to Build a Skyscraper.

I’ve found that another talk from the conference has stuck with me and I’ve referred to it several times in conversations. It is “Surviving the Framework Hype Cycle” by Brandon Hays. It is funny, engaging, insightful, and especially cathartic given the rapid pace of change in frameworks these days.

It can be tough to set aside the time to focus on a conference talk video, but I think this one is well worth it for programmers!

The 5 phases of the framework hype cycle that he identifies and elaborates on are:

Technology Trigger
Peak of Inflated Expectations
Trough of Disillusionment
Slope of Enlightenment
Plateau of Productivity

And he shows how different groups of people with different needs can benefit at different stages, akin to settling new land:

Pioneers
Settlers
Town Planners

The ebb and flow of technology fads can be a lot easier to navigate when we realize there isn’t an absolute right and wrong to technology choices, and we must consider the project and its maturity level, the people involved, and the current state of the technologies under consideration.

See also the Surviving the Framework Hype Cycle video page and Brandon’s @tehviking Twitter account.

Creating API for Invoice Generator Using C# and Minimal APIs

Prerequisites

Setting up the Project

Setting up the Swagger UI

Setting up the Database Context with Entity Framework

Designing the Invoice Generator API

Creating and running database migrations

Implementing API Endpoints

Adding CORS for development

Integrating with Vue 3 Application

Deployment

Conclusion

How to Migrate from Struts 2 to Struts 6

Getting Ready for Migration from Struts 2 to Struts 6

Config and Code Changes

Servlet API Dependency

Deprecated Sitegraph Plugin Removed

Velocity Plugin

DTD of struts.xml

Class Changes

Constant Changes

OGNL

HTML Escaping

Tiles Support

Conclusion

Learning Vue 3 composables by creating an invoice generator

What are Vue 3 composables?

Core functionalities for invoice generator

Prerequisites

Setting up the project

Create first composable for invoice: useInvoice

Define interfaces for Invoice and InvoiceItem

Adding business logic

Rendering the invoice with composable functions

Create a second composable for using localStorage to save and retrieve invoice data

Printing Invoice

Bonus: create a third composable for showing dashboard data

Next Steps

Conclusion

Migration from Struts 1 to Struts 2

A Comparison of Struts 1 and Struts 2

Migration

Dependencies

Request handling

Configure web application

Migrating actions

Action Configuration

Introduction to Nuxt3 and Rendering Modes

Nuxt3 features

Rendering Modes

1. Universal Rendering (SSR + CSR)

2. Client-Side Rendering (CSR)

3. Hybrid Rendering

I wrote the same app twice, with Hotwire and Blazor Server — here’s what I learned

What this article is

An overview of Blazor

How Blazor works under the hood

An abstraction over the request/response cycle

How Blazor supports common frontend framework features

Handling DOM events

Including other Blazor components

Passing parameters to components

Defining, handling and triggering custom component events

Handling component lifecycle events

Templates

Routing

State management

Interoperability with JavaScript

An overview of Hotwire

Partial page updates with Turbo Frames

Imperative rendering with Turbo Streams

Adding JavaScript with Stimulus

A final comparison

Table of contents

Vue 3 is out with exciting new features

Composition API

Summary

Teleport

Fragments

Emits component option

Create first composable for invoice: `useInvoice`

Define interfaces for `Invoice` and `InvoiceItem`