Warning! This documentation is a work in progress. Expect things to be out of date and not actually work according to instructions.

Java Web Application

1. Make sure Java 1.8 is installed

Ensure you have Java 1.8u40 or greater on the class path:

>java -version

If not, download and install Java from Oracle or from the OpenJDK.

If you have multiple java versions on your machine, you may have to symlink the Java 1.8 binary to /usr/bin/java

2. Create a new directory for your app:

>mkdir myapp

3. Download or install the stallion binary into a subfolder called “bin” and give the file executable permissions:

>cd myapp
>mkdir bin
>curl -L -o bin/stallion https://stallion.io/downloads/stallion-core/latest/stallion
>chmod 700 bin/stallion

4. Run the stallion set up wizard

bin/stallion new

Choose option #4 – “Java App”

Complete the wizard as desired.

5. Start the development server

Go to the folder myapp/java-app and run ./run-dev.sh to run the server. This will compile and execute the current project source code using maven. You can look at the source of run-dev.sh to see how it works.

Go to http://localhost:8090/ to see your project.

6. Open the project in your IDE

Using Eclipse, Intellij or another IDE, you should be able to open the project based on its pom.xml which is in myapp/java-app.

7. Finding your way around the project

Here are some of the default files and what they do:

In the myapp/site folder:

  • conf/stallion.toml - defines settings for this instance of the application, such as the database connection, the SMTP services, etc.
  • conf/stallion.prod.toml - defines any settings overrides for the production environment.

In the Java project:

  • my.package.myapp.MainRunner.java - the entry point for running the server via the command line.
  • my.package.myapp.<MyApp>Plugin.java - defines the app/plugin you have just created. The most important method is the “boot” method, which gets called after the core Stallion services have been loaded. In this “boot” method is where you want to register endpoints, hooks, and data access controllers.
  • my.package.myapp.<MyApp>Settings.java - defines any settings that can be custom for a particular instance of this Java application. These settings will be configured in the site site/conf/<plugin name>.toml.
  • my.package.myapp.Endpoints.java - defines the RESTful endpoints for the application. You will see a root endpoint that is accessible at http://localhost:8090/ and a “Hello, world” endpoint accessible at http://localhost:8090/hello-world.
  • resources/templates/app.jinja - this template is rendered by the root endpoint defined in Endpoints.java
  • resources/assets/app.bundle - this asset bundle is included by app.jinja. It contains a list of javascript and css files. In development mode, each file will be included on the page separately for easy debugging. When the project is built and packaged using maven, the bundle is combined and minified into single css and js files.

8. Making your first change

In your Java IDE, go to the “Endpoints” class. Change the method hello() to return map(val("greeting", "hello"));. Change the annotation @Produces("text/html") to @Produces("application/json"). Stop the server if it is running, and restart it. Go to http://localhost:8090/hello-world in your web browser. You should see a JSON response – {"greeting": "hello"}. Stallion has automatically converted the HashMap that you returned from the endpoint method into a JSON response.

Go to templates/app.jinja. Change the line “I need to be implemented” to “Work in progress!.” Reload http://localhost:8090/ in your browser. You should see the new text.

9. That’s it!

See the reference guides in the left menu to learn more about customizing endpoints, doing data access, deploying, etc.

© 2024 Stallion Software LLC