RestVertx is a mini-framework that makes it easier to build HTTP services with Vert.x
**** Latest Version released 2/14/2016 ****
Main Features
Getting Started
Annotations
Benchmarks
Tests
Google Group
Simply call RestVertx.register() in your constructor and annotate your methods. Instantiate the handling class(es) in your verticle and you're ready to go!
Example constructor of handling class:
@Base("items")
public class ShoppingList {
public ShoppingList(Vertx _vertx, Router router)
{
RestVertx.register(_vertx, router, this);
}
}(Read Feature #2 below to see examples of handling methods)
Let's say you have a several variables, and/or nested objects you need to pass in to your endpoint as arguments. You can create a model which contains your variables and/or nested objects and use it as the parameter in your handling method. If you send a JSON object in your request (via path param or request body), it will automatically be deserialized into the model (using FasterJackson databind, core, and annotations - https://github.com/FasterXML/jackson-core).
Simply specify the model as the parameter in both the endpoint and handling method and send a valid JSON object in the request
Example handling method using URL encoded Json in the path param for Json object:
@Method("Post")
@ResultType("json")
@Path("shoppingLists/:request")
public RestResponse getShoppingListPost(ShoppingListRequest request)
{
return new RestResponse(manager.getShoppingList(request.getId()));
}Example handling method using Json in the request body (automatically detected and deserialized):
@Method("Post")
@ResultType("json")
@Path("shoppingLists")
public RestResponse getShoppingListPost(ShoppingListRequest request)
{
return new RestResponse(manager.getShoppingList(request.getId()));
}Example data model that RestVertx deserializes into w/Jackson annotations (handling method argument):
@JsonIgnoreProperties(ignoreUnknown = true)
@JsonInclude(Include.NON_EMPTY)
public class ShoppingListRequest {
private String id;
private String name;
private GroceryStore store;
public ShoppingListRequest() {
...
}
// Getters/Setters
...
}Example on the client side a request to be sent before stringifying:
var request = {
id: "1",
name: "Angela",
store: {
name: "fake store"
}
}More examples can be found in the testing source files of the main branch (newer example) as well as in the example branch (older example)
Great for cross-IDE development. Are you transferring your web application code from one IDE to another because you prefer one for web development and the other for your Vertx endpoints? Do you want to serve files with node in one IDE while running your Vertx service endpoints in Eclipse on a different port?
Simply call CORS.allowAll() in your App setup before the request handlers in your verticle, or else use the CORS annotation to open up a specific handling method
Example: enable CORS for a specific method:
@Method("Get")
@CORS("http://localhost:3000")
@Path("/")
public RestResponse getItems()
{
...
}Example: enable CORS at a higher level:
@Override
public void start() throws Exception {
HttpServer server = vertx.createHttpServer();
server = vertx.createHttpServer();
router = Router.router(vertx);
// Enable CORS
// This is useful for developing on a node-dependent IDE where node serves the app, but your service endpoints exist in Vertx
CORS.allow(router, "http://localhost:3000");
...
}- Vert.x version 3+
- Maven
- Your favorite java editor
- A cup of hot tea, coffee, or espresso drink :)
Add this to your repositories:
<repository>
<id>git-codesipcoffee</id>
<name>CodeSipCoffee's Git based repo</name>
<url>https://raw.github.com/codesipcoffee/RestVertx/releases</url>
</repository>Add this in your dependencies:
<dependency>
<groupId>code.sip.coffee</groupId>
<artifactId>restvertx</artifactId>
<version>0.0.6</version>
</dependency>(You may need to do a maven force update)
1.Use static method RestVertx.register() in the handling class (no need to extend RestVertx)
public ShoppingListFinder(Vertx _vertx, Router router)
{
RestVertx.register(_vertx, router, this);
}2.Add your annotations to your handling class(es) - you must return a RestResponse object in your handling method
// Vertx handling method in Java
@Method("Post")
@ResultType("json")
@Path("shoppingLists/:request")
public RestResponse getShoppingListPost(ShoppingListRequest request)
{
if (request.hasSugar()) {
// This will return a 404 status code with following status message
return new RestResponse("", 404, "Sugar not found ;)");
}
// This will return a normal 200 status code
return new RestResponse(manager.getShoppingList(request.getId()));
}3.Instantiate new instance of handling class in your app (don't forget to include the body handler!)
@Override
public void start() throws Exception {
HttpServer server = vertx.createHttpServer();
server = vertx.createHttpServer();
router = Router.router(vertx);
// So we can use getBodyAsJson() and/or getBodyAsString() in our handling methods
router.route().handler(BodyHandler.create());
// Register your custom handlers
RegisterRoutes();
...}
private void RegisterRoutes()
{
ShoppingListFinder mng = new ShoppingListFinder(vertx, router);
}4.Make sure you set compiler to remember parameter values for your project
That's it, you're done. Just enough time left to make another espresso ;)
## Annotations@Path
Required
example: @Path("name/:id")
-
If you don't set the path, then the method will skipped
-
At a minimum, make sure to set the Path as "/"
-
In the example path, :id is a path variable
-
If you set your project to remember parameters in your build arguments, then path variable will be matched to parameters, no matter the order in the path
-
If you don't set your project to remember params in your build arguments, then path variables will be processed as if they are in the same order as the parameters (even if they're not). It is highly recommended to set your compiler to remember params for your project to get the most benefit out of RestVertx
@Method
Optional
example: @Method("Get")
- If you don't set the method, we will attempt to determine if the name of the handling method is or contains an http method name and set the http method registered for the route to that name
- Defaults to Get
@Base (Class Annotation)
Optional
example: @Base("api/monkeys")
- Set base path for all methods in the class
@ResultType
Optional
example: @ResultType("json")
- Sets the return type, which affects the header info as well
- Don't specify a result type unless it's JSON or a file
@RestIgnore
Optional
example: @RestIgnore
- Ignores the method
- Note that any method not specifying a path is also ignored
@CORS
Optional
example: @CORS and @CORS("http://localhost:3000")
- Enables CORS on a specific method(s) instead of across the board
- Can optionally specify the ip/port
@Blocking
Optional
example: @Blocking(value = "true", serial = "false")
- Determines whether handling method is blocking or not
- First string argument is for blocking, second string argument is for serial
- Defaults to non-blocking
Times should only be compared relative to one another to give a very rough estimate of time differences between using RestVertx on top of Vert.x vs Vert.x alone. There is always a cost for adding a layer on top of something else
While one test ran, the other @test annotation AND the other route were commented out in TimeTest.java (included under testing source code)
v 0.0.6
RestVertx + Vert.x
Time taken = 105761 ms Time taken (nano) = 105761359928
Vert.x alone
Time taken Vert.x alone = 96890 ms Time taken (nano) Vert.x alone = 96890834528
Observations
- v0.0.6 RestVertx on top of Vertx is 9.155% slower than Vertx alone
- v0.0.5 RestVertx 11.5% slower
- Two percent difference isn't alot
v 0.0.5
RestVertx + Vert.x
Time taken = 39835 ms
Time taken (nano) = 39835314664
Vert.x alone
Time taken Vert.x alone = 35721 ms
Time taken (nano) Vert.x alone = 35721488940
As of 2/14/16 v0.0.6, this is not production ready and may have bugs lurking underneath.
Testing & documentation is more important than benchmarks for this project, please include tests with any pull requests you make here
Any comments/questions, see the RestVertx Google Group
Please submit any issues you find
RestVertx is written in Java