From de452c1ab553b16b1d143e0670469e4558825f97 Mon Sep 17 00:00:00 2001 From: Andrea Di Cesare Date: Fri, 12 Jan 2024 18:27:00 +0100 Subject: [PATCH] :memo: Update documentation for examples [skip ci] --- examples/README.md | 62 +++++++++++++++++++--------- examples/bytes-array-service/run.sh | 5 --- examples/form-handler/run.sh | 5 --- examples/greeter-service/run.sh | 5 --- examples/instance-name/run.sh | 5 --- examples/mongo-status-service/run.sh | 5 --- examples/node-plugin/README.md | 6 +-- 7 files changed, 45 insertions(+), 48 deletions(-) delete mode 100755 examples/bytes-array-service/run.sh delete mode 100755 examples/form-handler/run.sh delete mode 100755 examples/greeter-service/run.sh delete mode 100755 examples/instance-name/run.sh delete mode 100755 examples/mongo-status-service/run.sh diff --git a/examples/README.md b/examples/README.md index 09cfebd6e5..16e9349464 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,30 +1,52 @@ # RESTHeart Example Plugins - - [Greeter Service](greeter-service/README.md) - A basic Java REST Web service with JSON payloads (implements `JsonService`) -- [User Signup](user-signup/README.md) - Implements a user signup process. This is an example of a complex process implemented with few interceptors, a service and uses json schema validation and security permissions - - [Hello World](bytes-array-service/README.md) - A basic Java REST Web service with text payloads (implements `ByteArrayService`) - - [MongoDB serverStatus service](mongo-status-service/README.md) - Exposes the `serverStatus` MongoDB system call; shows how to inject the `MongoClient` in a plugin. - - [Random String](random-string-service/README.md) - Service that just return a random number; shows how to deploy a service that uses external dependencies. - - [CSV Interceptor](csv-interceptor/README.md) - Converts coordinates from [CSV](https://en.wikipedia.org/wiki/Comma-separated_values) to a [GeoJSON](https://geojson.org) object; shows how to transform the requests handled by an existing Service with Interceptors.. - - [Kotlin Greeter Service](kotlin-greeter-service/README.md) - Simple service implemented in Kotlin programming language. - - [Credit Card Hider](credit-card-hider/README.md) - Simple JavaScript Interceptor to obfuscate the credit card numbers from the response of the MongoService. Shows how to transform the response generated by an existing Service with Interceptors. - - [Protocol Buffer Contacts](protobuffer-contacts/README.md) - Interceptors that modify the request and response to MongoService to use Protocol Buffer as payloads. - - [Freemarker HTML page](freemarker/README.md) - This example uses [Apache Freemarker](https://freemarker.apache.org/) to generate an HTML Web site. +This collection showcases various RESTHeart plugins, each serving a specific purpose. Below is a brief overview of each plugin: - ## Requirements to build and run the examples +## Java Plugins - You need java 17, Docker. + - **[Greeter Service](greeter-service/README.md)**: Implements a basic Java REST Web service returning JSON payloads. Demonstrates usage of `JsonService`. + - **[Example Configuration Files](example-conf-files/README.md)**: Provides a collection of sample configuration files for RESTHeart. + - **[User Signup](user-signup/README.md)**: Facilitates user signup processes. Utilizes interceptors, services, JSON schema validation, and security permissions. + - **[Slack Notifier](slack-notifier/README.md)**: An asynchronous interceptor that posts messages to a Slack channel when a document is created in a specified collection. + - **[Hello World](bytes-array-service/README.md)**: A simple Java REST Web service delivering text payloads. Employs `ByteArrayService`. + - **[MongoDB serverStatus Service](mongo-status-service/README.md)**: Offers access to MongoDB's `serverStatus` system call and demonstrates how to inject the `MongoClient` in a plugin. + - **[Random String Service](random-string-service/README.md)**: Provides random strings. Showcases deployment of services with external dependencies. + - **[CSV Interceptor](csv-interceptor/README.md)**: Transforms CSV coordinates into GeoJSON objects. Illustrates how to modify requests with Interceptors. + - **[Protocol Buffer Contacts](protobuffer-contacts/README.md)**: Interceptors adjusting request and response formats to and from MongoService for Protocol Buffer payloads. + - **[Freemarker HTML page](freemarker/README.md)**: Generates HTML Web pages using [Apache Freemarker](https://freemarker.apache.org/). + - **[Custom Logging Field](custom-logging-field/README.md)**: Details adding custom fields to logs via MDC Context. + - **[Form Header](form-header/README.md)**: A Service with a bespoke `Request` to manage Form POST requests. + - **[Instance name](instance-name/README.md)**: Adds an `X-Restheart-Instance` header to responses handled by `MongoService`. + - **[X-Headers-to-qparams](x-headers-to-qparams/README.md)**: An interceptor that converts headers into query parameters. + - **[X-Powered-By Remover](x-powered-by-remover/README.md)**: Response interceptors that remove the `X-Powered-By: restheart.org` header from service and proxied resource responses. - Some examples also require MongoDB running on localhost. +# Kotlin Plugins - Install java it with [sdk](https://https://sdkman.io/) +- **[Kotlin Greeter Service](kotlin-greeter-service/README.md)**: A basic service implemented using Kotlin. - ```bash - $ sdk install java 17.0.9-tem - ``` +# JavaScript Plugins -The examples also uses maven, but this is available through `mwnw` (Maven wrapper), so there is no need to install it. +- **[JavaScript Plugins](js-plugin/README.md)**: A compilation of example JavaScript plugins. +- **[Node Plugin](node-plugin/README.md)**: A JavaScript plugin for RESTHeart, running on GraalVM's Node.js implementation. +- **[Credit Card Hider](credit-card-hider/README.md)**: A JavaScript Interceptor that obfuscates credit card numbers in responses. Demonstrates response transformation in existing Services. -To easily run RESTHeart, you also need Docker. +## Requirements to Build and Run the Examples -To execute test requests, you need the http CLI command [httpie](https://httpie.io/cli). \ No newline at end of file +To work with these examples, the following are required: + +1. **Java 17**: Install it using [sdkman](https://sdkman.io/): + ```bash + $ sdk install java 17.0.9-tem + ``` + +2. **Docker**: Necessary for running RESTHeart. + +3. **MongoDB**: Some examples need a MongoDB instance running locally. + +4. **HTTPie**: A command-line HTTP client for testing, available at [httpie.io/cli](https://httpie.io/cli). + +Note: The examples use Maven, but it's accessible through the included Maven wrapper (`mvnw`), so a separate installation is not required. + +--- + +This revision organizes the plugins list into a more readable format, adds a brief description to each plugin for context, and clarifies the requirements section for better user guidance. \ No newline at end of file diff --git a/examples/bytes-array-service/run.sh b/examples/bytes-array-service/run.sh deleted file mode 100755 index 59a8f02200..0000000000 --- a/examples/bytes-array-service/run.sh +++ /dev/null @@ -1,5 +0,0 @@ -#!/bin/bash - -source ../utils.sh - -run bytes-array-service.jar \ No newline at end of file diff --git a/examples/form-handler/run.sh b/examples/form-handler/run.sh deleted file mode 100755 index 59a8f02200..0000000000 --- a/examples/form-handler/run.sh +++ /dev/null @@ -1,5 +0,0 @@ -#!/bin/bash - -source ../utils.sh - -run bytes-array-service.jar \ No newline at end of file diff --git a/examples/greeter-service/run.sh b/examples/greeter-service/run.sh deleted file mode 100755 index 59a8f02200..0000000000 --- a/examples/greeter-service/run.sh +++ /dev/null @@ -1,5 +0,0 @@ -#!/bin/bash - -source ../utils.sh - -run bytes-array-service.jar \ No newline at end of file diff --git a/examples/instance-name/run.sh b/examples/instance-name/run.sh deleted file mode 100755 index be96772740..0000000000 --- a/examples/instance-name/run.sh +++ /dev/null @@ -1,5 +0,0 @@ -#!/bin/bash - -source ../utils.sh - -run instance-name.jar \ No newline at end of file diff --git a/examples/mongo-status-service/run.sh b/examples/mongo-status-service/run.sh deleted file mode 100755 index 0abd6e5928..0000000000 --- a/examples/mongo-status-service/run.sh +++ /dev/null @@ -1,5 +0,0 @@ -#!/bin/bash - -source ../utils.sh - -run mongo-status-service.jar \ No newline at end of file diff --git a/examples/node-plugin/README.md b/examples/node-plugin/README.md index 5cafeaa7a2..e62c9ccb00 100644 --- a/examples/node-plugin/README.md +++ b/examples/node-plugin/README.md @@ -21,8 +21,8 @@ $ git clone --depth 1 git@github.com:SoftInstigate/restheart.git (here we use the brilliant sdkman) ```bash -$ sdk install java 22.3.r17-grl -$ sdk use java 22.3.r17-grl +$ sdk install java 17.0.9-graal +$ sdk use java 17.0.9-graal $ gu install nodejs ``` @@ -38,7 +38,7 @@ Where is the RESTHeart installation directory. ## Run RESTHeart on Node ```bash -$ $(sdk home java 22.3.r17-grl)/bin/node --jvm --vm.cp=restheart.jar restheart.js +$ $(sdk home java 17.0.9-graal)/bin/node --jvm --vm.cp=restheart.jar restheart.js ``` (we use `sdk home` to make sure to use the GraalVM's node implementation)