The weblocks-stores Reference Manual

This is the weblocks-stores Reference Manual, version 0.5.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 07:07:09 2024 GMT+0.

Table of Contents


1 Systems

The main system appears first, followed by any subsystem dependency.


1.1 weblocks-stores

A base for weblocks stores

Maintainer

Olexiy Zamkoviy, Scott L. Burson

Author

Olexiy Zamkoviy

License

LLGPL

Version

0.5.1

Dependencies
  • closer-mop (system).
  • metatilities (system).
  • weblocks-util (system).
Source

weblocks-stores.asd.

Child Component

src (module).


2 Modules

Modules are listed depth-first from the system components tree.


2.1 weblocks-stores/src

Source

weblocks-stores.asd.

Parent Component

weblocks-stores (system).

Child Components

2.2 weblocks-stores/src/store

Dependency

package.lisp (file).

Source

weblocks-stores.asd.

Parent Component

src (module).

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 weblocks-stores/weblocks-stores.asd

Source

weblocks-stores.asd.

Parent Component

weblocks-stores (system).

ASDF Systems

weblocks-stores.

Packages

weblocks-stores-asd.


3.1.2 weblocks-stores/src/package.lisp

Source

weblocks-stores.asd.

Parent Component

src (module).

Packages

weblocks-stores.


3.1.3 weblocks-stores/src/store/store-api.lisp

Source

weblocks-stores.asd.

Parent Component

store (module).

Public Interface

3.1.4 weblocks-stores/src/store/store-utils.lisp

Source

weblocks-stores.asd.

Parent Component

store (module).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 weblocks-stores

Base for weblocks store drivers

Source

package.lisp.

Use List
  • anaphora.
  • common-lisp.
  • metabang.utilities.
  • weblocks-util.
Public Interface
Internals

4.2 weblocks-stores-asd

Source

weblocks-stores.asd.

Use List
  • asdf/interface.
  • common-lisp.

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Special variables

Special Variable: *debug-stores*

Debugging flag, set ’T’ to see record ids in repl, set ’NIL’ to have usual objects behavior.

Package

weblocks-stores.

Source

store-api.lisp.

Special Variable: *default-serialization-format*

Debugging flag, set ’T’ to see record ids in repl, set ’NIL’ to have usual objects behavior.

Package

weblocks-stores.

Source

store-api.lisp.

Special Variable: *default-store*

The default store to which objects are persisted. Bound while a webapp is handling a request to the value of its ‘webapp-default-store-name’. By using ‘defstore’ after the relevant ‘defwebapp’ in the same package, barring an explicit setting, the webapp will be set to use the defined store automatically.

Package

weblocks-stores.

Source

store-api.lisp.

Special Variable: *store-names*

A list of store names in the order in which they were defined.

Package

weblocks-stores.

Source

store-utils.lisp.


5.1.2 Macros

Macro: defstore (name type &rest store-args)

A macro that helps define a store. A global variable ’name’ is defined, and ’open-store’ is called with appropriate store type and arguments. Note that the last store will also be the default (see *default-store*). All stores defined via ’defstore’ will be opened and bound when ’start-weblocks’ is called, and closed when ’stop-weblocks’ is called. If ‘store-args’ contains a keyword ’load-store-system-p’ with a value of NIL following it then the store’s ASDF system (‘weblocks-STORENAME’) will not be loaded afterwards. Turning this off is useful for binary images.

Package

weblocks-stores.

Source

store-utils.lisp.


5.1.3 Ordinary functions

Function: class-visible-slots (cls &key readablep writablep)

Converts ’cls’ to class object if it is a name, and calls ’class-visible-slots-impl’.

Package

weblocks-stores.

Source

store-api.lisp.

Function: close-stores ()

Closes all stores.

Package

weblocks-stores.

Source

store-utils.lisp.

Function: list-store-types ()
Package

weblocks-stores.

Source

store-utils.lisp.

Function: mapstores (fn)

Maps a function over existing stores in the order in which they were defined. Returns NIL.

Package

weblocks-stores.

Source

store-utils.lisp.

Function: object-id-slot-name (obj)

Returns the slot name of the slot that holds the unique identifier of ’obj’. This information is obtained via calling ’class-id-slot-name’.

Package

weblocks-stores.

Source

store-utils.lisp.

Function: object-store (obj)

Returns the store for the object by calling ’class-store’.

Package

weblocks-stores.

Source

store-utils.lisp.

Function: open-stores ()

Opens and binds all stores.

Package

weblocks-stores.

Source

store-utils.lisp.

Function: persist-objects (store objects &rest keys)

Persists all objects in ’objects’ sequence into ’store’.

Package

weblocks-stores.

Source

store-utils.lisp.

Function: register-store-type (store-type)
Package

weblocks-stores.

