Implements: IConfigurable, IReferenceable, IOpenable, IUnreferenceable, IRegisterable
Description
The RestController class allows you to create REST services that receive remote calls via the HTTP/REST protocol.
Configuration parameters
- base_route: base route for remote URI
- dependencies:
- endpoint: override for HTTP Endpoint dependency
- controller: override for Controller dependency
- connection(s):
- discovery_key: (optional) key to retrieve the connection from IDiscovery
- protocol: connection protocol (http or https)
- host: host name or IP address
- port: port number
- uri: resource URI or connection string with all parameters in it
- credential: the HTTPS credentials:
- ssl_key_file: SSL private key in PEM
- ssl_crt_file: SSL certificate in PEM
- ssl_ca_file: certificate authorities (root cerfiticates) in PEM
References
- *:logger:*:*:1.0 - (optional) ILogger components to pass log messages
- *:counters:*:*:1.0 - (optional) ICounters components to pass collected measurements
- *:traces:*:*:1.0 - (optional) ITracer components to record traces
- *:discovery:*:*:1.0 - (optional) IDiscovery services to resolve connection
- *:endpoint:http:*:1.0 - (optional) HttpEndpoint reference
Fields
Instance methods
close
Closes a component and frees used resources.
public
void close(IContext context) throws ApplicationException
- context: IContext - (optional) a context to trace execution through a call chain.
configure
Configures a component by passing its configuration parameters.
public
void configure(ConfigParams config) throws ConfigException
- config: ConfigParams - configuration parameters, containing a “connection(s)” section.
getTraceId
Returns correlationId from a request
protected
gString getTraceId(ContainerRequestContext req)
- req: ContainerRequestContext - an HTTP request
- returns: String - the correlation id from request.
instrument
Adds instrumentation to log calls and measure call time. It returns a Timing object that is used to end the time measurement.
protected
InstrumentTiming instrument(IContext context, String name)
- context: IContext - (optional) a context to trace execution through a call chain.
- name: String - method name.
- returns: InstrumentTiming - InstrumentTiming object to end the time measurement.
isOpen
Checks if the component is open.
public
boolean isOpen()
- returns: boolean - True if the component has been opened and False otherwise.
open
Opens the component.
public
void open(IContext context) throws ApplicationException
- context: IContext - (optional) a context to trace execution through a call chain.
registerInterceptor
Registers a middleware for a given route in HTTP endpoint.
protected
void registerInterceptor(String route, Function<ContainerRequestContext, ?> action)
- route: String - command route. Base route will be added to this route
- action: Function<ContainerRequestContext, ?> - action function that is called when middleware is invoked.
registerOpenApiSpec
Registers the open api spec.
protected
void registerOpenApiSpec(String content)
- content: String - response header content
registerOpenApiSpecFromFile
Registers the open api spec from a file.
protected
void registerOpenApiSpecFromFile(String path)
- path: String - path to the file
registerRoute
Registers a route in HTTP endpoint.
protected
void registerRoute(String method, String route, Schema schema, Inflector<ContainerRequestContext, Response> action)
- method: string - HTTP method: “get”, “head”, “post”, “put”, “delete”
- route: string - command route. The base route will be added to this route
- schema: Schema - validation schema to validate received parameters.
- action: (req: any, res: any) => void - action function that is called when an operation is invoked.
registerRouteWithAuth
Registers a route with authorization in HTTP endpoint.
protected
void registerRouteWithAuth(String method, String route, Schema schema, AuthorizeFunction<ContainerRequestContext, Inflector<ContainerRequestContext, Response>, Response> authorize, Inflector<ContainerRequestContext, Response> action)
- method: String - HTTP method: “get”, “head”, “post”, “put”, “delete”
- route: String - command route. The base route will be added to this route
- schema: Schema - validation schema to validate received parameters.
- authorize: AuthorizeFunction<ContainerRequestContext, Inflector<ContainerRequestContext, Response>, Response> - authorization interceptor
- action: (req: any, res: any) => void - action function that is called when an operation is invoked.
sendCreatedResult
Creates a callback function that sends a newly created object as JSON. The callack function call be called directly or passed as a parameter to business logic components.
If the object is not null, it returns 200 status code. For null results it returns 204 status code. If an error occurs, it sends ErrorDescription with the approproate status code.
protected
Response sendCreatedResult(Object result)
- result: Object - an execution result
- returns: Response - response.
sendDeletedResult
Creates a callback function that sends deleted object as JSON. That callack function call be called directly or passed as a parameter to business logic components.
If object is not null it returns 200 status code. For null results it returns 204 status code. If error occur it sends ErrorDescription with approproate status code.
protected
Response sendDeletedResult(Object result)
- result: Object - an execution result
- returns: Response - response.
sendError
Sends an error serialized as ErrorDescription object and the appropriate HTTP status code. If status code is not defined, it uses 500 status code.
protected
Response sendError(Exception ex)
- ex: Exception - exception
- returns: Response - response
sendResult
Creates a callback function that sends a result as a JSON object. The callack function call be called directly or passed as a parameter to business logic components.
If the object is not null it returns 200 status code. For null results, it returns 204 status code. If an error occurs, it sends ErrorDescription with the approproate status code.
protected
Response sendResult(Object result)
- result: Object - an execution result
- returns: Response - response.
setReferences
Sets references to dependent components.
public
void setReferences(IReferences references) throws ReferenceException, ConfigException
- references: IReferences - references to locate the component dependencies.
unsetReferences
Unsets (clears) previously set references to dependent components.
public
void unsetReferences()
Abstract methods
register
Registers all service routes in a HTTP endpoint.
This method is called by the service and must be overriden in child classes.
public abstract
void register() throws ReferenceException
Examples
{@code
class MyRestController extends RestController {
private IMyService _service;
...
public MyRestController() {
super();
this._dependencyResolver.put(
"service",
new Descriptor("mygroup","service","*","*","1.0")
);
}
public void setReferences(IReferences references) {
super.setReferences(references);
this._service = (IMyService)this._dependencyResolver.getRequired("service");
}
public void register() {
this.registerRoute(
HttpMethod.GET, "/get_mydata",
null,
this::getData
);
...
}
private Response getData(ContainerRequestContext req) {
...
}
}
MyRestController controller = new MyRestController();
controller.configure(ConfigParams.fromTuples(
"connection.protocol", "http",
"connection.host", "localhost",
"connection.port", 8080
));
controller.setReferences(References.fromTuples(
new Descriptor("mygroup","service","default","default","1.0"), service
));
controller.open("123");
System.out.println("The REST controller is running on port 8080");
}