Skip to content

Latest commit

 

History

History
222 lines (142 loc) · 11.8 KB

README.md

File metadata and controls

222 lines (142 loc) · 11.8 KB
Raw

xoom-schemata

Gitter Docker Stars Docker Pulls Build

The VLINGO XOOM Schema Registry.

Quick Start

Docker

The quickest way to run XOOM Schemata is to use the docker image published by the VLINGO XOOM Team:

docker run -it --rm -eXOOM_ENV=dev -p '9019:9019' vlingo/xoom-schemata

TIP: When using Docker to run XOOM Designer integrated with XOOM Schemata, name your Schemata container with --name xoom-schemata so that you can reference it in Designer-Schemata integration options:

docker run -it --rm -eXOOM_ENV=dev -p9019:9019 --name xoom-schemata vlingo/xoom-schemata

Select the Designer menu OPTIONS, and use the image name as the host.

designer-schemata-options

Maven

⚠️ Make sure you are using a Java 8 JDK.

Build 

& "{yourInstallPath}\xoom-schemata\mvnw.cmd" clean package -Pfrontend -f "{yourInstallPath}\xoom-schemata\pom.xml"
e.g. 
& "d:\vlingo\xoom-schemata\mvnw.cmd" clean package -Pfrontend -f "d:\vlingo\xoom-schemata\pom.xml"

Run 

java -jar target/xoom-schemata-{version}-jar-with-dependencies.jar
e.g. 
java -jar target/xoom-schemata-1.8.2-SNAPSHOT-jar-with-dependencies.jar

We provide an interface to allow for easy retrieval of schemata and schemata meta information, e.g. available versions and publication status. The UI/Frontend can be accessed at http://localhost:9019.

Advanced Options

Build

If you have maven installed, you can run the full build using: mvn clean package -Pfrontend Else, there is also a maven wrapper, so you can also build using the command in Quick Start.

The maven build takes care of the following:

  • Generate sources for the schema grammars in src/main/antlr4
  • Build the backend application
  • Download the dependencies for the UI build (node & npm) [Maven Profile 'frontend']
  • Run the UI build (npm run export in src/main/frontend) [Maven Profile 'frontend']
  • Package the backend, frontend and dependencies within a fat jar

Docker Build

After building, you can optionally build the docker container with docker build . -t vlingo/xoom-schemata.

GraalVM Build

mvn clean package -Pfrontend -Pnative-image
./target/xoom-schemata

More details GraalVM

Run

If you want to configure the schemata runtime profile, you have several options:

java -jar target/xoom-schemata-{version}-jar-with-dependencies.jar {arg}
arg What does it do? Properties file
dev starts with an in-memory HSQLDB src/main/resources/xoom-schemata-dev.properties
prod starts with a preconfigured PostgreSQL DB src/main/resources/xoom-schemata-prod.properties
env uses environment variables for configuration src/main/resources/xoom-schemata-env.properties

e.g. 

java -jar target/xoom-schemata-1.5.1-SNAPSHOT-jar-with-dependencies.jar dev

env:

The defaults are the same as configured in dev.

Property Variable Default
server.port XOOM_SCHEMATA_PORT 9019
database.type XOOM_SCHEMATA_DB_TYPE io.vlingo.xoom.schemata.infra.persistence.HSQLDBSchemataObjectStore
database.driver XOOM_SCHEMATA_DB_DRIVER org.hsqldb.jdbc.JDBCDriver
database.url XOOM_SCHEMATA_DB_URL jdbc:hsqldb:mem:
database.name XOOM_SCHEMATA_DB_NAME xoom_schemata
database.username XOOM_SCHEMATA_DB_USER SA
database.password XOOM_SCHEMATA_DB_PASS
database.originator XOOM_SCHEMATA_DB_ORIGINATOR MAIN

Docker Run:

You can run the registry with an in-memory database within docker using docker run -p9019:9019 vlingo/xoom-schemata. The docker image supports the three runtime profiles by setting $XOOM_ENV inside the Dockerfile accordingly.

Usage

You can find detailed instructions at: https://docs.vlingo.io/xoom-schemata#working-with-schema-specifications-and-schema-dependencies.

An example for talking to the schema registry as part of a maven build: https://github.com/vlingo/xoom-examples/tree/master/xoom-schemata-integration

API Examples

Schema Definitions:

$ curl -i -X POST -H "Content-Type: application/json" -d '{"organizationId":"","name":"Org1","description":"My organization."}' http://localhost:9019/api/organizations

$ curl -i -X POST -H "Content-Type: application/json" -d '{"organizationId":"","unitId":"","name":"Unit1","description":"My unit."}' http://localhost:9019/api/organizations/{orgId}/units

$ curl -i -X POST -H "Content-Type: application/json" -d '{"organizationId":"","unitId":"","contextId":"","namespace":"io.vlingo.xoom.schemata","description":"Schemata Context."}' http://localhost:9019/api/organizations/{orgId}/units/{unitId}/contexts

$ curl -i -X POST -H "Content-Type: application/json" -d '{"organizationId":"","unitId":"","contextId":"","schemaId":"","category":"Event","name":"SchemaDefined","description":"Schemata was defined event."}' http://localhost:9019/api/organizations/{orgId}/units/{unitId}/contexts/{contextId}/schemas

$ curl -i -X POST -H "Content-Type: application/json" -d '{"organizationId":"","unitId":"","contextId":"","schemaId":"","schemaVersionId":"","description":"Initial revision.","specification":"event SchemaDefined { type eventType }","status":"Draft","previousVersion":"0.0.0","currentVersion":"1.0.0"}' http://localhost:9019/api/organizations/{orgId}/units/{unitId}/contexts/{contextId}/schemas/{schemaId}/versions

Schema Queries:

