Microsphere Java Framework

Welcome to the Microsphere Java Framework

Table of Contents

• Introduction
• Features
• Modules
• Prerequisites
• Getting Started
• Maven
• Gradle
• Usage Examples
• Building from Source
• Documentation
• Contributing
• Getting Help
• Maintainers
• License

Introduction

Microsphere Java Framework is a foundational library that serves as the backbone for the MicroSphere ecosystem. It provides a rich set of reusable components, utilities, and annotation processing capabilities that address common challenges in Java development. Whether you're building enterprise applications, microservices, or standalone Java tools, this framework offers the building blocks you need to accelerate development and maintain consistency across your projects.

The framework is designed with modularity at its core, allowing you to use only the components you need while keeping your application lightweight and efficient. It's built on standard Java APIs and integrates seamlessly with popular frameworks like Spring, making it a versatile addition to any Java developer's toolkit.

Features

• String & Collection Utilities — Null-safe helpers for strings, arrays, lists, sets, maps, and deques
• Reflection Utilities — Simplified access to fields, methods, constructors, and generic type arguments
• Type Conversion — Extensible Converter SPI with built-in converters for standard Java types (primitives, collections, Duration, InputStream, and more)
• Event Dispatching — Lightweight EventDispatcher with sequential and parallel execution modes
• Class Loading & Artifact Detection — Utilities for classpath scanning, JAR introspection, and Maven/module artifact resolution
• Networking — Custom URLStreamHandler and URL utility helpers
• I/O — Enhanced file, stream, and charset utilities, plus a file-watch service
• Concurrency — Delegating executor wrappers and custom thread factory
• Configuration Properties — SPI-based property loading with annotation-driven generation
• Annotation Processing — Compile-time processor for @ConfigurationProperty metadata generation
• Language Model — Components and utilities for the Java Language Model API
• JDK Tools — Helpers bridging the Java compiler and annotation processing tool APIs
• Testing Support — Base classes and utilities for JUnit 5-based unit tests

Modules

The framework is organized into several focused modules:

Module	Artifact ID	Purpose
microsphere-java-annotations	microsphere-java-annotations	Common annotations (@Nullable, @Nonnull, @Immutable, @Experimental, @Since, …)
microsphere-java-core	microsphere-java-core	Core utilities: strings, collections, reflection, I/O, concurrency, events, type conversion, and more
microsphere-lang-model	microsphere-lang-model	Components and utilities for the Java Language Model API
microsphere-jdk-tools	microsphere-jdk-tools	Helpers for Java compiler and JDK tool APIs
microsphere-annotation-processor	microsphere-annotation-processor	Compile-time annotation processor for @ConfigurationProperty metadata generation
microsphere-java-test	microsphere-java-test	Models and utilities for JUnit 5-based testing
microsphere-java-dependencies	microsphere-java-dependencies	BOM (Bill of Materials) managing dependency versions across the project
microsphere-java-parent	microsphere-java-parent	Parent POM with shared build configuration

Prerequisites

• Java 8, 11, 17, 21, or 25 (all actively tested in CI)
• Maven 3.6+ (or use the included mvnw/mvnw.cmd wrapper)

Getting Started

Maven

Add the BOM to your pom.xml to manage versions centrally:

<dependencyManagement>
  <dependencies>
      <dependency>
          <groupId>io.github.microsphere-projects</groupId>
          <artifactId>microsphere-java-dependencies</artifactId>
          <version>${microsphere-java.version}</version>
          <type>pom</type>
          <scope>import</scope>
      </dependency>
  </dependencies>
</dependencyManagement>

Then declare only the modules you need:

<dependencies>
  <!-- Core utilities -->
  <dependency>
      <groupId>io.github.microsphere-projects</groupId>
      <artifactId>microsphere-java-core</artifactId>
  </dependency>

  <!-- Compile-time annotation processor (optional) -->
  <dependency>
      <groupId>io.github.microsphere-projects</groupId>
      <artifactId>microsphere-annotation-processor</artifactId>
      <optional>true</optional>
  </dependency>
