DEV Community: Ed Legaspi

Stop Rebuilding Exception Handling in Every Spring Boot Project

Ed Legaspi — Mon, 06 Jul 2026 13:20:38 +0000

After working on multiple Spring Boot projects over the years, I noticed an interesting pattern.

Every application had different business requirements.

But almost every application ended up with the same exception handling infrastructure.

I found myself recreating the same classes over and over again:

@RestControllerAdvice
Custom exceptions
Error response models
Error codes
Validation handlers
Feign error decoders
Utility classes
Configuration

The business logic changed.

The exception handling didn't.

Eventually I asked myself:

Why am I rebuilding this for every project?

That question became nerv-exception.

Instead of copying hundreds of lines of exception handling infrastructure from project to project, I wanted a reusable, production-ready library that could become the foundation for every Spring Boot application.

The Problem

A typical Spring Boot application usually starts with something like this.

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<ApiError> handle(UserNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND)
                .body(new ApiError(
                        "USER_NOT_FOUND",
                        ex.getMessage()));
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ApiError> handle(MethodArgumentNotValidException ex) {
        ...
    }

}

Looks simple.

Until the application grows.

Now you have:

business exceptions
validation exceptions
security exceptions
Feign client exceptions
Kafka consumer exceptions
asynchronous processing
scheduled jobs

Every new integration introduces another place where exceptions need to be translated.

Soon enough, different parts of your application return completely different error payloads.

Your REST API becomes inconsistent.

What I Wanted

I wasn't trying to replace Spring Boot.

Spring Boot already provides excellent exception handling capabilities.

Instead, I wanted a reusable foundation that provides:

consistent API responses
centralized error codes
minimal boilerplate
RFC 7807 Problem Details
Spring Boot auto-configuration
modular architecture

Most importantly...

I wanted something I would actually use in production.

Introducing nerv-exception

The library is intentionally split into multiple modules.

nerv-exception-api
nerv-exception-core
nerv-exception-spring-web
nerv-exception-spring-boot-starter
nerv-exception-spring-feign
nerv-exception-event
nerv-exception-spring-kafka

Each module has a single responsibility.

For example:

api contains only the public contracts.
core contains the domain exception model.
spring-web integrates with Spring MVC.
starter provides auto-configuration.
feign handles remote service errors.
event standardizes exception events.
spring-kafka integrates with Kafka consumers.

Applications only depend on what they actually need.

Adding the Library

Getting started is intentionally simple.

<dependency>
    <groupId>com.czetsuyatech</groupId>
    <artifactId>nerv-exception-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

That's it.

Spring Boot auto-configuration registers everything automatically.

Standardized Error Responses

One of the biggest goals of the project was consistency.

Instead of every controller returning its own custom JSON, APIs can return standardized RFC 7807 Problem Details.

Example:

{
  "type": "https://example.com/problems/user-not-found",
  "title": "User not found",
  "status": 404,
  "detail": "User 123 was not found.",
  "instance": "/users/123"
}

This makes APIs significantly easier to consume.

Frontend developers know exactly what to expect.

API documentation becomes simpler.

Clients become easier to implement.

Designed for Extension

One design decision I made very early was:

Avoid forcing applications into one way of doing things.

The library provides sensible defaults while remaining extensible.

For example:

custom error codes
custom exception mapping
trace context propagation
Feign integration
Kafka integration
event publishing

Applications can override behavior without modifying the library itself.

Runnable Examples

Documentation is helpful.

Runnable code is even better.

That's why I also created a companion repository containing complete Spring Boot applications demonstrating how to use the library in real projects.

Rather than reading isolated snippets, developers can clone the repository, run the application, and explore the implementation themselves.

Repository:

https://github.com/czetsuyatech/nerv-examples

Why Open Source?

Throughout my career I've benefited enormously from open source.

Many libraries have saved me countless hours.

Building nerv-exception is my opportunity to give something back.

If another developer no longer has to rebuild the same exception handling infrastructure for their next project, then this library has already accomplished its goal.

Resources

GitHub

https://github.com/czetsuyatech/nerv-exception

Maven Central

<dependency>
    <groupId>com.czetsuyatech</groupId>
    <artifactId>nerv-exception-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

Example Projects

https://github.com/czetsuyatech/nerv-examples

I'm continuously improving the library based on real-world experience.

If you have ideas, suggestions, or find it useful, I'd love to hear your feedback.

Happy coding! 🚀

Stop Rewriting CI/CD: Reusable GitHub Actions for Maven Projects

Ed Legaspi — Tue, 28 Apr 2026 00:36:48 +0000

If you’ve worked on multiple Java projects, you’ve probably run into this:

Every repository has its own version of a CI/CD pipeline.

Slightly different YAML.

Slightly different setup steps.

Slightly different ways of doing the same thing.

And somehow… none of them are reusable.

😤 The Real Problem

It’s not that CI/CD is hard.

It’s that it’s repetitive.

You end up doing the same things over and over:

Set up Java
Cache Maven dependencies
Run tests
Build artifacts
Handle versioning
Publish or release

Then copy that workflow into another repo…

…and tweak it just enough to break consistency.

This is exactly the kind of problem automation should solve — yet we keep duplicating it.

💡 A Different Approach

Instead of treating each pipeline as a one-off YAML file, I started thinking:

What if CI/CD steps were modular and reusable — just like code?

That’s where NERV-Actions came from.

👉 https://github.com/czetsuyatech/nerv-actions

⚙️ What NERV-Actions Is

NERV-Actions is a collection of reusable GitHub Actions designed for Maven-based projects.

The idea is simple:

Break CI/CD into small, composable actions
Reuse them across repositories
Keep pipelines consistent without rewriting everything

Instead of this:

# repeated in every repo
- uses: actions/setup-java@v4
- run: mvn clean install

You plug in reusable building blocks that already handle those concerns.

🧱 Why This Matters

Reusable workflows aren’t just about convenience — they solve real scaling problems.

When you define things once and reuse them:

