Routing in ActiveWeb is an act of matching an incoming request URL to a controller and action. Current implementation supports:
- Standard routing
- REST - based routing
- Custom routing
Definition of terms
There are some routing terms defined in ActiveWeb:
- Controller name - logical name of controller as it relates to the URI mapping. a controller name is an underscored or hyphenated short class name. For instance, if the class name is
app.controllers.api.v2.AuthorsControllerthen the controller name is
authors_controller. It will be the same for a class
- Controller class - Java class name of controller
- Action - action is part of URL mapped to a method of a controller.
- Action method - method of controller mapped to an action. Every public method of a controller is theoretically an action.
- ID - id sometimes present on the URL, such as:
Example, for URI:
- Controller name is:
- Controller class name:
- Action is:
- Action method is:
- ID is 123
context in all URIs is a web application context, which is usually a WAR file name.
In standard routing, the HTTP method is not considered, but you might get an exception of you send an HTTP method to an action that is configured for a different HTTP method. Routing and action HTTP methods are independent in case of standard routing. For standard routing, there is no need to do anything, it works by default
If action is missing, it is assumed to be
In case of restful routing, the actions are pre-configured. RESTful routing is configured by placing a @RESTfull annotation on a controller. For more informaiton, see: RESTful controllers
|HTTP method||path||controller||action||used for|
|GET||/books||app.controllers.BooksController||index||display a list of all books|
|GET||/books/new_form||app.controllers.BooksController||new_form||return an HTML form for creating a new book|
|POST||/books||app.controllers.BooksController||create||create a new book|
|GET||/books/id||app.controllers.BooksController||show||display a specific book|
|GET||/books/id/edit_form||app.controllers.BooksController||edit_form||return an HTML form for editing a book|
|PUT||/books/id||app.controllers.BooksController||update||update a specific book|
|DELETE||/books/id||app.controllers.BooksController||destroy||delete a specific book|
Routing with packages
app.controllers is a default package for controllers, you might want to organize them into sub-packages. These sub-packages can only be children of
app.controllers package though. In case a controller is located in a sub-packages, the path mapping would also include sub-package names:
RESTful routing supports sub-packaging exactly the same as standard.
Please note: Controller names must not match (sub)package names.
Mapping paths to controller names
When matching a path to a controller class, ActiveWeb converts a name of a controller from underscore or hyphenated format to CamelCase:
Mapping actions to action methods
ActiveWeb will automatically translate underscored or hyphenated action names to CameCased action method names.
Besides standard and RESTful, ActiveWeb also offers custom routing. Custom routing provides ability to configure custom URIs to be forwarded to specific controllers and actions.
Custom routing configuration
As with any other types of configuration, ActiveWeb route configuration is done in code, rather that property or XML files. Custom routing is done by adding a new class to the application:
Custom routing is based on URI segments, which are chunks of URIs submitted of the request separated by slashes. For example the following URI has three segments:
The above URI has three segments:
ActiveWeb defines three types of segments:
- Built in
- User (or dynamic)
I case of a custom routing, the automatic detection of a format of a template name is not engaged. A developer needs to manually use a
render("index.xml")method inside a controller (if the URI contains aformat).
ActiveWeb defines three built-in segments:
Using built-in segments, you can reorder where controller, action and Id appear on the URI:
When such a route is specified, this URI:
Will be routed to:
app.controllers.PhotoController#show with ID ==123.
Static segments are simply plain text without the braces. The are matched one to one with the incoming request. Example:
In the snippet above,
greeting is a static segment.
User segments are any text in braces in configuration which are then converted to parameters that can be retrieved inside controllers and filters. Here is an example:
name is a placeholder whose value will be available in controller:
will be routed to controller
app.controllers.HelloController#show and value
name will be available:
Wild card routing
Sometimes you need to route a really long URI to a controller. Here is how:
In a case the following URL is submitted:
it will be routed to controller
app.controllers.PostsController#index and value
items will be available:
Http method - based routing
You can include an Http method used in the request into the routing rule:
In this example, this route will only match the incoming request if the Http method of the request is GET. There are four corresponding methods:
delete(). They can be used in isolation or in combination. For instance, this route:
will match these requests:
Of course the action
save() needs to have a @POST annotation for this to work. Annotations are independent of routing rules.
Default Http method used in routing rules is
Custom routing with packages
It works similarly to standard routing with packages:
/api/v2/authors/9 will map to a custom route:
app.config.RouteConfig is recompiled and reloaded in development environment in case a system property
active_reload is set to true. This makes it easy and fun to play with the routes during development. Please see Running in development mode for more information.
Strict mode (since v3.0)
Generally, any custom route does not preclude any standard or Restful routes, meaning if you have a custom route to a resource, a standard route to the same or any other resource is still working. That can be turned off like this:
If you call the
strictMode() method in the
RouteConfig as above, only the routes listed in this class will work. Per example above, only access to
/myposts will work. Any other request will result in a 404 response.
Excluding some routes
Exclusion of some routes is necessary for most applications. Static content, such as CSS, HTML, images, etc. should not be processed by the framework, but rather should be served by container directly. Please, see the
exclusions section of the filter configuration in: RequestDispatcher configuration for more information.
Ignoring some routes
Exclusions mechanism described above is sometimes too crude. Lets say we want to dynamically compile Less files into CSS in development environment, but also want the same URL be served directly from container in any environment except development.
Here is an example configuration:
In the example above, the web request to this
/bootstrap URI will result in passing control to a
BootstrapController only in
development environment. The same request will be completely ignored in any other environment. This means that in non-
development environment, the server will simply serve
This is a convenience feature that is commonly used with Lessc compiler.
How to comment
The comment section below is to discuss documentation on this page.
If you have an issue, or discover bug, please follow instructions on the Support page