</dependencies>

Gradle

dependencies {
  implementation platform("io.github.microsphere-projects:microsphere-java-dependencies:${microsphereJavaVersion}")

  implementation "io.github.microsphere-projects:microsphere-java-core"
  annotationProcessor "io.github.microsphere-projects:microsphere-annotation-processor"
}

Usage Examples

String Utilities

import io.microsphere.util.StringUtils;

StringUtils.isBlank(null);      // true
StringUtils.isBlank("");        // true
StringUtils.isBlank("  ");      // true
StringUtils.isBlank("Hello");   // false

Collection Utilities

import io.microsphere.collection.CollectionUtils;

CollectionUtils.isEmpty(null);              // true
CollectionUtils.isEmpty(List.of());         // true
CollectionUtils.isEmpty(List.of("item"));   // false

Reflection Utilities

import io.microsphere.reflect.FieldUtils;
import io.microsphere.reflect.MethodUtils;

// Read a private field value without boilerplate
Object value = FieldUtils.getFieldValue(myObject, "fieldName");

// Find all declared methods matching a predicate
Set<Method> methods = MethodUtils.findMethods(MyClass.class, m -> m.isAnnotationPresent(Override.class));

Type Conversion

import io.microsphere.convert.Converters;

// Convert a String to Integer
Integer number = Converters.convert("42", Integer.class);

// Convert a String to a List of Strings
List<String> items = Converters.convert("a,b,c", List.class);

Event Dispatching

import io.microsphere.event.EventDispatcher;
import io.microsphere.event.EventListener;

// Sequential (direct) dispatcher
EventDispatcher dispatcher = EventDispatcher.newDefault();
dispatcher.addEventListener((EventListener<MyEvent>) event -> System.out.println("Received: " + event));
dispatcher.dispatch(new MyEvent("hello"));

// Parallel dispatcher with a custom thread pool
Executor executor = Executors.newFixedThreadPool(4);
EventDispatcher parallel = EventDispatcher.parallel(executor);
parallel.addEventListener(myListener);
parallel.dispatch(new MyEvent("world"));

Artifact / Version Detection

import io.microsphere.util.Version;

// Detect the runtime version of a library from its JAR manifest
Version springVersion = Version.ofVersion(org.springframework.core.SpringVersion.class);
boolean isModern = springVersion.isGreaterThanOrEqualTo("6.0.0");

Building from Source

You don't need to build from source to use the library — published artifacts are available on Maven Central. Clone and build only if you want to try the latest unreleased code or contribute to the project.

git clone https://github.com/microsphere-projects/microsphere-java.git
cd microsphere-java

Linux / macOS

./mvnw package

Windows

mvnw.cmd package

To run the full test suite with coverage:

./mvnw test --activate-profiles test,coverage

Documentation

Resource	Link
User Guide	user-guide.md
AI-powered docs (DeepWiki)
Ask Zread
Wiki	GitHub Wiki
Release Notes	release-notes.md

JavaDoc

• microsphere-java-annotations
• microsphere-java-core
• microsphere-lang-model
• microsphere-jdk-tools
• microsphere-annotation-processor
• microsphere-java-test

Contributing

Contributions are welcome! To get started:

1. Fork the repository and create a feature branch.
2. Make your changes with tests.
3. Ensure all tests pass: ./mvnw test
4. Submit a pull request against the main branch.

Please read CODE_OF_CONDUCT.md before contributing.

Getting Help

• Bug reports & feature requests — Open an issue (search existing issues first)
• Questions & discussions — GitHub Discussions
• AI-powered documentation — DeepWiki

Maintainers

Name	Role	Contact
Mercy Ma (mercyblitz)	Lead Architect & Developer	mercyblitz@gmail.com

License

The Microsphere Java Framework is released under the Apache License 2.0.