You reduce duplication
You avoid inconsistencies across repos
You make updates easier (change once, apply everywhere)
You spend less time debugging YAML

🧠 Design Philosophy

I didn’t try to build a “one-size-fits-all” pipeline.

Instead, NERV-Actions focuses on:

Composable units → mix only what you need
Sensible defaults → minimal setup required
Consistency → same patterns across projects
Extensibility → override when necessary

It’s closer to building blocks than a framework.

🚀 Example Use Case

For a typical Maven project, your pipeline usually boils down to:

Run tests
Build artifacts
Publish packages
Create releases

With reusable actions, you don’t redefine these steps every time—you just assemble them.

🤔 Why Not Just Copy-Paste?

Because copy-paste doesn’t scale.

It works for 2–3 repos.

It breaks down at 10+.

Suddenly:

Fixes don’t propagate
Pipelines drift
Debugging becomes inconsistent

Reusable actions solve that by centralizing the logic.

🧪 Still Evolving

This isn’t meant to be a “perfect CI/CD solution.”

It’s a practical attempt to reduce the friction I kept running into across projects.

If you’re dealing with the same repetition in GitHub Actions, this might be useful:

👉 https://github.com/your-repo-link

💬 Curious About Your Setup

Are you:

copying workflows between repos?
using reusable workflows heavily?
or building your own internal action libraries?

Would be interesting to hear how others are handling this.

I Got Tired of Rewriting Audit Logs in Spring Boot — So I Built nerv-audit

Ed Legaspi — Fri, 17 Apr 2026 07:18:23 +0000

Every backend system eventually hits this moment:

“Who changed this record?”
“What was the previous value?”
“When did it happen?”

Simple questions… until you actually need answers in production.

⚠️ Note: The core module is commercial, but you can explore the public modules and examples here:
👉 https://github.com/czetsuyatech/nerv-audit
👉 https://github.com/czetsuyatech/nerv-examples

The Problem

In most of my Spring Boot projects, I relied on Hibernate Envers.

It works—but in real systems, it starts to hurt:

You repeat the same setup across services
Audit queries are hard to read and maintain
Business-level audit logic gets scattered
Small mistakes become painful in production

After a few projects, I realized:

I wasn’t building features anymore—I was rebuilding audit infrastructure.

What I Actually Wanted

Not a replacement for Envers.

Just something that:

Standardizes audit handling
Reduces boilerplate
Makes queries readable
Works consistently across projects

So I Built nerv-audit

nerv-audit is a lightweight layer on top of Envers that focuses on developer experience.

Instead of wiring everything manually, you get a cleaner way to work with audit data.

Example

Without nerv-audit

You end up dealing with low-level Envers APIs and custom query logic.

With nerv-audit

service.getVerticalAudits(entity, criteria);

That’s it.

Want to see how it's implemented in a real project?
👉 https://github.com/czetsuyatech/nerv-audit
👉 https://github.com/czetsuyatech/nerv-examples

What It Improves

1. Consistent Audit Handling

Define audit behavior once, reuse everywhere.

@AuditedEntity
public class Order {
    private String status;
}

2. Cleaner Queries

No more complex Envers query construction.

You focus on:

What changed
When it changed

Not how to retrieve it.

3. Less Repetition

Across projects, the pattern is always the same.

nerv-audit abstracts that pattern so you don’t rewrite it every time.

Why I Built This

This came from real production work:

Multiple systems
Repeated audit requirements
Real incidents where audit data mattered

At some point, it made more sense to abstract the solution than keep rebuilding it.

About the Model (Transparency)

nerv-audit is not fully open-source.

There is a free tier you can use
Some advanced capabilities are part of a paid core

I chose this approach to:

Keep the project sustainable
Continue improving it over time
Focus on real-world use cases

Who This Is For

This might be useful if you:

Build Spring Boot applications
Use Hibernate Envers (or plan to)
Want a cleaner way to handle audit logs

I’d Like Your Input

How are you handling audit logs today?

Pure Envers?
Custom implementation?
Something else?

I’m especially interested in:

Pain points
Query challenges
Scaling issues

If you're working with Envers, try it out and let me know what breaks—or what works better.

🔗 Resources

Hands-On Coding: Exploring Hyperparameters for Programmers

Ed Legaspi — Thu, 07 Mar 2024 04:54:31 +0000

Introduction

In this article, we will explore different techniques for finding the optimal hyperparameter values from a given set of parameters in a grid. Particularly we will look at RandomizedSearchCV, GridSearchCV, and BayesSearchCV.

In this blog you will learn:

How to initialize the parameter grid.
How to find the optimal hyperparameters based on a given technique.
How to build a model (XGBClassifier) to use the hyperparameters.
How to score the performance of the model.

RandomizedSearchCV

param_grid = {
    "gamma": [0, 0.1, 0.2, 0.5, 1, 1.5, 2, 3, 6, 12, 20],
    "learning_rate": [0.01, 0.02, 0.03, 0.05, 0.1, 0.2, 0.3, 0.5, 0.7, 0.8],
    "max_depth": [1, 2, 3, 4, 5, 6, 8, 12],
    "n_estimators": [25, 50, 65, 80, 100, 115, 200]
}

grid_search = RandomizedSearchCV(estimator=classifier_0, param_distributions=param_grid, scoring=scoring)

GridSearchCV

param_grid = {
    "gamma": [0, 0.1, 0.2, 0.5, 1, 1.5, 2, 3, 6, 12, 20],
    "learning_rate": [0.01, 0.02, 0.03, 0.05, 0.1, 0.2, 0.3, 0.5, 0.7, 0.8],
    "max_depth": [2, 3, 4, 5, 6, 8, 12],
    "n_estimators": [25, 50, 65, 80, 100, 115, 200]
}

grid_search = GridSearchCV(estimator=classifier_0, param_grid=param_grid, scoring=scoring)

BayesSearchCV

