`hx` 运行时 API 参考

原文: https://finproducts.atlassian.net/wiki/spaces/JIDD3/pages/34793455692/FIN+5.3.1+hx 中文整理基于 FIN 5.3.1

导读： hx 是 Haxall 运行时核心 Fantom API：上下文（HxContext）、服务、CLI、Watch、核心函数等。学习平台扩展与 Axon 宿主时查阅本页。

以下为 API 参考，保留英文以便对照源码；目录已列出（英文标题便于检索）。

目录（导读）

mixins
classes
facets
HxApiOp
- Slot Details
- def
- make
- name
- onRequest
- onService
HxCli
- Slot Details
- aliases
- appName
- find
- list
- log
- name
- printLine
- run
- summary
HxContext
- Slot Details
- checkAdmin
- checkSu
- db
- rt
- session
- user
HxContextService
- Slot Details
- create
HxCoreFuncs
- Slot Details
- about
- commit
- context
- diff
- isSteadyState
- isWatched
- libAdd
- libRemove
- libStatus
- passwordSet
- pods
- read
- readAll
- readAllStream
- readAllTagNames
- readAllTagVals
- readById
- readByIdPersistentTags
- readByIdTransientTags
- readByIds
- readByIdsStream
- readCount
- readLink
- services
- stripUncommittable
- toRec
- toRecId
- toRecIdList
- toRecList
- tzdb
- unitdb
- watchAdd
- watchClose
- watchOpen
- watchPoll
- watchRemove
- xetoReload
HxHttpService
- Slot Details
- apiUri
- siteUri
HxLib
- Slot Details
- equals
- hash
- houseKeepingFreq
- isRunning
- log
- make
- name
- observables
- observe
- onHouseKeeping
- onReady
- onRecUpdate
- onStart
- onSteadyState
- onStop
- onUnready
- rec
- rt
- services
- subscriptions
- toStr
- web
HxLibWeb
- Slot Details
- lib
- make
- rt
- uri
HxMsg
- Slot Details
- a
- b
- c
- d
- e
- equals
- hash
- id
- make0
- make1
- make2
- make3
- make4

概述（中译）

Haxall（hx）提供运行时宿主：项目上下文、会话用户、库加载、记录读写、Watch 订阅与 CLI。多数 Axon 函数最终映射到本页中的 Fantom 类型。

API 正文（英文）

hx

Haxall framework APIs

mixins


HxContextService	Context factory service
HxHttpService	HTTP APIs
HxObsService	Observable APIs
HxRuntime	HxRuntime is the top level coordinator of a Haxall server.
HxRuntimeLibs	Haxall runtime library management APIs
HxService	HxService is a marker interface used to indicate a service API.
HxServiceRegistry	Registry for service APIs by type.
HxSession	User authentication session
HxStdServices	Lookups for the standard built-in services supported by all runtimes.
HxUser	Haxall user account
HxUserService	User management APIs
HxWatchService	Watch subscription APIs

classes


HxApiOp	Base class for Haxall 3.x style HTTP API operation processing
HxCli	Haxall command line interface.
HxContext	Haxall execution and security context.
HxCoreFuncs	Haxall core "hx" axon functions supported by all runtimes
HxLib	Base class for all Haxall library runtime instances.
HxLibWeb	HxLib plugin to add web servicing capability.
HxMsg	HxMsg provides simple immutable tuple to use for actor messages.
HxPlatform	HxPlatform models the meta data of the platform running Haxall.
HxTest	HxTest is a base class for writing Haxall tests which provide access to a booted runtime instance.
HxUtil	Haxall utility methods
HxWatch	HxWatch is a subscription to a set of records in a project database.


HxRuntimeTest	Annotates a `HxTest` method to setup a test runtime instance

HxApiOp

abstract class HxApiOp : Obj

Base class for Haxall 3.x style HTTP API operation processing

Constructors


make	Subclasses must declare public no-arg constructor

Methods


def	Op definition
name	Programmatic name of the op
onRequest	Process parsed request.
onService	Process an HTTP service call to this op

Slot Details

def

Def def()

Op definition

make

new make()

Subclasses must declare public no-arg constructor

name

Str name()

Programmatic name of the op

onRequest

abstract Grid onRequest(Grid req, HxContext cx)

Process parsed request. Default implentation attempts to eval an Axon function of the same name.

onService

virtual Void onService(WebReq req, WebRes res, HxContext cx)

Process an HTTP service call to this op

HxCli

abstract class HxCli : AbstractMain

Haxall command line interface. To create a new hx command:

Define subclass of HxCli
Register type qname via indexed prop as "hx.cli"
Annotate options and args using AbstractMain design

Methods


aliases	Command name alises/shortcuts
appName	App name is "hx {name}"
find	Find a specific command or return null
list	List installed commands
log	Log name is "hx"
name	Command name
printLine	Print a line to stdout
run	Run the command.
summary	Single line summary of the command for help

Slot Details

aliases

virtual Str[] aliases()

Command name alises/shortcuts

appName

override Str appName()

App name is "hx {name}"

find

static HxCli? find(Str name)

Find a specific command or return null

list

static HxCli[] list()

List installed commands

log

virtual override Log log()

Log name is "hx"

name

abstract Str name()

Command name

printLine

Void printLine(Str line := "")

Print a line to stdout

run

abstract override Int run()

Run the command. Return zero on success

summary

abstract Str summary()

Single line summary of the command for help

HxContext

abstract class HxContext : AxonContext

