SkySpark by SkyFoundry

abstract const class proj::Proj

sys::Obj
  proj::Proj

Proj is the interface for working with a local in-VM project database.

appendBin

abstract Void appendBin(Dict rec, Str tag, Buf data)

Append the specified bytes to the end of the bin. If tag doesn't map to a Bin value, then throw UnknownNameErr. The bytes are written according to OutStream.writeBuf. Once this method is called the buf should not be modified. This method blocks until the data is successfully appended. Throw IOErr on failure.

commit

abstract Diff commit(Diff diff)

Convenience for commitAll to commit a single diff.

commitAll

abstract 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.

compact

abstract Void compact()

Kick off a compaction operation in the background. During this process the project is readonly - see mode. A compaction will rewrite proj.diffs resulting a smaller file size and faster load time. Compaction always implicitly performs an emptyTrash operation. Use status to monitor the progress of the maintenance operation.

dir

abstract File dir()

Base directory for project

dis

Str dis()

Display string for the project which is status->dis or if not defined then the project name.

emptyTrash

abstract Void emptyTrash()

Remove all the records and their bins which are marked with the trash flag.

ext

Ext? ext(Str name, Bool checked := true)

Find an installed extension by its programtic name. If not found then throw Err or return null based on checked flag.

extActorPool

abstract ActorPool extActorPool()

The shared actor pool for extensions to use for their actors.

exts

Ext[] exts()

List the extensions which are enabled for this project.

isSteadyState

abstract Bool isSteadyState()

Has the proj has reached steady state. Steady state is reached after a configurable wait period elapses after the project is fully loaded. This gives internal services time to spin up before interacting with external systems. The default is 1min, but may be tuned via the steadyState tag on projMeta. See Tuning.

log

Log log(Str category := "sys")

Get log to use for project specific logging.

mode

abstract ProjMode mode

Proj mode: rw, ro, disabled.

If this field is set to rw then the project is put into normal read-write operation. Set to ro to put the project into manual read-only mode, any attempt to write records or bins will throw ReadonlyErr. Setting to disabled throws DisabledErr for both reads/writes (status is still available).

Setting this field during a maintanence operation has no effect until the operation completes.

name

abstract Str name()

Project name

passwords

abstract PasswordManager passwords()

Get the password manager for the project. General practice is store a single password associated with a record where the password key is the string encoding of the record id.

read

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

Find the first record which matches the given filter string. Throw UnknownRecErr or return null based on checked flag. See Filter Chapter for filter format.

readAll

abstract Grid readAll(Str filter)

Match all the records against a filter string and return as grid. See Filter Chapter for filter format.

readBin

abstract InStream readBin(Dict rec, Str tag)

Open an input stream to read the bin contents of the specified rec. If tag doesn't map to a Bin value, then throw UnknownNameErr. If the bin content has never been successfully written throw IOErr. It is critical that the input stream be closed upon completion.

readById

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

Convenience for read(id=$id, checked).

readByIds

abstract 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).

readByName

abstract Dict? readByName(Str? name, Bool checked := true)

Convenience for read(name=$name, checked).

readCount

abstract Int readCount(Str filter)

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

restore

abstract Void restore(Snapshot snapshot, Dict opts := Etc.emptyDict())

Rewrite the project using the given snapshot database image. During this process the project is readonly - see mode. Use status to monitor the progress of the maintenance operation. Also see snapshots and snapshot.

The following options are supported:

  • snapshot: if this tag is defined then perform a snapshot to save current state before restore is started
snapshot

abstract Void snapshot()

Kick off a snapshot operation in the background. During this process the project is readonly - see mode. A snapshot is a zip file which contains a compressed proj.diffs file and all the reachable bins. Transient and trash records are not included in a snapshot. Use status to monitor the progress of the maintenance operation. Also see snapshots and restore.

snapshots

abstract Snapshot[] snapshots()

List the snapshots available for this Proj. Also see snapshot and restore.

status

abstract Dict status()

Return status information about this project which includes:

  • projName: name of the project
  • dis: display name of the project
  • projStatus: one of the following strings:
    • "rw"
    • "ro: maint"
    • "ro: manual"
    • "disabled"
  • projDir: directory Uri of project in file system
  • recCount: number of records in project
  • any tags defined on proj meta-data record

If the project status is currently "ro: maint" then:

  • maint: summary of maintenance operation
  • progress: maintenance progress 0%-100%
  • progressMsg: maintenance activity str
toStr

virtual override Str toStr()

Return name

watch

abstract Watch? watch(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.

watchOpen

abstract Watch watchOpen(Str dis)

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

watches

abstract Watch[] watches()

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

writeBin

abstract OutStream writeBin(Dict rec, Str tag, Int? size)

Open an output stream to write the bin of the specified rec. If tag doesn't map to a Bin value, then throw UnknownNameErr. If the size of the bin content is known, then it should be given for efficiency, otherwise pass null. It is critical that the output stream be closed upon completion.