param_bayes = {
    'gamma': Categorical(param_grid['gamma']),
    'learning_rate': Categorical(param_grid['learning_rate']),
    'max_depth': Categorical(param_grid['max_depth']),
    'n_estimators': Categorical(param_grid['n_estimators'])
}

grid_search = BayesSearchCV(estimator=classifier_0, search_spaces=param_bayes, scoring=scoring, n_jobs=-1, cv=10)

Finding the Best HyperParameters

best_model = grid_search.fit(X_train, y_train)
hyperparams = best_model.best_params_

Building and Scoring the Classifier using the HyperParameters

# Fitting the Model
ne = hyperparams['n_estimators']
lr = hyperparams['learning_rate']
md = hyperparams['max_depth']
gm = hyperparams['gamma']
print("Recommended Params >>", f"ne: {ne},", f"lr: {lr}", f"md: {md}", f"gm: {gm}")

# Build Classification Model
classifier_1 = XGBClassifier(
    base_score=0.5,
    colsample_bylevel=1,
    colsample_bynode=1,
    objective=objective,
    booster="gbtree",
    eval_metric=eval_metric_list,
    n_estimators=ne,
    learning_rate=lr,
    max_depth=md,
    gamma=gm,
    subsample=0.8,
    colsample_bytree=1,
    random_state=1
)

# Fit Model
eval_set = [(X_train, y_train)]
classifier_1.fit(
    X_train,
    y_train,
    eval_set=eval_set,
    verbose=False
)

# Get predictions for training data
train_yhat = classifier_1.predict(X_train)
print("Training Preds: \n", train_yhat[:5])

# Set K-Fold Cross Validation Levels
cv = RepeatedStratifiedKFold(n_splits=5, n_repeats=3, random_state=1)

# Training Results
train_results = cross_val_score(classifier_1, X_train, y_train, scoring=scoring, cv=cv, n_jobs=1)

# Brief Review of Training Results
print("Average Accuracy K-Fold: ", round(train_results.mean(), 2))
print("Std Deviation K-Fold: ", round(train_results.std(), 2))
print("Precision Score 0: ", round(precision_score(y_train, train_yhat, average=None)[0], 3))
print("Precision Score 1: ", round(precision_score(y_train, train_yhat, average=None)[1], 3))

Performance

Machine: Laptop
Processor: AMD Ryzen 7
OS: Windows
DataFrame Shape: (7282, 17)

Understanding How Scope Affects Values in Your Spring REST Controller

Ed Legaspi — Sat, 02 Mar 2024 03:33:59 +0000

Below we explore how a scope annotation affects an instance value in a Spring REST controller.

Each controller is annotated with scope.

@RestController
@Scope([SCOPE_VALUE])
public class XXXScopeController {}

How to Convert Vertically Stored Asset Data into Columnar Format for Cointegration Analysis

Ed Legaspi — Sat, 02 Mar 2024 01:12:16 +0000

Introduction

This piece of code fetches asset information from a table stored vertically.

Dependencies

Install the following package.

conda install pandas
conda install numpy as np
conda install mysql-connector-python
conda install sqlalchemy
conda install pymysql

Hands-on Coding

Connect to the database

def query_df(query):
    try: 
        engine_uri = f"mysql+pymysql://db_user:db_pass_123@localhost:3306/tradewise_pse"
        db_conn = create_engine(engine_uri)        
        df_result = pd.read_sql(query, db_conn)    
        return df_result

    except Exception as e:    
        print(str(e))

Fetching the Dataset

if not load_existing:
    sql_distinct_tickers = "select ticker from candlestick where event_time='2023-12-29' and ticker not like '^%%'"
    df_tickers = query_df(sql_distinct_tickers)

    df = pd.DataFrame(index=['event_time'])

    ### Get the candlesticks
    for ticker in df_tickers['ticker']:
        sql_ticker_col = "select event_time, close from candlestick where ticker='{0}'"
        df_temp = query_df(sql_ticker_col.format(ticker))
        df_temp.set_index('event_time', inplace=True)
        df_temp.rename(columns={'close': ticker}, inplace=True)        
        df = df.add(df_temp, fill_value=0)

    df.to_csv(file_name)

Load the dataset from file

df = pd.read_csv(file_name, index_col=0)
df.drop(index=df.index[-1],axis=0, inplace=True)

Drop NA

df.dropna(axis=1, inplace=True)

Print the Dataset

print(f"Shape: {df.shape}")
print(f"Null values: {df.isnull().values.any()}")
df

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6ypd0yfpe8ihrfvx58cl.png)

Learn to Incorporate Rolling Hurst Values into Your DataFrame

Ed Legaspi — Sat, 02 Mar 2024 01:08:30 +0000

The hurst function.

def hurst(ts, min_lag=1, max_lag=7):
    lags = range(min_lag, max_lag)
    tau = [np.sqrt(np.std(np.subtract(ts[lag:], ts[:-lag]))) for lag in lags]
    poly = np.polyfit(np.log(lags), np.log(tau), 1)
    return poly[0]*2.0

Adding to our DataFrame

The hurst value is computed with the last 14 close values.

df['Hurst'] = df['close'].rolling(14).apply(hurst, raw=True)
df[10:20]

Implementing Glowroot: A Hands-On Tech Review for Application Monitoring Mastery

Ed Legaspi — Mon, 05 Feb 2024 02:16:41 +0000

Introduction

In the realms of information technology and systems management, Application Performance Management (APM) involves monitoring and overseeing the performance and availability of software applications. APM aims to identify and diagnose intricate application performance issues to uphold a predefined level of service.

Glowroot is an open-source APM that facilitates a quicker resolution of application performance issues by helping us pinpoint the root causes. It supports applications running from Java 6 onwards.

Key Features