Haxall execution and security context.

Methods


checkAdmin	If missing admin permission, throw PermissionErr
checkSu	If missing superuser permission, throw PermissionErr
db	Folio database for the runtime
rt	Runtime associated with this context
session	Authentication session associated with this context if applicable
user	User account associated with this context

Slot Details

checkAdmin

virtual Void checkAdmin(Str action)

If missing admin permission, throw PermissionErr

checkSu

virtual Void checkSu(Str action)

If missing superuser permission, throw PermissionErr

db

abstract Folio db()

Folio database for the runtime

rt

abstract HxRuntime rt()

Runtime associated with this context

session

abstract HxSession? session(Bool checked := true)

Authentication session associated with this context if applicable

user

abstract HxUser user()

User account associated with this context

HxContextService

const mixin HxContextService : HxService

Context factory service

Methods


create	Create new context for given user

Slot Details

create

abstract HxContext create(HxUser user)

Create new context for given user

HxCoreFuncs

const class HxCoreFuncs : Obj

Haxall core "hx" axon functions supported by all runtimes

Methods


about	Return `about` dict
commit	Commit one or more diffs to the folio database.
context	Get the current context as a Dict with the following tags
diff	Construct a modification "diff" used by `commit`.
isSteadyState	Return `HxRuntime.isSteadyState`
isWatched	Return if given record is under at least one watch.
libAdd	Enable a library by name in the runtime
libRemove	Disable a library by name in the runtime
libStatus	Return grid of enabled libs and their current status.
passwordSet	Store a password key/val pair into current project's password store.
pods	Return list of installed Fantom pods
read	Read from database the first record which matches filter.
readAll	Reall all records from the database which match the filter.
readAllStream	Reall all records which match filter as stream of Dict records.
readAllTagNames	Return the intersection of all tag names used by all the records matching the given filter.
readAllTagVals	Return the range of all the values mapped to a given tag name used by all the records matching the given filter.
readById	Read a record from database by `id`.
readByIdPersistentTags	Given record id, read only the persistent tags from Folio.
readByIdTransientTags	Given record id, read only the transient tags from Folio.
readByIds	Read a list of record ids into a grid.
readByIdsStream	Read a list of ids as a stream of Dict records.
readCount	Return the number of records which match the given filter expression.
readLink	Read a record Dict by its id for hyperlinking in a UI.
services	Grid of installed services.
stripUncommittable	Strip any tags which cannot be persistently committed to Folio.
toRec	Coerce a value to a record Dict
toRecId	Coerce a value to a Ref identifier
toRecIdList	Coerce a value to a list of Ref identifiers
toRecList	Coerce a value to a list of record Dicts
tzdb	Return the installed timezone database as Grid with following columns
unitdb	Return the installed unit database as Grid with following columns
watchAdd	Add a grid of recs to an existing watch and return the grid passed in.
watchClose	Close an open watch by id.
watchOpen	Open a new watch on a grid of records.
watchPoll	Poll an open watch and return all the records which have changed since the last poll.
watchRemove	Remove a grid of recs from an existing watch and return grid passed in.
xetoReload	Reload all the Xeto libraries

Slot Details

about

@Axon static Dict about()

Return about dict

commit

@Axon { admin=true } static Obj? commit(Obj diffs)

Commit one or more diffs to the folio database. The argument may be one of the following:

result of diff()
list of diff() to commit multiple diffs at once
stream of diff(); see Streams.

If one diff is passed, return the new record. If a list of diffs is passed return a list of new records.

This is a synchronous blocking call which will return the new record or records as the result.

Examples:

// add new record
newRec: commit(diff(null, {dis:"New Rec!"}, {add}))

// add someTag to some group of records
readAll(filter).toRecList.map(r => diff(r, {someTag})).commit

context

@Axon static Dict context()

Get the current context as a Dict with the following tags:

username for current user
userRef id for current user
locale current locale

SkySpark tags:

projName if evaluating in context of a project
nodeId local cluster node id
ruleRef if evaluating in context of a rule engine
ruleTuning if evaluating in context of rule engine

diff

@Axon static Diff diff(Dict? orig, Dict? changes, Dict? flags := null)

Construct a modification "diff" used by commit. The orig should be the instance which was read from the database, or it may be null only if the add flag is passed. Any tags to add/set/remove should be included in the changes dict.

The following flags are supported:

add: indicates diff is adding new record
remove: indicates diff is removing record (in general you should add trash tag instead of removing)
transient: indicate that this diff should not be flushed to persistent storage (it may or may not be persisted).
force: indicating that changes should be applied regardless of other concurrent changes which may be been applied after the orig version was read (use with caution!)

Examples:

// create new record
diff(null, {dis:"New Rec", someMarker}, {add})

// create new record with explicit id like Diff.makeAdd
diff(null, {id:151bd3c5-6ce3cb21, dis:"New Rec"}, {add})

// set/add dis tag and remove oldTag
diff(orig, {dis:"New Dis", -oldTag})

// set/add val tag transiently
diff(orig, {val:123}, {transient})

isSteadyState

@Axon static Bool isSteadyState()

Return HxRuntime.isSteadyState

isWatched

@Axon static Bool isWatched(Obj rec)

Return if given record is under at least one watch. The rec argument can be any value accepted by toRecId().

libAdd

@Axon { admin=true } static Dict libAdd(Str name, Dict? tags := null)

Enable a library by name in the runtime:

libAdd("mqtt")