Source

store-utils.lisp.


5.1.4 Generic functions

Generic Function: begin-transaction (store)

Begins a transaction on ’store’. Note, if the given
store does not have transaction support, this function should return NIL without signalling errors.

Package

weblocks-stores.

Source

store-api.lisp.

Generic Function: class-id-slot-name (class)

Must return the symbol that identifies the slot name which represents the unique ID of the class named ’class’. Default implementation returns ’ID’. Specialize this function if you want to name the slot that holds the class’ unique ID differently.

Package

weblocks-stores.

Source

store-utils.lisp.

Methods
Method: class-id-slot-name (class)
Generic Function: class-store (class-name)

Returns the store where objects of class name
should be persisted. This function should be used by widgets to persist objects. Default implementation returns *default-store*.

Package

weblocks-stores.

Source

store-utils.lisp.

Methods
Method: class-store (class-name)
Generic Function: class-visible-slots-impl (cls &key readablep writablep)

Returns a list of ’standard-direct-slot-definition’
objects for a class and its subclasses. Slots objects for slots that do not have reader accessors are filtered out and not returned.

If ’readablep’ is true, filters out the slots that don’t have a reader (or accessor) defined.
If ’writablep’ is true, filters out the slots that don’t have a writer (or accessor) defined.

Package

weblocks-stores.

Source

store-api.lisp.

Methods
Method: class-visible-slots-impl (cls &key readablep writablep)
Generic Function: clean-store (store)

Cleans all the data in the store. This function
should erase data, but not necessarily any schema information (like tables, etc.)

Package

weblocks-stores.

Source

store-api.lisp.

Generic Function: close-store (store)

Closes a connection to the store. If the value of
*default-store* is equal to ’store’, *default-store* must be set to NIL.

Package

weblocks-stores.

Source

store-api.lisp.

Generic Function: commit-transaction (store)

Commits a transaction started on ’store’. Note, if
the given store does not have transaction support, or the store isn’t in a transaction, this function should return NIL without signalling errors.

Package

weblocks-stores.

Source

store-api.lisp.

Generic Function: count-persistent-objects (store class-name &key &allow-other-keys)

Returns the number of persistent objects stored in
’store’ of ’class-name’, bound by the given keyword parameters. For documentation of keyword parameters, see ’find-persistent-objects’.

Other implementation dependent keys may be defined by a given store.

Package

weblocks-stores.

Source

store-api.lisp.

Generic Function: delete-model-class (store cls)

Completely removes model class. ‘list-model-classes‘ should not contain class after calling this method.

Package

weblocks-stores.

Source

store-api.lisp.

Methods
Method: delete-model-class (store cls)
Generic Function: delete-persistent-object (store object)

Deletes the persistent object from ’store’. After
deleting the persistent object, set unique ID of ’object’ to NIL (see ’(setf object-id)’).

Package

weblocks-stores.

Source

store-api.lisp.

Generic Function: delete-persistent-object-by-id (store class-name object-id)

Similar to ’delete-persistent-object’, but instead deletes object with the specified ’object-id’.

Package

weblocks-stores.

Source

store-api.lisp.

Generic Function: dynamic-transaction (store proc)

Call PROC, a thunk, while in a transaction of STORE. See ‘use-dynamic-transaction-p’ for details.

Package

weblocks-stores.

Source

store-api.lisp.

Methods
Method: dynamic-transaction (store proc)
Generic Function: find-persistent-object-by-id (store class-name object-id)

Finds and returns a persistent object of a given
class name in a given store by its unique id. If the object isn’t found, returns NIL.

Package

weblocks-stores.

Source

store-api.lisp.

Generic Function: find-persistent-objects (store class-name &key order-by range &allow-other-keys)

Looks up and returns objects of appropriate
’class-name’ in the ’store’ bound by the given keyword parameters.

If ’order-by’ is specified, orders the returned objects by the given slot in the given order. If ’order-by’ is not NIL, it is expected to be a cons cell with slot name as ’car’ and :asc or :desc as ’cdr’.

If ’range’ is specified, returns only the specified range of objects. The CAR of ’range’ is the index of the initial
object (inclusive) and CDR is the index past the last object. Note, the range should be applied after the objects have been filtered and ordered if necessary.

Other implementation dependent keys may be defined by a given store.

Package

weblocks-stores.

Source

store-api.lisp.

Generic Function: list-model-classes (store)

Returns list with symbols - models class names

Package

weblocks-stores.

Source

store-api.lisp.

Generic Function: object-id (obj)

Returns a value that uniquely identifies an object in memory or in a backend store. The default implementation looks for an ’id’ slot via ’slot-value’. If such slot is not present, signals an
error. Specialize this function for various back end stores and other object identification schemes.

Package

weblocks-stores.

Source

