JarCastingavans
Tiny and thin web application framework for Java 8.
SYNOPSIS
public static class MyController extends ControllerBase {
@BeforeDispatchTrigger
public Optional<WebResponse> beforeDispatch() {
return Optional.empty();
}
@GET("/")
public WebResponse index() {
return new ByteArrayResponse(200,
"Hello world".getBytes(StandardCharsets.UTF_8));
}
}
Motivation
I need tiny, thin, and simple web application framework for Java 8. I need the web application framework like Sledge(Popular web application framework for Perl5).
Architecture
You can build web application based on servlet API. That's all.
INSTALLATION
avans was uploaded on maven central. Please look maven central site: http://search.maven.org/#search%7Cga%7C1%7Cavans
Create skeleton site
avans supports maven archetype. You can create a simple site by this skeleton generator.
mvn archetype:generate \
-DarchetypeGroupId=me.geso.avans \
-DarchetypeArtifactId=avans-setup \
-DarchetypeVersion=LATEST \
-DgroupId=com.example.myapp \
-DartifactId=MyWebApp
web.xml
You can initialize servlets by web.xml.
<?xml version="1.0" encoding="UTF-8"?>
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
<servlet>
<servlet-name>hello</servlet-name>
<servlet-class>me.geso.avans.AvansServlet</servlet-class>
<init-param>
<param-name>class</param-name>
<param-value>com.example.helloworld.Main$Foo</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>hello</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>
Pass the controller class names in CSV.
You can pass the controller class list by packages.
<init-param>
<param-name>package</param-name>
<param-value>my.project.sp,my.project.pc</param-value>
</init-param>
How do I write controller code?
@PathParam
Capture the path parameters.
In following code, path will be "foo/bar" when user accessed "/download/foo/bar". * rule matches all characters. This path pattern is same as ^/download/.*$ in regexp.
@GET("/download/*")
public WebResponse download(@PathParam("*") String path) {
return this.renderText(slurp(path));
}
In following code, memberId will be "59" when user accessed "/member/59". * rule matches some characters. This path pattern is same as ^/member/[a-zA-Z0-9._-]+$ in regexp.
@GET("/member/{memberId}")
public WebResponse member(@PathParam("*") long memberId) {
...
}
@Param(name)
You can get query/form parameters by @Param annotation. In this case, when user calle /member/detail?id=3, memberId parameter will be 3.
@GET("/member/detail")
public WebResponse member(@Param("id") long memberId) {
...
}
You can get multiple params by string array.
@GET("/member/list")
public WebResponse member(@Param("ids") String[] ids) {
...
}
@BeanParam
You can map form parameters to Bean.
@GET("/")
public WebResponse foo(@BeanParam MyBean bean) {
return this.renderJSON(bean);
}
@Data
public static class MyBean {
@Param("string")
private String string;
@Param("object_boolean")
private Boolean object_boolean;
}
Controller hooks
@BeforeDispatchTrigger
public class MyController extends ControllerBase {
@BeforeDispatchTrigger
public Optional<WebResponse> beforeDispatch() {
return Optional.empty();
}
}
The callback methods will execute before dispatching controller methods. You can prepare the controller states at here.
If the return value contains instance of WebResponse, ControllerBase use the response as the response. It'll skip the controller method.
@ResponseFilter
You can modify every response by this hook point.
public class MyController extends ControllerBase {
@ResponseFilter
public void responseFilter(WebResponse resp) {
resp.addHeader("X-Content-Type-Options", "nosniff");
}
}
@HTMLFilter
You can rewrite HTML in hook point. It supported by avans-freemarker.
public static class MyController extends ControllerBase {
@HTMLFilter
public String htmlFilter(String src) {
return src.toUpperCase();
}
@GET("/")
public WebResponse foo() {
return this.renderText(this.filterHTML("Hige"));
}
}
@ResponseConverter
You can convert return value from controller method at this hook point.
@Data
public static class MyValue {
private final int foo = 3;
}
public static class MyController extends ControllerBase {
@ResponseConverter(MyValue.class)
public Optional<WebResponse> responseFilter(MyValue o) {
return Optional.of(this.renderJSON(o));
}
@GET("/")
public MyValue call() {
return new MyValue();
}
}
@ParamProcessor
You can implement your own controller parameter converter.
public static class MyController extends ControllerBase {
@ParamProcessor(targetClass = String.class)
public ParameterProcessorResult paramUpperQ(Parameter parameter) {
final Optional<String> q = this.getRequest().getQueryParams()
.getFirst("q");
if (q.isPresent()) {
return ParameterProcessorResult.fromData(q.get().toUpperCase());
} else {
final WebResponse response = this.renderError(400, "Missing Q");
return ParameterProcessorResult.fromWebResponse(response);
}
}
@GET("/")
public WebResponse index(String q) {
return this.renderText(q);
}
}
You can filter the injection target by annotation.
@Slf4j
public static class MyController extends ControllerBase {
@ParamProcessor(targetAnnotation = MyAnnotation.class)
public ParameterProcessorResult paramAnnotation(Parameter parameter) {
log.info("paramAnnotation");
return ParameterProcessorResult.fromData(3.14);
}
@GET("/annotation")
public WebResponse annotation(@MyAnnotation Double pi) {
return this.renderText("" + pi);
}
}
Concrete use case: Inject member object deflated from X-MY-TOKEN header.
Supported parameter types
Supported types by @Param, @BeanParam, and @PathParam are followings:
StringintshortlongdoublebooleanOptionalIntOptionalDoubleOptionalLongStringLong[]long[]Integer[]int[]Boolean[]boolean[]List<String>List<Integer>List<Long>List<Boolean>List<Double>Optional<String>
FAQ
Is there a HTML::FillInForm support?
No there isn't. You should do it with JavaScript.
Incompatible changes
0.35.0
- Removed
ControllerBase#getBaseDirectory() - AvansUtil was gone.
me.geso.APIResponsewas gone.me.geso.APIResponseno longer convertsAPIResponseby default.- You need to add your own response converter by
@ResponseConverter - Or, you can use BasicAPIResponse instead.
- You need to add your own response converter by
- Removed
ControllerBase#BEFORE_INIThook point. - Removed
ControllerBase#AFTER_INIThook point. - Removed
ControllerBase#getServletResponsemethod. - Removed
ControllerBase#BEFORE_DISPATCHmethod.- Use
@BeforeDispatchTriggermethod instead.
- Use
- ControllerBase no longer execute tinyvalidator by default.
- You need to implement avans-tinyvalidator on your controller class
- Removed
ControllerBase#GET_PARAMETERmethod.- Use
@ParamProcessormethod instead.
- Use
- Added JsonParamReader interface and JacksonJsonParamReader.
- It ignores unknown parameters by default.
- It throws IOException
- avans-session package was splitted from core
LICENSE
The MIT License (MIT) Copyright © 2014 Tokuhiro Matsuno, http://64p.org/ [email protected]
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.