libRemove

@Axon { admin=true } static Obj? libRemove(Obj name)

Disable a library by name in the runtime:

libRemove("mqtt")

libStatus

@Axon { admin=true } static Grid libStatus()

Return grid of enabled libs and their current status. Columns:

name: library name string
libStatus: status enumeration string
statusMsg: additional message string or null

passwordSet

@Axon { admin=true } static Void passwordSet(Obj key, Str? val)

Store a password key/val pair into current project's password store. The key is typically a Ref of the associated record. If the val is null, then the password will be removed. See Folio.

passwordSet(@abc-123, "password")
passwordSet(@abc-123, null)

pods

@Axon { admin=true } static Grid pods()

Return list of installed Fantom pods

read

@Axon static Dict? read(Expr filterExpr, Expr checked := Literal.trueVal)

Read from database the first record which matches filter. If no matches found throw UnknownRecErr or null based on checked flag. If there are multiple matches it is indeterminate which one is returned. See readAll for how filter works.

Examples:

read(site)                 // read any site rec
read(site and dis=="HQ")   // read site rec with specific dis tag
read(chiller)              // raise exception if no recs with chiller tag
read(chiller, false)       // return null if no recs with chiller tag

readAll

@Axon static Grid readAll(Expr filterExpr, Expr? optsExpr := null)

Reall all records from the database which match the filter. The filter must an expression which matches the filter structure. String values may parsed into a filter using parseFilter() function.

Options:

limit: max number of recs to return
sort: sort by display name

Examples:

readAll(site)                      // read all site recs
readAll(equip and siteRef==@xyz)   // read all equip in a given site
readAll(equip, {limit:10})         // read up to ten equips
readAll(equip, {sort})             // read all equip sorted by dis

readAllStream

@Axon static Obj readAllStream(Expr filterExpr)

Reall all records which match filter as stream of Dict records. See Streams.

readAllTagNames

@Axon static Grid readAllTagNames(Expr filterExpr)

Return the intersection of all tag names used by all the records matching the given filter. The results are returned as a grid with following columns:

name: string name of the tag
kind: all the different value kinds separated by "|"
count: total number of recs with the tag Also see readAllTagVals and gridColKinds().

Examples:

// read statistics on all tags used by equip recs
readAllTagNames(equip)

readAllTagVals

@Axon static Grid readAllTagVals(Expr filterExpr, Expr tagName)

Return the range of all the values mapped to a given tag name used by all the records matching the given filter. This method is capped to 200 results. The results are returned as a grid with a single val column. Also see readAllTagNames.

Examples:

// read grid of all unique point unit tags
readAllTagVals(point, "unit")

readById

@Axon static Dict? readById(Ref? id, Bool checked := true)

Read a record from database by id. If not found throw UnknownRecErr or return null based on checked flag. In Haxall all refs are relative, but in SkySpark refs may be prefixed with something like "p:projName:r:". This function will accept both relative and absolute refs.

Examples:

readById(@2b00f9dc-82690ed6)          // relative ref literal
readById(@:demo:r:2b00f9dc-82690ed6)  // project absolute literal
readById(id)                          // read using variable
readById(equip->siteRef)              // read from ref tag

readByIdPersistentTags

@Axon static Dict? readByIdPersistentTags(Ref id, Bool checked := true)

Given record id, read only the persistent tags from Folio. Also see readByIdTransientTags and readById.

readByIdTransientTags

@Axon static Dict? readByIdTransientTags(Ref id, Bool checked := true)

Given record id, read only the transient tags from Folio. Also see readByIdPersistentTags and readById.

readByIds

@Axon static Grid readByIds(Ref[] ids, Bool checked := true)

Read a list of record ids into a grid. The rows in the result correspond by index to the ids list. If checked is true, then every id must be found in the database or UnknownRecErr is thrown. If checked is false, then an unknown record is returned as a row with every column set to null (including the id tag). Either relative or project absolute refs may be used.

Examples:

// read two relative refs
readByIds([@2af6f9ce-6ddc5075, @2af6f9ce-2d56b43a])

// read two project absolute refs
readByIds([@p:demo:r:2af6f9ce-6ddc5075, @p:demo:r:2af6f9ce-2d56b43a])

// return null for a given id if it does not exist
readByIds([@2af6f9ce-6ddc5075, @2af6f9ce-2d56b43a], false)

readByIdsStream

@Axon static Obj readByIdsStream(Ref[] ids, Bool checked := true)

Read a list of ids as a stream of Dict records. If checked if false, then records not found are skipped. See Streams.

readCount

@Axon static Number readCount(Expr filterExpr)

Return the number of records which match the given filter expression.

Examples:

readCount(point)    // return number of recs with point tag

readLink

@Axon static Dict? readLink(Ref? id)

Read a record Dict by its id for hyperlinking in a UI. Unlike other reads which return a Dict, this read returns the columns ordered in the same order as reads which return a Grid.

services

@Axon { admin=true } static Grid services()

Grid of installed services. Format of the grid is subject to change.

stripUncommittable

@Axon static Obj stripUncommittable(Obj val, Obj? opts := null)

Strip any tags which cannot be persistently committed to Folio. This includes special tags such as hisSize and any transient tags the record has defined. If val is Dict, then a single Dict is returned. Otherwise val must be Dict[] or Grid and Dict[] is returned. The mod tag is stripped unless the {mod} option is specified. The id tag is not stripped for cases when adding records with swizzled ids; pass {-id} in options to strip the id tag also.

