xoom-schemata

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.

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.