Home

Home - Java Server Interface (JSI)

Welcome to the Java Server Interface (JSI) documentation! This framework provides a highly modular, protocol-agnostic foundation for building custom server implementations in Java.

Before use

Warning

DISCLAIMER - Educational purpose

This project is currently built for educational purpose, and is NOT production-ready. Any deployment of code based on this package is at your own risk, and highly discouraged. A lot of important features, such as security checks and safety measures for privacy, are not in the scope of this project for now.

Further implementations of this framework may include production-ready solutions. See the Changelog for a full list of official releases.

Table of Contents

Getting Started

• Getting Started - Quick start guide with installation and basic examples
• Architecture Overview - Understanding the layered design philosophy

Core Framework

• Core Abstractions - The foundational Server, Client, Request, and Response interfaces
• ConnectionServer - TCP connection handling with Java's Socket API

Protocol Implementations

• HTTP Server - Annotation-based routing and static file serving
• Database Server - Query execution, storage engines, and MySQL implementation

Advanced Topics

• Extensibility Guide - Creating custom protocols and storage engines
• Design Patterns - SOLID principles applied in JSI

What is JSI?

Java Server Interface is a teaching framework that demonstrates how to build server applications from first principles. Instead of hiding complexity behind abstractions, JSI exposes the building blocks and shows you how they fit together.

Key Features

• Layered Architecture: Three distinct abstraction layers (Generic Server → Transport → Protocol)
• Maximum Modularity: Every component is independently replaceable
• Protocol Agnostic: Build HTTP, database, game servers, or anything custom
• Zero Dependencies: Pure Java with no external libraries
• Educational: Clear code structure designed for learning

Architecture at a Glance

┌─────────────────────────────────────┐
│  Layer 3: Protocol Layer            │  ← HttpServer, DatabaseServer
│  (Application Logic)                │     Your custom protocol here
├─────────────────────────────────────┤
│  Layer 2: Transport Layer           │  ← ConnectionServer
│  (TCP/Socket Management)            │     Thread-per-client model
├─────────────────────────────────────┤
│  Layer 1: Server Foundation         │  ← Server (abstract base)
│  (Lifecycle & Hooks)                │     start(), stop(), hooks
└─────────────────────────────────────┘

Each layer can be used independently or combined for maximum flexibility.

Quick Example

import jsi.connection.http.*;

public class MyWebServer extends HttpServer {
    public MyWebServer(int port) { super(port); }
    
    @Route(path = "/")
    public HttpResponse home(HttpRequest request) {
        return createHtmlResponse(HttpResponseType.OK, 
            "<h1>Hello, World!</h1>");
    }
    
    public static void main(String[] args) {
        new MyWebServer(8080).start();
    }
}

Documentation Structure

This wiki is organized to guide you through JSI systematically:

1. Start with Getting Started for installation and first examples
2. Read Architecture Overview to understand the design philosophy
3. Explore Core Abstractions to see the foundational building blocks
4. Dive into specific implementations: HTTP Server or Database Server
5. Learn to extend: Extensibility Guide shows how to build custom protocols

Cross-References

Throughout this wiki, you'll find links to:

• Source code in the jsi/ directory
• Related wiki pages for deeper dives into specific topics
• Example implementations in the repository

License

JSI is licensed under CC BY-NC-SA 4.0 - free for educational and non-commercial use. See LICENSE for details.

Contributing

Found an issue or want to improve the documentation? Contributions are welcome! This framework is designed to be easy to understand and extend.

---

New to JSI? → Start with Getting Started
Want to understand the design? → Read Architecture Overview
Ready to build? → Check out HTTP Server or Database Server