Examples:

// strip uncommittable tags and keep id
toCommit: rec.stripUncommittable

// strip uncommittable tags and the id tag
toCommit: rec.stripUncommittable({-id})

// strip uncommittable tags, but keep id and mod
toCommit: rec.stripUncommittable({mod})

toRec

@Axon static Dict toRec(Obj? val)

Coerce a value to a record Dict:

Row or Dict returns itself
Grid returns first row
List returns first row (can be either Ref or Dict)
Ref will make a call to read database

toRecId

@Axon static Ref toRecId(Obj? val)

Coerce a value to a Ref identifier:

Ref returns itself
Row or Dict, return id tag
Grid return first row id

toRecIdList

@Axon static Ref[] toRecIdList(Obj? val)

Coerce a value to a list of Ref identifiers:

Ref returns itself as list of one
Ref[] returns itself
Dict return id tag
Dict[] return id tags
Grid return id column

toRecList

@Axon static Dict[] toRecList(Obj? val)

Coerce a value to a list of record Dicts:

null return empty list
Ref or Ref[] (will make a call to read database)
Row or Row[] returns itself
Dict or Dict[] returns itself
Grid is mapped to list of rows

tzdb

@Axon static Grid tzdb()

Return the installed timezone database as Grid with following columns:

name: name of the timezone
fullName: qualified name used by Olson database

unitdb

@Axon static Grid unitdb()

Return the installed unit database as Grid with following columns:

quantity: dimension of the unit
name: full name of the unit
symbol: the abbreviated Unicode name of the unit

watchAdd

@Axon static Grid watchAdd(Str watchId, Grid grid)

Add a grid of recs to an existing watch and return the grid passed in.

watchClose

@Axon static Obj? watchClose(Str watchId)

Close an open watch by id. If the watch does not exist or has expired then this is a no op. Also see HxWatch.close and Watches.

watchOpen

@Axon static Grid watchOpen(Grid grid, Str dis)

Open a new watch on a grid of records. The dis parameter is used for the watch's debug display string. Update and return the grid with a meta watchId tag. Also see HxWatchService.open and Watches.

Example:

readAll(myPoints).watchOpen("MyApp|Points")

watchPoll

@Axon static Grid watchPoll(Obj watchId)

Poll an open watch and return all the records which have changed since the last poll. Raise exception if watchId doesn't exist or has expired. Also see HxWatch.poll and Watches.

watchRemove

@Axon static Grid watchRemove(Str watchId, Grid grid)

Remove a grid of recs from an existing watch and return grid passed in.

xetoReload

@Axon { su=true } static Obj? xetoReload()

Reload all the Xeto libraries

HxHttpService

const mixin HxHttpService : HxService

HTTP APIs

Methods


apiUri	URI on this host to the Haystack HTTP API.
siteUri	Public HTTP or HTTPS URI of this host.

Slot Details

apiUri

abstract Uri apiUri()

URI on this host to the Haystack HTTP API. This is always a host relative URI which end withs a slash such /api/.

siteUri

abstract Uri siteUri()

Public HTTP or HTTPS URI of this host. This is always an absolute URI such https://acme.com/

HxLib

abstract const class HxLib : Obj

Base class for all Haxall library runtime instances. All Haxall libs must be standard Haystack 4 libs. This class is used to model the instance of the library within a HxRuntime to provide runtime services.

To create a new library:

Create a pod with a standard Haystack 4 "lib/lib.trio" definition
Register the lib name using the indexed prop "ph.lib"
Create subclass of HxLib
Ensure your lib definition has typeName tag for subclass qname

Also see Libs.

Constructors


make	Framework use only.

Methods


equals	Equality is based on reference equality
hash	Identity hash
houseKeepingFreq	Override to return non-null for onHouseKeeping callback
isRunning	Running flag.
log	Logger to use for this library
name	Programmatic name of the library
observables	Return list of observables this extension publishes.
observe	Subscribe this library to an observable.
onHouseKeeping	Callback made periodically to perform background tasks.
onReady	Callback when all libs are fully started.
onRecUpdate	Callback when associated database `rec` is modified.
onStart	Callback when library is started.
onSteadyState	Callback when runtime reaches steady state.
onStop	Callback when library is stopped.
onUnready	Callback before we stop the runtime This is called on dedicated background actor.
rec	Database record which enables this library and stores settings.
rt	Runtime
services	Return list of services this library publishes.
subscriptions	Observable subscriptions for this extension
toStr	Return `name`
web	Web service handling for this library

Slot Details

equals

override Bool equals(Obj? that)

Equality is based on reference equality

hash

override Int hash()

Identity hash

houseKeepingFreq

virtual Duration? houseKeepingFreq()

Override to return non-null for onHouseKeeping callback

isRunning

Bool isRunning()

Running flag. On startup this flag transitions to true before calling ready and start on the library. On shutdown this flag transitions to false before calling unready and stop on the library.

log

Log log()

Logger to use for this library

make

new make()

Framework use only. Subclasses must declare public no-arg constructor.

name

Str name()

Programmatic name of the library

observables

virtual Observable[] observables()

Return list of observables this extension publishes. This method must be overridden as a const field and set in the constructor.

observe

Subscription observe(Str name, Dict config, Obj callback)

Subscribe this library to an observable. The callback must be an Actor instance or Method literal on this class. If callback is a method, then its called on the lib's dedicated background actor. pool. This method should be called in the onStart callback. The observation is automatically unsubscribed on stop. You should not unsubscribe this subscription - it must be managed by the extension itself. See Observables.

