Skip to content

Getting Started

Jump to bottom
Luca_Previ0o edited this page Dec 10, 2025 · 2 revisions

Getting Started with JSI

This guide will help you get up and running with Java Server Interface quickly.

Prerequisites

  • Java 11 or higher (tested with Java 17+)
  • Basic understanding of Java and OOP concepts
  • Familiarity with client-server architecture (helpful but not required)

Installation

Clone the Repository

Use the following command to clone the GitHub repository inside the jsi root package folder:

git clone https://github.com/LucaPrevi0o/JavaServerInterface.git jsi
cd jsi

Build the Project

JSI includes a custom build script (jmake) that works without Maven or Gradle:

# Compile all sources
./jmake

# Compile and run the default Main class
./jmake run

# Compile and run a specific class
./jmake run -n MyServer

# Build an executable JAR
./jmake jar

# Clean build artifacts
./jmake clean

Your First Server

Example 1: Simple HTTP Server

Create a file MyFirstServer.java:

import jsi.connection.http.*;
import jsi.connection.http.response.HttpResponseType;

public class MyFirstServer extends HttpServer {
    
    public MyFirstServer(int port) {
        super(port);
    }
    
    @Route(path = "/")
    public HttpResponse home(HttpRequest request) {
        String html = "<html><body>" +
                      "<h1>Welcome to JSI!</h1>" +
                      "<p>Your first server is running.</p>" +
                      "</body></html>";
        return createHtmlResponse(HttpResponseType.OK, html);
    }
    
    @Route(path = "/about")
    public HttpResponse about(HttpRequest request) {
        String html = "<html><body>" +
                      "<h1>About</h1>" +
                      "<p>Built with Java Server Interface</p>" +
                      "</body></html>";
        return createHtmlResponse(HttpResponseType.OK, html);
    }
    
    public static void main(String[] args) {
        System.out.println("Starting server on port 8080...");
        new MyFirstServer(8080).start();
    }
}

Compile and run:

./jmake run -n MyFirstServer

Access in browser:

  • http://localhost:8080/ - Home page
  • http://localhost:8080/about - About page

Example 2: Serving Static Files

JSI can serve static HTML files directly:

import jsi.connection.http.*;
import jsi.connection.http.response.HttpResponseType;

public class StaticFileServer extends HttpServer {
    
    public StaticFileServer(int port) {
        super(port);
    }
    
    // Serve static file automatically
    @Route(path = "/", staticResource = "static/index.html")
    public HttpResponse home(HttpRequest request) {
        return null; // File served automatically
    }
    
    // Mix static and dynamic routes
    @Route(path = "/api/status")
    public HttpResponse status(HttpRequest request) {
        String json = "{\"status\": \"running\", \"version\": \"1.0\"}";
        return createJsonResponse(HttpResponseType.OK, json);
    }
    
    public static void main(String[] args) {
        new StaticFileServer(8080).start();
    }
}

Example 3: Database Server

Create a simple database server with JSON persistence:

import jsi.connection.database.*;
import jsi.connection.database.json.JsonStorageEngine;
import jsi.connection.database.mysql.MySqlServer;

public class MyDatabaseServer {
    public static void main(String[] args) throws Exception {
        // Create storage engine with path to database directory
        StorageEngine storage = new JsonStorageEngine("./database");
        
        // Create database engine
        DatabaseEngine engine = new DatabaseEngine(storage);
        
        // Start MySQL-compatible server on port 3306
        DatabaseServer server = new MySqlServer(3306, engine);
        
        System.out.println("Database server started on port 3306");
        server.start();
    }
}

Next Steps

Now that you have a basic server running, explore:

  1. Architecture Overview - Understand how JSI layers work together
  2. Core Abstractions - Learn about Server, Client, Request, Response
  3. HTTP Server - Deep dive into HTTP routing and request handling
  4. Database Server - Build database-backed applications
  5. Extensibility Guide - Create your own protocols

Common Patterns

Adding Request Parameters

@Route(path = "/greet")
public HttpResponse greet(HttpRequest request) {
    String name = (String) request.getParameter("name");
    if (name == null) name = "Guest";
    
    String html = "<h1>Hello, " + name + "!</h1>";
    return createHtmlResponse(HttpResponseType.OK, html);
}

Access with: http://localhost:8080/greet?name=Alice

Error Handling

@Route(path = "/divide")
public HttpResponse divide(HttpRequest request) {
    try {
        int a = Integer.parseInt((String) request.getParameter("a"));
        int b = Integer.parseInt((String) request.getParameter("b"));
        int result = a / b;
        
        return createHtmlResponse(HttpResponseType.OK, 
            "<h1>Result: " + result + "</h1>");
    } catch (Exception e) {
        return createHtmlResponse(HttpResponseType.BAD_REQUEST, 
            "<h1>Error: Invalid parameters</h1>");
    }
}

Custom 404 Handler

Override handleNotFound() in your server class:

@Override
protected HttpResponse handleNotFound(Request request) {
    String html = "<html><body>" +
                  "<h1>404 - Page Not Found</h1>" +
                  "<p>The page you're looking for doesn't exist.</p>" +
                  "<a href='/'>Go Home</a>" +
                  "</body></html>";
    return createHtmlResponse(HttpResponseType.NOT_FOUND, html);
}

Troubleshooting

Port Already in Use

If you get a "port already in use" error, either:

  1. Stop the existing process using that port
  2. Change the port number in your constructor

Files Not Found

Ensure static file paths are relative to the project root:

project/
├── static/
│   └── index.html
└── MyServer.java

Use path: static/index.html

Compilation Errors

Make sure you're in the project root directory when running ./jmake.

Related Documentation

Questions? Check the main README or explore the source code.

JSI - Java Server Interface | Educational Server Framework | Zero Dependencies

Home • Getting Started • Architecture • Source Code

Made for learning | Report Issues • Discussions

Last updated: December 2025 | JSI v1.0

Home

Documentation

Getting Started

Architecture

Components

Quick Links

By Topic

HTTP Development

Database Development

Custom Protocols

Clone this wiki locally