def-view-class

Macro

Summary

Extends the syntax of defclass to allow special slots to be mapped onto the attributes of database views.

Package

sql

Signature

def-view-class
name
superclasses
slots
&rest
class-option
s =>
class

Arguments

name

A class name.

superclasses

The superclasses of the class to be created.

slots

The slot definitions of the new class.

class-options

The class options of the new class.

Values

class

The defined class.

Slot Options

The slot options for
def-view-class
are
:db-kind
and
:db-info
. In addition the slot option
:type
is treated specially for View Classes.

:db-kind
may be one of
:base
,
:key
,
:join
, or
:virtual
. The default is
:base
. Each value is described below:

:base

This indicates that this slot corresponds to an ordinary attribute of the database view. You can name the database attribute by using the keyword
:column
. By default, the database attribute is named by the slot.

:key

This indicates that this slot corresponds to part of the unique key for this view. A
:key
slot is also a
:base
slot. All View Classes must have
:key
fields that uniquely distinguish the instances, to maintain object identity.

:join

This indicates that this slot corresponds to a join. A slot of this type will contain View Class objects.

:virtual

This indicates that this slot is an ordinary CLOS slot not associated with a database column.

A join is defined by the slot option
:db-info
, which takes a list. Items in the list may be:

:join-class
class-name

This is the class to join on.

:home-key
slot-name

This is the slot of the defining class to be a subject for the join. The argument
slot-name
may be an element or a list of elements, where elements can be symbols,
nil
, strings, integers or floats.

:foreign-key
slot-name

This is the name of the slot of the
:join-class
to be a subject for the join. The
slot-name
may be an element or a list of elements, where elements can be symbols,
nil
, strings, integers or floats.

:target-slot
target-slot

This is the name of a
:join
slot in
:join-class
. This is optional and is only specified if you want the defining slot to contain instances of this target slot as opposed to those of
:join-class
. The actual behavior depends on the value of
set
. An example of its usage is when the
:join-class
is an intermediate class and you are really only interested in it as a route to the
:target-slot
.

:retrieval
retrieval-time

retrieval-time
can be
:deferred
, which defers filling this slot from the database until the slot itself is accessed. This is the default value.

retrieval-time
can alternatively be
:immediate
which generates the join SQL for this slot whenever a query is generated on the class. In other words, this is an intermediate class only, which is present for the purpose of joining two entities of other classes together. When
retrieval-time
is
:immediate
, then
set
is
nil
.

:set
set

When
set
is
t
and
target-slot
is defined, the slot will contain a list of pairs (
target-value
join-instance
) where
target-value
is the value of the target slot and
join-instance
is the corresponding instance of the join class.

When
set
is
t
and
target-slot
is undefined, the slot will contain a list of instances of the join class.

When
set
is
nil
the slot will contain a single instance.

The default value of
set
is
t
.

The syntax for
:home-key
and
:foreign-key
means that an object from a join class will only be included in the join slot if the values from the home-key are
equal
to the values in the
:foreign-key
, in order. These values are calculated as follows: if the element in the list is a symbol it is taken to be a slot name and the value of the slot is used, otherwise the element is taken to be the value. See the second example below.

The
:type
slot option is treated specially for View Classes. There is a need for stringent type-checking in View Classes because of the translation into database data, and therefore
:type
is mandatory for slots with
:db-kind
:base
or
:key
. Some methods are provided for type checking and type conversion. For example, a
:type
specifier of
(string 10)
in SQL terms means allow a character type value with length of less than or equal to 10. The following Lisp types are accepted for
type
, and correspond to the SQL type shown:

(string n)

CHAR(n)

integer

INTEGER

(integer
n
)

INTEGER(n)

float

FLOAT

(float
n
)

FLOAT(n)

sql:universal-time

TIMESTAMP

Class Options

A class option for
def-view-class
is
:base-table
, which is the name of the table corresponding to the class. If you do not specify it, it defaults to the name of the class.

Description

The macro
def-view-class
creates a class called
name
which maps onto a database view. Such a class is called a View Class.

The macro
def-view-class
extends the syntax of defclass to allow special
base slots
to be mapped onto the attributes of database views (presently single tables). When a
select
query that names a View Class is submitted, then the corresponding database view is queried, and the slots in the resulting View Class instances are filled with attribute values from the database.