Sparknotation
Sparknotation is a library to use Sparkjava framework with annotation. It is useful when working on projects with a lot of endpoints where it sometimes becomes messy to deal with all these Spark.something methods. It also saves the hassle of always getting back parameters, query parameters and headers from the Request object.
Download
Maven
Add this repository to your pom.xml
<dependency>
<groupId>com.ftpix</groupId>
<artifactId>sparknotation</artifactId>
<version>1.17</version>
</dependency>
Gradle
Add the dependency as follow
dependencies {
compile group: "com.ftpix", name: "sparknotation", version:"1.17"
}
How to use
Simple GET request
Create a class with the annotation @SparkController and add a method with the annotation @SparkGet
@SparkController
public class TestController {
@SparkGet("/hello/:name")
public String hello(@SparkParam("name") String name){
return "Hello "+ name;
}
}
Once this is done, you just need to add this line of code in your main method or wherever you would usually declare your Spark endpoints.
public static void main(String[] args) {
Sparknotation.init();
}
And query the server to test
$ curl http://localhost:4567/hello/world
>>> Hello world
An instance of each SparkController will be created and you can get it back
Sparknotation.getController(TestController.class);
Note that is still possible to configure SparkJava normally or to add any other endpoint using SparkJava original way.
If your controllers have contructor parameters, you can add them when calling Sparknotation.init()
MyController myController = new MyController("hello");
MySecondController mySecondController = new MySecondController("world");
Sparknotation.init(myController, mySecondController);
Note that this will still add other controllers that have @SparkController.
Response Transformer
SparkJava offers a great way to transform the response before sending it back to the client (JSON results or templating engine), Sparknnnotation offers the same options so the method annotations take in a parameter for classes extending Spark's ResponseTransformer
To follow SparkJava's Response Transformer example using Sparknotation it will be as following using the same JsonTransformer
@SparkGet(value = "/hello", transformer = JsonTransformer.class)
public MyMessage hello(){
return new MyMessage("Hello World");
}
Detailed usage
Class annotation
@SparkController
Used on a class to declare a SparkController.
Parameter | Usage |
---|---|
value (optional) | Used to identify a controller by a name |
path (optional) | Prefix path for every endpoints under this controller |
Method annotations
@SparkGet
Used on a method to create a GET endpoint
Parameter | Usage |
---|---|
value (optional) | the path of the endpoint |
accept (optional) | the type of request this endpoint should respond to |
transformer (optional) | A response transformer to transform the result of the method (example: return a json of an object) |
templateEngine (optional) | A template engine, works the same way as Spark. note that templateEngine has the priority against transformer if both are set |
@SparkPost
Used on a method to create a POST endpoint
Parameter | Usage |
---|---|
value (optional) | the path of the endpoint |
accept (optional) | the type of request this endpoint should respond to |
transformer (optional) | A response transformer to transform the result of the method (example: return a json of an object) |
templateEngine (optional) | A template engine, works the same way as Spark. note that templateEngine has the priority against transformer if both are set |
@SparkPut
Used on a method to create a PUT endpoint
Parameter | Usage |
---|---|
value (optional) | the path of the endpoint |
accept (optional) | the type of request this endpoint should respond to |
transformer (optional) | A response transformer to transform the result of the method (example: return a json of an object) |
templateEngine (optional) | A template engine, works the same way as Spark. note that templateEngine has the priority against transformer if both are set |
@SparkDelete
Used on a method to create a DELETE endpoint
Parameter | Usage |
---|---|
value (optional) | the path of the endpoint |
accept (optional) | the type of request this endpoint should respond to |
transformer (optional) | A response transformer to transform the result of the method (example: return a json of an object) |
templateEngine (optional) | A template engine, works the same way as Spark. note that templateEngine has the priority against transformer if both are set |
@SparkOptions
Used on a method to create an OPTIONS endpoint
Parameter | Usage |
---|---|
value (optional) | the path of the endpoint |
accept (optional) | the type of request this endpoint should respond to |
transformer (optional) | A response transformer to transform the result of the method (example: return a json of an object) |
templateEngine (optional) | A template engine, works the same way as Spark. note that templateEngine has the priority against transformer if both are set |
Combining methods
You can combine the different methods on a single method
@SparkGet("/hello")
@SparkPost("/hello")
public String hello(){
return hello;
}
Method annotations
@SparkParam
Used on a method Parameter. Will retrieve the value of a Request.params(String)
Parameter | Usage |
---|---|
value | The name of the parameter to retrieve |
@SparkGet("/hello/:name")
public String hello(@SparkParam("name") String name){
return "Hello " + name;
}
@SparkQueryParam
Used on a method Parameter. Will retrieve the value of a Request.queryParams(String)
Used to get POST method form values or query strings
Parameter | Usage |
---|---|
value | The name of the query param parameter to retrieve |
@SparkPost
public String hello(@SparkQueryParam("name") String name){
return name;
}
curl -d "name=world" http://localhost:4567/hello
>>> world
@SparkHeader
Used on a method Parameter. Will retrieve the value of a request header Request.headers(String)
Parameter | Usage |
---|---|
value | The name of the header to retrieve |
@SparkBefore("/*")
public void auth(@SparkHeader("Authorization") String token){
// do something
}
@SparkSplat
Used on a method Parameter. Will retrieve the value of a splat form the endpoint
Parameter | Usage |
---|---|
value (defaults to 0) | Index of splat to retrieve (starting from 0) |
@SparkGet("/my-path/*/something/*")
public String hello(@SparkSplat(1) String secondSplat, @SparkSplat String firstSplat){
return firstSplat+" "+secondSplat;
}
@SparkBody
Sparknotation can help you convert the body of a request to a java object
For that there are two options
Assign a BodyTransformer when using Sparknotation.init()
This way will apply the body transformer to all the @SparkBody parameters of all your controllers if not specified othewise with the transformer parameter of the annotation.
Example using Gson
Gson gson = new Gson();
Sparknotation.init(gson::fromJson);
This works because BodyTransformer is a functional interface and Gson.fromJson(String json, Class class) fits right into it.
You can create your own transformer by implementing the BodyTransformer interface.
@SparkPost
public String hello(@SparkBody MyObject myObject){
//use myObject
}
Using @SparkBody transformer parameter
The @SparkBody annotation has can take a transformer parameter which is a class that implements BodyTransformer
Parameter | Usage |
---|---|
value | Class of a class inplementing BodyTransformer |
@SparkPost
public String hello(@SparkBody(MyBodyTransformer.class) MyObject myObject){
//use myObject
}
Request and Response objects
You can easily get back the Request and Response objects from Spark if needed, simply add it to your method parameters
@SparkGet
public String hello(Request req, Response res){
//Do something with request and response
return "hello";
}