Common Lisp Package: SUBMARINE

A very simple quasi-object persistency system built on top of Postmodern.

README:

FUNCTION

Public

GET-DAO (TYPE ID)

Get the dao corresponding to the given primary key, or return nil if it does not exist.

MAKE-DAO (TYPE INITARGS)

Create a DAO of the given `TYPE' and initialize it according to the values of the alist `INITARGS'. `Initargs' may contain additional values, not used in the initialization proccess.

QUERY-DAO-FUN (TYPE QUERY)

Execute the given `QUERY' (which can be either a string or a S-SQL expression, which will be evaluated) and return the result as daos of the given `TYPE'. The names of the fields returned by the query must match the slots of the dao. This is a functional interface for `QUERY-DAO'.

RELATE (OBJECT1 OBJECT2 &KEY RELATION (WEIGHT 1))

Make OBJECT1 and OBJECT2 enter into the many-to-many relation `RELATION'. If `RELATION' is not provided, the unnamed relation is assumed.

RELATEDP (OBJECT1 OBJECT2 &KEY RELATION)

Tell whether `OBJECT1' and `OBJECT2' are in the many-to-many relation `RELATION' (or the unnamed relation if `RELATION' is not provided).

SELECT-DAO-FUN (TYPE TEST)

Functional interface for SELECT-DAO.

SLOT-VALUE-OR-ID-IF-FOREIGN (OBJECT SLOT)

SLOT-VALUE if SLOT in OBJECT is not foreign, the ID of the object in the slot otherwise. If the object is not saved, save it.

UNRELATE (OBJECT1 OBJECT2 &KEY RELATION)

`OBJECT1' stops being with `OBJECT2' in `RELATION'.

Private

CLASS-DB-SLOTS (CLASS)

Return the list of non-transient, instance allocated slots of a class.

DB-SLOTS-OF (OBJECT)

List of non-transient, instance allocated slots of OBJECT

NON-DB-SLOT (SLOT)

Slot is transient or its allocation is :CLASS.

WITH-CLASS-CONNECTION-FUN (CLASS WHAT-TO-DO)

Functional interface to the macro WITH-CLASS-CONNECTION. the connection will be pooled.

WITH-CONNECTION-FUN (CONNECTION-SPEC WHAT-TO-DO)

Functional interface to the macro WITH-CONNECTION.

WITH-OBJECT-CONNECTION-FUN (OBJECT WHAT-TO-DO)

Functional interface to the macro WITH-OBJECT-CONNECTION.

Undocumented

ID-SEQ-NAME (CLASS)

SET-FIELDS (OBJECT)

MACRO

Public

DEF-MANY-TO-MANY (CLASS1-NAME CLASS2-NAME &KEY CONNECTION-SPEC NAME)

Defines a possibly named many-to-many mapping between two persistent classes. There can be only one unnamed mapping between any two classes, and any number of named mappings. CLASS*-NAME should be an (unquoted) symbol with class name. Defines additional mapping persistent class `NAME' (if `NAME' is not provided, `CLASS1-NAME-CLASS2-NAME' is used), and for each of classes, a method that retrieves list of instances of second class (named like that class or, if the relation is named, CLASS-NAME-IN-NAME. Mapping class has three slots, `CLASS1-NAME' and `CLASS2-NAME' that hold instances of first and second class, and `WEIGHT' that holds an integer representing the strength of the relationship. The following functions are available: * A predicate `RELATEDP', taking a keyword argument `RELATION', which tells whether two objects are in a relation (if `RELATION' is not provided, the unnamed relation is assumed). It returns a `NAME' or `CLASS1-NAME-CLASS2-NAME' object. It has an accessor `WEIGHT'. * A function `RELATE' (`RELATE-IN-NAME') that establishes a relationship between its two arguments. It takes a key-argument, `WEIGHT', by default 1. The order in which the object arguments are provided is irrelevant. `CONNECTION-SPEC' specifies the connection to be used to create the link table.

DEFDAO (NAME SUPERS &BODY BODY)

Wrapper macro for defining a class inheriting from DAO and with the metaclass set to DB-CLASS.

MAKE-AND-SAVE (TYPE &REST REST)

Make a DAO and immediately save it. Takes the same arguments as (make-instance ((dao dao))).

QUERY-DAO (TYPE QUERY)

Execute the given `QUERY' (which can be either a string or a S-SQL expression, which won't be evaluated) and return the result as daos of the given `TYPE'. The names of the fields returned by the query must match the slots of the dao.

SELECT-DAO (TYPE &OPTIONAL (TEST T))

Select daos of TYPE for the rows in its table for which the given TEST holds.

WITH-CLASS-CONNECTION ((CLASS) &BODY BODY)

Run BODY in an environment with an always pooled connection to the database specified by the DB-CLASS-CONNECTION-SPEC of CLASS.

WITH-CONNECTION ((DATABASE USER PASSWORD HOST &KEY (PORT 5432) POOLED-P) &BODY BODY)

Binds *database* to a new connection and runs body in that scope.

WITH-OBJECT-CONNECTION ((OBJECT) &BODY BODY)

Run BODY in an environment with a connection to the database specified by the DB-CLASS-CONNECTION-SPEC of the class of OBJECT.

GENERIC-FUNCTION

Public

DAO-EXISTS-P (DAO)

Return a boolean indicating whether the given DAO exists in the database.

DAO= (LEFT RIGHT &KEY TEST (TEST 'EQL))

T if all the slot-values of `LEFT' and `RIGHT' are the same. If the compared values are not DAO's, they are compared using `TEST' (which defaults to `EQL'). Otherwise, they are `DAO='ed, with the same `TEST' argument as specified in the topmost call of `DAO='. If neither `LEFT' nor `RIGHT' are DAOs, `TEST' is called.

DELETE-DAO (DAO)

Delete the given dao from the database.

GET-ALL (TYPE OBJECT)

Get all objects of TYPE that stand in a many-to-one relation with OBJECT.

INSERT-DAO (DAO)

Insert the given DAO into the database.

SAVE-DAO (OBJECT)

Save a dao: update it when it already exists, insert it otherwise.

UPDATE-DAO (DAO)

Update the DAO's representation in the database with the values in the given object and return it.

Private

ADD-CONSTRAINT (SLOT CONSTRAINT)

Add a constraint to this slot's class' table.

CREATE-TABLE (CLASS)

Create a table whose columns match the fields of CLASS in the connected database. If CLASS is a symbol, the class it names is used.

DATABASE-CONSISTENT-WITH-SPECIFICATION (CLASS)

Return nothing if TABLE in the connected-p database meets its specification. Otherwise, throw an appropriate error. There must exist a connection to the DATABASE in order to run this function.

RELATE-METHOD (OBJECT1 OBJECT2 RELATION WEIGHT)

Relate `OBJECT1' with `OBJECT2' in `RELATION'.

RELATEDP-METHOD (OBJECT1 OBJECT2 RELATION)

Tell if `OBJECT1' is related to `OBJECT2' in `RELATION'.

REMOVE-FINISHED-CLASSES (CLASS)

Remove classes that are already finished from UNFINISHED-CLASSES of CLASS.

TRY-DELAYED-CONSTRAINTS (CLASS)

Try to call all the delayed constraints present.

UNRELATE-METHOD (OBJECT1 OBJECT2 RELATION)

`OBJECT1' stops being with `OBJECT2' in `RELATION'.

Undocumented

ACTUAL-TYPE (CONDITION)

APPLY-FOREIGN-KEY-CONSTRAINTS (CLASS)

APPLY-UNIQUE-CONSTRAINTS (CLASS)

COLLECT-CONSTRAINTS (CLASS)

COLUMN-NAME (CONDITION)

COLUMN-TYPE (CONDITION)

ID (CONDITION)

NEEDED-TYPE (CONDITION)

TABLE-NAME (CONDITION)

SLOT-ACCESSOR

Public

Undocumented

FOREIGN-TYPE-P (OBJECT)

SETFFOREIGN-TYPE-P (NEW-VALUE OBJECT)

GET-ID (OBJECT)

SETFGET-ID (NEW-VALUE OBJECT)

Private

DB-CLASS-FOREIGN-KEYS (OBJECT)

List of foreign-key slots.

SETFDB-CLASS-FOREIGN-KEYS (NEW-VALUE OBJECT)

List of foreign-key slots.

DB-CLASS-UNFINISHED-CLASSES (OBJECT)

A class allocated slot containing classes for whom not all the constraints could be applied.

SETFDB-CLASS-UNFINISHED-CLASSES (NEW-VALUE OBJECT)

A class allocated slot containing classes for whom not all the constraints could be applied.

DB-CLASS-UNIQUE-KEYS (OBJECT)

List of slots whose value should be unique.

SETFDB-CLASS-UNIQUE-KEYS (NEW-VALUE OBJECT)

List of slots whose value should be unique.

DELAYED-CONSTRAINT (OBJECT)

Closures adding constraints that, for some reason, could not be executed. If there's a slot with this attribute not-NIL in a class definition, then there's something wrong with its SQL counterpart.

SETFDELAYED-CONSTRAINT (NEW-VALUE OBJECT)

Closures adding constraints that, for some reason, could not be executed. If there's a slot with this attribute not-NIL in a class definition, then there's something wrong with its SQL counterpart.

NOT-NULL-P (OBJECT)

If non-NIL, a NON NULL database constrained will be introduced.

SETFNOT-NULL-P (NEW-VALUE OBJECT)

If non-NIL, a NON NULL database constrained will be introduced.

ON-DELETE (OBJECT)

Action to be performed for this slot when the refering row in the database ceases to exist. Possible values: :CASCADE, :RESTRICT, :SET-NULL, :SET-DEFAULT. If this slot is not a foreign key, it does nothing.

SETFON-DELETE (NEW-VALUE OBJECT)

Action to be performed for this slot when the refering row in the database ceases to exist. Possible values: :CASCADE, :RESTRICT, :SET-NULL, :SET-DEFAULT. If this slot is not a foreign key, it does nothing.

TRANSIENT-P (OBJECT)

If non-NIL, this slot should be treated as transient and ignored in all database related operations.

SETFTRANSIENT-P (NEW-VALUE OBJECT)

If non-NIL, this slot should be treated as transient and ignored in all database related operations.

Undocumented

DB-CLASS-CONNECTION-SPEC (OBJECT)

DB-CLASS-INDICES (OBJECT)

DB-CLASS-UNIQUE (OBJECT)

UNIQUE (OBJECT)

SETFUNIQUE (NEW-VALUE OBJECT)

CLASS

Public

DAO

Base class for any PostgreSQL aware classes.

DB-CLASS

Metaclass for PostgreSQL aware classes. It takes two additional arguments in DEFTABLE: :INDICES (which slots are used as indices) and :CONNECTION-SPEC, which specifies how the class should connect to the database (its format is the same as in POSTMODERN:CONNECT-TOPLEVEL). If :CONNECTION-SPEC is not provided, SUBMARINE assumes it is a class created just for the sake of inheritance and does not create any tables for it.

Private

Undocumented

DB-CLASS-DIRECT-SLOT-DEFINITION

DB-CLASS-EFFECTIVE-SLOT-DEFINITION

DB-CLASS-SLOT-DEFINITION

CONDITION

Public

DAO-ERROR

Base class for DAO related errors.

DAO-NONEXISTENT-ID

Condition signaling the attempt to initialize a dao with a non-existant ID.

UNRESOLVED-FOREIGN-KEY

Condition signaling that a class with a foreign-key reference to a non-defined class has been tried to be used.

Private

SQL-COLUMN-DOES-NOT-EXIST

Condition signaling a missing column in an existing table.

SQL-COLUMN-ERROR

An error symbolizing that there is a column of the right name in the table, but its type is wrong