Documentation

Panaragan is a lightweight Java framework for web apps, APIs, templates, sessions, validation, database access, scheduled jobs, email, and static assets inside one JAR.

<dependency>
    <groupId>com.panaragan</groupId>
    <artifactId>panaragan</artifactId>
    <version>1.0.0</version>
</dependency>

app.name=Panaragan
app.version=1.0.0
app.port=8005
app.base_url=https://your-domain.example/
template.path=views
template.minify=true
session.mode=MEMORY

Quick Start

Use the starter generator on the home page, or create the minimal structure manually.

your-app/
|-- pom.xml
|-- src/main/java/app/App.java
|-- src/main/java/app/controllers/Home.java
`-- src/main/resources/
    |-- .env
    `-- views/frontend/home.html

App.java

package app;

import app.controllers.Home;
import com.panaragan.*;

public class App extends Server {
    public static void main(final String[] args) { new App().run(); }
    public void boot(final Routers routers) {
        routers.get("/", Home::index);
        routers.get("/json", Home::json);
    }
}

Home.java

package app.controllers;

import com.panaragan.*;

public class Home {
    public static void index(final Request request, final Response response) {
        response.send("Hello World");
    }
    public static void json(final Request request, final Response response) {
        final PJsonObject json = new PJsonObject()
                .set("username", request.getQuery("username"))
                .set("password", request.getQuery("password"));
        response.send(json);
    }
}

