templates.docs.miscellaneous.html Maven / Gradle / Ivy
{#==========================================
Docs : "Miscellaneous"
==========================================#}
Miscellaneous
{#==========================================
Default Configurations
==========================================#}
Default Configurations
To know what are the default Spincast configurations,
have a look at the
Spincast Config plugin page, which is the
default implementation of the "ISpincastConfig" interface. But here are some
important ones:
-
getServerHost() : The host/IP the HTTP server
will listen on. The default is 0.0.0.0, which
means the server will listen on any IP.
-
getHttpServerPort() : The port the server
will listen to for HTTP (unsecure) requests.
If <= 0, the server won't listen on HTTP requests.
-
getHttpsServerPort() : The port the server
will listen to for HTTPS (secure) requests.
If <= 0, the server won't listen on HTTPS requests.
If you use HTTPS, you also have to provide some extra
configurations related to the SSL
certificate to use.
-
isDebugEnabled() : If true,
a development environment is taken for granted, and
internal error messages may be displayed publicly, no cache will be
used for the templates, etc. The default is true, so make
sure you change this to false before deploying to
production!
{#==========================================
SSL
==========================================#}
Using a SSL certificate (HTTPS)
It is recommended that you serve your application over HTTPS and
not HTTP, which is not secure. To achieve that, you need to install a
SSL certificate.
If you download the Quick Start application, you will
find two files explaining the required procedure:
-
/varia/ssl_certificate_howto/self-signed.txt
Shows how to use a self-signed certificate, for development
purpose.
-
/varia/ssl_certificate_howto/lets-encrypt.txt
Shows how to use a Let's Encrypt
certificate. Let's Encrypt is a provider of free, but totally valid,
SSL certificates. Instructions in this file will probably work for certificates
obtained from other providers, but we haven't tested it yet.
{#==========================================
JsonObject
==========================================#}
JsonObject
The JsonObject (interface IJsonObject) is a class
provided by Spincast to mimic a real Json object. It is, essentially,
a typed Map<String, Object>. So there is a put(String key, Object value)
method, but the getters are typed:
-
String getString(String key)
-
Integer getInteger(String key)
-
IJsonObject getJsonObject(String key)
-
...
You can create a JsonObject, or a JsonArray, using the IJsonManager
component. This component can be injected by Guice, or it can be accessed through the
json() add-on:
public void myHandler(IAppRequestContext context) {
IJsonObject obj = context.json().create();
obj.put("name", "Stromgol");
obj.put("lastName", "Laroche");
context.response().sendJson(obj);
}
Spincast uses JsonObject objects in many places. For example,
to get the content of a request for which a Json body has been sent
via ajax :
public void myHandler(IAppRequestContext context) {
IJsonObject json = context.request().getJsonBodyAsJsonObject();
// ...
}}
Or even when XML is sent :
public void myHandler(IAppRequestContext context) {
IJsonObject json = context.request().getXmlBodyAsJsonObject();
// ...
}}
{#==========================================
@MainArgs
==========================================#}
@MainArgs
Both SpincastCoreGuiceModule and SpincastDefaultGuiceModule
Guice modules have a constructor which accepts
String[] mainArgs. You can pass to it the arguments received in
your main(...) method. For example:
public static void main(String[] args) {
Injector guice = Guice.createInjector(new SpincastDefaultGuiceModule(args));
App app = guice.getInstance(App.class);
app.start();
}
By doing so, those arguments will be bound, using a @MainArgs
annotation. You can then inject them anywhere you need:
public class AppConfig extends SpincastConfig implements IAppConfig {
private final String[] mainArgs;
@Inject
public AppConfig(@MainArgs String[] mainArgs) {
this.mainArgs = mainArgs;
}
protected String[] getMainArgs() {
return this.mainArgs;
}
@Override
public int getHttpServerPort() {
int port = super.getHttpServerPort();
if(getMainArgs().length > 0) {
port = Integer.parseInt(getMainArgs()[0]);
}
return port;
}
}
{#==========================================
Using an init() method
==========================================#}
Using an init() method
This is more about standard Guice development than about Spincast, but we
feel it's a useful thing to know.
Guice doesn't provide
support for a @PostConstruct annotation out of the box.
And since it is often seen as a bad practice to do too much work directly in a constructor, what we want
is an init() method to be called once the
object it fully constructed, and do the initialization work there.
The trick is that Guice calls any @Inject annotated methods
once the object is created, so let's use this to our advantage:
public class UserService implements IUserService {
private final ISpincastConfig spincastConfig;
@Inject
public UserService(ISpincastConfig spincastConfig) {
this.spincastConfig = spincastConfig;
}
@Inject
protected void init() {
doSomeValidation();
doSomeInitialization();
}
//...
}
Explanation :
-
5-8 : The constructor's job is only to
receive the dependencies.
-
10-14 : An
init() method is
also annotated with @Inject. This method will be called once the
object is fully constructed. This is a good place to do some initialization work!
What we recommend is constructor injection + one (and only one) @Inject
annotated method. The problem with multiple @Inject annotated methods (other than
constructors) is that it's hard to know in which order they will be called.
Finally, if the init() method must be called as soon as the application starts, make sure
you bind the object using
asEagerSingleton()!