wftk core: list method adaptor

[ back to the core ] [ discussion ]

A list adaptor is effectively the definition of how to store objects in a list. The canonical list adaptor is localdir, which stores objects as XML files in a directory. Other examples of lists are database tables, wftk-specific repositories, lines in a file, and so on. The repository manager can be used to manage lists and the processing to be done when lists' data is changed.

Just as the adaptor mechanism is a poor man's ActiveX, the list adaptor is a poor man's Recordset (see ADO). I'm taking everything Microsoft does and doing it more simply. Eventually I'll put them right out of business.

These are the functions exposed by a list adaptor, with many more to come, I'm sure:
0: init   Initialize adaptor instance
1: free   Clean up instance before shutting down
2: info   Return XML describing the adaptor
3: create List definition Create a list.
4: destroy List definition Destroy a list.
5: add List definition
Add an object to a list.
6: update List definition
Update an object.
7: delete List definition
Delete an object. If no key given, deletes current object in list.
8: get List definition
Retrieve an object. If no key given, retrieves the current object.
9: query List definition Fills out the list definition with abbreviated records.
10: first List definition Iterates through a list. Note that the list defn is used as a cursor. Don't use the original!
11: next List definition Iterates.
12: prev List definition Iterates.
13: last List definition Iterates.
14: keygen List definition
Builds a key from the object definition.
15: attach_open List definition
Field name
(optional) name of local file
Opens an attachment stream for writing. The adaptor takes care of everything once the stream is closed. The localdir adaptor can use the name of local file to determine a filename for storage of the attachment (this makes it easy to treat, say, an images directory as a list with attachments.) The function returns a handle which can be decorated with a MIME type in content-type.
16: attach_write Buffer to read from
Writes data to an open attachment handle (like fwrite())
17: attach_close Handle Does the actual attachment; until attach_close is called, no effect is visible on the object. Among other things, the adaptor takes care of version control at this point.
18: attach_cancel Handle Closes the attachment handle with no effect on the object and no embarrassment.
19: retrieve_open List definition
Field name
Opens an attachment (or any other field for that matter) for reading. The handle is XML and is decorated with attributes 'size' and 'content-type'.
20: retrieve_read Buffer to write to
Reads data from an open attachment retrieval handle (like fread()).
21: retrieve_close Handle. Finishes a retrieval action.


This code and documentation are released under the terms of the GNU license. They are additionally copyright (c) 2001, Vivtek. All rights reserved except those explicitly granted under the terms of the GNU license. This presentation was prepared with LPML. Try literate programming. You'll like it.