Skip to content

Latest commit

 

History

History
740 lines (596 loc) · 18.1 KB

howto.md

File metadata and controls

740 lines (596 loc) · 18.1 KB
Raw

Complete list of json messages version 0.3.0.

Content.

Terminology.

  • Chime address is event bus address Chime is listen to. Given with verticle configuration. Default is "chime".
  • Scheduler address or name is given name scheduler is created with. Chime listens event bus at this address for the messages to the given scheduler.
  • Timer name is given name timer is created with.
  • Timer full name is 'scheduler name' and 'timer name' separated with ':', i.e. 'scheduler name:timer name'. Chime sends or publishes timer events to this address.

Chime.

Configuration.

Provided with verticle deploy configuration.

{
	"address": "String address Chime has to listen, default is 'chime'",
	"tolerance": "Integer tolerance in milliseconds used to compare actual and requested times, default is 10ms",
	"local": "Boolean, If 'true' _Chime_ and schedulers event bus addresses have not to propagate across the cluster",
	"services": [
		"module name/module version"
	],
	"schedulers": ["list of schedulers as JsonObjects"],
	"timers": ["list of timers as JsonObjects"],
}

services is a list of modules with version to look the extensions as service providers.

local identifies the event bus listening area.
If true Chime and schedulers event bus addresses have not to propagate across the cluster, i.e. Chime has to listen only messages from this local node.
If false Chime has to listen all nodes in the cluster.
Default is false.

schedulers is a list of schedulers to be instantiated at start. Each scheduler is in format as described in create scheduler section.

timers is a list of timers to be instantiated at start. Each timer is in format as described in create timer.

Additional options may be specified to be available to extensions during initialization.

Info on installed extensions.

To be sent to Chime address.

Request.
{
	"operation": "info",
	"name": ""
}
Response.
{
	"schedulers": [],
	"services": [
		{
			"type": "parameter declaration",
			"provider type, returned by 'Extension.type'": "declaration"
		}
	]
}

Where schedulers array contains JsonObject's of scheduler info.

Scheduler request.

Create scheduler.

To be sent to Chime address.

Request.
{
	"operation": "create",
	"name": "scheduler name",
	"state": "String, optional, one of running, paused or completed, default is running",
	"time zone": "String, optional, default time zone, applied to timer if no one given at timer level",
	"time zone provider": "String, optional, extracts default time zone",
	"message source": "String, optional, default message source",
	"message source options": "JsonObject, optional, options applied to instantiate message source",
	"event producer": "String, optional, default event producer type",
	"event producer options": "JsonObject, optional, default options applied to event producer factory"
}

operation and name fields are mandatory.

state field is optional with default value set to "running".

time zone field is optional. Time zone applied at scheduler level is default for timers created within this scheduler. If time zone provider then the given provider is used to extract time zone, otherwise default "jvm" provider is used.
Available time zones.

Response.
{
	"name": "scheduler name",
	"state": "running, paused or completed"
}

Delete scheduler.

To be sent to Chime address or to scheduler address.

Request.
{
	"operation": "delete",
	"name": "scheduler name"
}
Response.
{
	"name": "scheduler name",
	"state": "completed"
}

Delete all schedulers.

To be sent to Chime address.

Request.
{
	"operation": "delete",
	"name": ""
}
Response.
{
	"schedulers": ["name of first scheduler name", "...", "name of nth scheduler"]
}

Where 'schedulers' array contains String names of deleted schedulers.

Delete a list of schedulers.

To be sent to Chime address.

Request.
{
	"operation": "delete",
	"name": ["name of first scheduler", "...", "name of nth scheduler"]
}

Where name array contains Strings with names of schedulers to be deleted.

Response.
{
	"schedulers": ["name of first scheduler", "...", "name of nth scheduler"]
}

Where 'schedulers' array contains String names of actually deleted schedulers.

Get scheduler info.

To be sent to Chime address or to scheduler address.

Request.
{
	"operation": "info",
	"name": "scheduler name"
}
Response.
{
	"name": "scheduler name",
	"state": "running, paused or completed",
	"time zone": "time zone ID",
	"timers": []
}

Where timers array contains JsonObject's of timer info.

Get info on all schedulers.

see info on installed extensions

Get info on a list of schedulers.

To be sent to Chime address.

Request.
{
	"operation": "info",
	"name": ["name of first scheduler", "...", "name of nth scheduler"]
}

Where names is array of Strings with names of schedulers info is requested for.

Response.
{
	"schedulers": []
}

Where schedulers array contains JsonObject's of scheduler info.

Get scheduler state.

