Document Management API

This page is for (rapidly!) designing the new DMS APIs. As Martin says, "Basically we'll have an API that interfaces Moodle files handling everywhere via a plugin to the chosen repository (or repositories). This allows us to use all the great repositories are around without needing to restrict ourselves to just one." (relevant forum post)

This is an interesting thing to do, because some DMS backends will provide features that others don't provide, and Moodle will/may have to provide those features transparently for backends that don't.

This is a first pass at doing this, and the naming conventions I'm using are intended to be clear but not necessarily to indicate what I think these things should really be called in code.

DMS Properties Object

class dms_document_properties

var $id;

var $name;

var $author;

var $directory;

// every time a separate module/instance refers to this document, refcount is bumped. When refcount==0, bye-bye, document!

// Hopefully most DMS backends will already implement this sort of thing themselves, so those plugins don't have to mess with this.

var $refcount;

var $credentials; // username, password, stuff like that

/* OK, some shameless module promotion here. I've implemented a generic access_control module that I think could be useful here. Maybe it's duplicating some other functionality I just don't know about yet and maybe it has horrible problems that haven't been pointed out to me yet, but I'll mention it here just the same. It's under contrib/ in the portfolio module. */

var $access_control; // object with access control specification/methods

DMS Data Object

class dms_document

var $dms_document_properties;

var $content;

var $pwd; // I'm not sure I like this. You can traipse around the filesystem carrying $content and the content's $dms_document_properties->directory along with you?

Methods

/* This is just a first pass to get something on the table. */

get_document_content();

Content of the document sufficiently specified by $this->dms_document_properties is fetched from DMS backend.

Returns: value of $this->id, or false

put_document_content();

Content of document sufficiently specified by $this->dms_document_properties is stored/updated in DMS backend.

Returns: value of $this->id, or false

get_document_properties();

Full properties of the document sufficiently specified by $this->dms_document_properties (id, owner, title, etc.) are fetched from DMS backend.

Returns: dms_document_properties object, or false

access_change($access_object);

Change the access un/specified for $this according to the $access_object specification (type of access, grant/deny/revoke, designee, etc.)

Returns: true/false

access_test($access_object);

Check to see whether the specified $access_object describes access that has been granted to $this.

Returns: true if specified access is granted, false otherwise

delete();

Decrements the refcount and deletes $this if refcount==0. Hopefully most DMSes already have their own refcount (or whatever); I"m shooting from the hip here.

Returns: true/false

move($new_directory_path);

Moves the document from its present directory to the specified new one.

Returns: true/false

link_that_to_me($new_dms_document);

Make $new_dms_document's directory, name, owner, etc., refer to $this. (Think of a UNIX hard link, where the inode -- in our case, id -- gets another reference.)

Returns: true/false

link_me_to_that($old_dms_document);

Make $this refer to $old_dms_document. (Think of a UNIX hard link, where the inode -- in our case, id -- gets another reference.)

Returns: true/false

copy_this_to($new_dms_document);

Copies $this into the directory_path, owner, title, etc. specified by $new_dms_document.

Returns: $new_dms_document->id, or false

copy_this_from($old_dms_document);

Copies $old_dms_document into the directory_path, owner, title, etc. specified by $this.

Returns: $this->id, or false

lock();

Locks $this.

Returns: true/false

unlock();

Unlocks $this.

Returns: true/false

break_lock();

Forcibly unlocks $this.

Returns: true/false

mkdir($new_dir);

Make the specified new directory, including necessary parent directories as required (perhaps if an additional boolean parameter is set).

Returns: true/false

pwd();

Get the present working directory.

Returns: present working directory as a string, or false

chdir($new_directory_path);

Change PWD to the specified $new_directory_path, which can be absolute or relative.

Returns: true/false

list();

List the files/directories in $pwd.

Returns: array of document_properties of all the files/directories in $pwd, or false

get_property($property_name);

Get the named property from $this->dms_document_properties.

Returns: value of property, or false (er... 'false' on failure?)

set_property($property_name, $value);

Set the named property in $this->dms_document_properties.

Returns: true/false

get_my_url();

Return a URL that points to the document specified by $this, if possible.

Returns: URL or false

Other methods

change_owner();

Other Considerations

• Will the plugged-in DMS store access controls, or will Moodle handle those? (I think it best to let Moodle handle them but perhaps also pass-through as well as possible; not all external DMSes will have the same or sufficient access controls.)

See also

• Using Moodle RFC - Remote object repositories -- consolidating implementations forum discussion