Sinobu

Sinobu is not obsolete framework but utility. It acts as an extremely condensed facade for common development tasks, designed to be intuitive and efficient.

Weighing in at approximately 120 KB with zero external dependencies, Sinobu prioritizes lightweight deployment and avoids dependency conflicts. Despite its small size, its various operations are engineered for high performance, often rivaling or exceeding competing specialized libraries (see Benchmark).

This library aims to simplify and consolidate functionalities frequently encountered in real-world projects, making them easier and safer to use. Key areas covered include:

• Dependency Injection
• Object lifecycle management
• Property based object modeling
• HTTP(S) Client
• Web Socket Client
• JSON
• HTML (Tag Soup Tolerant)
• XML
• Reactive Programming (Rx)
• Asynchronous & Parallel processing
• Multilingualization
• Template Engine (Mustache Syntax)
• Dynamic Extensibility / Plugin System
• Object persistence
• Logging (Garbage-Less)
• Virtual Job Scheduler
• Task Scheduling (Cron Syntax)

Sinobu adheres to core principles ensuring ease of use, safety, and efficiency.

Sinobu's design philosophy is guided by several core principles, aimed at delivering a powerful yet minimalistic development experience:

🚀 Lightweight

Sinobu maintains a minimal footprint (approximately 120 KB) with absolutely no external dependencies. This design choice results in faster startup times, significantly smaller deployment packages, and complete avoidance of dependency conflicts — an ideal fit for embedded systems, microservices, or any environment where lean execution is key.

⚡ High Performance

Performance is at the heart of every component. Internal operations are implemented with a focus on low memory overhead and high throughput. Most allocations are short-lived and garbage-friendly, which makes Sinobu suitable even for latency-sensitive systems. See the benchmark section for in-depth comparative results.

✨ Simplicity

The API surface is deliberately kept minimal and expressive. Developers can often accomplish complex tasks using a few static methods on the I facade class. This reduces boilerplate, encourages readability, and lowers the learning curve for new contributors.

void access() {
    I.http("http://xxx.com/", XML.class).to(html -> {
        String name = html.find("#user").text();
    });
}

🖥️ Multifunction

Despite its small size, Sinobu is packed with a wide array of capabilities. These features are not isolated; they are thoughtfully composed so that they work together seamlessly, forming a cohesive and versatile toolkit.

♻️ Reactivity

Sinobu embraces reactivity as a foundation for composing asynchronous, event-driven logic. The Signal class acts as a reactive primitive that allows values to propagate through a declarative flow of transformations, observers, and combinators.

🛡️ Type Safety

All APIs are designed to leverage Java’s static type system to the fullest. This promotes correctness, allows for confident refactoring, and minimizes the risk of runtime errors.

It is probably easiest to use a build tool such as Maven or Gradle. Replace `` with the desired version number.

<dependency>
     <groupId>com.github.teletha</groupId>
     <artifactId>sinobu</artifactId>
     <version>VERSION<version>
 </dependency>

Sinobu is an open-source project hosted on GitHub. Contributions, bug reports, and feature requests are welcome.

• Repository:https://github.com/teletha/sinobu
• Issues: Please report bugs or suggest features via GitHub Issues.
• Contributions: Pull requests are welcome! Please ensure code style consistency and include tests where applicable.

In Sinobu, lifestyle refers to the way an object is created and managed, corresponding to the scope in terms of DI containers such as SpringFramework and Guice, but without the process of registering with the container or destroying the object.

In order to define a lifestyle, you need to implement Lifestyle interface. This interface is essentially equivalent to Callable. It is called when container requests the specific type. It makes the following 3 decisions:

1. Which class to instantiate actually.
2. How to instantiate it.
3. How to manage the instances.

Sinobu defines two lifestyles that are frequently used. One is the prototype pattern and the other is the singleton pattern.

To apply a non-prototype lifestyle, you need to configure each class individually. There are two ways to do this.

Dependency Injection (DI) is a mechanism that solves various problems related to component dependencies in 'a nice way'. Component dependency refers to the relationship from upper layer to lower layer, such as Controller → Service → Repository in a general layered architecture. 'A nice way' means that the framework will take care of the problem without the developer having to work hard manually.

In modern Java application development, DI is an almost indispensable mechanism. The detailed explanation of the DI concept is left to another website.

