<reference id="ref-ooddl">
<title>Object Oriented Data Definition Language (OODDL)</title>
<partintro>
- <para>
- <!-- introduction -->
- </para>
+ <para>
+ The Object Oriented Data Definition Language (OODDL) provides
+ access to relational SQL tables using Common Lisp Object System
+ (CLOS) objects. SQL tables are mapped to CLOS objects with the
+ SQL columns being mapped to slots of the CLOS object.
+ </para>
+ <para>
+ The mapping between SQL tables and CLOS objects is defined
+ with the macro <link
+ linkend="def-view-class"><function>def-view-class</function></link>. SQL
+ tables are created with <link
+ linkend="create-view-from-class"><function>create-view-from-class</function></link>
+ and SQL tables can be deleted with <link
+ linkend="drop-view-from-class"><function>drop-view-from-class</function></link>.
+ </para>
+ <note>The above functions refer to the Lisp <emphasis>view</emphasis> of the SQL
+ table. This Lisp view should not be confused with SQL <function>VIEW</function> statement.
+ </note>
</partintro>
<refentry id="standard-db-object">
<title class="contenttitle">Slots</title>
<para>
<simplelist>
- <property>slot VIEW-DATABASE is of type T</property>
+ <property>slot VIEW-DATABASE is of type (OR NULL DATABASE)
+ which stores the associated database for the
+ instance.</property>
</simplelist>
</para>
</refsect1>
</refentry>
- <refentry id="default-varchar-length">
+ <refentry id="default-string-length">
<refnamediv>
<refname>*DEFAULT-STRING-LENGTH*</refname>
- <refpurpose>Default length of SQL strings</refpurpose>
+ <refpurpose>Default length of SQL strings.</refpurpose>
<refclass>Variable</refclass>
</refnamediv>
<refsect1>
</refsect1>
<refsect1>
<title>Initial Value</title>
- <para><symbol>255</symbol></para>
+ <para><parameter>255</parameter></para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
If a slot of a class defined by
<function>DEF-VIEW-CLASS</function> is of the type
- <symbol>STRING</symbol> or <symbol>VARCHAR</symbol> and does
+ <parameter>STRING</parameter> or <parameter>VARCHAR</parameter> and does
not have a length specified, then the value of this variable
is used as SQL length.
</para>
</refsect1>
<refsect1>
<title>Affected By</title>
- <para>Some SQL backends do not support <symbol>VARCHAR</symbol>
+ <para>Some SQL backends do not support <parameter>VARCHAR</parameter>
lengths greater than 255 .</para>
</refsect1>
<refsect1>
<refentry id="create-view-from-class">
<refnamediv>
<refname>CREATE-VIEW-FROM-CLASS</refname>
- <refpurpose>Create a SQL table from Lisp class</refpurpose>
+ <refpurpose>Create a SQL table from a view class.</refpurpose>
<refclass>Function</refclass>
</refnamediv>
<refsect1>
<title>Syntax</title>
<synopsis>
- <function> (CREATE-VIEW-FROM-CLASS VIEW-CLASS-NAME &KEY (DATABASE *DEFAULT-DATABASE*) (TRANSACTIONS T)) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
+ <function> (create-view-from-class view-class-name &key (database *default-database*) (transactions t))</function> => <returnvalue><!-- no values --></returnvalue></synopsis>
</refsect1>
<refsect1>
<title>Arguments and Values</title>
<variablelist>
- <!-- arguments and values -->
+ <varlistentry>
+ <term><parameter>view-class-name</parameter></term>
+ <listitem>
+ <para>
+ The name of a view class that has been defined with
+ <link linkend="def-view-class"><function>def-view-class</function></link>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>database</parameter></term>
+ <listitem>
+ <para>
+ The database in which to create the SQL table.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>transactions</parameter></term>
+ <listitem>
+ <para>
+ When &nil; specifies that a table type which does not support transactions should be used.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</refsect1>
<refsect1>
<refsect1>
<title>Examples</title>
<screen>
- <!-- examples -->
+ * (def-view-class 'foo () ((a :type (string 80))))
+ #<CLSQL-SYS::STANDARD-DB-CLASS FOO>
+ * (create-view-from-class 'foo)
+ * (list-tables)
+ ("FOO")
</screen>
</refsect1>
<refsect1>
<refsect1>
<title>Affected by</title>
<para>
- <simplelist>
- <!-- affected by -->
- </simplelist>
+ Most SQL database systems will signal an error if a table
+ creation is attempted when a table with the same name already
+ exists. The SQL user, as specified in the database connection,
+ must have sufficient permission for table creation.
</para>
</refsect1>
<refsect1>
<title>Exceptional Situations</title>
<para>
- <!-- execeptional situations -->
+ A condition will be signaled if the table can not be created
+ in the SQL database.
</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<simplelist>
- <!-- see also -->
- </simplelist>
+ <member><link linkend="def-view-class"><function>def-view-class</function></link></member>
+ <member><link linkend="drop-view-from-class"><function>drop-view-from-class</function></link></member>
+ </simplelist>
</para>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
- <!-- notes -->
+ Currently, only &mysql; supports transactionless
+ tables. &clsql; provides the ability to create such tables for
+ applications which would benefit from faster table access and
+ do not require transaction support.
</para>
</refsect1>
</refentry>
<refentry id="def-view-class">
<refnamediv>
<refname>DEF-VIEW-CLASS</refname>
- <refpurpose><!-- purpose --></refpurpose>
- <refclass>Function</refclass>
+ <refpurpose>Defines CLOS classes with mapping to SQL database.</refpurpose>
+ <refclass>Macro</refclass>
</refnamediv>
<refsect1>
<title>Syntax</title>
<synopsis>
- <function> (DEF-VIEW-CLASS CLASS SUPERS SLOTS &REST CL-OPTIONS) [macro]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
+ <function>(def-view-class name superclasses slots &rest class-options) [macro]</function> => <returnvalue>class</returnvalue></synopsis>
</refsect1>
<refsect1>
<title>Arguments and Values</title>
<variablelist>
- <!-- arguments and values -->
+ <varlistentry>
+ <term><parameter>name</parameter></term>
+ <listitem>
+ <para>
+ The class name.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>name</parameter></term>
+ <listitem>
+ <para>
+ The superclasses for the defined class.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>slots</parameter></term>
+ <listitem>
+ <para>
+ The class slot definitions.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>class</parameter></term>
+ <listitem>
+ <para>
+ The defined class.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</refsect1>
+ <refsect1>
+ <title>Slot Options</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <parameter>:db-kind</parameter> - specifies the kind of
+ DB mapping which is performed for this slot and defaults
+ to <parameter>:base</parameter> which indicates that the
+ slot maps to an ordinary column of the database table. A
+ <parameter>:db-kind</parameter> value of
+ <parameter>:key</parameter> indicates that this slot is
+ a special kind of <parameter>:base</parameter> slot
+ which maps onto a column which is one of the unique keys
+ for the database table, the value
+ <parameter>:join</parameter> indicates this slot
+ represents a join onto another View Class which contains
+ View Class objects, and the value
+ <parameter>:virtual</parameter> indicates a standard
+ CLOS slot which does not map onto columns of the
+ database table.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>:db-info</parameter> - if a slot is specified with
+ <parameter>:db-kind</parameter> <parameter>:join</parameter>, the
+ slot option <parameter>:db-info</parameter> contains a list
+ which specifies the nature of the join.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>:type</parameter> - for slots of
+ <parameter>:db-kind</parameter> <parameter>:base</parameter> or
+ <parameter>:key</parameter>, the <parameter>:type</parameter> slot
+ option has a special interpretation such that Lisp
+ types, such as string, integer and float are
+ automatically converted into appropriate SQL types for
+ the column onto which the slot maps. This behaviour may
+ be overridden using the <parameter>:db-type</parameter> slot
+ option. The valid values are:
+ <simplelist>
+ <member>
+ <parameter>string</parameter> - a variable length character field up to
+ <link linkend="default-string-length">*default-string-length*</link> characters.
+ </member>
+ <member>
+ <parameter>(string n)</parameter> - a fixed length character field
+ <parameter>n</parameter> characters long.
+ </member>
+ <member>
+ <parameter>varchar</parameter> - a variable length character field up to
+ <link linkend="default-string-length">*default-string-length*</link> characters.
+ </member>
+ <member>
+ <parameter>(varchar n)</parameter> - a variable length character field up to
+ <parameter>n</parameter> characters in length.
+ </member>
+ <member>
+ <parameter>char</parameter> - a single character field
+ </member>
+ <member><parameter>integer</parameter> - signed integer at least 32-bits wide</member>
+ <member><parameter>(integer n)</parameter></member>
+ <member><parameter>float</parameter></member>
+ <member><parameter>(float n)</parameter></member>
+ <member><parameter>long-float</parameter></member>
+ <member><parameter>number</parameter></member>
+ <member><parameter>(number n)</parameter></member>
+ <member><parameter>(number n p)</parameter></member>
+ <member>
+ <parameter>smallint</parameter> - An integer column 16-bits
+ wide. [not supported by all database backends]
+ </member>
+ <member>
+ <parameter>bigint</parameter> - An integer column
+ 64-bits wide. [not supported by all database backends]
+ </member>
+ <member>
+ <parameter>universal-time</parameter> - an integer
+ field sufficiently wide to store a
+ universal-time. On most databases, a slot of this
+ type assigned a SQL type of
+ <parameter>BIGINT</parameter>
+ </member>
+ <member>
+ <parameter>wall-time</parameter> - a slot which
+ stores a date and time in a SQL timestamp
+ column. &clsql; provides a number of time
+ manipulation functions to support objects of type
+ <type>wall-time</type>.
+ </member>
+ <member>
+ <parameter>duration</parameter> - stores a <type>duration</type> structure.
+ &clsql; provides routines for <type>wall-time</type> and <type>duration</type>
+ processing.
+ </member>
+ <member><parameter>boolean</parameter> - stores a &t; or &nil; value.</member>
+ <member>
+ <parameter>generalized-boolean</parameter> - similar
+ to a <parameter>boolean</parameter> in that either a
+ &t; or &nil; value is stored in the SQL
+ database. However, any Lisp object can be stored in
+ the Lisp object. A Lisp value of &nil; is stored as
+ <constant>FALSE</constant> in the database, any
+ other Lisp value is stored as
+ <constant>TRUE</constant>.
+ </member>
+ <member>
+ <parameter>keyword</parameter> - stores a keyword
+ </member>
+ <member><parameter>symbol</parameter> - stores a symbol</member>
+ <member>
+ <parameter>list</parameter> - stores a list by writing it to a string. The items
+ in the list must be able to be readable written.
+ </member>
+ <member><parameter>vector</parameter> - stores a vector similarly to <parameter>list</parameter></member>
+ <member><parameter>array</parameter> - stores a array similarly to <parameter>list</parameter></member>
+ </simplelist>
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>:column</parameter> - specifies the name of
+ the SQL column which the slot maps onto, if
+ <parameter>:db-kind</parameter> is not
+ <parameter>:virtual</parameter>, and defaults to the
+ slot name.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>:void-value</parameter> - specifies
+ the value to store in the Lisp instance if the SQL value is NULL and defaults
+ to NIL.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>:db-constraints</parameter> - is a string
+ representing an SQL table constraint expression or a
+ list of such strings.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>:db-type</parameter> - a string to specify the SQL
+ column type. If specified, this string overrides the SQL
+ column type as computed from the <parameter>:type</parameter>
+ slot value.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </refsect1>
+ <refsect1>
+ <title>Class Options</title>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <parameter>:base-table</parameter> - specifies the name of the
+ SQL database table. The default value is the class name.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </refsect1>
<refsect1>
<title>Description</title>
- <para>Creates a View Class called CLASS whose slots SLOTS can
- map onto the attributes of a table in a database. If SUPERS is
- nil then the superclass of CLASS will be STANDARD-DB-OBJECT,
- otherwise SUPERS is a list of superclasses for CLASS which
- must include STANDARD-DB-OBJECT or a descendent of this
- class. The syntax of DEFCLASS is extended through the addition
- of a class option :base-table which defines the database table
- onto which the View Class maps and which defaults to
- CLASS. The DEFCLASS syntax is also extended through additional
- slot options. The :db-kind slot option specifies the kind of
- DB mapping which is performed for this slot and defaults to
- :base which indicates that the slot maps to an ordinary column
- of the database table. A :db-kind value of :key indicates that
- this slot is a special kind of :base slot which maps onto a
- column which is one of the unique keys for the database table,
- the value :join indicates this slot represents a join onto
- another View Class which contains View Class objects, and the
- value :virtual indicates a standard CLOS slot which does not
- map onto columns of the database table. If a slot is specified
- with :db-kind :join, the slot option :db-info contains a list
- which specifies the nature of the join. For slots of :db-kind
- :base or :key, the :type slot option has a special
- interpretation such that Lisp types, such as string, integer
- and float are automatically converted into appropriate SQL
- types for the column onto which the slot maps. This behaviour
- may be over-ridden using the :db-type slot option which is a
- string specifying the vendor-specific database type for this
- slot's column definition in the database. The :column slot
- option specifies the name of the SQL column which the slot
- maps onto, if :db-kind is not :virtual, and defaults to the
- slot name. The :void-value slot option specifies the value to
- store if the SQL value is NULL and defaults to NIL. The
- :db-constraints slot option is a string representing an SQL
- table constraint expression or a list of such strings.
+ <para>
+ Creates a View Class called <parameter>NAME</parameter> whose
+ slots <parameter>SLOTS</parameter> can map onto the attributes
+ of a table in a database. If
+ <parameter>SUPERCLASSES</parameter> is &nil; then the
+ superclass of <parameter>CLASS</parameter> will be
+ <parameter>STANDARD-DB-OBJECT</parameter>, otherwise
+ <parameter>SUPERCLASSES</parameter> is a list of superclasses
+ for <parameter>CLASS</parameter> which must include
+ <parameter>STANDARD-DB-OBJECT</parameter> or a descendent of this
+ class.
</para>
+
</refsect1>
<refsect1>
<title>Examples</title>
</refsect1>
<refsect1>
<title>Side Effects</title>
- <para>
- <!-- side effects -->
- </para>
+ <para>Creates a new CLOS class.</para>
</refsect1>
<refsect1>
<title>Affected by</title>
<para>
- <simplelist>
- <!-- affected by -->
- </simplelist>
+ Nothing.
</para>
</refsect1>
<refsect1>
<title>Exceptional Situations</title>
<para>
- <!-- execeptional situations -->
+ None.
</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<simplelist>
- <!-- see also -->
+ <member><link linkend="create-view-from-class"><function>create-view-from-class</function></link></member>
+ <member><link linkend="standard-db-object"><parameter>standard-db-object</parameter></link></member>
+ <member><link linkend="drop-view-from-class"><function>drop-view-from-class</function></link></member>
</simplelist>
</para>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
- <!-- notes -->
+ The actual SQL type for a column depends up the database type
+ in which the SQL table is stored. As an example, the view
+ class type <parameter>(varchar 100)</parameter> specifies a
+ SQL column type <parameter>VARCHAR(100)</parameter> in &mysql;
+ and a column type <parameter>VARCHAR2(100)</parameter> in
+ &oracle;
</para>
</refsect1>
</refentry>
<refentry id="drop-view-from-class">
<refnamediv>
<refname>DROP-VIEW-FROM-CLASS</refname>
- <refpurpose><!-- purpose --></refpurpose>
+ <refpurpose>Delete table from SQL database.</refpurpose>
<refclass>Function</refclass>
</refnamediv>
<refsect1>
<title>Syntax</title>
<synopsis>
- <function> (DROP-VIEW-FROM-CLASS VIEW-CLASS-NAME &KEY (DATABASE *DEFAULT-DATABASE*)) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
+ <function>(drop-view-from-class view-class-name &key (database *default-database*))</function> => <returnvalue><!-- result --></returnvalue></synopsis>
</refsect1>
<refsect1>
<title>Arguments and Values</title>
<variablelist>
- <!-- arguments and values -->
+ <varlistentry>
+ <term><parameter>view-class-name</parameter></term>
+ <listitem>
+ <para>
+ The name of the view class.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>Removes a table defined by the View Class
- VIEW-CLASS-NAME from DATABASE which defaults to
- *DEFAULT-DATABASE*.
+ <parameter>VIEW-CLASS-NAME</parameter> from
+ <parameter>DATABASE</parameter> which defaults to
+ <parameter>*DEFAULT-DATABASE*</parameter>.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<screen>
- <!-- examples -->
+ * (list-tables)
+ ("FOO" "BAR")
+ * (drop-view-from-class 'foo)
+ * (list-tables)
+ ("BAR")
</screen>
</refsect1>
<refsect1>
<title>Side Effects</title>
<para>
- <!-- side effects -->
+ Deletes a table from the SQL database.
</para>
</refsect1>
<refsect1>
<title>Affected by</title>
<para>
- <simplelist>
- <!-- affected by -->
- </simplelist>
+ Whether the specified table exists in the SQL database.
</para>
</refsect1>
<refsect1>
<title>Exceptional Situations</title>
<para>
- <!-- execeptional situations -->
+ A condition may be signalled if the table does not exist in
+ the SQL database or if the SQL connection does not have
+ sufficient permissions to delete tables.
</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<simplelist>
- <!-- see also -->
+ <member><link linkend="create-view-from-class"><function>create-view-from-class</function></link></member>
+ <member><link linkend="def-view-class"><function>def-view-class</function></link></member>
</simplelist>
</para>
</refsect1>
<refentry id="list-classes">
<refnamediv>
<refname>LIST-CLASSES</refname>
- <refpurpose><!-- purpose --></refpurpose>
+ <refpurpose>List classes for tables in SQL database.</refpurpose>
<refclass>Function</refclass>
</refnamediv>
<refsect1>
<title>Syntax</title>
<synopsis>
- <function> (LIST-CLASSES &KEY (TEST #'IDENTITY) (ROOT-CLASS (FIND-CLASS 'STANDARD-DB-OBJECT)) (DATABASE *DEFAULT-DATABASE*)) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
+ <function>(list-classes &key (test #'identity) (root-class (find-class 'standard-db-object)) (database *default-database*))</function> => <returnvalue>classes</returnvalue></synopsis>
</refsect1>
<refsect1>
<title>Arguments and Values</title>
<variablelist>
- <!-- arguments and values -->
+ <varlistentry>
+ <term><parameter>test</parameter></term>
+ <listitem>
+ <para>
+ a function used to filter the search. By default, <parameter>identity</parameter> is used which
+ will return all classes.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>root-class</parameter></term>
+ <listitem>
+ <para>
+ specifies the root class to the search. By default, <parameter>standard-db-object</parameter> is used
+ which is the root for all view classes.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>database</parameter></term>
+ <listitem>
+ <para>
+ The database to search for view classes.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>classes</parameter></term>
+ <listitem>
+ <para>
+ List of view classes.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
- <para>Returns a list of all the View Classes which
- are connected to DATABASE, which defaults to
- *DEFAULT-DATABASE*, and which descend from the class
- ROOT-CLASS and which satisfy the function TEST. By
- default ROOT-CLASS is STANDARD-DB-OBJECT and TEST is
- IDENTITY.
+ <para>Returns a list of all the View Classes which have been
+ defined in the Lisp session and are connected to
+ <parameter>DATABASE</parameter>, which defaults to
+ <parameter>*DEFAULT-DATABASE*</parameter>, and which descended
+ from the class ROOT-CLASS and which satisfy the function
+ TEST. By default ROOT-CLASS is STANDARD-DB-OBJECT and
+ <parameter>TEST</parameter> is IDENTITY.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<screen>
- <!-- examples -->
+ * (list-classes)
+ (#<clsql-sys::standard-db-class big> #<clsql-sys::standard-db-class employee-address>
+ #<clsql-sys::standard-db-class address> #<clsql-sys::standard-db-class company>
+ #<clsql-sys::standard-db-class employee>)
+
+ * (list-classes :test #'(lambda (c) (> (length (symbol-name (class-name c))) 3)))
+ (#<clsql-sys::standard-db-class employee-address> #<clsql-sys::standard-db-class address>
+ #<clsql-sys::standard-db-class company> #<clsql-sys::standard-db-class employee>)
</screen>
</refsect1>
<refsect1>
<title>Side Effects</title>
<para>
- <!-- side effects -->
+ None.
</para>
</refsect1>
<refsect1>
<title>Affected by</title>
<para>
<simplelist>
- <!-- affected by -->
+ Which view classes have been defined in the Lisp session.
</simplelist>
</para>
</refsect1>
<refsect1>
<title>Exceptional Situations</title>
<para>
- <!-- execeptional situations -->
+ None.
</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<simplelist>
- <!-- see also -->
- </simplelist>
+ <member><link linkend="def-view-class"><function>def-view-class</function></link></member>
+ </simplelist>
</para>
</refsect1>
<refsect1>
projects / clsql.git / commitdiff