Response Time Breakdown Charts: Visualizes the breakdown of response times for better analysis.
Response Time Percentile Charts: Offers percentile charts to understand response time distribution.
SQL Capture and Aggregation: Captures and aggregates SQL queries for in-depth analysis.
Service Call Capture and Aggregation: Gathers and aggregates data on service calls for comprehensive insights.
MBean Attribute Capture and Charts: Monitors and charts MBean attributes for performance evaluation.
Configurable Alerting: Allows users to configure alerts based on specific criteria.
Historical Rollup: Provides historical data rollup at different intervals (1m, 5m, 30m, 4h) with configurable retention settings.
Full Support for Async Requests: Supports asynchronous requests that span multiple threads.
Responsive UI with Mobile Support: User-friendly and responsive interface with mobile support for accessibility.
Optional Central Collector: Offers the flexibility of an optional central collector for centralized data management.
Supports Multiple Application Servers: Wildfly, JBoss EAP, Tomcat, TomEE, Jetty, Glassfish, Payara, WebLogic, WebSphere

Central Collector

The central collector collects runtime information from the registered services and offers a GUI for easy viewing. https://github.com/glowroot/glowroot/wiki/Central-Collector-Installation

Installation

You can follow the steps above for running the GlowRoot central collector either as a standalone or as a docker image. For this section, I'll share how it can be run locally.
Here's my docker-compose file for running glowroot-central with cassandra. Override username, password, and contactPoints in glowroot-central.properties.



version: '3.8'

networks:

  tradewise-network:

services:

  cassandra:

    image: cassandra:latest

    container_name: cassandra

    restart: unless-stopped

    ports:

      - "9042:9042"

    networks:

      - tradewise-network

glowroot-central:

    image: glowroot/glowroot-central:0.14.1

    container_name: glowroot-central

    restart: unless-stopped

    volumes:

      - ./glowroot-central.properties:/usr/share/glowroot-central/glowroot-central.properties

    depends_on:

      - cassandra

    ports:

      - "4000:4000"

      - "8181:8181"

    networks:

      - tradewise-network

Instrumentation

There are 4 ways in which we can integrate GlowRoot into our services https://glowroot.org/instrumentation.html. For this exercise, we will focus on using the agent API.

Editing the pom.xml File

In our Spring Boot project's pom.xml file, add the GlowRoot agent configuration.



<plugin>

    <groupId>org.apache.maven.plugins</groupId>

    <artifactId>maven-resources-plugin</artifactId>

    <executions>

        <execution>

            <id>glowroot-plugins</id>

            <phase>validate</phase>

            <goals>

                <goal>copy-resources</goal>

            </goals>

            <configuration>

                <outputDirectory>target/glowroot-plugins/</outputDirectory>

                <resources>

                    <resource>

                        <directory>glowroot-plugins</directory>

                        <filtering>false</filtering>

                    </resource>

                </resources>

            </configuration>

        </execution>

    </executions>

</plugin>

<plugin>

    <groupId>org.apache.maven.plugins</groupId>

    <artifactId>maven-dependency-plugin</artifactId>

    <version>${maven-dependency-plugin.version}</version>

    <executions>

        <execution>

            <id>copy-glowroot-jar</id>

            <phase>prepare-package</phase>

            <goals>

                <goal>copy</goal>

            </goals>

        </execution>

    </executions>

    <configuration>

        <artifactItems>

            <artifactItem>

                <groupId>org.glowroot</groupId>

                <artifactId>glowroot-agent</artifactId>

                <version>${glowroot-agent.version}</version>

                <type>jar</type>

                <overWrite>false</overWrite>

                <outputDirectory>${project.build.directory}</outputDirectory>

                <destFileName>glowroot.jar</destFileName>

            </artifactItem>

        </artifactItems>

    </configuration>

</plugin>

Preparing the Dockerfile

We need to add the GlowRoot files in the docker image.



  
  
  Base Image


FROM eclipse-temurin:17-jdk-alpine

LABEL author=CzetsuyaTech

LABEL maintainer=CzetsuyaTech

  
  
  Configuration


WORKDIR /

RUN addgroup --system czetsuyatech && \

    adduser --system czetsuyatech --ingroup czetsuyatech && \

    mkdir -p /glowroot /glowroot/tmp /glowroot/logs /glowroot/plugins && \

    echo '{ "web": { "bindAddress": "0.0.0.0" } }' > /glowroot/admin.json && \

    chown czetsuyatech:czetsuyatech -R /glowroot && \

    chmod -R 777 /glowroot

USER czetsuyatech

ADD --chown=czetsuyatech:czetsuyatech target/glowroot.jar /glowroot

ADD --chown=czetsuyatech:czetsuyatech target/glowroot-plugins /glowroot/plugins

  
  
  Service


