Document Management API
| Warning: This page is no longer in use. The information contained on the page should NOT be seen as relevant or reliable. |
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