mvn -q package
java -jar target/*.jar
curl https://your-domain.example/
curl "https://your-domain.example/json?username=imam&password=secret"

Features

Core

Application entrypoint extends Server. Panaragan calls these methods in order: boot at startup, then accept, route authorization, controller, respond, and error only on failures.

public class App extends Server {
    public void boot(final Routers routers) { routers.get("/", Home::index); }
    public void accept(final Request request, final Response response) {
        final String user = request.getSession("user");
        if(user!=null) { request.setPayload("user", PJsonObject.parse(user)); }
    }
    public boolean authorize(final Request request, final Response response, final String authority) {
        final Object user = request.getPayload("user");
        if("guest".equals(authority)&&user!=null) { response.redirect("dashboard"); }
        if(!"guest".equals(authority)&&user==null) { response.redirect("login", "callback_url", request.getFullUrl()); }
        return true;
    }
    public void respond(final Request request, final Response response) {
        response.addHeader("X-Frame-Options", "DENY");
        response.addHeader("X-Content-Type-Options", "nosniff");
    }
    public void error(final Request request, final Response response, final String reason) {
        response.renderView("error", new ParamsObject().set("error_reason", reason));
    }
}

Cache

Use cache for hot values and repeated expensive work. QueryBuilder read methods also use framework-level coalescing so concurrent identical SELECT calls can share one database execution.

Cache.set("profile:1", user, 30000);
final Object user = Cache.get("profile:1");
Cache.delete("profile:1");
Cache.clear();

For large request bursts, place the cache check before slow IO and invalidate cache when writes change the related data.

Config

Configuration is loaded from .env. Keep runtime values there and read them through Config so the same JAR can run in local, staging, and production.

app.name=Panaragan
app.version=1.0.0
app.port=8005
app.base_url=https://your-domain.example/
template.path=views
template.minify=true

final String appName = Config.get("app.name");
final int port = Config.get("app.port", 8005);
final boolean gzip = Config.get("response.gzip", false);

Cookies

Cookies are read from the request and written through response headers. Keep secure flags consistent with your deployed domain and protocol.

final String theme = request.getCookie("theme", "light");
response.setCookie("theme=dark; Path=/; Max-Age=31536000; SameSite=Lax");
response.setCookie("token=; Path=/; Max-Age=0; HttpOnly; SameSite=Lax");

CSRF

Use @csrf in POST forms. Validation methods check the token before processing field rules.

<form method="post" action="{{ url('profile/update') }}">
    @csrf
    <input name="name">
    <button type="submit">Save</button>
</form>

csrf.name=csrf-token
csrf.expired=3600

Router

Register routes in boot. Dynamic params use {id}. Authority strings are passed to authorize.

routers.get("/", Home::index);
routers.post("/login-submit", Login::submit, "guest");
routers.getOrPost("/api/users/list", Users::list, "user");
routers.get("/users/edit/{id}", Users::edit, "users_edit");
routers.group("/admin", "dashboard", admin -> {
    admin.get("/", Dashboard::index);
    admin.get("users", Users::index, "users_list");
});

Read route params with request.getParam("id"). Use response.redirect, response.send, response.renderView, or response.empty as terminal responses.

Request / Response

final String q = request.getQuery("q", "");
final int page = request.getPostOrQuery("page", 1);
final String token = request.getHeader("Authorization", "");
final UploadFile file = request.getFile("avatar");
final String user = request.getSession("user");

response.send("Hello World");
response.send(new PJsonObject().set("ok", true));
response.renderView("frontend.home", data);
response.redirect("login");
response.empty(204, "No Content");
response.send(file, "report.pdf", "application/pdf");

Database

Enable one JDBC URL in .env. Panaragan supports MySQL, PostgreSQL, SQL Server, and Oracle through the JDBC driver on the classpath.

db.max_pool_size=10
db.reconnect=5
db.url=jdbc:postgresql://db.example.internal:5432/app
db.username=postgres
db.password=secret

final ParamsObject data = new ParamsObject()
        .set("username", request.getPost("username"))
        .set("email", request.getPost("email"))
        .set("name", request.getPost("name"));

final Object id = Database.insert("users", data);
final boolean updated = Database.update("users", data, "id = ?", id);
final boolean deleted = Database.delete("users", "id = ?", id);

Datatable

Datatable builds server-side JSON for DataTables-style requests. Select explicit columns, add filters, and render computed action columns without exposing raw SQL to the browser.

final Datatable datatable = new Datatable("SELECT id, username, email, status FROM users")
        .where("status = ?", "ACTIVE")
        .addNumbering("no")
        .add("edit_url", (column, value, row) -> Url.to("users/edit/"+row.get("id")));

response.send(datatable.results(request));

Use where, orWhere, like, whereIn, between, add, edit, and sum to shape the response.

Query Builder

Use QueryBuilder for SELECT and pagination. Repeated identical SELECT queries are coalesced/cached by the framework path that serves query results.

final QueryBuilder qb = new QueryBuilder()
        .select("id", "name", "username", "email")
        .from("users")
        .where("status = ?", "ACTIVE")
        .orderBy("id", "DESC")
        .limit(50, 0);

final PJsonArray rows = qb.results();
final PJsonObject row = qb.row();
final int total = qb.count();
response.send(new PJsonObject().set("data", rows).set("total", total));

Template

Views live in src/main/resources/views. Dotted names map to folders, for example frontend.home maps to views/frontend/home.html.

final ParamsObject data = new ParamsObject()
        .set("page_title", "Home")
        .set("username", "imam");
response.renderView("frontend.home", data);

@extends('layouts.frontend')
@section('body')
    <h1>{{ page_title }}</h1>
    <p>Welcome, {{ username }}</p>
@endsection

Session

Session can run in memory, storage, database, custom store, or disabled. Use it for authenticated user context, flash messages, and CSRF storage.

session.key=SESSION_ID
session.expired=3600
session.path=/
session.same_site=Lax
session.mode=MEMORY
csrf.name=csrf-token
csrf.expired=3600

response.setSession("user", user.toString());
final String user = request.getSession("user");
response.deleteSession("user");

<form method="post" action="/profile/update">
    @csrf
    <input name="name">
</form>

Validation

final ParamsString rules = new ParamsString()
        .set("username", "required")
        .set("email", "required|email")
        .set("avatar", "uploaded");

if(!request.validatePost(rules)) { response.redirectBack(request.getPosts()); }

final UploadFile avatar = request.getFile("avatar");
if(avatar!=null) {
    final boolean saved = avatar.saveIfContentTypeMatch("avatars/user.jpg", new String[] { "image/jpeg", "image/png" });
    if(!saved) { response.send(new PJsonObject().set("error", avatar.getError())); }
}

Set app.path_upload, app.slug_upload, and request.max_size_on_mb before accepting large multipart requests.

Upload File

Uploaded files are exposed through UploadFile. Always validate size/type and save to a path relative to app.path_upload.

<form method="post" action="/profile/avatar" enctype="multipart/form-data">
    @csrf
    <input type="file" name="avatar">
</form>

final UploadFile avatar = request.getFile("avatar");
if(avatar==null) { response.redirectBack(request.getPosts()); }
final boolean saved = avatar.saveIfContentTypeMatch("avatars/user.jpg", new String[] { "image/jpeg", "image/png" });
if(!saved) { response.send(new PJsonObject().set("error", avatar.getError())); }

Email

Configure SMTP in .env, render an HTML view, and send it through Email.

smtp.host=smtp.example.com
smtp.port=587
smtp.username=user@example.com
smtp.password=secret
smtp.starttls=true

final ParamsObject data = new ParamsObject().set("activation_url", Url.to("activation/token"));
final String html = Template.render("email.activation-account", data);
Email.send("user@example.com", "Activation", html);

Job

Use jobs for background cleanup, warmup, and scheduled tasks that should not run inside request handlers.

Job.everyMinute(() -> {
    Database.delete("sessions", "expired_at < NOW()");
});

Job.everyHour(() -> {
    Cache.clear();
});

Language

Language files are stored in resources and resolved through Language. Use this for repeatable UI labels and messages.

final String title = Language.get("auth.login");
final String message = Language.get("validation.required");

Url

Generate app links consistently in controllers and templates. Keep asset, redirect, email, and JSON action URLs based on app.base_url.

final String profileUrl = Url.to("profile");
final String editUrl = Url.to("users/edit/"+id);
response.redirect("login", "callback_url", request.getFullUrl());

<a href="{{ url('docs') }}">Documentation</a>
<link rel="stylesheet" href="{{ url('css/frontend.css') }}">

Build & Deploy

# Maven
mvn -q clean package
java -jar target/*.jar

# Generated Gradle starter
gradle shadowJar
java -jar build/libs/*-all.jar

For production, run behind Nginx/Caddy/Traefik for TLS, size JVM memory to the server/container, keep database pool size measured against workload, and ship assets/templates inside the JAR for immutable deployment.

Troubleshooting

Panaragan Framework Classes

Generated from the Panaragan framework artifact used by this website. Total documented classes: 37.