The most common form of dependency injection is for a class to request its dependencies through its constructor. This ensures the client is always in a valid state, since it cannot be instantiated without its necessary dependencies.

public void objectInjection() {
    class Injectable {
    }

    class Injection {
        private Injectable value;

        Injection(Injectable injectable) {
            this.value = injectable;
        }
    }

    assert I.make(Injection.class).value != null;
}

In the context of Java programming, a 'property' generally refers to the characteristics or attributes of a class or object. These properties define the state of an object and encapsulate the data associated with it. In Java, properties are typically represented as private fields within a class, with corresponding getter and setter methods to access and modify their values.

Here's an example of a Java class with properties:

class Person {
    private String name; // Property: name

    private int age; // Property: age

    // Constructor
    public Person(String name, int age) {
        this.name = name;
        this.age = age;
    }

    // Getter method for name property
    public String getName() {
        return name;
    }

    // Setter method for name property
    public void setName(String name) {
        this.name = name;
    }

    // Getter method for age property
    public int getAge() {
        return age;
    }

    // Setter method for age property
    public void setAge(int age) {
        this.age = age;
    }
}

In this example, the Person class has two properties: name and age. These properties are declared as private fields within the class to encapsulate their implementation details and prevent direct access from outside the class. Getter and setter methods (getName(), setName(), getAge(), setAge()) are provided to allow controlled access to these properties.

Using properties in Java classes promotes encapsulation, which is one of the fundamental principles of object-oriented programming (OOP). Encapsulation hides the internal state of an object and exposes only the necessary interfaces for interacting with it, improving code maintainability, reusability, and flexibility.

In Sinobu, model is a set of properties. If a class you define has properties, it is already a model.

Models can be retrieved from a class using the kiss.Model#of(Class) method, but there should not be many situations where the end user needs to retrieve the model directly.

Model model = Model.of(Person.class);

In Sinobu, a property refers to a value accessible by name and defined by a field or method. Property name is arbitrary.

Normally, end users do not use Model API to manipulate or traverse properties. The following is mainly required for framework and library production.

Models and properties can be used to get, set and monitor property values.

import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import org.junit.jupiter.api.Test;
import kiss.Extensible;
import kiss.I;

public class ExtensionTest {

    /**
     * This is extension point.
     */
    interface Codec<T> extends Extensible {

        String encode(T value);
    }

    /**
     * This is extension with LocalDate key.
     */
    class LocalDateCodec implements Codec<LocalDate> {

        public String encode(LocalDate value) {
            return DateTimeFormatter.ISO_DATE.format(value);
        }
    }

    /**
     * Load all extensions once at application's entry point.
     */
    static {
        I.load(ExtensionTest.class);
    }

    /**
     * User code.
     */
    @Test
    void usage() {
        // find extension by type
        Codec<LocalDate> codec = I.find(Codec.class, LocalDate.class);
        assert codec.encode(LocalDate.of(2022, 11, 11)).equals("2022-11-11");
    }
}

Sinobu has a general-purpose plug-in mechanism for extending application functions. An extensible place is called Extension Point, and its substance is a type (interface or class) marked with the Extensible interface.

We give a definition of Extension Point like the following.

• It implements Extensible interface directly.

interface ThisIsExtensionPoint extends Extensible {
}

class ThisIsAlsoExtensionPoint implements Extensible {
    // This class is both Extension Point and Extension.
}

interface ThisIsNotExtensionPoint extends ThisIsExtensionPoint {
}

In the usage example, Codec is the extension point that converts any object to a string representation.

interface Codec<T> extends Extensible {
    String encode(T value);
}

We give a definition of Extension like the following.

