Copyright © 2014-2015
Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.
About
DebugWebModule provides a configurable endpoint for developer related web resources from other modules. It allows other modules to register
one or more debug web controllers upon the presence of the DebugWebModule. A typical example of a debug web controller
would be a controller to introspect and manage the cache. Out of the box DebugWebModule comes with a set of default controllers
that allow you to introspect the running AcrossContext
.
Module website: https://foreach.atlassian.net/wiki/display/AX/DebugWebModule
1. General information
1.1. Artifact
<dependencies>
<dependency>
<groupId>com.foreach.across.modules</groupId>
<artifactId>debug-web-module</artifactId>
<version>1.0.1.RELEASE</version>
</dependency>
</dependencies>
1.3. Module settings
All properties start with the debugWebModule. prefix.
Property | Type | Description | Default |
---|---|---|---|
root-path |
|
Root path for all debug web controllers. All mappings will be relative to this path. |
/debug |
dashboard |
|
Path within the debug web context for the initial dashboard. |
/ |
properties.masks |
|
Set regular expressions for all property names that should be masked. |
|
properties.masked-properties |
|
Set explicit property names that should be masked. |
2. What’s new in this version?
1.0.1.RELEASE
-
both root path and dashboard path are now configurable through properties
-
the context browser debug controller can now mask sensitive property values
1.0.0.RELEASE
Initial public release available on Maven central.
3. How DebugWebModule works
DebugWebModule creates a new RequestMappingHandlerMapping
endpoint that serves all @RequestMapping
methods from
beans annotated with @DebugWebController
. All mappings will be prefixed with the configured root path (eg: /debug) ensuring
that all web controllers are behind a base path. Under the hood, DebugWebModule achieves this by creating a specific PrefixingRequestMappingHandlerMapping
instance named DebugWebModule.
4. Configuring DebugWebModule
4.1. Root path
The root path is configured by setting the debugWebModule.root-path
property.
This can only be done when configuring the AcrossContext
, before it has bootstrapped.
If no custom root path is configured, the default is /debug.
4.2. Dashboard (landing page)
Pointing your web browser at the root path within your application will open DebugWebModule on the dashboard. By default the dashboard has no content other than the top menu. If you would like a particular controller to open you can set another relative path on the debugWebModule.dashboard property. The path should not contain the root path prefix.
5. Securing debug web
By default the DebugWebModule takes no care of securing the debug endpoints. This is considered the responsibility of the application itself. Securing can easily be done on a webserver level or through Spring security.
@Configuration
public class DebugWebSecurityConfiguration extends SpringSecurityWebConfigurerAdapter
{
@Autowired
private DebugWeb debugWeb;
@Override
public void configure( AuthenticationManagerBuilder auth ) throws Exception {
auth.inMemoryAuthentication()
.withUser( "debug" )
.password( "debug" )
.roles( "DEBUG_USER" );
}
@Override
public void configure( HttpSecurity http ) throws Exception {
http.antMatcher( debugWeb.path( "/**" ) )
.authorizeRequests().anyRequest().hasRole( "DEBUG_USER" )
.and()
.formLogin().disable()
.httpBasic()
.and()
.sessionManagement().sessionCreationPolicy( SessionCreationPolicy.STATELESS )
.and()
.csrf().disable();
}
}
6. Default debug controllers
Out of the box DebugWebModule provides some default debug controllers. These are all available through the top menu.
6.2. Section: Across
Allows you to introspect the running AcrossContext
.
You can navigate the entire ApplicationContext
hierarchy, see the modules registered in the Across context along with the beans they created (and expose) as well as the configuration properties visible within each module.
As some properties contain sensitive data (for example passwords), it is possible to mask property values based on the property name. By default all property names containing password or secret will have their values masked. Additional rules can be configured with debugWebModule.properties.masks or debugWebModule.properties.masked-properties.
Handlers lists the different request mapping endoints grouped by their handler mappings. Interceptors lists the mapped and unmapped interceptors that apply to a particular handler mapping.
7. Creating your own debug controller
7.1. @DebugWebController
Debug web controllers are just like any other controller bean with RequestMapping
methods, except they are annotated
with @DebugWebController
instead of the standard @Controller
. Any bean annotated with @DebugWebController
will be picked up by the DebugWebModule and will have its mappings prefixed with the debug web root path.
@DebugWebController
@AcrossDepends(required = "DebugWebModule")
public class DebugEhcacheController
{
@RequestMapping(value = "/test", method = RequestMethod.GET)
public String test() {
return "th/mymodule/debug/test";
}
}
7.2. Thymeleaf template
Unless a named template is specified, the default Thymeleaf template from debug web will be applied to the output. The default template will add a top menu for all registered debug web controllers. Like any Across web Thymeleaf template, this implementation requires you to put the actual output in a content fragment.
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<title>My test debug controller</title>
</head>
<body th:fragment="content">
This is a test debug controller.
</body>
</html>
If you need additional javascript or custom CSS, you can register it using the WebResourceRegistry
and it will
automatically be added to the output by the layout template.
@DebugWebController
@AcrossDepends(required = "DebugWebModule")
public class DebugEhcacheController
{
@ModelAttribute
public void registerCss( WebResourceRegistry registry ) {
registry.addWithKey( WebResource.CSS, "MyModule", "/css/mymodule/debug.css", WebResource.VIEWS );
}
@RequestMapping(value = "/test", method = RequestMethod.GET)
public String test() {
return "th/mymodule/debug/test";
}
}
7.3. Customizing the top menu
The default layout template builds and renders a top menu. This menu is built by publishing a DebugMenuEvent
. Any
AcrossEventHandler
- and all controllers are event handlers by default - can listen for this event and modify the menu.
The menu is built using a PathBasedMenuBuilder
, allowing the entire menu hierarchy to be specified using a path structure.
Note
|
By default the menu item path is also used as the url for the menu endpoint. All menu item urls will be processed by
the debug web WebAppPathResolver and any relative path will be prefixed with the configured root path.
|
@DebugWebController
@AcrossDepends(required = "DebugWebModule")
public class DebugEhcacheController
{
@Event
public void registerMenuItem( DebugMenuEvent event ) {
event.builder().item( "/test", "Test controller" );
}
@RequestMapping(value = "/test", method = RequestMethod.GET)
public String test() {
return "th/mymodule/debug/test";
}
}
7.4. Linking to debug web controllers
The actual URL endpoint of debug web controllers depends on the application-specific configured root path. When implementing
custom debug web controllers you can ensure your relative links point to the correct controller by running them through
the PrefixingPathContext
. DebugWebModule has registered a prefixer named debugWeb, this prefixer can be used to
correctly point to a debug web controller from any other controller.
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<title>My test debug controller</title>
</head>
<body th:fragment="content">
Relative to debug web root path:
* <a th:href="@{#webapp.path('/test')}">when rendered from a debug web controller</a>
* <a th:href="@{#webapp.path('@debugWeb:/test')}">always</a>
</body>
</html>
In code the DebugWeb
bean - implementation of the PrefixingPathContext
- can be used to generate the correct URL.
@DebugWebController
@AcrossDepends(required = "DebugWebModule")
public class DebugEhcacheController
{
@Autowired
private DebugWeb debugWeb;
@RequestMapping(value = "/redirect", method = RequestMethod.GET)
public String test() {
return debugWeb.redirect( "/test" );
}
}
8. Customizing debug web template
DebugWebModule uses a default Thymeleaf layout template that builds the top menu and renders HTML for Bootstrap CSS and
JQuery. If you wish to replace the default layout, you can wire the debugWebTemplateRegistry
, register
your own WebTemplateProcessor
and set it as the default template for all debug web controllers.
Alternatively you can specify any registered WebTemplateProcessor
by name, using the @Template
annotation on specific debug web controllers.
Note
|
Because DebugWebModule uses its own WebTemplateRegistry , only templates registered explicitly on the debugWebTemplateRegistry bean will be available.
|
For more details, please see the source code of com.foreach.across.modules.debugweb.config.DebugWebInterceptorsConfiguration
.