onHouseKeeping

virtual Void onHouseKeeping()

Callback made periodically to perform background tasks. Override houseKeepingFreq to enable the frequency of this callback.

onReady

virtual Void onReady()

Callback when all libs are fully started. This is called on dedicated background actor.

onRecUpdate

virtual Void onRecUpdate()

Callback when associated database rec is modified. This is called on dedicated background actor.

onStart

virtual Void onStart()

Callback when library is started. This is called on dedicated background actor.

onSteadyState

virtual Void onSteadyState()

Callback when runtime reaches steady state. This is called on dedicated background actor.

onStop

virtual Void onStop()

Callback when library is stopped. This is called on dedicated background actor.

onUnready

virtual Void onUnready()

Callback before we stop the runtime This is called on dedicated background actor.

rec

virtual Dict rec()

Database record which enables this library and stores settings. This field may be overridden with a TypedDict subclass. Also see Libs.

rt

virtual HxRuntime rt()

Runtime

services

virtual HxService[] services()

Return list of services this library publishes. This callback is made during initialization and each time a lib is added/removed from the runtime.

subscriptions

Subscription[] subscriptions()

Observable subscriptions for this extension

toStr

override Str toStr()

Return name

web

virtual HxLibWeb web()

Web service handling for this library

HxLibWeb

abstract const class HxLibWeb : WebMod

HxLib plugin to add web servicing capability. See Libs.

Constructors


make	Subclass constructor

Methods


lib	Parent library.
rt	Runtime for parent library
uri	Base uri for this library's endpoint such as "/myLib/"

Slot Details

lib

virtual HxLib lib()

Parent library. Subclasses can override this method to be covariant.

make

new make(HxLib lib)

Subclass constructor

rt

virtual HxRuntime rt()

Runtime for parent library

uri

Uri uri()

Base uri for this library's endpoint such as "/myLib/"

HxMsg

const class HxMsg : Obj

HxMsg provides simple immutable tuple to use for actor messages.

Constructors


make0	Constructor with zero arguments
make1	Constructor with one argument
make2	Constructor with two arguments
make3	Constructor with three arguments
make4	Constructor with four arguments
make5	Constructor with five arguments

Fields


a	Argument a
b	Argument b
c	Argument c
d	Argument d
e	Argument e
id	Message identifier type

Methods


equals	Equality is based on id and arguments
hash	Hash is based on id and arguments
toStr	Return debug string representation

Slot Details

a

const Obj? a

Argument a

b

const Obj? b

Argument b

c

const Obj? c

Argument c

d

const Obj? d

Argument d

e

const Obj? e

Argument e

equals

virtual override Bool equals(Obj? that)

Equality is based on id and arguments

hash

virtual override Int hash()

Hash is based on id and arguments

id

const Str id

Message identifier type

make0

new make0(Str id)

Constructor with zero arguments

make1

new make1(Str id, Obj? a)

Constructor with one argument

make2

new make2(Str id, Obj? a, Obj? b)

Constructor with two arguments

make3

new make3(Str id, Obj? a, Obj? b, Obj? c)

Constructor with three arguments

make4

new make4(Str id, Obj? a, Obj? b, Obj? c, Obj? d)

Constructor with four arguments

make5

new make5(Str id, Obj? a, Obj? b, Obj? c, Obj? d, Obj? e)

Constructor with five arguments

toStr

virtual override Str toStr()

Return debug string representation

HxObsService

const mixin HxObsService : HxService

Observable APIs

Methods


get	Lookup a observable for the runtime by name.
list	List the published observables for the runtime

Slot Details

get

abstract Observable? get(Str name, Bool checked := true)

Lookup a observable for the runtime by name.

list

abstract Observable[] list()

List the published observables for the runtime

HxPlatform

const class HxPlatform : Obj

HxPlatform models the meta data of the platform running Haxall. Note this API provides readonly summary information about the platform. Actual integration to configure the platform is handled in pluggable libraries such as hxPlatform, hxPlatformSerial, etc.

Constructors


make	Construct with meta data dict

Methods


arch	Microprocessor architecture - see `Env.arch`
faviconUri	Relative URI to favicon.png image
hostModel	Host model
hostOs	Host operating system platform and version
isSkySpark	Is this the full SkySpark runtime
logoUri	Relative URI to the SVG logo
meta	Meta data
os	Operating system name - see `Env.os`
productName	Product name for about op
productUri	Product home page for about op
productVersion	Product version for about op
vendorName	Vendor name for about op
vendorUri	Vendor home page for about op

Slot Details

arch

virtual Str arch()

Microprocessor architecture - see Env.arch

faviconUri

virtual Uri faviconUri()

Relative URI to favicon.png image

hostModel

virtual Str hostModel()

Host model

hostOs

virtual Str hostOs()

Host operating system platform and version

isSkySpark

virtual Bool isSkySpark()

Is this the full SkySpark runtime

logoUri

virtual Uri logoUri()

Relative URI to the SVG logo

make

new make(Dict meta)

Construct with meta data dict

meta

virtual Dict meta()

Meta data

os

virtual Str os()

Operating system name - see Env.os

productName

virtual Str productName()

Product name for about op

productUri

virtual Uri productUri()

Product home page for about op

productVersion

virtual Str productVersion()

Product version for about op

vendorName

virtual Str vendorName()

Vendor name for about op

vendorUri

virtual Uri vendorUri()

Vendor home page for about op

HxRuntime

const mixin HxRuntime : HxStdServices

HxRuntime is the top level coordinator of a Haxall server.

Methods


db	Folio database for this runtime
dir	Runtime project directory.
dis	Display name of the runtime.
isRunning	Running flag.
isSteadyState	Has the runtime has reached steady state.
lib	Lookup a library by name.
libs	Library managment APIs
meta	Runtime level meta data stored in the `projMeta` database record
name	Programatic name of the runtime.
ns	Namespace of definitions
platform	Platform hosting the runtime
services	Service registry
sync	Block until currently queued background processing completes
version	Runtime version

Slot Details

db

abstract Folio db()

Folio database for this runtime

dir

abstract File dir()

Runtime project directory. It the root directory of all project oriented operational files. The folio database is stored under this directory in a sub-directory named db/.

dis

abstract Str dis()

Display name of the runtime.

isRunning

abstract Bool isRunning()

Running flag. On startup this flag transitions to true before calling ready and start on all the libraries. On shutdown this flag transitions to false before calling unready and stop on all the libraries.

isSteadyState

abstract Bool isSteadyState()

Has the runtime has reached steady state. Steady state is reached after a configurable wait period elapses after the runtime is fully loaded. This gives internal services time to spin up before interacting with external systems. See Runtime.

lib

abstract HxLib? lib(Str name, Bool checked := true)

Lookup a library by name. Convenience for libs.get.

libs

abstract HxRuntimeLibs libs()

Library managment APIs

meta

abstract Dict meta()

Runtime level meta data stored in the projMeta database record

name

abstract Str name()

Programatic name of the runtime. This string is always a valid tag name.

ns

abstract Namespace ns()

Namespace of definitions

platform

abstract HxPlatform platform()

Platform hosting the runtime

services

abstract HxServiceRegistry services()

Service registry

sync

abstract This sync(Duration? timeout := 30sec)

Block until currently queued background processing completes

version

abstract Version version()

Runtime version

HxRuntimeLibs

const mixin HxRuntimeLibs

Haxall runtime library management APIs

Methods


actorPool	Actor thread pool to use for libraries
add	Enable a library in the runtime
get	Lookup an enabled lib by name.
has	Check if there is an enabled lib with given name
list	List of libs currently enabled sorted by name
remove	Disable a library from the runtime.

Slot Details

actorPool

abstract ActorPool actorPool()

Actor thread pool to use for libraries

add

abstract HxLib add(Str name, Dict tags := Etc.emptyDict())

Enable a library in the runtime

get

abstract HxLib? get(Str name, Bool checked := true)

Lookup an enabled lib by name. If not found then return null or raise UnknownLibErr based on checked flag.

has

abstract Bool has(Str name)

Check if there is an enabled lib with given name

list

abstract HxLib[] list()

List of libs currently enabled sorted by name

remove

abstract Void remove(Obj lib)

Disable a library from the runtime. The lib arg may be a HxLib instace, Lib definition, or Str name.

HxRuntimeTest

@Serializable facet class HxRuntimeTest : Obj, Facet

Annotates a HxTest method to setup a test runtime instance

Fields


meta	Database meta data encoded as a Trio string

Slot Details

meta

const Obj? meta

Database meta data encoded as a Trio string

HxService

const mixin HxService

HxService is a marker interface used to indicate a service API.

Slot Details

HxServiceRegistry

const mixin HxServiceRegistry : HxStdServices

Registry for service APIs by type. Service APIs implement the HxService mixin and are published by libraries enabled in the runtime using HxLib.services.

Methods


get	Lookup a service installed for the given type.
getAll	Lookup all services installed for the given type.
list	List the registered service types

Slot Details

get

abstract HxService? get(Type type, Bool checked := true)

Lookup a service installed for the given type. If multiple services are installed for the given type, then its indeterminate which is returned. If the service is not found then raise UnknownServiceErr or return null based on the check flag.

getAll

abstract HxService[] getAll(Type type)

Lookup all services installed for the given type. Return an empty list if no services are registered for given type.

list

abstract Type[] list()

List the registered service types

HxSession

@Js const mixin HxSession

User authentication session

Methods


attestKey	Attestation session key used as secondary verification of cookie key
key	Unique identifier for session
user	Authenticated user associated with the sesssion

Slot Details

attestKey

abstract Str attestKey()

Attestation session key used as secondary verification of cookie key

key

abstract Str key()

Unique identifier for session

user

abstract HxUser user()

Authenticated user associated with the sesssion

HxStdServices

const mixin HxStdServices

Lookups for the standard built-in services supported by all runtimes. This mixin is implemented by both HxServiceRegistry and HxRuntime, but by convention client code should access services the runtime.

Methods


context	Context factory service
http	HTTP APIs
obs	Observable APIs
user	User management APIs
watch	Watch subscription APIs

Slot Details

context

abstract HxContextService context()

Context factory service

http

abstract HxHttpService http()

HTTP APIs

obs

abstract HxObsService obs()

Observable APIs

user

abstract HxUserService user()

User management APIs

watch

abstract HxWatchService watch()

Watch subscription APIs

HxTest

abstract class HxTest : HaystackTest

HxTest is a base class for writing Haxall tests which provide access to a booted runtime instance. Annotate test methods which require a runtime with HxRuntimeTest. This class uses the hxd implementation for its runtime.

@HxRuntimeTest
Void testBasics()
{
  x := addRec(["dis":"It works!"])
  y := rt.db.readById(x.id)
  verifyEq(y.dis, "It works!")
}

Methods


addLib	Add a library and all its depdenencies to the runtime.
addRec	Add a record to `rt` using the given map of tags.
commit	Convenience for commit to `rt`
eval	Evaluate an Axon expression using a super user context.
makeContext	Create a new context with the given user.
read	Convenience for `read` on `rt`
readById	Convenience for `readById` on `rt`
rt	Test runtime if `@HxRuntimeTest` configured on test method
setup	If `@HxRuntimeTest` configured then open `rt`
teardown	If `@HxRuntimeTest` configured then close down `rt`

Slot Details

addLib

HxLib addLib(Str libName, Str:Obj? tags := [Str:Obj?][:])

Add a library and all its depdenencies to the runtime.

addRec

Dict addRec(Str:Obj? tags := [Str:Obj?][:])

Add a record to rt using the given map of tags.

commit

Dict? commit(Dict rec, Obj? changes, Int flags := 0)

Convenience for commit to rt

eval

Obj? eval(Str axon)

Evaluate an Axon expression using a super user context.

makeContext

virtual HxContext makeContext(HxUser? user := null)

Create a new context with the given user. If user is null, then use a default test user with superuser permissions.

read

Dict? read(Str filter, Bool checked := true)

Convenience for read on rt

readById

Dict? readById(Ref id, Bool checked := true)

Convenience for readById on rt

rt

HxRuntime? rt(Bool checked := true)

Test runtime if @HxRuntimeTest configured on test method

setup

virtual override Void setup()

If @HxRuntimeTest configured then open rt

teardown

virtual override Void teardown()

If @HxRuntimeTest configured then close down rt

HxUser

@Js const mixin HxUser

Haxall user account

Methods


dis	Display string for user
email	Email address if configured
id	Ref identifier
isAdmin	Does this user have admin permissions
isSu	Does this user have superuser permissions
meta	User meta data as Haystack dict
username	Username identifier

Slot Details

dis

abstract Str dis()

Display string for user

email

abstract Str? email()

Email address if configured

id

abstract Ref id()

Ref identifier

isAdmin

abstract Bool isAdmin()

Does this user have admin permissions

isSu

abstract Bool isSu()

Does this user have superuser permissions

meta

abstract Dict meta()

User meta data as Haystack dict

username

abstract Str username()

Username identifier

HxUserService

const mixin HxUserService : HxService

User management APIs

Methods


authenticate	Authenticate a web request and return a context.
read	Lookup a user by username.

Slot Details

authenticate

abstract HxContext? authenticate(WebReq req, WebRes res)

Authenticate a web request and return a context. If request is not authenticated then redirect to login page and return null. Session information is available via HxContext.session.

read

abstract HxUser? read(Obj username, Bool checked := true)

Lookup a user by username. If not found then raise exception or return null based on the checked flag.

HxUtil

const class HxUtil : Obj

Haxall utility methods

Methods


parseEnum	Parse enum as ordered map of Str:Dict keyed by name.
parseEnumNames	Convenience for parseEnum which returns only a list of string names.
pid	Process id or null if cannot be determined
pods	List pods as grid
threadDump	Dump a specific thread by its id
threadDumpAll	Dump all threads
threadDumpDeadlocks	Dump thread deadlocks if detected
threadId	Current thread id
tzdb	List timezones as grid
unitdb	List units as grid

Slot Details

parseEnum

static Str:Dict parseEnum(Obj? enum)

Parse enum as ordered map of Str:Dict keyed by name. Dict tags:

name: str key
doc: fandoc string if available

Supported inputs:

null returns empty list
Dict of Dicts
Str[] names
Str newline separated names
Str comma separated names
Str fandoc list as - name: fandoc lines

parseEnumNames

static Str[] parseEnumNames(Obj? enum)

Convenience for parseEnum which returns only a list of string names. Using this method is more efficient than calling parseEnums and then mapping the keys.

pid

static Int? pid()

Process id or null if cannot be determined

pods

static Grid pods()

List pods as grid

threadDump

static Str threadDump(Int id)

Dump a specific thread by its id

threadDumpAll

static Str threadDumpAll()

Dump all threads

threadDumpDeadlocks

static Str threadDumpDeadlocks()

Dump thread deadlocks if detected

threadId

static Int threadId()

Current thread id

tzdb

static Grid tzdb()

List timezones as grid

unitdb

static Grid unitdb()

List units as grid

HxWatch

abstract const class HxWatch : Obj

HxWatch is a subscription to a set of records in a project database. It provides an efficient mechanism to poll for changes. Also see Watches.

Fields


lease	The lease determines the max duration which may elapse without a renew call before the watch is expired.

Methods


add	Convenience for `addAll([id])`
addAll	Add the given records to this watch.
addGrid	Convenience for `addAll` for `id` column of each row.
close	Close this watch and unsubscribe all its records.
dis	Debug display string used during `watchOpen`
equals	Equality based on reference equality
hash	Identity hash
id	Identifier which uniquely identifies this watch in the project
isClosed	Return if this watch has been closed
isEmpty	Return if the list of recs currently subscribed is empty.
list	List the rec ids currently subscribed by this watch.
poll	Get all the records which have been modified since the given ticks.
remove	Convenience for `removeAll([id])`
removeAll	Remove the given records from this watch.
removeGrid	Convenience for `removeAll` for `id` column of each row
rt	Runtime associated with this watch
toStr	Debug string

Slot Details

add

Void add(Ref id)

Convenience for addAll([id])

addAll

abstract Void addAll(Ref[] ids)

Add the given records to this watch. Silently ignore any ids already subscribed by this watch, not found in the database, or which are inaccessible to the current user. Raise exception if watch is closed. This call renews the lease.

addGrid

Void addGrid(Grid grid)

Convenience for addAll for id column of each row. If any row is missing an id tag then it is silently skipped.

close

abstract Void close()

Close this watch and unsubscribe all its records. If watch is already closed, this method is a no op.

dis

abstract Str dis()

Debug display string used during watchOpen

equals

override Bool equals(Obj? that)

Equality based on reference equality

hash

override Int hash()

Identity hash

id

abstract Str id()

Identifier which uniquely identifies this watch in the project

isClosed

abstract Bool isClosed()

Return if this watch has been closed

isEmpty

abstract Bool isEmpty()

Return if the list of recs currently subscribed is empty.

lease

abstract Duration lease

The lease determines the max duration which may elapse without a renew call before the watch is expired. The default is 1min. Clients can attempt to tune the lease time by setting this field, but no guarantee is made that the framework will honor extremely long lease times.

list

abstract Ref[] list()

List the rec ids currently subscribed by this watch. Raise exception if watch is closed.

poll

abstract Dict[] poll(Duration ticks := this.lastPoll())

Get all the records which have been modified since the given ticks. An empty list is returned if no changes have been made to the watched records since ticks. There is no ordering to the resulting list. This method automatically renews the lease and keeps track of the last poll ticks. Also see Watches.

remove

Void remove(Ref id)

Convenience for removeAll([id])

removeAll

abstract Void removeAll(Ref[] ids)

Remove the given records from this watch. Any ids not currently subscribed by this watch are silently ignored. Raise exception if watch is closed. This call renews the lease.

removeGrid

Void removeGrid(Grid grid)

Convenience for removeAll for id column of each row

rt

abstract HxRuntime rt()

Runtime associated with this watch

toStr

override Str toStr()

Debug string

HxWatchService

const mixin HxWatchService : HxService

Watch subscription APIs

Methods


get	Find an open watch by its identifier.
isWatched	Return if given record id is under at least one watch
list	List the watches currently open for this runtime.
listOn	Return list of watches currently subscribed to the given id, or return empty list if the given id is not in any watches.
open	Open a new watch with given display string for debugging.

Slot Details

get

abstract HxWatch? get(Str id, Bool checked := true)

Find an open watch by its identifier. If not found then throw Err or return null based on checked flag. Also see Watches.

isWatched

abstract Bool isWatched(Ref id)

Return if given record id is under at least one watch

list

abstract HxWatch[] list()

List the watches currently open for this runtime. Also see Watches.

listOn

abstract HxWatch[] listOn(Ref id)

Return list of watches currently subscribed to the given id, or return empty list if the given id is not in any watches.

open

abstract HxWatch open(Str dis)

Open a new watch with given display string for debugging. Also see Watches.

hx 运行时 API 参考 ​

目录（导读） ​

概述（中译） ​

API 正文（英文） ​

hx ​

mixins ​

classes ​

facets ​

HxApiOp ​

Slot Details ​

def ​

make ​

name ​

onRequest ​

onService ​

HxCli ​

Slot Details ​

aliases ​

appName ​

find ​

list ​

log ​

name ​

printLine ​

run ​

summary ​

HxContext ​

Slot Details ​

checkAdmin ​

checkSu ​

db ​

rt ​

session ​

user ​

HxContextService ​

Slot Details ​

create ​

HxCoreFuncs ​

Slot Details ​

about ​

commit ​

context ​

diff ​

isSteadyState ​

isWatched ​

libAdd ​

libRemove ​

libStatus ​

passwordSet ​

pods ​

read ​

readAll ​

readAllStream ​

readAllTagNames ​

readAllTagVals ​

readById ​

readByIdPersistentTags ​

readByIdTransientTags ​

readByIds ​

readByIdsStream ​

readCount ​

readLink ​

services ​

stripUncommittable ​

toRec ​

toRecId ​

toRecIdList ​

toRecList ​

tzdb ​

unitdb ​

watchAdd ​

watchClose ​

watchOpen ​

watchPoll ​

watchRemove ​

xetoReload ​

HxHttpService ​

Slot Details ​

apiUri ​

siteUri ​

`hx` 运行时 API 参考

目录（导读）

概述（中译）

API 正文（英文）

hx

mixins

classes

facets

HxApiOp

Slot Details

def

make

name

onRequest

onService

HxCli

Slot Details

aliases

appName

find

list

log

name

printLine

run

summary

HxContext

Slot Details

checkAdmin

checkSu

db

rt

session

user

HxContextService

Slot Details

create

HxCoreFuncs

Slot Details

about

commit

context

diff

isSteadyState

isWatched

libAdd

libRemove

libStatus

passwordSet

pods

read

readAll

readAllStream

readAllTagNames

readAllTagVals

readById

readByIdPersistentTags

readByIdTransientTags

readByIds

readByIdsStream

readCount

readLink

services

stripUncommittable

toRec

toRecId

toRecIdList

toRecList

tzdb

unitdb

watchAdd

watchClose

watchOpen

watchPoll

watchRemove

xetoReload

HxHttpService

Slot Details

apiUri

siteUri