Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/amayaframework/amaya-core
Placeholder
https://github.com/amayaframework/amaya-core
Last synced: 3 days ago
JSON representation
Placeholder
- Host: GitHub
- URL: https://github.com/amayaframework/amaya-core
- Owner: AmayaFramework
- License: apache-2.0
- Created: 2022-01-28T21:32:58.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-09-23T16:37:25.000Z (5 days ago)
- Last Synced: 2024-09-24T20:51:06.321Z (3 days ago)
- Language: Java
- Homepage:
- Size: 400 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# UNDER BIG RECONSTRUCTION
main&develop branches is totally outdated.
# amaya-core [](https://repo1.maven.org/maven2/io/github/amayaframework/amaya-core/)
The basis of the amaya framework, which provides basic functionality.
It includes basic implementations of routes, filters, controllers, http transactions and everything related to them,
method packaging, as well as assistive utilities.
## Getting Started
To install it, you will need:
* java 8+
* [classindex](https://github.com/atteo/classindex)
* some implementation of slf4j
* Maven/Gradle
## Installing
### Gradle dependency
```Groovy
dependencies {
implementation group: 'org.atteo.classindex', name: 'classindex', version: '3.11'
annotationProcessor group: 'org.atteo.classindex', name: 'classindex', version: '3.11'
implementation group: 'io.github.amayaframework', name: 'amaya-core', version: 'LATEST'
}
```
### Maven dependency
```
org.atteo.classindex
classindex
3.11
io.github.amayaframework
amaya-core
LATEST
```
## Usage example
### A quick overview
The core of the framework is its mandatory part, the main one, the functionality of which
will somehow be used by the rest of the parts.
The core provides ample opportunities for customization of the framework functionality:
* implementation of user code in the process of interaction between the controller and the network code
* creating custom filters for path parameters
* creation of additional annotations for injecting values into the arguments of the route method
* creating custom packers for controller methods
* creating a custom router (a mechanism that finds the necessary method according to the received path)
* creating custom classes that implement standard HttpRequest and HttpResponse
Important
The kernel does NOT contain implementations for any particular http-server/java-servlets
to increase the versatility and customization of the framework.
### Pipelines
To communicate the controller with the http server, the framework uses a mechanism called "pipeline".
In fact, it is a changeable chain of named functions that are executed sequentially/asynchronously.
Thus, you can create your own actions for their subsequent implementation.
Custom action
```Java
public class MyAction extends PipelineAction {
@Override
public RequestData execute(RequestData data) {
// Do something
return data;
}
}
```
Inserting
```Java
public class MyConfigurator implements Configurator {
@Override
public void configureController(Controller controller) {
// Do something
}
@Override
public void configureInput(NamedPipeline input) {
input.put(new MyAction());
}
@Override
public void configureOutput(NamedPipeline output) {
// Do something
}
}
```
### Filters for path parameters
The route may contain any parameters (for example, "/a/{b:int}")
To check whether the sent parameter matches the expected type (b must be of type int), filters (filter) are used,
which in this case
a) transform b from the string representation into int,
b) in case of inconsistency, report this to the framework by means of an exception
You can very easily create your own filter in this way:
```Java
@NamedFilter("int")
public class IntegerFilter implements Filter {
@Override
public Object transform(String source) {
return Integer.parseInt(source);
}
}
```
### Annotations for injecting route method arguments
The injection of values into method arguments in the framework is implemented by redirecting the return value of
the HttpRequest getter method.
Thus, any inject annotation is, in fact, a repository of arguments that should be passed to the getter.
For example, in the case of @Path("param") (annotation to get the path parameter),
the method will be called HttpRequest::getpathparameters with the argument "param",
and the value it returns will be in the annotated argument.
By default, there are 5 such annotations (Header, Http Cookie, Path, Query, Body) and custom ones can be added.
To do this, you will need to create your own annotation (if it has parameters, explicitly specify their position)
and link it to the getter in your HttpRequest implementation.
Implementation
Custom request
```Java
@SourceRequest(MyReq.class)
public class MyReq extends CommonHttpRequest {
public MyReq(HttpRequest body) {
super(body);
}
@Provider(MyAnnot.class)
public String getSome(String a, int b) {
return a + b;
}
}
```
Custom annotation
```Java
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnot {
@Position
String a();
@Position(1)
int b();
}
```
### Controller Method Packers
In general, the task of the packager is to turn a pair from an instance of your controller and
a method (from java-reflect) into a ready-to-call Action.
Example of dummy implementation using java reflection
```Java
public static class MyPacker implements Packer {
@Override
public Action pack(Object instance, Method method) {
return request -> (HttpResponse) method.invoke(instance, request);
}
}
```
### Routers
The router processes the path that came from the user and directs it to the appropriate route.
For example, "/index/5" will be routed to "/index/{i:int}".
Although the kernel provides the necessary minimum of routers by default, if you lack their functionality,
you can implement your own.
Example of a plain router embedded in the core
```Java
public class BaseRouter extends MethodRouter {
@Override
public MethodRoute follow(HttpMethod method, String route) {
Map methodRoutes = routes.get(method);
if (methodRoutes == null) {
return null;
}
return methodRoutes.get(route);
}
}
```
### Custom HttpRequest and HttpResponse
If you need to create custom entities that implement a http transaction,
you just need to inherit from ready-made existing classes.
Custom http request
```Java
public class MyReq extends CommonHttpRequest {
public MyReq(HttpRequest body) {
super(body);
}
// Some code
}
```
Custom http response
```Java
public class MyResp extends CommonHttpResponse {
// Some code
}
```
## Built With
* [Gradle](https://gradle.org) - Dependency management
* [classindex](https://github.com/atteo/classindex) - Annotation scanning
* [jeflect](https://github.com/RomanQed/jeflect) - Method wrapping
* [slf4j](https://www.slf4j.org) - Logging facade
* [javax.servet](https://docs.oracle.com/javaee/7/api/javax/servlet/Servlet.html) - Servlets
* [http-utils](https://github.com/AmayaFramework/http-utils) - Some http stuff
* [java-utils](https://github.com/RomanQed/java-utils) - Pipelines and other stuff
## Authors
* **RomanQed** - *Main work* - [RomanQed](https://github.com/RomanQed)
* **max0000402** - *Technical advices and ideas for features* - [max0000402](https://github.com/max0000402)
See also the list of [contributors](https://github.com/AmayaFramework/amaya-core/contributors) who participated
in this project.
## License
This project is licensed under the Apache License Version 2.0 - see the [LICENSE](LICENSE) file for details
## Acknowledgments
Thanks to everyone who was interested in this library, gave advice and suggested ideas.