Home / Documentation / Quick Start Guide

Quick Start Guide

Get up and running with Oorian in minutes. This guide walks you through creating your first Oorian web application from scratch.

1. Prerequisites

Before you begin, ensure you have the following installed:

  • Java Development Kit (JDK) 17 or higher - Oorian uses modern Java features
  • A Servlet Container - Apache Tomcat 10+ (for Jakarta EE) or Tomcat 9 (for Java EE)
  • An IDE - NetBeans, IntelliJ IDEA, Eclipse, or VS Code
Jakarta EE vs Java EE

Oorian provides two library versions: OorianJakartaLib for Jakarta EE (Tomcat 10+) and OorianJ2eeLib for Java EE (Tomcat 9). Choose the one matching your servlet container.

2. Create a Web App Project

Start by creating a Java web application project in your preferred IDE. If you're already familiar with creating Java web apps, create a new project and skip ahead to Step 3.

If you're new to Java web development, download one of our pre-configured starter projects below. Each includes the Oorian library, proper configuration, and a sample page to get you started immediately.

NetBeans (Recommended)

We personally think NetBeans is the best IDE for Java web app development. It has built-in Tomcat integration, excellent code completion, and just works out of the box.

Download Ant Project | Download Maven Project

IntelliJ IDEA

IntelliJ IDEA offers powerful refactoring tools and smart code assistance. The starter project is configured for both Community and Ultimate editions.

Download IntelliJ IDEA Starter Project

Eclipse

Eclipse with the Web Tools Platform (WTP) provides solid Java web development support. Requires Eclipse IDE for Enterprise Java Developers.

Download Eclipse Starter Project

Visual Studio Code

VS Code offers a lightweight option with the Tomcat for Java extension. Requires the Extension Pack for Java and a local Tomcat installation.

Download VS Code Starter Project

Jakarta EE vs Java EE

Each starter project is available in two versions: one for Jakarta EE (Tomcat 10+) and one for Java EE (Tomcat 9). Choose the version matching your servlet container.

3. Creating the Application Class

Every Oorian application needs an Application subclass annotated with @WebListener. This class has two lifecycle methods:

  • initialize() - The entry point, called when your application starts
  • destroy() - The exit point, called when your application shuts down
Java
package com.yourcompany;

import com.oorian.Application;
import javax.servlet.ServletContext;
import javax.servlet.annotation.WebListener;

@WebListener
public class MyApplication extends Application
{
    @Override
    protected void initialize(ServletContext servletContext)
    {
        registerPackage("com.yourcompany.pages");
    }

    @Override
    protected void destroy(ServletContext servletContext)
    {
        // Clean up resources if needed
    }
}

At a minimum, your initialize() method must call registerPackage() to tell Oorian where your page classes live. Oorian scans the registered package and all sub-packages for classes annotated with @Page.

Tip

You can register multiple packages if your application spans different namespaces, but you only need to register the top-level package. Sub-packages are scanned automatically.

4. Creating Your First Page

Pages in Oorian are Java classes that extend HtmlPage and are annotated with @Page.

Java
package com.yourcompany.pages;

import com.oorian.annotations.Page;
import com.oorian.html.HtmlPage;
import com.oorian.html.elements.*;

@Page("/")
public class HomePage extends HtmlPage
{
    @Override
    protected void createHead(Head head)
    {
        head.setTitle("My First Oorian App");
    }

    @Override
    protected void createBody(Body body)
    {
        H1 heading = new H1();
        heading.setText("Hello, Oorian!");
        body.addElement(heading);

        P paragraph = new P();
        paragraph.setText("Welcome to your first Oorian application.");
        body.addElement(paragraph);
    }
}

The @Page("/") annotation maps this page to the root URL. When you deploy and visit your application, you'll see this page.

5. Working with HTML Elements

Oorian provides Java classes for all standard HTML elements. Each element has type-safe methods for setting attributes and styles.

Common Elements

HTML TagOorian ClassExample Usage
<div>Divnew Div()
<span>Spannew Span()
<p>Pnew P()
<a>A or Anchornew A("/about")
<button>Buttonnew Button()
<img>Imagenew Image("/logo.png")
<h1>-<h6>H1-H6new H1()
<table>Tablenew Table()
<input>TextInput, Checkbox, etc.new TextInput()
<select>Selectnew Select()

Setting Styles

Elements provide type-safe methods for common CSS properties:

Java
Div container = new Div();
container.setWidth("800px");
container.setMargin("0 auto");
container.setPadding("20px");
container.setBackgroundColor("#f8fafc");
container.setBorderRadius("12px");

// Use CSS enums for type safety
container.setDisplay(Display.FLEX);
container.setFlexDirection(FlexDirection.COLUMN);
container.setAlignItems(AlignItems.CENTER);

Nesting Elements

Build your UI by nesting elements:

Java
Div card = new Div();
card.setBackgroundColor("#ffffff");
card.setPadding("24px");
card.setBorderRadius("8px");

H3 title = new H3();
title.setText("Welcome");
card.addElement(title);

P content = new P();
content.setText("This is a card component.");
card.addElement(content);

body.addElement(card);

6. Next Steps

Congratulations! You've learned the basics of Oorian. Here's where to go next: