FIN 5.3.1 中文文档

外观

folio ​

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

导读： Diff 封装了一组要应用到记录的更改。

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

目录（导读） ​

  • mixins
  • classes
  • Slot Details
    • add
    • changes
    • flags
    • force
    • forceTransient
    • getNew
    • getOld
    • id
    • isAdd
    • isForce
    • isRemove
    • isTransient
    • isUpdate
    • make
    • makeAdd
    • newMod
    • newRec
    • oldMod
    • oldRec
    • remove
    • toStr
    • transient
    • backup
    • close
    • closeAsync
    • commit
    • commitAll
    • commitAllAsync
    • commitAsync
    • config
    • dir
    • log
    • name
    • passwords
    • read
    • readAll
    • readAllList
    • readById
    • readByIds
    • readByIdsList
    • readCount
    • create
    • list
    • delete
    • in
    • size
    • ts
    • idPrefix
    • opts
    • pool
    • open
    • folio
    • main
    • supportsFolioX
    • supportsHis
    • supportsIdPrefixRename
    • supportsSparkIndex
    • supportsTransient
    • teardown
    • test
    • verify
    • verifyCurVerChange
    • verifyCurVerNoChange
    • verifyDictDis
    • verifyEq
    • verifyIdDis
    • verifyNotEq
    • verifyNotSame
    • verifyRecSame
    • verifySame
    • get
    • set

概述（中译） ​

const class Diff : Obj

Diff 封装了一组要应用到记录的更改。

构造函数

字段

方法

插槽详情

API 正文（英文） ​

add ​

const static Int add := 1

Flag bitmask for isAdd

changes ​

const Dict changes

Changes applied to oldRec with resulting newRec

flags ​

const Int flags

Bitmask meta-data for diff

force ​

const static Int force := 8

Flag bitmask for isForce

forceTransient ​

const static Int forceTransient := @force.or(@transient)

Flag bitmask for force and transient

getNew ​

Obj? getNew(Str tag, Obj? def := null)

Get tag value from new record or null.

getOld ​

Obj? getOld(Str tag, Obj? def := null)

Get tag value from old record or null.

id ​

const Ref id

Target record id

isAdd ​

Bool isAdd()

Flag indicating if adding a new record to the project

isForce ​

Bool isForce()

Flag indicating that changes should be applied regardless of other concurrent changes which may be been applied after the oldRec version was read.

isRemove ​

Bool isRemove()

Flag indicating if remove an existing record from the project

isTransient ​

Bool isTransient()

Flag indicating that this diff should not be flushed to persistent storage (it may or may not be persisted).

isUpdate ​

Bool isUpdate()

Update diff - not an add nor a remove

make ​

new make(Dict? oldRec, Obj? changes, Int flags := 0)

Construct a modfication for an existing record. The oldRec should be the instance which was read from the project. Any tags to add/set/remove should be included in the changes dict. Use Remove.val to indicate a tag should be removed. See makeAdd to create a Diff for adding a new record to a project.

makeAdd ​

new makeAdd(Obj? changes, Ref id := Ref.gen())

Make a Diff to add a new record into the database.

newMod ​

const DateTime? newMod

Timestamp version of newRec or null

newRec ​

const Dict? newRec

Updated record which is null until after commit

oldMod ​

const DateTime? oldMod

Timestamp version of oldRec or null if adding new record

oldRec ​

const Dict? oldRec

Original record or null if adding new record

remove ​

const static Int remove := 2

Flag bitmask for isRemove

toStr ​

virtual override Str toStr()

String representation

transient ​

const static Int transient := 4

Flag bitmask for isTransient

Folio ​

abstract const class Folio : Obj

Folio database

Constructors

makeSub-class constructor

Fields

configConfiguration used to init database
dirHome directory for this database
logLogging for this database
nameName of this database

Methods

backupBackup APIs
closeClose the database synchronously (block until closed)
closeAsyncClose the database asynchronously and return future
commitConvenience for commitAll with a single diff.
commitAllApply a list of diffs to the database in batch.
commitAllAsyncCommit a list of diffs to the database asynchronously.
commitAsyncConvenience for commitAllAsync with a single diff.
passwordsGet storage for passwords and other secrets
readFind the first record which matches the given filter.
readAllMatch all the records against a filter and return as grid.
readAllListMatch all the records against a filter and return as list.
readByIdConvenience for readByIds with single id.
readByIdsRead a list of records by ids into a grid.
readByIdsListRead a list of records by id.
readCountReturn the number of records which match given filter.

Slot Details ​

backup ​

abstract FolioBackup backup()

Backup APIs

close ​

Void close(Duration? timeout := null)

Close the database synchronously (block until closed)

closeAsync ​

FolioFuture closeAsync()

Close the database asynchronously and return future

commit ​

Diff commit(Diff diff)

Convenience for commitAll with a single diff.

commitAll ​

Diff[] commitAll(Diff[] diffs)

Apply a list of diffs to the database in batch. Either all the changes are successfully applied, or else none of them are applied and an exception is raised. Return updated Diffs which encapsulate both the old and new version of each record.

If any of the records have been modified since they were read for the given change set then ConcurrentChangeErr is thrown unless Diff.force configured.

commitAllAsync ​

FolioFuture commitAllAsync(Diff[] diffs)

Commit a list of diffs to the database asynchronously.

commitAsync ​

FolioFuture commitAsync(Diff diff)

Convenience for commitAllAsync with a single diff.

config ​

const FolioConfig config

Configuration used to init database

dir ​

const File dir

Home directory for this database

log ​

const Log log

Logging for this database

make ​

new make(FolioConfig config)

Sub-class constructor

name ​

const Str name

Name of this database

passwords ​

abstract PasswordStore passwords()

Get storage for passwords and other secrets

read ​

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

Find the first record which matches the given filter. Throw UnknownRecErr or return null based on checked flag.

readAll ​

Grid readAll(Filter filter, Dict? opts := null)

Match all the records against a filter and return as grid.

Options:

  • limit: max number of recs to read
  • search: search string to apply in addition to filter
  • sort: marker tag to sort recs by dis string
  • trash: marker tag to include recs with trash tag
  • gridMeta: Dict to use for grid meta

readAllList ​

Dict[] readAllList(Filter filter, Dict? opts := null)

Match all the records against a filter and return as list. This method uses same semantics and options as readAll.

readById ​

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

Convenience for readByIds with single id.

readByIds ​

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

Read a list of records by 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 project 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).

readByIdsList ​

Dict?[] readByIdsList(Ref[] ids, Bool checked := true)

Read a list of records by id. The resulting list matches the list of ids by index (null if record not found).

readCount ​

Int readCount(Filter filter, Dict? opts := null)

Return the number of records which match given filter. This method supports the same options as readAll.

FolioBackup ​

const mixin FolioBackup

FolioBackup provides APIs associated with managing backups

Methods

createKick off a backup operation in the background.
listList the backups currently available ordered from newest to oldest.

Slot Details ​

create ​

abstract FolioFuture create()

Kick off a backup operation in the background. Raise exception if a backup is already running.

list ​

abstract FolioBackupFile[] list()

List the backups currently available ordered from newest to oldest.

FolioBackupFile ​

const class FolioBackupFile : Obj

Handle to a backup zip file

Methods

deleteDelete the backup file which is an unrecoverable operation
inOpen an input stream to read the backup zip file
sizeSize in bytes of the backup zip file
toStrReturn file name
tsTimestamp the backup was started

Slot Details ​

delete ​

Void delete()

Delete the backup file which is an unrecoverable operation

in ​

InStream in()

Open an input stream to read the backup zip file

size ​

Int size()

Size in bytes of the backup zip file

toStr ​

virtual override Str toStr()

Return file name

ts ​

DateTime ts()

Timestamp the backup was started

FolioConfig ​

const class FolioConfig : Obj

FolioConfig specifies initialization constants

Constructors

makeIt-block constructor

Fields

dirHome directory for this database
idPrefixRef prefix to make internal refs absolute.
logLogging for this database
nameName for this database
optsAdditional options
poolActor pool to use for threading

Slot Details ​

dir ​

const File dir

Home directory for this database

idPrefix ​

const Str? idPrefix

Ref prefix to make internal refs absolute. This prefix must include a trailing colon such as "p:project:r:"

log ​

const Log log

Logging for this database

make ​

new make(|This| f)

It-block constructor

name ​

const Str name := "db"

Name for this database

opts ​

const Dict opts := Etc.emptyDict

Additional options

pool ​

const ActorPool pool

Actor pool to use for threading

FolioFlatFile ​

const class FolioFlatFile : Folio

FolioFlatFile is a simple Folio implementation backed by a Trio flat file.

Methods

openOpen for given directory.

Slot Details ​

open ​

static FolioFlatFile open(FolioConfig config)

Open for given directory. Create automatically if file not found. The database is stored in a file named "folio.trio" under dir.

FolioFuture ​

abstract const class FolioFuture : Future

Response from a Folio database that provides access to eventual result

Slot Details ​

FolioTestImpl ​

abstract class FolioTestImpl : Obj

FolioTestImpl plugs a specific Folio implementation into AbstractFolioTest

Methods

closeClose the current database
folioFolio instance
mainDump implementations installed
nameImplementation name for output
openOpen the folio implementation
supportsFolioXDoes the implementation support FolioX APIS
supportsHisDoes the implementation support the history API
supportsIdPrefixRenameDoes the implementation support re-opening with different id prefix
supportsSparkIndexDoes the implementation support spark index APIs
supportsTransientDoes the implementation support transient commits
teardownClose and delete current database
testCurrent test
verify
verifyCurVerChangeVerify the current version of Folio is greater than prev.
verifyCurVerNoChangeVerify the current version the same as prev.
verifyDictDisVerify Dict.dis
verifyEq
verifyIdDisVerify Ref.dis
verifyNotEq
verifyNotSame
verifyRecSameVerify record a is the same b.
verifySame

Slot Details ​

close ​

virtual Void close()

Close the current database

folio ​

Folio folio()

Folio instance

main ​

static Void main()

Dump implementations installed

name ​

abstract Str name()

Implementation name for output

open ​

abstract Folio open(FolioConfig config)

Open the folio implementation

supportsFolioX ​

virtual Bool supportsFolioX()

Does the implementation support FolioX APIS

supportsHis ​

virtual Bool supportsHis()

Does the implementation support the history API

supportsIdPrefixRename ​

virtual Bool supportsIdPrefixRename()

Does the implementation support re-opening with different id prefix

supportsSparkIndex ​

virtual Bool supportsSparkIndex()

Does the implementation support spark index APIs

supportsTransient ​

virtual Bool supportsTransient()

Does the implementation support transient commits

teardown ​

virtual Void teardown()

Close and delete current database

test ​

AbstractFolioTest test()

Current test

verify ​

Void verify(Bool c, Str? msg := null)

verifyCurVerChange ​

virtual Int verifyCurVerChange(Int prev)

Verify the current version of Folio is greater than prev. Return new version

verifyCurVerNoChange ​

virtual Int verifyCurVerNoChange(Int prev)

Verify the current version the same as prev. Return new version

verifyDictDis ​

virtual Void verifyDictDis(Dict r, Str expect)

Verify Dict.dis

verifyEq ​

Void verifyEq(Obj? a, Obj? b, Str? msg := null)

verifyIdDis ​

virtual Void verifyIdDis(Ref id, Str expect)

Verify Ref.dis

verifyNotEq ​

Void verifyNotEq(Obj? a, Obj? b, Str? msg := null)

verifyNotSame ​

Void verifyNotSame(Obj? a, Obj? b, Str? msg := null)

verifyRecSame ​

virtual Void verifyRecSame(Dict? a, Dict? b)

Verify record a is the same b. If the implementation supports an in-memory cache then they should be the same instance in memory, otherwise they should be the same by tag values

verifySame ​

Void verifySame(Obj? a, Obj? b, Str? msg := null)

PasswordStore ​

const class PasswordStore : Obj

PasswordStore manages plaintext/hashed passwords and other secrets. It is stored via an obscured props file to prevent casual reading, but is not encrypted. The passwords file must be kept secret and reads must be sequestered from all network access. We separate secrets from the main database so that it may be more easily secured.

Methods

getGet a password by its key or return null if not found.
removeRemove a password by its key.
setSet a password by its key.

Slot Details ​

get ​

Str? get(Str key)

Get a password by its key or return null if not found.

remove ​

Void remove(Str key)

Remove a password by its key.

set ​

Void set(Str key, Str val)

Set a password by its key.