store-utils.lisp.

Methods
Method: object-id ((obj null))
Method: object-id ((obj standard-object))
Generic Function: (setf object-id) (obj)

Sets the value that uniquely identifies an object in memory or in a backend store. The default implementation tries to set an ’id’ slot via ’slot-value’. If such slot is not present, signals an
error. Specialize this function for various back end stores and other object identification schemes.

Package

weblocks-stores.

Source

store-utils.lisp.

Methods
Method: (setf object-id) ((obj standard-object))
Generic Function: open-store (store-type &rest args)

Opens a connection to a store specified by
’store-type’. This function must return the instance of the connection to the store. Methods can accept any number of custom keyword parameters. Additionally, the function must set *default-store* to the value of newly created store.

Package

weblocks-stores.

Source

store-api.lisp.

Generic Function: persist-object (store object &key)

Persists ’object’ into ’store’, answering
’object’. If the object does not have a unique ID (see ’object-id’), persist ’object’ into store and set its unique ID via (see ’(setf object-id)’). If the object has a unique ID, find relevant entry in the store and update it with ’object’.

Package

weblocks-stores.

Source

store-api.lisp.

Generic Function: replace-on-redefine-p (store-type)

When true replaces existing store on reexecuting (defstore ...) block.

Package

weblocks-stores.

Source

store-api.lisp.

Methods
Method: replace-on-redefine-p (store-type)
Generic Function: rollback-transaction (store)

Rolls back a transaction started on ’store’. Note,
if the given store does not have transaction support, or the store isn’t in a transaction, this function should return NIL without signalling errors.

Package

weblocks-stores.

Source

store-api.lisp.

Generic Function: serialize (obj &key format)

Method for serialization of objects, objects sets for specific model and stores.

Package

weblocks-stores.

Source

store-api.lisp.

Generic Function: store-type (store)

Should return keyword type of store

Package

weblocks-stores.

Source

store-api.lisp.

Methods
Method: store-type ((store null))
Method: store-type (store)
Generic Function: unserialize (obj &key format)

Method for deserialization of objects, objects sets for specific model and stores.

Package

weblocks-stores.

Source

store-api.lisp.

Generic Function: use-dynamic-transaction-p (store)

Answer whether ‘action-txn-hook’ and equivalents
should use GF ‘dynamic-transaction’ for transaction control rather than the ‘begin-transaction’, ‘commit-transaction’, and ‘rollback-transaction’ GFs. Be warned that non-local exit behavior for stores that answer true for this may have unique non-local exit unwind behavior.

Package

weblocks-stores.

Source

store-api.lisp.

Methods
Method: use-dynamic-transaction-p (store)

5.2 Internals


5.2.1 Special variables

Special Variable: *store-types*
Package

weblocks-stores.

Source

store-utils.lisp.

Special Variable: *stores*

A hashmap of stores, where each item has store name as key, and structure of type ’store-info’ as value.

Package

weblocks-stores.

Source

store-utils.lisp.


5.2.2 Ordinary functions

Function: %defstore-postdefine (name type)

Helper for ‘defstore’.

Package

weblocks-stores.

Source

store-utils.lisp.

Function: %defstore-predefine (name type &rest args)

Helper for ‘defstore’.

Package

weblocks-stores.

Source

store-utils.lisp.

Function: copy-store-info (instance)
Package

weblocks-stores.

Source

store-utils.lisp.

Function: make-store-info (&key type args)
Package

weblocks-stores.

Source

store-utils.lisp.

Function: maybe-replace-store (name)

Replaces store on (defstore ...) call repeating.
Works only for those stores for which (replace-on-redefine-p ...) is true

Package

weblocks-stores.

Source

store-utils.lisp.

Reader: store-info-args (instance)
Writer: (setf store-info-args) (instance)
Package

weblocks-stores.

Source

store-utils.lisp.

Target Slot

args.

Function: store-info-p (object)
Package

weblocks-stores.

Source

store-utils.lisp.

Reader: store-info-type (instance)
Writer: (setf store-info-type) (instance)
Package

weblocks-stores.

Source

store-utils.lisp.

Target Slot

type.


5.2.3 Structures

Structure: store-info

Information about a store.

Package

weblocks-stores.

Source

store-utils.lisp.

Direct superclasses

structure-object.

Direct slots
Slot: type
Package

common-lisp.

Type

symbol

Readers

store-info-type.

Writers

(setf store-info-type).

Slot: args
Readers

store-info-args.

Writers

