Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

Introduction

Request Hooks allow to execute custom code after a request completes.

Info

For example, request hooks can be used:

  • to send a confirmation email when a user registers 
  • to send push notifications when a resource is updated so that its properties satisfy a given condition.

Request Hooks are implemented in java and declared in the RESTHeart configuration file; once they are ready, they can be bound to resources via the hooks collection metadata.

Info

The class(es) that implements the Hook must be added to the java classpath.

For example, if the hook is packaged in the myhook.jar file, start RESTHeart with the following command:

$ java -server -classpath restheart.jar:myhook.jar org.restheart.Bootstrapper restheart.yml

Another option is packaging the classes with RESTHeart in a single jar using the maven shade plugin. For more information refer to the How to package custom code section.

The hooks collection metadata

With RESTHeart, not only documents but also dbs and collections have properties. Some properties are metadata, i.e. they have a special meaning for RESTheart that influences its behavior.

The collection metadata property hooks allows to declare the hooks to be applied to the requests involving the collection and its documents.

hooks is an array of objects with the following format:

Code Block
languagejs
themeMidnight
{ "hooks": [ 
    { "name": <hook_name>, "args": <arguments> }, 
    ...
   ]
}


Property
Description
Mandatory
name

name of the hook as defined in the configuration file.

Yes
argsarguments to be passed to the hook.No

How to develop an Hook

Hooks are developed implementing the java interface org.restheart.hal.metadata.singletons.Hook.

To add a dependency on RESTHeart using Maven, use the following:

Code Block
languagexml
<dependency>
    <groupId>org.restheart</groupId>
    <artifactId>restheart</artifactId>
    <version>2.0.0</version>
</dependency>

The Hook interface requires to implement two methods:

  • doesSupportRequests(RequestContext context)
  • hook(HttpServerExchange exchange, RequestContext context, BsonValue args);

The method doesSupportRequests() determines if the hook() method should be executed checking the RequestContext object that encapsulates all information about the request.

For instance, the following implementation returns true if the request actually created a document (either POSTing the collection or PUTing the document):

Code Block
languagejava
@Override
public boolean doesSupportRequests(RequestContext rc) {
    if (rc.getDbOperationResult() == null) {
        return false;
    }

    int status = rc.getDbOperationResult().getHttpCode();

    return (status == HttpStatus.SC_CREATED
            && (rc.getType() == RequestContext.TYPE.COLLECTION && rc.getMethod() == POST
            || rc.getType() == RequestContext.TYPE.DOCUMENT && rc.getMethod() == PUT));
}

Note the following useful RequestContext getters:



getDbOperationResult()returns the OperationResult object that encapsulates the information about the MongoDB operation, including the resource status (properties) before and after the request execution.
getType()returns the request resource type, e.g. DOCUMENT, COLLECTION, etc.
getMethod()returns the request method, e.g. GET, PUT, POST, PATCH, DELETE, etc.

The hook() method is where the custom logic is defined.

It has three arguments:

  • the HttpServerExchange and the RequestContext that give information about the request
  • the optional json args object specified in the hook collection metadata.

How to declare an Hook in the configuration file

The metadata-named-singletons section of the configuration file defines, among others, the hooks group: here hook implementation classes can be bound to logical names that can be used in the hooks collection metadata.

The following is the default hooks configuration that declares the example snooper hook (that just logs resource status before and after request db operation execution).

Code Block
languagetext
themeMidnight
metadata-named-singletons:
    - group: hooks
      interface: org.restheart.hal.metadata.singletons.Hook
      singletons:
        - name: snooper
          class: org.restheart.hal.metadata.singletons.SnooperHook