To be sent to Chime address or to scheduler address.

Request.
{
	"operation": "state",
	"name": "scheduler name",
	"state": "get"
}
Response.
{
	"name": "scheduler name",
	"state": "String, one of running, paused or completed"
}

Set scheduler to paused state.

To be sent to Chime address or to scheduler address.
Pausing scheduler leads to all timers operated within the given scheduler are paused.

Request.
{
	"operation": "state",
	"name": "scheduler name",
	"state": "paused"
}
Response.
{
	"name": "scheduler name",
	"state": "paused"
}

Set scheduler to running state.

To be sent to Chime address or to scheduler address.
Resuming scheduler leads to all timers with running state are resumed. While timers with paused state are remain paused.

Request.
{
	"operation": "state",
	"name": "scheduler name",
	"state": "running"
}
Response.
{
	"name": "scheduler name",
	"state": "running"
}

Timer request.

Create timer.

To be sent to Chime address with full timer name, i.e. "scheduler name:timer name" or to scheduler address with either full or short timer name.

Request.
{
	"operation": "create",
	"name": "scheduler name:timer name",
	"description": {},
	"state": "String, one of running, paused or completed, default is running",
	"maximum count": "Integer, maximum number of fires, default is unlimited",
	"start time": {
 		"seconds": "Integer",
 		"minutes": "Integer",
 		"hours": "Integer",
 		"day of month": "Integer",
 		"month": "Integer or String",
 		"year": "Integer"
	},
	"end time": {
 		"seconds": "Integer",
 		"minutes": "Integer",
 		"hours": "Integer",
 		"day of month": "Integer",
 		"month": "Integer or String",
 		"year": "Integer"
	},
	"time zone": "String, default is local time zone",
	"time zone provider": "String, extracts time zone, default is jvm",
	"message": "any Json value",
	"message source": "String, source type applied to extract message, default is given at scheduler or empty",
	"message source options": "String, options to instantiate message source",
	"event producer": "String, optional, event producer type",
	"event producer options": "JsonObject, optional, options applied to event producer factory"	
}

Where operation, name, and description are mandatory fields.
description field contains JsonObject with timer descriptions.
Other fields are optional, default values are:

  • state = "running"
  • maximum count = unlimited
  • start time = right now
  • end time = never
  • time zone = given at scheduler level or local
  • time zone provider = used only if time zone is given, default is "jvm"
  • message = unused
  • message source = given at scheduler level or unused
  • message source options = used only if message source is given
  • event producer = given at scheduler level or event bus
  • event producer options = given at scheduler level or empty

If name field is empty then unique timer name is generated, created timer is attached to default scheduler and timer full name (i.e. address to listen timer fire events) is returned with response in name field.

If only scheduler name is given in name field (i.e. timer name is omitted) then unique timer name is generated, created timer is attached to the given scheduler and timer full name (i.e. address to listen timer fire events) is returned with response in name field.

If scheduler with 'scheduler name' hasn't been created before then new scheduler with 'scheduler name' will be created.

Available time zones.

Response.

{
	"name": "scheduler name:timer name",
	"state": "running, paused or completed"
}

Delete timer.

To be sent to Chime address with full timer name, i.e. "scheduler name:timer name" or to scheduler address with either full or short timer name.

Request.
{
	"operation": "delete",
	"name": "scheduler name:timer name"
}
Response.
{
	"name": "scheduler name:timer name",
	"state": "completed"
}

Delete a list of timers.

To be sent to Chime address with full timer name, i.e. "scheduler name:timer name" or to scheduler address with either full or short timer name.

Request.
{
	"operation": "delete",
	"name": ["scheduler name:timer name"]
}

Where 'name' array contains Strings with names of timers to be deleted.

Response.
{
	"timers": ["name of first timer", "..." "name of nth timer"]
}

Where 'timers' array contains Strings with names of actually deleted timers.

Get timer info.

To be sent to Chime address with full timer name, i.e. "scheduler name:timer name" or to scheduler address with either full or short timer name.

Request.
{
	"operation": "info",
	"name": "scheduler name:timer name"
}
Response.
{
	"name": "scheduler name:timer name",
	"state": "running, paused or completed",
	"count": "Integer, total number of fires when request is received",
	"max count": "Integer, maximum allowed number of fires",
	"start time": {
		"seconds": "Integer",
		"minutes": "Integer",
		"hours": "Integer",
		"dayOfMonth": "Integer",
		"month": "String",
		"year": "Integer"
	},
	"end time": {
		"seconds": "Integer",
		"minutes": "Integer",
		"hours": "Integer",
		"dayOfMonth": "Integer",
		"month": "String",
		"year": "Integer"
	},
	"time zone": "String, time zone the timer operates with",
	"description": {}
}