(setf store-info-args).


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   %   (  
B   C   D   F   G   L   M   O   P   R   S   U  
Index Entry  Section

%
%defstore-postdefine: Private ordinary functions
%defstore-predefine: Private ordinary functions

(
(setf object-id): Public generic functions
(setf object-id): Public generic functions
(setf store-info-args): Private ordinary functions
(setf store-info-type): Private ordinary functions

B
begin-transaction: Public generic functions

C
class-id-slot-name: Public generic functions
class-id-slot-name: Public generic functions
class-store: Public generic functions
class-store: Public generic functions
class-visible-slots: Public ordinary functions
class-visible-slots-impl: Public generic functions
class-visible-slots-impl: Public generic functions
clean-store: Public generic functions
close-store: Public generic functions
close-stores: Public ordinary functions
commit-transaction: Public generic functions
copy-store-info: Private ordinary functions
count-persistent-objects: Public generic functions

D
defstore: Public macros
delete-model-class: Public generic functions
delete-model-class: Public generic functions
delete-persistent-object: Public generic functions
delete-persistent-object-by-id: Public generic functions
dynamic-transaction: Public generic functions
dynamic-transaction: Public generic functions

F
find-persistent-object-by-id: Public generic functions
find-persistent-objects: Public generic functions
Function, %defstore-postdefine: Private ordinary functions
Function, %defstore-predefine: Private ordinary functions
Function, (setf store-info-args): Private ordinary functions
Function, (setf store-info-type): Private ordinary functions
Function, class-visible-slots: Public ordinary functions
Function, close-stores: Public ordinary functions
Function, copy-store-info: Private ordinary functions
Function, list-store-types: Public ordinary functions
Function, make-store-info: Private ordinary functions
Function, mapstores: Public ordinary functions
Function, maybe-replace-store: Private ordinary functions
Function, object-id-slot-name: Public ordinary functions
Function, object-store: Public ordinary functions
Function, open-stores: Public ordinary functions
Function, persist-objects: Public ordinary functions
Function, register-store-type: Public ordinary functions
Function, store-info-args: Private ordinary functions
Function, store-info-p: Private ordinary functions
Function, store-info-type: Private ordinary functions

G
Generic Function, (setf object-id): Public generic functions
Generic Function, begin-transaction: Public generic functions
Generic Function, class-id-slot-name: Public generic functions
Generic Function, class-store: Public generic functions
Generic Function, class-visible-slots-impl: Public generic functions
Generic Function, clean-store: Public generic functions
Generic Function, close-store: Public generic functions
Generic Function, commit-transaction: Public generic functions
Generic Function, count-persistent-objects: Public generic functions
Generic Function, delete-model-class: Public generic functions
Generic Function, delete-persistent-object: Public generic functions
Generic Function, delete-persistent-object-by-id: Public generic functions
Generic Function, dynamic-transaction: Public generic functions
Generic Function, find-persistent-object-by-id: Public generic functions
Generic Function, find-persistent-objects: Public generic functions
Generic Function, list-model-classes: Public generic functions
Generic Function, object-id: Public generic functions
Generic Function, open-store: Public generic functions
Generic Function, persist-object: Public generic functions
Generic Function, replace-on-redefine-p: Public generic functions
Generic Function, rollback-transaction: Public generic functions
Generic Function, serialize: Public generic functions
Generic Function, store-type: Public generic functions
Generic Function, unserialize: Public generic functions
Generic Function, use-dynamic-transaction-p: Public generic functions

L
list-model-classes: Public generic functions
list-store-types: Public ordinary functions

M
Macro, defstore: Public macros
make-store-info: Private ordinary functions
mapstores: Public ordinary functions
maybe-replace-store: Private ordinary functions
Method, (setf object-id): Public generic functions
Method, class-id-slot-name: Public generic functions
Method, class-store: Public generic functions
Method, class-visible-slots-impl: Public generic functions
Method, delete-model-class: Public generic functions
Method, dynamic-transaction: Public generic functions
Method, object-id: Public generic functions
Method, object-id: Public generic functions
Method, replace-on-redefine-p: Public generic functions
Method, store-type: Public generic functions
Method, store-type: Public generic functions
Method, use-dynamic-transaction-p: Public generic functions

O
object-id: Public generic functions
object-id: Public generic functions
object-id: Public generic functions
object-id-slot-name: Public ordinary functions
object-store: Public ordinary functions
open-store: Public generic functions
open-stores: Public ordinary functions

P
persist-object: Public generic functions
persist-objects: Public ordinary functions

R
register-store-type: Public ordinary functions
replace-on-redefine-p: Public generic functions
replace-on-redefine-p: Public generic functions
rollback-transaction: Public generic functions

S
serialize: Public generic functions
store-info-args: Private ordinary functions
store-info-p: Private ordinary functions
store-info-type: Private ordinary functions
store-type: Public generic functions
store-type: Public generic functions
store-type: Public generic functions

U
unserialize: Public generic functions
use-dynamic-transaction-p: Public generic functions
use-dynamic-transaction-p: Public generic functions