• It implements any Extension Point or is Extension Point itself.
• It must be concrete class and has a suitable constructor for Sinobu (see also I#make(Class) method).

class ThisIsExtension implements Extensible {
    // This class is both Extension Point and Extension.
}

class ThisIsAlsoExtension extends ThisIsExtension {
    // But not Extension Point.
}

class ThisIsNotExtension extends ThisIsExtension {

    public ThisIsNotExtension(NotInjectable object) {
        // because of invalid constructor
    }
}

In the usage example, LocalDateCodec is the extension that is special implementation for LocalDate.

class LocalDateCodec implements Codec<LocalDate> {

    public String encode(LocalDate value) {
        return DateTimeFormatter.ISO_DATE.format(value);
    }
}

You can provide Extension Key for each Extensions by using parameter.

interface ExtensionPointWithKey<K> extends Extensible {
}

class ExtensionWithStringKey implements ExtensionPointWithKey<String> {
    // Associate this Extension with String class.
}

class ExtensionWithListKey implements ExtensionPointWithKey<List> {
    // Associate this Extension with List interface.
}

The key makes easy finding an Extension you need (see also I#find(Class, Class)).

void findExtensionByKey() {
    assert I.find(ExtensionPointWithKey.class, String.class) instanceof ExtensionWithStringKey;
}

All extensions are not recognized automatically, you have to load them explicitly using I#load(Class).

class ExtensionUser {
    static {
        I.load(ExtensionUser.class);
    }

    // write your code
}

class ApplicationMain {
    public static void main(String[] args) {
        I.load(ApplicationMain.class);

        // start your application
    }
}

JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write and easy for machines to parse and generate. It has become a de facto standard for data exchange on the web, especially for APIs. (JSON on Wikipedia)

Sinobu offers built-in support for JSON processing with an emphasis on performance, usability, and integration with Java object models.

✅ Simplicity

Offering straightforward APIs for parsing JSON from various sources and serializing Java objects into JSON.

void read() {
    I.json("""
                {
                "name": "Misa",
                "age": 21
            }
            """);
}

🧩 Model-Centric

Seamlessly mapping JSON data to and from Java objects (POJOs or Records) based on Sinobu's property model, reducing boilerplate.

public void writeRecord() {
    record Person(String name, int age) {
    }

    Person person = new Person("Joe", 23);
    String json = I.write(person);

    assertSame(json, """
            {
                "age": 23,
                "name": "Joe"
            }
            """);
}

👉 Direct Manipulation

Parsed JSON can be navigated and mutated via a DOM-like tree model using the JSON class. Access elements by key or index, modify values, or restructure nodes with intuitive syntax.

public void readValue() {
    JSON json = I.json("""
            {
                "number" : 10,
                "bool" : false
            }
            """);

    assert json.get(int.class, "number") == 10;
    assert json.get(boolean.class, "bool") == false;
}

You can read JSON from strings, files, and various inputs. All data will be expanded into memory in a tree format. It is not a streaming format, so please be careful when parsing very large JSON.

You can write JSON from property-based model.

public void writeRecord() {
    record Person(String name, int age) {
    }

    Person person = new Person("Joe", 23);
    String json = I.write(person);

    assertSame(json, """
            {
                "age": 23,
                "name": "Joe"
            }
            """);
}

Sinobu provides functionality for handling HTML and XML documents. It uses a built-in, lenient parser (often called a tag soup parser) that can handle malformed HTML, similar to how web browsers do. The core class for this is XML, which offers a jQuery-like API for traversing and manipulating the document structure.

🍜 Tag Soup Friendly

Handles malformed HTML gracefully, tolerating missing or mismatched tags commonly found in real-world web content.

public void caseInconsistencyLowerUpper() {
    XML root = parseAsHTML("<div>crazy</DIV>");

    assert root.find("div").size() == 1;
}

🎯 CSS Selector Power

Leverages CSS selectors for efficient and flexible element selection, similar to JavaScript libraries like jQuery.

public void tag() {
    XML xml = I.xml("""
            <root>
                <h1></h1>
                <article/>
                <article></article>
            </root>
            """);

    assert xml.find("h1").size() == 1;
    assert xml.find("article").size() == 2;
}

🛠️ jQuery-Like API

Provides a fluent and chainable API for easy DOM manipulation, inspired by the familiar jQuery syntax.

public void append() {
    XML root = I.xml("<m><Q><P/></Q><Q><P/></Q></m>");

    assert root.find("Q").append("<R/><R/>").find("R").size() == 4;
    assert root.find("Q > R").size() == 4;
    assert root.find("Q > R:first-child").size() == 0;
}

🌐 XML Ready

Supports not only HTML but also XML documents, providing a unified interface for structured data processing.

You can parse HTML/XML from various sources using the I class utility methods. Sinobu automatically detects whether the input is a URL, file path, or raw string. The parser is designed to be tolerant of errors and can handle common issues found in real-world HTML, such as missing tags or incorrect nesting. This makes it suitable for scraping or processing potentially messy markup.

• I#xml(String)
• I#xml(java.nio.file.Path)
• I#xml(java.io.InputStream)
• I#xml(java.io.Reader)
• I#xml(Node)

public void htmlLiteral() {
    XML root = I.xml("<html/>");

    assert root.size() == 1;
    assert root.name() == "html";
}

And can parse the invalid structure.

public void caseInconsistencyLowerUpper() {
    XML root = parseAsHTML("<div>crazy</DIV>");

    assert root.find("div").size() == 1;
}

public void slipOut() {
    XML root = parseAsHTML("<a><b>crazy</a></b>");

    assert root.find("a").text().equals("crazy");
    assert root.find("b").text().equals("crazy");
}

You can serialize the XML structure back into a string representation or write it to an Appendable (like Writer or StringBuilder). Sinobu offers both compact and formatted output options.

The XML#toString() method provides a compact string representation without extra formatting.

public void format() {
    XML root = I.xml("<root><child/><child/></root>");

    assert root.toString().equals(normalize("""
            <root>
                <child/>
                <child/>
            </root>
            """));
}

The XML#to(Appendable, String, String...) method allows for pretty-printing the XML structure with configurable indentation for improved readability. You can specify the indentation string (e.g., a tab character \t or spaces).

public void specialIndent() {
    StringBuilder out = new StringBuilder();
    I.xml("<root><child><nested/></child></root>").to(out, "*");

    assert out.toString().equals(normalize("""
            <root>
            *<child>
            **<nested/>
            *</child>
            </root>
            """));
}

You can also specify tag names that should be treated as inline elements (no line breaks around them), preserving the original formatting for elements like <span> or <a>.

public void inlineElement() {
    StringBuilder out = new StringBuilder();
    I.xml("<root><inline/></root>").to(out, "\t", "inline");

    assert out.toString().equals("<root><inline/></root>");
}

By using the special prefix `` before a tag name, you can also specify tags that should always be treated as non-empty elements (always have a closing tag like <script></script>, even if empty).

public void nonEmptyElement() {
    StringBuilder out = new StringBuilder();
    I.xml("<root/>").to(out, "\t", "&root");

    assert out.toString().equals("<root></root>");
}

By passing null as the indent character, formatting (indentation and line breaks) is disabled, similar to toString() but writing to an Appendable.

public void withoutFormat() {
    StringBuilder out = new StringBuilder();
    I.xml("<root><child/></root>").to(out, null);

    assert out.toString().equals("<root><child/></root>");
}

Sinobu leverages CSS selectors for querying elements within the document structure using the XML#find(String) method. This provides a powerful and familiar way to select nodes, similar to JavaScript's document.querySelectorAll. This library supports many standard CSS3 selectors and includes some useful extensions.

public void tag() {
    XML xml = I.xml("""
            <root>
                <h1></h1>
                <article/>
                <article></article>
            </root>
            """);

    assert xml.find("h1").size() == 1;
    assert xml.find("article").size() == 2;
}

public void attribute() {
    XML xml = I.xml("""
            <m>
                <e A='one' B='one'/>
                <e A='two' B='two'/>
            </m>
            """);

    assert xml.find("[A]").size() == 2;
    assert xml.find("[A=one]").size() == 1;
}

public void clazz() {
    XML xml = I.xml("""
            <root>
                <p class="on"/>
                <p class="on large"/>
                <p class=""/>
                <p no-class-attr="on"/>
            </root>
            """);

    assert xml.find(".on").size() == 2;
    assert xml.find(".large").size() == 1;
    assert xml.find(".on.large").size() == 1;
}

public void mix() {
    XML xml = I.xml("""
            <m>
                <ok/>
                <ok>
                    <ok id="not"/>
                    <not>
                        <ok/>
                    </not>
                </ok>
            </m>
            """);

    assert xml.find("ok").size() == 4;
    assert xml.find("not ok").size() == 1;
    assert xml.find("ok > ok").size() == 1;
}

The XML object provides a fluent API, similar to jQuery, for modifying the document structure.

Important: These manipulation methods modify the underlying DOM structure directly; the XML object itself is mutable in this regard. Explore the nested classes for specific manipulation categories.

Navigate the DOM tree relative to the currently selected elements. Most traversal methods return a new XML object containing the resulting elements, allowing for method chaining without modifying the original selection (unless intended). Explore the nested classes for specific traversal categories.

import org.junit.jupiter.api.Test;
import kiss.I;

class MustacheTest {

    String template = "She is {name}, {age} years old.";

    record Person(String name, int age) {
    }

    @Test
    void use() {
        Person data = new Person("Takina Inoue", 16);
        assert I.express(template, data).equals("She is Takina Inoue, 16 years old.");
    }
}

Mustache can be used for HTML, config files, source code - anything. It works by expanding tags in a template using values provided in a hash or object. We call it "logic-less" because there are no if statements, else clauses, or for loops. Instead there are only tags. Some tags are replaced with a value, some nothing, and others a series of values.

Java19 does not yet have a language built-in template syntax. Therefore, Sinobu provides a mechanism to parse Mustache syntax instead.

Sinobu provides a concise and powerful API for making HTTP(S) requests and handling WebSocket connections, built on top of Java's standard HttpClient. It simplifies common tasks like handling responses, content negotiation, and asynchronous processing using Signal.

💡 Fluent API

Simple static methods in I enable common HTTP GET requests and WebSocket connections without boilerplate.

🔧 Standard Integration

Built on java.net.http.HttpRequest.Builder, allowing fine-grained control over headers, methods, and request bodies.

🔄 Automatic Content Handling

Response bodies are automatically converted to suitable types (String, JSON, XML, beans, etc.), with gzip/deflate decompression handled transparently.

⚙️ Reactive Streams

Both HTTP and WebSocket messages are streamed asynchronously via Signal, promoting non-blocking and reactive design.

🔌 WebSocket Support

Provides a simple API for establishing WebSocket connections and handling incoming/outgoing messages with ease.

Making HTTP requests and processing responses is streamlined using I#http methods. You can make simple GET requests with just a URL or use Java's java.net.http.HttpRequest.Builder for full control over the request details (method, headers, body, etc.). Responses are delivered asynchronously as a Signal.

// Simple GET request, response as String
 I.http("https://example.com/data", String.class).to(html -> {
     System.out.println("Fetched HTML: " + html.substring(0, 100) + "...");
 });

 // POST request with custom headers, response mapped to a User object
 HttpRequest.Builder request = HttpRequest.newBuilder(URI.create("https://api.example.com/users"))
         .POST(HttpRequest.BodyPublishers.ofString("{\"name\":\"John\"}"))
         .header("Content-Type", "application/json")
         .header("Authorization", "Bearer your_token");

 I.http(request, User.class).to(user -> {
     System.out.println("Created user: " + user.getName());
 });

 // Synchronous execution (blocks until response or error)
 try {
     String result = I.http("https://example.com", String.class).waitForTerminate().to().exact();
     System.out.println("Synchronous result: " + result);
 } catch (Exception e) {
     System.err.println("Request failed: " + e);
 }

Errors during the request (network issues, HTTP status codes >= 400) are propagated through the I#signalError(Throwable) channel.

The I#http methods automatically convert the response body to the specified Java type. This simplifies handling different content types.

Supported types include:

• String: The response body is read as a UTF-8 string.
• InputStream: Provides direct access to the (potentially decompressed) response body stream. You are responsible for closing this stream.
• HttpResponse: Provides the full `HttpResponse ` object, giving access to status code, headers, and the body stream.
• XML: Parses the response body as XML/HTML into an XML object.
• JSON: Parses the response body as JSON into a JSON object.
• Any JSON-mappable Bean/Record: Parses the JSON response body and maps it to an instance of the specified class using Sinobu's object mapping capabilities.

Automatic Decompression: Sinobu automatically inspects the Content-Encoding response header. If the content is compressed using gzip or deflate, it will be decompressed transparently before being passed to the type converter or returned as an InputStream.

Sinobu provides a simple way to establish WebSocket connections using I#http(String, Consumer, HttpClient...). Communication is handled reactively using Signal for incoming messages and a WebSocket object for sending messages.

Disposable connection = I.http("wss://echo.websocket.org", ws -> {
     // Connection opened callback - send a message
     System.out.println("WebSocket Opened!");
     ws.sendText("Hello WebSocket!", true);

     // You can send more messages later using the 'ws' object
     // ws.sendText("Another message", true);

     // Request more messages from the server (default is 1)
     // ws.request(5); // Request up to 5 more messages

 }).to(message -> { // onNext - received message
     System.out.println("Received: " + message);
     // ws.sendText("Got it: " + message, true); // Example: Echo back
 }, error -> { // onError - connection error
     System.err.println("WebSocket Error: " + error);
 }, () -> { // onComplete - connection closed
     System.out.println("WebSocket Closed");
 });

 // To close the connection later:
 // connection.dispose();

The Consumer<WebSocket> open lambda is executed once the connection is successfully established. The WebSocket instance provided allows you to send messages (sendText, sendBinary, sendPing, etc.) and manage the connection state (request, sendClose).

Incoming messages are received through the Signal returned by I.http.

Automatic Decompression: Similar to HTTP responses, Sinobu automatically handles WebSocket messages compressed with the standard permessage-deflate extension (commonly used for gzip/deflate over WebSockets), ensuring you receive decompressed text messages in the Signal.

While I#http methods use a default, shared HttpClient instance internally, you can provide your own configured HttpClient instance(s) as optional trailing arguments to any of the I.http methods. This allows customization of timeouts, proxies, SSL contexts, authenticators, cookie handlers, etc., using the standard Java HttpClient.Builder API.

HttpClient customClient = HttpClient.newBuilder()
      .connectTimeout(Duration.ofSeconds(10))
      .followRedirects(HttpClient.Redirect.NORMAL)
      // .proxy(...)
      // .sslContext(...)
      // .authenticator(...)
      // .cookieHandler(...)
      .build();

 // Use the custom client for the request
 I.http("https://example.com", String.class, customClient).to(response -> { ... });

 // Use it for WebSocket too
 I.http("wss://example.com/ws", ws -> { ... }, customClient).to(message -> { ... });

If multiple clients are passed, the first non-null one is used. If none are provided or all are null, the default client (I.client) is used.

The concept of ReactiveX is very well summarized on the official website, so it is better to read there.

• ReactiveX
• Observable
• Operators

The Signal class that implements the Reactive Pattern. This class provides methods for subscribing to the Signal as well as delegate methods to the various observers.

In Reactive Pattern an observer subscribes to a Signal. Then that observer reacts to whatever item or sequence of items the Signal emits. This pattern facilitates concurrent operations because it does not need to block while waiting for the Signal to emit objects, but instead it creates a sentry in the form of an observer that stands ready to react appropriately at whatever future time the Signal does so.

The subscribe method is how you connect an Observer to a Signal. Your Observer implements some subset of the following methods:

• Observer#accept(Object) - A Signal calls this method whenever the Signal emits an item. This method takes as a parameter the item emitted by the Signal.
• Observer#error(Throwable) - A Signal calls this method to indicate that it has failed to generate the expected data or has encountered some other error. It will not make further calls to Observer#error(Throwable) or Observer#complete(). The Observer#error(Throwable) method takes as its parameter an indication of what caused the error.
• Observer#complete() - A Signal calls this method after it has called Observer#accept(Object) for the final time, if it has not encountered any errors.

By the terms of the Signal contract, it may call Observer#accept(Object) zero or more times, and then may follow those calls with a call to either Observer#complete() or Observer#error(Throwable) but not both, which will be its last call. By convention, in this document, calls to Observer#accept(Object) are usually called “emissions” of items, whereas calls to Observer#complete() or Observer#error(Throwable) are called “notifications.”

Scheduling tasks to run at specific times or intervals is a common requirement. Sinobu provides a simple yet powerful mechanism for this, based on the well-known Cron expression format. It integrates seamlessly with Sinobu's reactive streams.

✨ Simple API

Schedule tasks with a single static method call: I#schedule(String). No complex setup or scheduler instances needed.

void scheduling() {
    I.schedule(() -> {
        // execute your job immediately on job thread
    });

    I.schedule("0 0 * * *").to(() -> {
        // execute your job regularly on job thread
    });
}

🗓️ Cron Expression Syntax

Define complex schedules using the standard Cron format, specifying minutes, hours, days, months, and weekdays. Sinobu supports standard fields and special characters like *, /, -, ,, L, W, #, ?, and the randomizer R.

🔄 Reactive Integration

Scheduled events are delivered as a Signal, allowing you to use reactive operators for flow control (e.g., take), transformation, and lifecycle management (Disposable).

You can use I#schedule(String) to schedule jobs by cron expression.

void scheduling() {
    I.schedule("0 0 * * *").to(() -> {
        // execute your job
    });
}

To stop continuous task scheduling, execute the return value Disposable.

void stopScheduling() {
    Disposable disposer = I.schedule("0 0 * * *").to(() -> {
        // execute your job
    });

    // stop scheduling
    disposer.dispose();
}

Since the return value is Signal, it is easy to stop after five executions.

void stopSchedulingAfter5Executions() {
    I.schedule("0 0 * * *").take(5).to(() -> {
        // execute your job
    });
}

A Cron expression consists of five or six fields, separated by spaces. From left to right, they represent seconds, minutes, hours, days, months, and days of the week, with seconds being optional. The possible values for each field are as follows, and some special function characters can also be used.

If you want to specify 9:00 every morning, it would look like this

0 0 9 * * *

Seconds field is optional and can be omitted.

0 9 * * *

In addition to numbers, each field can contain characters with special meanings and functions.

Complex time specifications can be made by combining several special characters as follows

Sinobu provides a minimalist, high-performance logging library designed with an emphasis on garbage-less operation and zero-boilerplate code. It is especially well-suited for high-throughput applications where every microsecond and memory allocation matters.

🚀 No Boilerplate

Logging is as simple as calling a static method like I#info(Object). Therefore, there’s no need to create logger instances per class. This approach dramatically reduces code clutter and eliminates repetitive logger setup.

void log() {
    I.info("Hello Logging");
}

♻️ Garbage Less

Many logging libraries create temporary objects (log events, strings, byte arrays, etc.) each time they output logs, causing GC latency; Sinobu tackles this problem head on and does not create new objects unless you explicitly request stack trace.

⚡ High Performance

Sinobu is engineered for speed. Its optimized encoding, buffer reuse, and minimal synchronization mean it can outperform many mainstream logging libraries. Even under heavy logging loads, it maintains consistent performance with minimal CPU and memory impact. Check benchmark.

Logging is performed via static methods such as I#info(Object) or I#info(String, Object). These methods support various input types:

• Object - Use Object#toString() representation as message.
• Supplier - Delaying the construction of message avoids extra processing when the log level prevents writing.
• Throwable - A message and a stack trace back to the cause are written.

void basic() {
    I.trace("Write your message");
}

void lazyEvaluation() {
    I.debug(() -> "Delaying the construction of message.");
}

void throwable() {
    try {
        mayBeThrowError();
    } catch (Exception e) {
        I.error("Write message and stack trace");
        I.error(e);
    }
}

Most methods come in two forms:

• Without category - logs to the default system category.
• With category - the first argument specifies the log category, allowing fine-grained control.

void categorized() {
    I.debug("Write message in system category");
    I.warn("database", "Write message in database category");
}

Logging behavior can be configured via environment variables (I#env(String) Configuration keys follow a specific pattern to allow both fine-grained and global control.

Resolution Order

When any environment variable is required, configuration values are resolved in the following order:

1. Look for category.property (e.g. system.file)
2. If not found, look for *.property (e.g. *.file)
3. If still not found, use the built-in default (e.g. Level#WARNING)

Sinobu provides a simple mechanism for persisting the state of objects using the Storable interface. This allows objects to save their properties to JSON file and restore them later, making it easy to maintain application state across restarts.

🦤 Interface Based

Implement the Storable interface on your class to enable persistence.

class Data implements Storable<Data> {

    public int property;
}

⚒️ Saving Data

The Storable#store() method saves the current state of the object's properties to file. (check property)

void save() {
    Data data = new Data();
    data.property = 10;

    data.store(); // save data to file
}

⚒️ Restoring Data

The Storable#restore() method restores the object's properties from file (check property). If the file doesn't exist or an error occurs during reading/parsing, the operation typically fails silently, leaving the object in its current state (often default values).

void restore() {
    Data other = new Data();
    other.restore(); // load data from file

    assert other.property == 10;
}

Normally all properties are eligible for preservation, but there are several ways to make explicit which properties you do not want to preserve.

If the property is defined by field, add the transient modifier to the field declaration.

class TransientField implements Storable<TransientField> {

    public transient int unstorableProperty;
}

If the property is defined by method, add java.beans.Transient annotation. (You only need to add it to either the setter or the getter)

class TransientMethod implements Storable<TransientMethod> {

    private int value;

    @java.beans.Transient
    public int getUnstorableProperty() {
        return value;
    }

    public void setUnstorableProperty(int value) {
        this.value = value;
    }
}

Instead of manually calling Storable#store() every time a change occurs, you can be configured to save their state automatically when their properties change. This is achieved using the Storable#auto() method.

Since monitoring the values of arbitrary properties would be prohibitively expensive, value detection is only possible for properties defined by Variable.

Calling Storable#auto() instance monitors its (and nested) properties. When a change is detected, it schedules a save operation. By default, this operation is debounced (typically waiting 1 second after the last change) to avoid excessive writes during rapid changes.

void autoSave() {
    class Data implements Storable<Data> {
        public final Variable<String> name = Variable.empty();
    }

    Data data = new Data();
    data.auto(); // enable auto-save

    data.name.set("Misa"); // save after 1 sec
}

Calling Disposable#dispose() on the returned object will stop the automatic saving process for that instance.

void stopAutoSave() {
    class Data implements Storable<Data> {
        public final Variable<String> name = Variable.empty();
    }

    Data data = new Data();
    Disposable stopper = data.auto();

    stopper.dispose(); // stop auto-save
}

By default, persistence file is stored in a directory named .preferences within the application's working directory. The filename is derived from the fully qualified class name of the storable object, ending with .json. (e.g., .preferences/com.example.MyAppSettings.json).

This location can be customized in two main ways:

This section presents benchmark results comparing the performance of Sinobu with other popular libraries for various common tasks. The goal is to provide objective data on Sinobu's efficiency in terms of execution speed, memory allocation, and garbage collection impact.

🔬 Methodology

Benchmarks were conducted using a custom benchmarking framework inspired by principles similar to JMH (Java Microbenchmark Harness). This includes dedicated warm-up phases to allow for JIT compilation and stabilization, and techniques like blackholes to prevent dead code elimination and ensure accurate measurement of the intended operations. Each major benchmark suite (e.g., JSON, Logging) is typically run in a separate JVM process to ensure isolation and prevent interference between tests. Benchmarks were run under specific hardware and software configurations. The results shown in the graphs typically represent throughput (operations per second), execution time, or memory allocation. Interpretation depends on the specific metric shown in each graph (e.g. higher throughput is better, lower time/allocation is better).

📈 Comparisons and Metrics

Comparisons are often made against well-known libraries relevant to each domain (e.g., Jackson/Gson for JSON, Logback/Log4j2 for Logging). The latest stable versions of competitor libraries available at the time of measurement were typically used.

Operations specific to each domain (e.g., JSON parsing, logging throughput, template rendering) are performed to measure key performance indicators such as:

• Execution speed (throughput or time per operation)
• Garbage collection load (allocation rate)
• Memory consumption (footprint, retained size - though less frequently shown in graphs)

Lower values for time and allocation generally indicate better performance, while higher values for throughput are better.

⚠️ Disclaimer

Benchmark results can vary depending on the execution environment (JVM version, OS, hardware). These results should be considered indicative rather than absolute measures of performance in all scenarios.

Compares the performance of Sinobu's logging framework against other logging libraries. Focuses on throughput (operations per second) and garbage generation under different scenarios, highlighting Sinobu's garbage-less design advantage.

Compares Sinobu's JSON processing capabilities (parsing, traversing, mapping) against other well-known Java JSON libraries like FastJSON, Jackson, and Gson. Results highlight performance across various operations and document sizes.

• Sinobu
• FastJSON
• Jackson
• GSON

Compares the performance of Sinobu's HTML/XML parser (including tag soup handling) against other Java parsers. Focuses on parsing speed and memory usage for typical web documents.

Compares the performance of Sinobu's Mustache template engine implementation. Measures rendering speed and overhead for template processing with context data.