====================================================
SWORD 2 RUBY CLIENT
CONTENTS
Introduction
Sword2Client
About metadata
About headers
====================================================
Introduction
------------
Developed as part of the JISC SWORD 2.0 project
Provides SWORD client functionality as per the SWORD 2.0 spec
when run against a SWORD 2.0 compliant server.
see: http://www.swordapp.org/
exception - does not handle ORE responses yet.
Functionality is available by calling Sword2Client.new.
See the convenience functions and the execute function in the sword2_client.rb file for more information.
This code lives at http://code.cottagelabs.com/sword2ruby.
There is an issue tracker there too - and there probably will be some issues to work through.
====================================================
Sword2Client
------------
Set SWORD server username, password, service_doc_url and default_collection_url in config/sword.yml
require 'sword2_client'
sword = Sword2Client.new
This makes some convenience methods available to you:
# make a new container in a collection by POSTing a file or metadata or both
# URL expected to identify collection - should be collection IRI
def new_container(collection_url,filepath=nil,metadata={},headers={})
# POST content to an existing container
# URL expected to identify container - should be container edit IRI
def add_to_container(container_url,filepath=nil,headers={})
# PUT new content to a container (replacing current content)
# URL expected to identify container - should be container edit IRI
def replace_container_content(container_url,filepath=nil,headers={})
# PUT new metadata to a container (replacing current metadata)
# URL expected to identify container - should be container edit IRI
def replace_container_metadata(container_url,metadata={},headers={})
# PUT new content and metadata to a container (replacing current content and metadata)
# URL expected to identify container - should be container edit IRI
def replace_container_content_and_metadata(container_url,filepath,metadata={},headers={})
# DELETE content of a container
# URL expected to identify container - should be container edit IRI
def delete_container_content(container_url)
# DELETE a container (and its content)
# URL expected to identify container - should be container edit IRI
def delete_container(container_url)
# tell the sword server to change the in-progress header of an item
# URL expected to identify container - should be container edit IRI
def set_in_progress(container_url,headers={"In-Progress"=>false})
These all call the execute method. Which you can call directly if you wish:
# execute a method on collection, edit or edit-media
def execute(method="get",on="collection",url=nil,filepath=nil,metadata={},headers={})
The execute method provides a response as defined by return_response(response,on,method)
* When HTTPSuccess,
* get on collection will return a hash of the containers available
* get on edit IRI will return a deposit receipt object
* get on edit-media IRI will return the response body - a file
* post will return the location of the container, and set a deposit receipt object
* put or delete will return nil
* When HTTPError,
* you will receive the error response
====================================================
About metadata
--------------
In order to pass metadata to a SWORD 2 server, an ATOM entry is created if necessary.
This is deemed necessary when metadata is passed in to the client.
The metadata must be a hash where the top keys are conformant ATOM.
Optionally you can include a key of "dc" pointing to a hash of Dublin Core terms.
This could be extended, but nothing else is supported for now. See SwordClient::AtomEntry
{
"id":"SOME_ID",
"updated":"DATE_UPDATED",
"published":"PUBLISH_INFO",
"title":"TITLE",
"summary":"SUMMARY",
"rights":"RIGHTS",
"source":"SOURCE",
"content":"CONTENT",
"authors":[ "AUTHOR1", "AUTHOR2", ... ],
"contributors":[ "CONTRIBUTOR1", "CONTRIBUTOR2", ... ],
"links":[ "LINK1", "LINK2", ... ],
"categories":[ "CAT1", "CAT2", ... ],
"dc":{
"VALID_DC_TERM":"VALUE",
...
}
}
====================================================
About headers
-------------
# authorisation headers should be provided from the sword.yml
# On-Behalf-Of can be set there too
# these headers are added in SwordClient::Connection.request for every action
# User-Agent can be provided if so desired
# In-Progress can be provided if so desired, set to true or false
# Slug can be provided if so desired, should be a string representing the content
# Metadata-Relevant can be provided if so desired for PUT operations of file content
# Packaging header cannot be determined - must be provided if required
# e.g. if the deposit object has a package format that should be communicated to the server
# it will be assumed to be default http://purl.org/net/sword/package/Binary where appropriate
# Accept-Packaging can be set for a GET on the edit-media IRI, to specify
# which format is desired in response. The packaging formats the server supports are
# detailed in the repo.servicedoc
# FOLLOWING ARE NOTES ON WHAT SWORD SERVER EXPECTS
# THESE ARE HANDLED WHERE NECESSARY BY THE CLIENT, BUT CAN BE OVERRIDDEN
# (these are dealt with in SwordClient::DepositObject)
# create by POST with binary content
# MUST Content-Disposition
# SHOULD Content-Type, Content-MD5, Packaging
# MAY In-Progress (true/false), Slug
# create by POST with multipart
# combine a package (possibly a simple ZIP) - the Media Part
# with a set of Dublin Core metadata terms [DublinCore] embedded in an Atom Entry - the Entry part.
# MUST Content-Disposition - type attachment on Entry Part with a name param set to atom
# MUST Content-Disposition - type attachment on the Media Part with name param set to payload and a filename parameter
# SHOULD Content-MD5, Packaging - Media Part
# SHOULD add Dublin Core [DublinCore] terms to the Atom Entry as foreign markup (if appropriate);
# MUST be embedded as direct children of the atom:entry element, if present.
# MAY In-Progress (true/false), On-Behalf-Of, Slug on main HTTP header
# MAY add any other metadata formats or foreign markup to the atom:entry element
# replace by PUT of new file content to EM-IRI
# MUST Content-Disposition header with a filename parameter
# SHOULD Content-Type, Content-MD5, Packaging
# MAY On-Behalf-Of, Metadata-Relevant
# replace by PUT of metadata and content to Edit-IRI (as per POST with multipart)
# MUST Content-Disposition header of type attachment on Entry Part with a name parameter set to atom
# MUST Content-Disposition header of type attachment on Media Part with a name parameter set to payload and a filename parameter
# SHOULD Content-MD5, Packaging - Media Part
# SHOULD add Dublin Core [DublinCore] terms to Atom Entry as foreign markup (if appropriate);
# MUST be embedded as direct children of the atom:entry element, if present.
# MAY In-Progress, On-Behalf-Of, Metadata-Relevant
# MAY add any other metadata formats or foreign markup to the atom:entry element
# replace by PUT of new metadata to Edit-IRI
# SHOULD Content-Type header with the value application/atom+xml
# MAY On-Behalf-Of, In-Progress
====================================================