ADD --chown=czetsuyatech:czetsuyatech target/*.jar app.jar

  
  
  Start


ENV JAVA_JAR "/app.jar"

ENV JAVA_OTHERS "-Xshare:off"

ENV JAVA_OPTS ${JAVA_OPTS}

ENV JAVA_MEM ${JAVA_MEM}

RUN echo "exec java $JAVA_MEM $JAVA_OPTS $JAVA_OTHERS -jar $JAVA_JAR"

ENTRYPOINT exec java $JAVA_MEM $JAVA_OPTS $JAVA_OTHERS -jar $JAVA_JAR

Running the Spring Boot Service

To enable instrumentation in our instance, we need to specify the javaagent property. And to send information to the central collector we need to specify the central collector and give our instance an agent id.

JAVA_OPTS=-javaagent:glowroot/glowroot.jar -Dglowroot.collector.address=localhost:8181 -server -Dglowroot.agent.id=TradewiseAI

GUI

Usage

Transactions

Web

To assess our REST Endpoints' performance, we access the "Web" section. In the provided example:

By choosing "Response Time," we can identify which HttpRequests and JDBC Queries are taking longer in the REST Endpoints.
Opting for "Slow Traces" allows us to pinpoint the specific endpoint that consumes more time.
Selecting "Queries" reveals insights into the queries made, indicating that using the count query is more resource-intensive compared to the select query. This information aids in optimizing and refining the performance of REST Endpoints.

Background

To analyze our background performance, we navigate to the "Background" section. In the given example:

Choosing "Response Time" allows us to identify which Job and Hibernate Queries are consuming more time in the background processes.
Opting for "Slow Traces" reveals that some calls take more time, providing insights into areas that may require attention.
Selecting "Queries" and filtering by the select query, we observe that it is called more frequently and takes longer, particularly when filtered by status. This information helps in understanding and addressing potential bottlenecks in the background processes.

Startup

To assess our startup performance, we can utilize the "Startup" section. In the provided example:

By choosing "Response Time," we can identify which startup and filter init processes consume more time.
Opting for "Slow Traces" reveals the duration it takes for the context to initialize fully.
Selecting "Queries" provides insights into the database queries. Some queries will be more resource intensive, with fewer calls but longer duration. This information aids in pinpointing specific areas for optimization within the startup processes.

Errors

Web

To visualize errors in our REST endpoints, we can navigate to the "Web" section. In the following example:

Choosing "Error Messages" reveals errors of type XXXException.
Opting for "Error Traces" provides details on the errors.
Clicking on a specific error allows us to view the detailed trace, aiding in the understanding and resolution of the issue.

JVM

In our services' JVM, we can monitor and analyze memory status. This allows us to gain insights into the memory usage patterns, allocations, and overall health of the Java Virtual Machine, aiding in the effective management and optimization of our services.

MBeanTree

The MBeanTree functionality in Glowroot proves invaluable in monitoring instance creation. For instance, to track thread-related metrics and identify potential Thread Leaks, users can navigate to the java.lang section, specifically under Threading. This allows for a detailed examination of thread-related information, aiding in the identification and resolution of potential thread-related issues, such as Thread Leaks.

Recommendation

In a typical product infrastructure, Glowroot serves as our APM tool in each microservice. All microservices are instrumented to gather and transmit data to Glowroot, enhancing our understanding of system behavior. We've chosen Glowroot based on various criteria, including its license-free nature, alignment with the Java ecosystem, and straightforward instrumentation for microservices, ensuring a simple ramp-up and configuration process.

Navigating the Code: A Guide to Environment Variables, Configuration, and Feature Flags

Ed Legaspi — Thu, 14 Dec 2023 00:10:28 +0000

Determining the optimal location for storing essential information crucial for an application's functionality necessitates thoughtful planning. This guide aims to assist you in making informed decisions about where to store crucial data. Here, the term "application" encompasses any software created with code and deployed on various platforms and runtimes, irrespective of the underlying software architecture.

A fundamental principle is to avoid hard-coding any values within your application. Instead, adopt the practice of retrieving all configuration settings from a distinct storage system, separate from the deployment environment. This approach allows for seamless modifications to configuration settings even after the application has been deployed, eliminating the need for redeployment. This separation ensures greater flexibility and facilitates the adjustment of critical parameters without disrupting the operational state of your deployed application.

When considering the storage location for key/value pairs, it's crucial to evaluate the volatility of each pair—how frequently and by whom it might change. Reflect on the dynamic nature of the data and the responsibilities associated with its modification. This thoughtful approach will guide you in choosing an appropriate storage solution that aligns with the specific needs and characteristics of each key/value pair. By understanding the frequency and ownership of potential changes, you can make informed decisions that optimize the efficiency and maintainability of your data storage strategy.

Environment Variables

Environment variables, characterized by their infrequent changes, typically occur only once per deployment. Common examples include sensitive information like usernames and passwords for databases, which are often stored securely in a Vault. Additionally, environment variables encompass essential details required for the system's initialization, such as environment specifics and the connection details for the application configuration store, which hosts additional settings. By utilizing environment variables for these foundational aspects, you ensure a secure and stable system setup while centralizing critical configuration information.

Application Configuration

Application configuration, in contrast to environment variables, operates independently of deployments. It encompasses supplementary settings for the system that have the potential to change between deployments at runtime. This flexibility allows for real-time adjustments to the application's behavior and features, accommodating evolving requirements without the need for redeployment. By leveraging application configuration for these dynamic settings, you establish a modular and adaptable structure, enhancing the responsiveness of your system to changing runtime conditions.

Runtime User Settings

Runtime user settings represent the most volatile category, as users can alter any key/value pair at any given moment. Therefore, the system must be designed to accommodate this high level of dynamism. Options for handling such volatility include implementing robust real-time validation mechanisms and ensuring the integrity and security of user-initiated changes. Additionally, the system should provide an intuitive user interface for managing these settings, enabling seamless customization while maintaining overall system stability and security.

Here are three options for handling configuration updates:

Re-read Configuration All the Time: Continuously monitor and re-read the configuration, ensuring that the system remains up-to-date with any changes. This approach provides real-time responsiveness to modifications but may impose a continuous processing overhead.

Re-read Configuration at Set Intervals (e.g., Every 15 Minutes): Implement a periodic schedule to re-read the configuration at predefined intervals, such as every 15 minutes. This approach balances responsiveness with reduced processing overhead, making it suitable for scenarios where near-real-time updates are acceptable.

Receive Push Notifications When New Application Configuration Is Available: Set up a push notification mechanism to alert the system when new application configuration becomes available. This approach minimizes the need for continuous or scheduled re-reading, optimizing efficiency by updating the system only when changes occur. However, it requires a reliable notification infrastructure. Choosing among these options depends on the specific requirements of your system, considering factors such as the criticality of real-time updates, resource constraints, and the overall responsiveness desired for configuration changes.

Java XML Validation: How to Validate an XML Document against an XSD

Ed Legaspi — Sat, 01 Jul 2023 11:58:22 +0000

Introducing our Java XML Validation Project! Master the art of validating XML effortlessly against XSD in a Java environment. Gain hands-on experience, ensuring the integrity and conformity of your data.

1. Introduction

Introducing our Java XML Validation Project! Gain hands-on experience in validating XML documents against XSD with ease. This project serves as a practical guide, equipping you with the necessary knowledge and tools to ensure the integrity and conformity of your XML data in a Java environment. Discover the simplicity of our step-by-step approach, which walks you through the entire validation process. Master the art of validating XML effortlessly and unlock a new level of confidence in your data. Join us on this journey as we empower you to harness the power of XML validation in your Java projects.

2. Generating Java Classes from XSD

For this exercise, we will be using an XSD from w3schools https://www.w3schools.com/xml/schema_example.asp.

To be able to generate the Java classes from XSD, we will be using Eclipse Enterprise Edition. IntelliJ can also do it with the Jakarta plugin, but Eclipse performs better, especially when dealing with XJB files.

IntelliJ

Eclipse JAXB Classes Generator

Generated Classes

3. Dependencies

<dependency>
    <groupId>com.fasterxml.jackson.dataformat</groupId>
    <artifactId>jackson-dataformat-xml</artifactId>
</dependency>

<dependency>
    <groupId>jakarta.activation</groupId>
    <artifactId>jakarta.activation-api</artifactId>
    <version>2.1.1</version>
</dependency>
<dependency>
    <groupId>jakarta.xml.bind</groupId>
    <artifactId>jakarta.xml.bind-api</artifactId>
    <version>${jakarta.version}</version>
</dependency>
<dependency>
    <groupId>org.glassfish.jaxb</groupId>
    <artifactId>jaxb-runtime</artifactId>
    <version>${jakarta.version}</version>
    <scope>runtime</scope>
</dependency>

4. Core Classes

To run the validations and throw the appropriate exception or name of the tag where a constraint is violated, we will need the following classes.

4.1 ResourceResolver

To import an external XSD, for example, if we will be using the XML digital signature.

<xs:import namespace="http://www.w3.org/2000/09/xmldsig#" schemaLocation="xmldsig-core-schema.xsd"/>

public class ResourceResolver implements LSResourceResolver {

  private static final Logger LOGGER = LoggerFactory.getLogger(ResourceResolver.class);

  public LSInput resolveResource(String type, String namespaceURI, String publicId, String systemId, String baseURI) {

    // note: in this sample, the XSD's are expected to be in the root of the classpath
    InputStream resourceAsStream = this.getClass().getClassLoader().getResourceAsStream("xsd/" + systemId);
    return new Input(publicId, systemId, resourceAsStream);
  }

  static class Input implements LSInput {

    private String publicId;

    private String systemId;

    public String getStringData() {

      String textDataFromFile;

      try {
        BufferedReader bufferReader = new BufferedReader(new InputStreamReader(inputStream));
        StringBuilder stringBuilder = new StringBuilder();
        String eachStringLine;

        while ((eachStringLine = bufferReader.readLine()) != null) {
          stringBuilder.append(eachStringLine).append("\n");
        }
        textDataFromFile = stringBuilder.toString();

        return textDataFromFile;

      } catch (IOException e) {
        LOGGER.error("Fail reading from inputStream={}", e.getMessage());
        return null;
      }
    }
...

4.2 SaxErrorHandler

For us to be able to know the tag where a constraint exception is thrown, we need to define a custom exception that accepts an XMLStreamReader object where we can get the localName property.

public class SaxErrorHandler implements ErrorHandler {

  private XMLStreamReader reader;

  public SaxErrorHandler(XMLStreamReader reader) {
    this.reader = reader;
  }

  @Override
  public void error(SAXParseException e) {
    warning(e);
  }

  @Override
  public void fatalError(SAXParseException e) {
    warning(e);
  }

  @Override
  public void warning(SAXParseException e) {

    throw new XmlValidationException(reader.getLocalName());
  }
}

4.3 Miscellaneous Classes

We will also be needing utility classes for:

Creating a JAXBElement
Convert JAXBElement to XMLStreamReader
Defining the correct marshaller object

These classes are all available in the project.

4.4 XmlSchemaValidator Interface

And finally, the interface that pieces together all components to do the validation.

default void validateXMLSchema(String xsdPath, JAXBElement<?> xml) {

  Validator validator = null;
  try {
    SchemaFactory factory = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
    factory.setProperty(XMLConstants.ACCESS_EXTERNAL_DTD, "");
    factory.setProperty(XMLConstants.ACCESS_EXTERNAL_SCHEMA, "");
    factory.setResourceResolver(new ResourceResolver());

    Schema schema = factory.newSchema(ResourceUtils.getFile(xsdPath));
    validator = schema.newValidator();
    XMLStreamReader xmlStreamReader = asStreamReader(xml);

    ErrorHandler errorHandler = new SaxErrorHandler(xmlStreamReader);
    validator.setErrorHandler(errorHandler);

    validator.validate(new StAXSource(xmlStreamReader));

  } catch (IOException | SAXException | JAXBException | XMLStreamException e) {

    var xmlEx = getXmlValidationExceptionIfPresent(e);
    throw new InvalidXmlException(xmlEx.getLocalName(), e);
  }
}

5. Source Code / Git Repository

The complete source code for this project is available for my sponsors at https://github.com/czetsuyatech/java-xml-validation-by-xsd.

Sponsorship link: https://github.com/sponsors/czetsuya

Project Screenshot

Unlocking Google Calendar API with Keycloak: A Developer's Guide

Ed Legaspi — Sat, 20 May 2023 07:52:14 +0000

1. Overview

Unlock the power of Keycloak for seamless authentication and authorization in your applications. This comprehensive guide is designed for software developers who want to integrate Keycloak into their systems to enable secure user login and token exchange with Google.

By following step-by-step instructions and best practices, you'll learn how to leverage Keycloak's robust features to facilitate seamless authentication and obtain a Google token. With this token, you can effortlessly access the Google Calendar API and unlock a wealth of functionality for your application. Enhance user experience and streamline calendar integration - start implementing Keycloak and Google integration today.

You need prior knowledge with:

Google
Keycloak
Spring Boot

2. Google

Before we can do the integration with Keycloak we need to create a project in Google Console, create a credential and obtain OAuth client id and secret.

If you haven't done so, you can create a Google console account at https://cloud.google.com/cloud-console.

2.1 Creating the Google Cloud Project

At the top left of your Google Cloud Console, click the project and click New Project.

I call this project "Lab".

2.2 Create OAuth2 Client

The next step is to create the OAuth2 client credential that will give us the client id and secret. This combination will be used when we set up the Google Identity provider in Keycloak.

With the Lab project selected, find API & Services / Credentials in the menu.

Click Create Credentials with the following inputs:

Type: OAuth client ID
Application type: Web application
Name: Lab

There are two important entries in this section:

Authorized Javascript origins

This should be the URL where the request for login will come from.

Authorized redirect URIs

This entry is a common cause of problems if not properly set up. This is where Google will redirect the user after a successful login.

Some common redirect URIs.

Amazon Cognito: https://lab.auth.ap-southeast-1.amazoncognito.com/oauth2/idpresponse
Postman: https://www.getpostman.com/oauth2/callback
Keycloak broker: http://localhost:8080/realms/czetsuyatech/broker/google/endpoint
Keycloak token: http://localhost:8080/realms/czetsuyatech/protocol/openid-connect/token

When you have a redirect issue, this is one of the first things you may want to check.

This is how my Lab client looks like.

On the same page, you should be able to see the client id and secret. Take note because we will need them later.

2.3 Setup OAuth Consent Screen

This section will ask for several application-related settings. You can enter values as you see fit, but normally I set the following.

Non-sensitive scopes:

auth-userinfo-email
auth-userinfo-profile
openid Don't forget to add a test user. We will use it to login later.

3. Keycloak

For this exercise, we need to create a new Keycloak realm and client. We must enable authentication in the client.

3.1 Client

Enabling authentication will give us access to Keycloak's client and secret, which we will need later for testing. Take note of it.

We also need to download the Adapter config of our newly created client.

The downloaded config should look like this. Save it as we will use it in our Spring Boot application later.

{
  "realm": "czetsuyatech",
  "auth-server-url": "http://localhost:8080/",
  "ssl-required": "external",
  "resource": "web-front",
  "credentials": {
    "secret": "BxYWD11qCAW6ZybPTy6b9M8ej0thTxxx"
  },
  "confidential-port": 0
}

3.2 Identity Provider

Identity providers are third-party services that allow users to log in to Keycloak. In our example, we will do an authorization as well by exchanging the Keycloak token to Google to allow us to call Google API services such as Calendar and Gmail.

So login to Keycloak as admin, click Identity Providers on the left side, Click Add Provider, and select Google.

In the Client ID and secret fields, enter the values that we saved when we were configuring the Google client earlier.

Under Advance settings, change the value of Scopes to "email profile openid https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.events https://www.googleapis.com/auth/gmail.readonly", without double quotes. This will give us permission to call list endpoints from Calendar and Gmail APIs.

3.3 Permissions

In this section, we will give our client permission to exchange tokens with the newly created Google identity provider.

On the identity provider page, click the Permissions tab. Toggle Permissions enabled to ON. Under the Permission list, click token-exchange.

Set the Decision strategy to Unanimous. Click Save.

Next, we need to create the permission scope. At the top-left of the page, click Client details. It should redirect you to the Authorization tab. Open the Policies sub-tab. Create a new policy with the following values:

Type: Client
Name: google-token-exchange
Clients: web-front (the Keycloak client we created earlier)
Logic: Positive

Go back to your Google identity provider’s permission page and set the Policies to the one we just created.

The setup should now be ready to exchange tokens.

4. Testing

To test the exchange of tokens between Keycloak and Google, I have created a Postman collection where we can:

Authenticate a user
Exchange Keycloak to Google token

Before we proceed with the testing, we need to run a Keycloak instance. I have prepared a docker-compose to do that.

We need to authenticate our user, so create a new POST request in Postman and use OAuth2 authorization. Set the URL to http://localhost:8080/realms/czetsuyatech/protocol/openid-connect/token.

Be sure to set the client id and secret to the ones we saved earlier when we created the Keycloak client.

For the truncated values:

Callback URL: https://www.getpostman.com/oauth2/callback

Auth URL: http://localhost:8080/realms/czetsuyatech/protocol/openid-connect/auth

Access Token URL: http://localhost:8080/realms/czetsuyatech/protocol/openid-connect/token

Click Get New Access Token. It should redirect us to a Google login page, use the test email address that you added earlier when creating the Google client.

The next page will show you the scopes that will be permitted for your user. We defined this when we created the Google identity provider earlier.

Click Allow.

Copy the access token and paste it on a bearerToken variable. The succeeding requests will have Authorization Type = Bearer and will use this value.

The Body of the request must have the following URL encoded parameters:

Click Send. It should return with the following response.

This is the token that we can use to access Google APIs.

Obviously, we need to automate the process if we wanted this feature in our application. Thus, I have created a Spring project to do it.

5. Spring Project

This project demonstrates the token-exchange feature available on Keycloak. With this, we can exchange Keycloak for Google’s token, which we can use to call Google APIs.

Note: This project is only available for my sponsors https://github.com/sponsors/czetsuya.

5.1 Available Features

Get the bearer token from the request and store it in a Bean that can be autowired.
Exchange Keycloak token to Google, this will allow us to call Google APIs (Calendar, Gmail).
Use Spring exchange to provide abstraction in calling Google APIs.
Endpoints to list Calendar events and Gmail messages.

The heart of the application exchanges tokens between Keycloak and Google.

@Component
public class GoogleTokenExchange implements TokenExchange {

  @Override
  public String exchangeToken(String accessToken) {

    AuthzClient authzClient = AuthzClient.create();
    Configuration keycloakConfig = authzClient.getConfiguration();
    String baseUrl = authzClient.getServerConfiguration().getTokenEndpoint();

    RestTemplate restTemplate = new RestTemplate();

    HttpHeaders headers = new HttpHeaders();
    headers.add("Content-Type", MediaType.APPLICATION_FORM_URLENCODED.toString());
    headers.add("Accept", MediaType.APPLICATION_JSON.toString());

    MultiValueMap<String, String> requestBody = new LinkedMultiValueMap<>();
    requestBody.add("client_id", keycloakConfig.getResource());
    requestBody.add("client_secret", keycloakConfig.getCredentials().get("secret").toString());
    requestBody.add("grant_type", "urn:ietf:params:oauth:grant-type:token-exchange");
    requestBody.add("subject_token_type", "urn:ietf:params:oauth:token-type:access_token");
    requestBody.add("subject_token", accessToken);
    requestBody.add("requested_issuer", "google");

    HttpEntity formEntity = new HttpEntity<>(requestBody, headers);

    ResponseEntity<AccessTokenResponse> response = restTemplate.exchange(baseUrl, HttpMethod.POST, formEntity,
        AccessTokenResponse.class);

    return response.getBody().getToken();
  }
}

5.2 Testing

If you have subscribed as my sponsor, you will be given access to my repository and proceed with this testing.

The project provides two endpoints, to test calling list calendar events and Gmail messages from Google. Matching Postman requests are also available to make testing easier.

As we have done earlier, we need to get an access token from Keycloak and set it as bearerToken environment variable inside Postman.

Get Calendar Events Response

Get Gmail Messages

6. Source Code

All the resources used in this article and demo are available on the GitHub repository https://github.com/czetsuyatech/auth-exchange.

Spring project source code
Docker/compose file
Keycloak realm
Postman collection for testing

7. References

Implementing X509 Certificate Validation in Java: A Step-by-Step Guide

Ed Legaspi — Sun, 07 May 2023 05:09:15 +0000

Unlock the power of secure communication with Java! Learn how to implement X509 certificate validation simply and straightforwardly, step-by-step.

Overview

An X.509 certificate is a digital certificate used to verify a particular entity's identity, such as a website or an individual. X.509 certificates are widely used in various applications, including secure communication protocols like HTTPS, SSL, and TLS.

An X.509 certificate contains several pieces of information, including the identity of the entity being verified, the public key that is associated with that entity, and various other pieces of metadata that provide additional information about the certificate itself.

Importance

One of the key benefits of X.509 certificates is that they allow entities to authenticate themselves to other parties securely and reliably. This can help to prevent various types of attacks, including man-in-the-middle attacks, where an attacker intercepts and modifies communication between two parties to steal sensitive information.

Overall, X.509 certificates play a critical role in modern security infrastructure and are essential to many different types of secure communication protocols.

Requirements

You must have the following installed on your computer.

Git
Maven
IDE (IntellIJ / Visual Studio)
Java 17+

Dependencies

This project uses the following dependencies.

bcpkix-jdk15on - certificate revocation check
spring-boot-starter-test (for testing)
lombok (for logging)
Certificates from https://www.digicert.com/kb/digicert-root-certificates.htm

Project Code

The certificate validation process.

To implement the validation, we will introduce a bean where we can define the:

Certificate that we are validating
The pem file that we can cross-check #1
Root certificate to check if the certificate is already revoked

Let's examine the code.
The CertificateBundle class is just a simple Java bean.

@Getter
@Setter
@Builder
public class CertificateBundle {

  // Certificate extracted from the message
  private X509Certificate certificate;

  // Certificate loaded from the application must match the certificate
  private X509Certificate confirmationCertificate;

  // RootCertificate of the certificate
  private X509Certificate rootCertificate;
}

To validate the certificate expiration, we need to extract the X509Certificate object and perform a time comparison against the value of getNotAfter(). Here, we're making sure that the current date is greater than the certificate's expiry date.

Date expiresOn = cert.getNotAfter();
Date now = new Date();

if (now.getTime() > expiresOn.getTime()) {
  throw new ExpiredCertificateException();
}

Comparing digital signature against a PEM file. In most fintech applications, there is a need to sign the message before sending it to another service. Upon receiving the message, the server needs to extract the public certificate embedded in it and compare it to a PEM file. This PEM file is a public key of the private key certificate used to sign the message.

boolean match = Arrays.equals(cert1.getPublicKey().getEncoded(),
    cert2.getPublicKey().getEncoded());

if (!match) {
  throw new MismatchCertificateException("Embedded certificate does not match the given PEM");
}

And finally, we do the revocation check. This process allows us to know whether a website's certificate is trustworthy or not. It uses the root certificate that we used for signing as the trust anchor.

try {
  List<X509Certificate> certs = Collections.singletonList(cb.getCertificate());
  CertificateFactory cf = CertificateFactory.getInstance("X509");
  CertPath cp = cf.generateCertPath(certs);

  // load the root CA cb
  X509Certificate rootCACert = cb.getRootCertificate();

  // init trusted certs
  TrustAnchor ta = new TrustAnchor(rootCACert, null);
  Set<TrustAnchor> trustedCerts = new HashSet<>();
  trustedCerts.add(ta);

  // init PKIX parameters
  PKIXParameters params = new PKIXParameters(trustedCerts);

  // load the CRL
  params.addCertStore(CertStore.getInstance("Collection",
      new CollectionCertStoreParameters(getX509Crls(cf, getCrl(cb.getCertificate())))));

  // perform validation
  CertPathValidator cpv = CertPathValidator.getInstance("PKIX");
  PKIXCertPathValidatorResult cpvResult = (PKIXCertPathValidatorResult) cpv.validate(cp,
      params);
  X509Certificate trustedCert = cpvResult.getTrustAnchor().getTrustedCert();

  if (trustedCert == null) {
    log.error("Trusted certificate not found");
    throw new CertificateException("Trusted certificate not found");

  } else {
    log.debug("Trusted CA DN = " + trustedCert.getSubjectX500Principal());
  }

} catch (InvalidAlgorithmParameterException | java.security.cert.CertificateException |
         CRLException |
         NoSuchAlgorithmException |
         CertPathValidatorException |
         IOException e) {
  throw new RevokedCertificateException(e);
}