Response contains all fields set at timer create request.
description field contains JsonObject with timer descriptions.

start time, end time and max count are optional and may not be given if ignored in timer create request.

Get info on a list of timers.

To be sent to Chime address with full timer name, i.e. "scheduler name:timer name" or to scheduler address with either full or short timer name.

Request.
{
	"operation": "info",
	"name": ["name of first timer", "..." "name of nth timer"]
}

Where names is array of Strings with names of timers the info is requested for.

Response.
{
	"timers": []
}

Where timers array contains JsonObject's of timer info.

Get timer state.

To be sent to Chime address with full timer name, i.e. "scheduler name:timer name" or to scheduler address with either full or short timer name.

Request.
{
	"operation": "state",
	"name": "scheduler name:timer name",
	"state": "get"
}
Response.
{
	"name": "scheduler name:timer name",
	"state": "running, paused or completed"
}

Set timer to running state.

To be sent to Chime address with full timer name, i.e. "scheduler name:timer name" or to scheduler address with either full or short timer name.

Request.
{
	"operation": "state",
	"name": "scheduler name:timer name",
	"state": "running"
}
Response.
{
	"name": "scheduler name:timer name",
	"state": "running"
}

Set timer to paused state.

To be sent to Chime address with full timer name, i.e. "scheduler name:timer name" or to scheduler address with either full or short timer name.

Request.
{
	"operation": "state",
	"name": "scheduler name:timer name",
	"state": "paused"
}
Response.
{
	"name": "scheduler name:timer name",
	"state": "paused"
}

Timer descriptions.

Used in timer create request.

Cron-style timer.

{
	"type": "cron",
	"seconds": "String in cron-style",
	"minutes": "String in cron-style",
	"hours": "String in cron-style",
	"days of month": "String in cron-style",
	"months": "String in cron-style",
	"days of week": "String in cron-style, optional",
	"years": "String in cron-style, optional"
}

type, seconds, minutes, hours, days of month and months are mandatory.
days of week and years are optional.

Cron specification.
  • seconds, mandatory
    • allowed values: 0-59
    • allowed special characters: , - * /
  • minutes, mandatory
    • allowed values: 0-59
    • allowed special characters: , - * /
  • hours, mandatory
    • allowed values: 0-23
    • allowed special characters: , - * /
  • days of month, mandatory
    • allowed values 1-31
    • allowed special characters: , - * /
  • months, mandatory
    • allowed values 1-12, Jan-Dec, January-December
    • allowed special characters: , - * /
  • days of week, optional
    • allowed values 1-7, Sun-Sat, Sunday-Saturday
    • allowed special characters: , - * / L #
  • years, optional
    • allowed values 1970-2099
    • allowed special characters: , - * /

Names of months and days of the week are case insensitive.

Sunday is the first day of week.

Special characters.
  • '*' means all values
  • ',' separates list items
  • '-' specifies range, for example, '10-12' means '10, 11, 12'
  • '/' specifies increments, for example, '0/15' in seconds field means '0,15,30,45', '0-30/15' means '0,15,30'
  • 'L' has to be used after digit and means the last xxx day of the month, where xxx is day of week, for example, '6L' means the last Friday of the month
  • '#' has to be used with digits before and after: 'x#y' and means the y'th x day of the month, for example, '6#3' means the third Friday of the month

Interval timer.

{
	"type": "interval",
	"delay": "Integer > 0"
}

type and interval are mandatory.

Union timer.

{
	"type": "union",
	"timers": []
}

Where timers array contains JsonObject's of timer descriptions.
type and timers are mandatory.

Timer events.

Fire event.

Sent or published by Chime to timer full name ("scheduler name:timer name") address.

{  
	"name": "String, timer name",  
	"event": "fire",
	"count": "Integer, total number of fire times",
	"time": "String formated time / date",
	"seconds": "Integer, number of seconds since last minute",
	"minutes": "Integer, number of minutes since last hour",
	"hours": "Integer, hour of day",
	"day of month": "Integer, day of month",
	"month": "Integer, month",
	"year": "Integer, year",
	"time zone": "String, time zone the timer works in",
	"message": "message given at a timer create request, optional"  
}

message is given at create timer request in any Json supported type.

Complete event.

Published by Chime to timer full name ("scheduler name:timer name") address.

{
	"name": "scheduler name:timer name",
	"event": "complete",
	"count": "Integer, total number of fires"
}

Complete event is always published in order all consumers may receive it.