templates.docs.installation.html Maven / Gradle / Ivy
{#==========================================
Docs : "installation"
==========================================#}
Installation
There are a lot of different ways to use Spincast and to bootstrap your application.
In fact, an entire Bootstrapping your app section is dedicated to this topic! But
in this section you'll learn the quickest ways to get started.
{#==========================================
Section "installation / requirements"
==========================================#}
{#==========================================
Section "installation / Quick Start"
==========================================#}
Quick Start
{% if spincastCurrrentVersionIsSnapshot %}
Warning! The current version,
"{{spincastCurrrentVersion}}" is a snapshot version. That means that it
can change, it is not a stable version. Do not use this
as a start for a real application!
{% endif %}
The easiest way to try Spincast is to download the Quick Start application,
which is a simple but working Spincast application. This Quick Start even makes
a good starting point to build a real application! For this Quick Start, you need to have
Maven installed, but the application could easily be tweaked to
be used by another tool like Gradle.
-
Download the Spincast Quick Start [.zip]
application.
-
Decompress the zip file, go inside the "spincast-quick-start"
root directory using a command prompt and run:
mvn clean package
This will compile the application and produce an executable .jar file
containing an embedded HTTP server.
-
Start the application using :
java -jar target/spincast-quickstart-1.0.0-SNAPSHOT.jar
-
Once the application is running, open
http://localhost:44419
in your browser. Bingo!
-
The next step would probably be to import the project in your favorite IDE and start debugging it to see
how it works. The entry point of a standard Spincast application is the classic
main(...)
method. You'll find this method in class
org.spincast.quickstart.App.
{#==========================================
Section "installation / using Default Module"
==========================================#}
Using SpincastDefaultGuiceModule
{% if spincastCurrrentVersionIsSnapshot %}
Warning! The current version,
"{{spincastCurrrentVersion}}" is a snapshot version. That means that it
can change, it is not a stable version. Do not use this
as a start for a real application!
{% endif %}
Spincast is modular, and pretty much all components can be replaced. There are some required components
though, and an implementation must be provided for those. This is exactly what the spincast-default
artifact is: an easy way to bind a default implementation for all the required components.
{% if spincastCurrrentVersionIsSnapshot %}
Since this is a SNAPSHOT version, you first have to add this repository
to your pom.xml:
<repositories>
<repository>
<id>sonatype-snapshots</id>
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
</repositories>
{% endif %}
Add the
org.spincast:spincast-default:{{spincastCurrrentVersion}}
dependency to your pom.xml :
<dependency>
<groupId>org.spincast</groupId>
<artifactId>spincast-default</artifactId>
<version>{{spincastCurrrentVersion}}</version>
</dependency>
If you use other tools like Gradle or Ivy, you already know how to use Maven coordinates, aren't you?
This artifact gives you access to a Guice module, SpincastDefaultGuiceModule,
which binds default implementations. (Look here if you are curious about what
those default implementations are!).
Then, create a Guice context using that module, in general inside a main(...)
method:
public static void main(String[] args) {
Injector guice = Guice.createInjector(new SpincastDefaultGuiceModule(args));
IServer server = guice.getInstance(IServer.class);
server.start();
}
Explanation :
-
1 : A good old Java's
main(...) method! This
is the entry point of a standard Spincast application.
-
3 : The very first thing a Spincast application
does is to create a Guice context. Here, we use the provided
SpincastDefaultGuiceModule module. This is going to bind a default
implementation for all the required components.
By passing the main method's args as a parameter to the constructor,
the module will bind them using the @MainArgs
annotation so you can easily access them wherever you need (more info).
-
5 : We get the
server instance from the Guice context.
-
6 : We start the server.
Run this application and point a browser at : http://localhost:44419.
You'll see that the server works, but since no route have been defined, you'll always get
a 404 Not Found response!
This is the very basic on how to start a Spincast application. But how do you add routes? How to make
your application do something useful? Keep reading if you want to learn about Spincast and its architecture,
or jump to the Bootstrapping your app section is you want
to see code straight away!