EzyHTTP Annotations

EzyHTTP provides a list of annotations:

#	Annotation	Scopes	Description
1	Api	Class, Method	Indicates whichs APIs are mapping to the classes or methods is API
2	ApplicationBootstrap	Class	EzyHttp will load the annotated class first
3	BodyConvert	Class	For request body converter class
4	Async	Method	Indicates the APIs is mapping to annotated method is async
5	Authenticated	Class, Method	Indicates the URIs are mapping to the annotated class or methods are Authenticated
6	ComponentClasses	Class	Registers singleton class to bean manager
7	ComponentsScan	Class	Registers package to scan to bean manager
8	Controller	Class	Indicates the annotated class is controller
9	DoDelete	Method	Indicates which URI is mapping to the annotated method is DELETE
10	DoGet	Method	Indicates which URI is mapping to the annotated method is GET
11	DoPost	Method	Indicates which URI is mapping to the annotated method is POST
12	DoPut	Method	Indicates which URI is mapping to the annotated method is PUT
13	ExceptionHandler	Class	Indicates the annotated class will handle exceptions
14	Interceptor	Class	Indicate the annotated class will intercept requests
15	PathVariable	Parameter	Maps a path variable to a java parameter
16	PropertiesSources	Class	Regiesters properties file to the bean managemer
17	RequestArgument	Parameter	Maps a request argument to a java parameter
18	RequestBody	Parameter	Maps a request body to a java parameter
19	RequestCookie	Parameter	Maps a request cookie to a java parameter
20	RequestHeader	Parameter	Maps a request header to a java parameter
21	RequestParam	Parameter	Maps a request prameter to a java parameter
22	Service	Class	Register a service class to the bean mananager, it's equals to EzySingleton but more meaningful
23	StringConvert	Class	Registers a string converter class to the bean manager
24	TryCatch	Method	Indicates the annotated method will handle the exception in TryCatch

1. Api

When you annotate a class with this annotation then all URIs in the class will be API. In bellow example, 2 URIs /api/v1/author/add and /api/v1/author/{authorId} will be API:

@Api
@Controller("/api/v1/author")
public class AuthorController {
    @DoPost("/add")
    public AuthorResponse addAuthor(@RequestBody AddAuthorRequest request) {
       // implementation
    }

    @DoGet("/{authorId}")
    public AuthorResponse getAuthor(@PathVariable long authorId) {
        // implementation
    }
}

But in some cases, you just want to specific som methods in a controller is a controller, so you can use Api annotation on the methods, example:

@Api
@DoPost("/book/add")
public BookResponse addBook(@RequestBody AddBookRequest request) {
    // implementation
}

You can use RequestUriManager.isAuthenticatedURI to check whether an URI is API or not, please take a look EzyHTTP Request Inteceptor for more details.

2. ApplicationBootstrap

This annotation is useful when you want to create a new entrypoint for EzyHTTP, example entrypoint for tomcat, glassfish, jboss, ... Currently EzyHTTP is using JettyApplicationBootstrap

3. BodyConvert

When you want to create a new request body converter, you need use annotation to help bean manager detects and registers the converter class, example:

@BodyConvert(ContentTypes.APPLICATION_XML)
private static class JsonBodyDataConverter implements BodyConverter {
    @Override
    public byte[] serialize(Object body) throws IOException {
        // implementation
    }
    @Override
    public <T> T deserialize(String data, Class<T> bodyType) throws IOException {
        // implementation
    }
}

4. Async

When you want to handle an request in async mode, you can use this annotation. It's suitalbe for taken time APIs like upload or download APIs, example:

@Async
@DoGet("/files/{file}")
public void uploadPost(
    RequestArguments requestArguments,
    @PathVariable("file") String file,
) throws Exception {
    ResourceRequestHandler handler = new ResourceRequestHandler(
        "files/" + file,
        "files/" + file,
        EzyFileUtil.getFileExtension(file),
        resourceDownloadManager
    );
    handler.handle(requestArguments);
}

5. Authenticated

You can use this annotation on class or method like this:

@Authenticated
@Controller
public class UserController {
    // implementation
}

@Authenticated
@DoGet("/user/update")
public View userUpdateGet(@UserId long userId) {
    // implementation
}

And then you can check URI is authenticated or not like this:

@Interceptor
public class AuthenticationInterceptor implements RequestInterceptor {

    private final RequestURIManager requestUriManager;
    
    @Override
    public boolean preHandle(RequestArguments arguments, Method handler) throws Exception {
        final HttpMethod method = arguments.getMethod();
        final String uri = arguments.getUriTemplate();

        if (!requestUriManager.isAuthenticatedURI(method, uri)) {
            return true;
        }
        // implementation
    }
}

6. ComponentClasses

You can use this annotation in a class to register bean classes to the bean manager like this:

@ComponentClasses({ EventService.class })
public class GlobalConfig {
}

7. ComponentsScan

You can use this annotation in a class to register packages to scan to the bean manager

@ComponentsScan({
    "com.tvd12.ezyhttp.server.core.test"
})
public class BootApp {}

8. Controller

You can only use this annotation for controller class, example:

@Controller
public class UserController {

    @DoGet("/user/update")
    public View userUpdateGet(@UserId long userId) {
        // implementation
    }
}

9. DoDelete

You can use this annotation for method that handles a delete request URI, for more information, please refer Handle Client Requests guide

10. DoGet

You can use this annotation for method that handles a get request URI, for more information, please refer Handle Client Requests guide

11.DoPost

You can use this annotation for method that handles a post request URI, for more information, please refer Handle Client Requests guide

12. DoPut

You can use this annotation for method that handles a put request URI, for more information, please refer Handle Client Requests guide

13. ExceptionHandler

You can use this annotation for a class that handles exceptions, please refer Handle Exceptions guide

14. Interceptor

You can use this annotation for a class that intercepts client requests, please refer Request Interceptor guide

15. PathVariable

You can you this annotation for a method parameter that maps to a URI path variable, please refer Request Arguments guide

16. PropertiesSources

You can use this annotation in a class to register properties sources to the bean manager, example

@PropertiesSources({
    "my-configuration.yaml",
    "app-configuration.properties"
})
public class GlobalConfig {
}

17. RequestArgument

You can you this annotation for a method parameter that maps a request argument, please refer Request Arguments guide

18. RequestBody

You can you this annotation for a method parameter that maps a request body, please refer Request Arguments guide

19. RequestCookie

You can you this annotation for a method parameter that maps a request cookie, please refer Request Arguments guide

20. RequestHeader

You can you this annotation for a method parameter that maps a request header, please refer Request Arguments guide

21. RequestParam

You can you this annotation for a method parameter that maps a request parameter, please refer Request Arguments guide

22. Service

You can use this annotation for a service class, example:

@Service
public class BookService {
    // implementation
}

23. StringConvert

You can use this annotation for a class that is a StringConverter, example:

@StringConvert
public class MyStringConverter extends DefaultStringDeserializer {

    public MyStringConverter() {
        mappers.put(List.class, v -> {
            String[] strs = v.split(",");
            return Lists.newArrayList(strs);
        });
    }
}

24. TryCatch

You can use this annotation for a method that handles exceptions, please refer Handle Exceptions guide

Next Step

You can take a look the list of ezyhttp server properties