$ curl -i -X GET -H "Accept: application/json" http://localhost:9019/api/organizations

$ curl -i -X GET -H "Accept: application/json" http://localhost:9019/api/organizations/{orgId}

$ curl -i -X GET -H "Accept: application/json" http://localhost:9019/api/organizations/{orgId}/units

$ curl -i -X GET -H "Accept: application/json" http://localhost:9019/api/organizations/{orgId}/units/{unitId}

$ curl -i -X GET -H "Accept: application/json" http://localhost:9019/api/organizations/{orgId}/units/{unitId}/contexts

$ curl -i -X GET -H "Accept: application/json" http://localhost:9019/api/organizations/{orgId}/units/{unitId}/contexts/{contextId}

$ curl -i -X GET -H "Accept: application/json" http://localhost:9019/api/organizations/{orgId}/units/{unitId}/contexts/{contextId}/schemas

$ curl -i -X GET -H "Accept: application/json" http://localhost:9019/api/organizations/{orgId}/units/{unitId}/contexts/{contextId}/schemas/{schemaId}

$ curl -i -X GET -H "Accept: application/json" http://localhost:9019/api/organizations/{orgId}/units/{unitId}/contexts/{contextId}/schemas/{schemaId}/versions

$ curl -i -X GET -H "Accept: application/json" http://localhost:9019/api/organizations/{orgId}/units/{unitId}/contexts/{contextId}/schemas/{schemaId}/versions/{versionId}

$ curl -i -X GET -H "Accept: application/json" http://localhost:9019/api/schema/categories

  • Enumeration names: Command, Data, Document, Envelope, Event, Unknown

$ curl -i -X GET -H "Accept: application/json" http://localhost:9019/api/schema/scopes

  • Enumeration names: Public, Private

$ curl -i -X GET -H "Accept: application/json" http://localhost:9019/api/code/{reference}/{language}

  • Takes the form: /code/Org:Unit:Context:Schema:Version/Language
  • Or more precisely: /code/vlingo:PlatformDevelopment:io.vlingo.xoom.schemata:SchemaDefined:1.0.0/java

Schema Modifications:

$ curl -i -X PATCH -H "Content-Type: application/json" -d 'My organization changed.' http://localhost:9019/api/organizations/{organizationId}/description $ curl -i -X PATCH -H "Content-Type: application/json" -d 'Org123' http://localhost:9019/api/organizations/{organizationId}/name

$ curl -i -X PATCH -H "Content-Type: application/json" -d 'My unit changed.' http://localhost:9019/api/organizations/{orgId}/units/{unitId}/description $ curl -i -X PATCH -H "Content-Type: application/json" -d 'Unit123' http://localhost:9019/api/organizations/{orgId}/units/{unitId}/description

$ curl -i -X POST -H "Content-Type: application/json" -d 'My context changed.' http://localhost:9019/api/organizations/{organizationId}/units/{unitId}/contexts/{contextId}/description $ curl -i -X POST -H "Content-Type: application/json" -d 'io.vlingo.xoom.schemata.changed' http://localhost:9019/api/organizations/{organizationId}/units/{unitId}/contexts/{contextId}/namespace

$ curl -i -X POST -H "Content-Type: application/json" -d 'Command' http://localhost:9019/api/organizations/{organizationId}/units/{unitId}/contexts/{contextId}/schemas/{schemaId}/cateogry $ curl -i -X POST -H "Content-Type: application/json" -d 'DefineSchema command defined.' http://localhost:9019/api/organizations/{organizationId}/units/{unitId}/contexts/{contextId}/schemas/{schemaId}/description $ curl -i -X POST -H "Content-Type: application/json" -d 'DefineSchema' http://localhost:9019/api/organizations/{organizationId}/units/{unitId}/contexts/{contextId}/schemas/{schemaId}/name

$ curl -i -X POST -H "Content-Type: application/json" -d 'Initial revision of SchemaDefined.' http://localhost:9019/api/organizations/{orgId}/units/{unitId}/contexts/{contextId}/schemas/{schemaId}/versions/{versionId}/description $ curl -i -X POST -H "Content-Type: application/json" -d 'event SchemaDefined { type eventType\n timestamp occurredOn }' http://localhost:9019/api/organizations/{orgId}/units/{unitId}/contexts/{contextId}/schemas/{schemaId}/versions/{versionId}/specification $ curl -i -X POST -H "Content-Type: application/json" -d 'Published' http://localhost:9019/api/organizations/{orgId}/units/{unitId}/contexts/{contextId}/schemas/{schemaId}/versions/{versionId}/status

Development

Backend

Prerequisites:

  • Java 8

  • Maven, 3.6.0 is known to work, alternatively, you can rely on the bundled maven wrapper

  • Generate schema specification sources: mvn generate-sources

  • Test: mvn test

  • Build fat jar: mvn package

Frontend

Prerequisites:

  • Node 12.18.3 is known to work
  • If you use vscode, recommended extensions: Svelte for VS Code, Svelte Intellisense

The UI is built using Svelte and Svelte-Materialify.

  • Project setup npm install
  • Compiles and hot-reloads for development npm run dev, makes the UI available on http://localhost:8080/
  • Compile to static resources for production npm run export

When running the UI via npm run dev, API calls are proxied to a local backend instance. It is assumed to be running at http://localhost:9019/.

You can run the backend from:

  • the IDE, in case you want to debug the backend in parallel. XoomInitializer.java, which gets generated on build, has the main method.
  • the jar, in case you do not want to delve into the backend code: Quick Start.
  • Docker, in case you don't want bother w/ Java at all: Docker Run.

Note that this also pulls in the current UI, so don't get confused.

Testing

Unit Tests:

Unit tests live in src/test/java and are executed by the Maven build (e.g. mvn test) as you would expect.