RDaisy

RDaisy:  A Ruby Library for Accessing a Daisy Repository

The Daisy repository server library for Ruby provides a layer of abstraction to allow Ruby developers to easily access content stored in a Daisy repository for use in Ruby applications, in particular, Ruby on Rails based web applications.  The library contains the following series of classes to perform this.

RDaisyObject

This class provides a mechanism so that methods and attributes that might be needed by all classes in the library can be shared.  It is currently unused however.

RepositoryServer

This is the key to the project.  It allows for resources to be retrived, posted and deleted from the server by partially abstracting the REST interface.  It implements the following methods:

initialize(host, username, password, proxy_options = {})

This is the contructor method for the class.  It sets the host and creates a connection object.  It also stores the username and password used for http authentication (NOTE:  I am considering moving the username and password out of being instance variables to being method scoped variabled passed in on each request for a resource.  This would enhance security by not storing the passwords in cleartext).  In addition, Ruby provides for the use of a proxy server when making a connection.  The forth parameter is for a Hash containing the options neccessary for making a proxied connection.  They are as follows:

• :p_host
• The host of the proxy server
• :p_port
• The port on which to connect to on the proxy server
• :p_user
• The username to use on the proxy server if needed
• :p_password
• The corresponding password

get_resource(path, params={})

This method retrives the text found at a particular path on the repository server.  The path specifies the resource path to use.  The params are a hash of key value pairs to be included in the query string.  It only returns the body of the request if the request is of the 2xx type.  Otherwise it throws a HTTPError or HTTPServerException exception with the invalid response object.

post_resource(path, data, params = {}, options = {})

This method posts the value specified in the data argument to the given path.  The params argument is the same as in the get_resource method.  options currently include :content_type which allows the user to specify the content type of the body being posted.  It returns the response from the repository.

post_multi_resource(path, data, params = {}, options = {})

This is identical to the post_resource method except that the data argument should be a hash in the form {:dataDef => data}, for a multipart form-data post.

delete_resource(path, params ={})

This method deletes the resource at the specified path.  The params argument is the same as in get_resource.  It returns the response given by the repository server.

Document

This object represents a document in the repository.  Because of the way Daisy works, it represents exactly one document variant version a time, but it will have the ability to pull other variants/versions of the same document.  Currently, it works by pulling a copy of the document from the repository server, thereby determining which fields and parts to include from the given document.  To create new documents, however, I want to implement the ability to use the document schemas in the repository to create templates for new Document objects.

self.get(server, id, options ={})

This method pulls the xml representing the document with id from the server and uses it to instantiate a document object.  options include :version, :language and :branch.  By default, it will pull the latest version of the default variant.

initialize(data = nil, rs =nil)

Creates a Document object with the REXML::Document data.  It will use the RepositoryServer rs if it needs to pull any additional data.

get_version(version, server, params={})

Currently changes the current documents version to the one specified by version and stored in RepositoryServer server.  The params are any options that need to be sent such as :language or :branch in the query string

save(server, params={})

This saves the document to the specified server with the parameters in params.  I am going to change it so that it returns the latest document version.

id

returns the id of the current document

name

returns the name of the current document variant version.

name=(name}

Sets the current document variant's name which will be reflected

collections

Returns an array of Collection objects that represents the collections that the document is a member of.

fields

Returns an array of Field objects of the current document.

parts

Returns an array of Part objects of the current document.

links

Returns an array of Link objects of the current document.

to_xml

Converts the current document to xml according to the document.xsd schema file.  Originally I was going to use pippin (pippin.rubyforge.org), but I found the project to be out of date and was not easily installable.  So for the time being, I am hard coding the schema into the library, but I plan to change it if a new library becomes available.

update_from_element(root, rs=nil)

Updates the current document with an REXML::Element object specified by root.  If additional data needs to be fetched, it will be done with RepositoryServer rs.  As with to_xml, the schema is hard coded and should be updated at a later point.

Collection

The collection object corresponds to a Daisy collection and stores the id, name and other attributes.  I am going to add a method that pulls all the document ids in this collection.

initialize(data)

instantiates a Collection object with a Hash data

id

Returns the id of the given collection.

CustomField

This holds a custom field associated with a document variant.

initialize(data)

Intiantiates a CustomField with a Hash data that has the keys :name and :value

name, value

Returns the name and value respectively.

name=(name), value=(value)

Sets the value of name and value respectively

to_xml(xml)

Creates an xml fragment based on the CustomField object.  xml should be of type Builder::XmlMarkup

Field

This is a daisy document field.  I had to hard code part of the schema more or less directly into the code in this class, so it will need to be refactored at a later point.

initialize(data)

Instantiates a Field object with the nested Hash  data.  Currently, it should be in the format {:type_id =>  tid, :data_type =>  dt, :values => ["value 1", "value 2"]}.  I may change this format however.

to_xml(xml)

Creates an xml fragment based on the Field object.  xml should be of type Builder::XmlMarkup.  The output xml corresponds to the part format specified in document.xsd

Part

This corresponds to a daisy document part.  It should be noted that for it to be able to access the repository server for more data, the Document#update_from_element needed to be passed a RepositoryServer object.

initialize(data)

Intiantiates a Part with a Hash data that has the keys :name, :id, :rs and others

data(retrive = true)

returns the current data of the part.  It will try and pull a locally cached copy of the value if possible, but if not it will try and retrive it from the server.  It will not goto the server, however, if the argument retrive is false.

type_id

Returns the part's typeId

data_ref

Returns the data_ref value to be used when submitting the part to the repository.

get_data!

Forces a reload of the part from the servers.

data, synced?, new?

Returns the part type data, the syncronization status (which will be updated when an attribute is modified), and to see if its new respectively.

to_xml(xml)

Creates an xml fragment based on the Part object.  xml should be of type Builder::XmlMarkup.  The output xml corresponds to the part format specified in document.xsd

ToDo

• Get posting to work
• Finish writing attribute readers, writers and accessors
• Implement Locks
• Rails-Engine