org.dspace.rest

Class ItemsResource

java.lang.Object

org.dspace.rest.Resource

org.dspace.rest.ItemsResource

public class ItemsResource
extends Resource

Class which provide all CRUD methods over items.

Author:

Rostislav Novak (Computing and Information Centre, CTU in Prague)

Field Summary

Fields inherited from class org.dspace.rest.Resource

servletContext

Constructor Summary

Constructors

Constructor and Description
ItemsResource()

Method Summary

Methods

Modifier and Type	Method and Description
Bitstream	addItemBitstream(Integer itemId, InputStream inputStream, String name, String description, Integer groupId, Integer year, Integer month, Integer day, String user_ip, String user_agent, String xforwardedfor, javax.ws.rs.core.HttpHeaders headers, javax.servlet.http.HttpServletRequest request) Create bitstream in item.
javax.ws.rs.core.Response	addItemMetadata(Integer itemId, List<MetadataEntry> metadata, String user_ip, String user_agent, String xforwardedfor, javax.ws.rs.core.HttpHeaders headers, javax.servlet.http.HttpServletRequest request) Adding metadata fields to item.
javax.ws.rs.core.Response	deleteItem(Integer itemId, String user_ip, String user_agent, String xforwardedfor, javax.ws.rs.core.HttpHeaders headers, javax.servlet.http.HttpServletRequest request) Delete item from DSpace.
javax.ws.rs.core.Response	deleteItemBitstream(Integer itemId, Integer bitstreamId, String user_ip, String user_agent, String xforwardedfor, javax.ws.rs.core.HttpHeaders headers, javax.servlet.http.HttpServletRequest request) Delete bitstream from item bundle.
javax.ws.rs.core.Response	deleteItemMetadata(Integer itemId, String user_ip, String user_agent, String xforwardedfor, javax.ws.rs.core.HttpHeaders headers, javax.servlet.http.HttpServletRequest request) Delete all item metadata.
Item[]	findItemsByMetadataField(MetadataEntry metadataEntry, String expand, String user_ip, String user_agent, String xforwardedfor, javax.ws.rs.core.HttpHeaders headers, javax.servlet.http.HttpServletRequest request) Find items by one metadada field.
Item	getItem(Integer itemId, String expand, String user_ip, String user_agent, String xforwardedfor, javax.ws.rs.core.HttpHeaders headers, javax.servlet.http.HttpServletRequest request) Return item properties without metadata and bitstreams.
Bitstream[]	getItemBitstreams(Integer itemId, Integer limit, Integer offset, String user_ip, String user_agent, String xforwardedfor, javax.ws.rs.core.HttpHeaders headers, javax.servlet.http.HttpServletRequest request) Return array of bitstreams in item.
MetadataEntry[]	getItemMetadata(Integer itemId, String user_ip, String user_agent, String xforwardedfor, javax.ws.rs.core.HttpHeaders headers, javax.servlet.http.HttpServletRequest request) Returns item metadata in list.
Item[]	getItems(String expand, Integer limit, Integer offset, String user_ip, String user_agent, String xforwardedfor, javax.ws.rs.core.HttpHeaders headers, javax.servlet.http.HttpServletRequest request) It returns an array of items in DSpace.
javax.ws.rs.core.Response	updateItemMetadata(Integer itemId, MetadataEntry[] metadata, String user_ip, String user_agent, String xforwardedfor, javax.ws.rs.core.HttpHeaders headers, javax.servlet.http.HttpServletRequest request) Replace all metadata in item with new passed metadata.

Methods inherited from class org.dspace.rest.Resource

createContext, getActionString, getServletContextPath, getToken, getUser, mySplit, processException, processFinally, writeStats

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ItemsResource

public ItemsResource()

Method Detail

getItem

public Item getItem(Integer itemId,
           String expand,
           String user_ip,
           String user_agent,
           String xforwardedfor,
           @Context
           javax.ws.rs.core.HttpHeaders headers,
           @Context
           javax.servlet.http.HttpServletRequest request)
             throws javax.ws.rs.WebApplicationException

Return item properties without metadata and bitstreams. You can add additional properties by parameter expand.

Parameters:

itemId - Id of item in DSpace.

expand - String which define, what additional properties will be in returned item. Options are separeted by commas and are: "all", "metadata", "parentCollection", "parentCollectionList", "parentCommunityList" and "bitstreams".

headers - If you want to access to item under logged user into context. In headers must be set header "rest-dspace-token" with passed token from login method.

Returns:

If user is allowed to read item, it returns item. Otherwise is thrown WebApplicationException with response status UNAUTHORIZED(401) or NOT_FOUND(404) if was id incorrect.

Throws:

javax.ws.rs.WebApplicationException - This exception can be throw by NOT_FOUND(bad id of item), UNAUTHORIZED, SQLException if wasproblem with reading from database and ContextException, if there was problem with creating context of DSpace.

getItems

public Item[] getItems(String expand,
              Integer limit,
              Integer offset,
              String user_ip,
              String user_agent,
              String xforwardedfor,
              @Context
              javax.ws.rs.core.HttpHeaders headers,
              @Context
              javax.servlet.http.HttpServletRequest request)
                throws javax.ws.rs.WebApplicationException

It returns an array of items in DSpace. You can define how many items in list will be and from which index will start. Items in list are sorted by handle, not by id.

Parameters:

limit - How many items in array will be. Default value is 100.

offset - On which index will array start. Default value is 0.

headers - If you want to access to item under logged user into context. In headers must be set header "rest-dspace-token" with passed token from login method.

Returns:

Return array of items, on which has logged user into context permission.

Throws:

javax.ws.rs.WebApplicationException - It can be thrown by SQLException, when was problem with reading items from database or ContextException, when was problem with creating context of DSpace.

getItemMetadata

public MetadataEntry[] getItemMetadata(Integer itemId,
                              String user_ip,
                              String user_agent,
                              String xforwardedfor,
                              @Context
                              javax.ws.rs.core.HttpHeaders headers,
                              @Context
                              javax.servlet.http.HttpServletRequest request)
                                throws javax.ws.rs.WebApplicationException

Returns item metadata in list.

Parameters:

itemId - Id of item in DSpace.

headers - If you want to access to item under logged user into context. In headers must be set header "rest-dspace-token" with passed token from login method.

Returns:

Return list of metadata fields if was everything ok. Otherwise it throw WebApplication exception with response code NOT_FOUND(404) or UNAUTHORIZED(401).

Throws:

javax.ws.rs.WebApplicationException - It can be thrown by two exceptions: SQLException if was problem wtih reading item from database and ContextException, if was problem with creating context of DSpace. And can be thrown by NOT_FOUND and UNAUTHORIZED too.

getItemBitstreams

public Bitstream[] getItemBitstreams(Integer itemId,
                            Integer limit,
                            Integer offset,
                            String user_ip,
                            String user_agent,
                            String xforwardedfor,
                            @Context
                            javax.ws.rs.core.HttpHeaders headers,
                            @Context
                            javax.servlet.http.HttpServletRequest request)
                              throws javax.ws.rs.WebApplicationException

Return array of bitstreams in item. It can be pagged.

Parameters:

itemId - Id of item in DSpace.

limit - How many items will be in array.

offset - On which index will start array.

headers - If you want to access to item under logged user into context. In headers must be set header "rest-dspace-token" with passed token from login method.

Returns:

Return pagged array of bitstreams in item.

Throws:

javax.ws.rs.WebApplicationException - It can be throw by NOT_FOUND, UNAUTHORIZED, SQLException if was problem with reading from database and ContextException if was problem with creating context of DSpace.

addItemMetadata

public javax.ws.rs.core.Response addItemMetadata(Integer itemId,
                                        List<MetadataEntry> metadata,
                                        String user_ip,
                                        String user_agent,
                                        String xforwardedfor,
                                        @Context
                                        javax.ws.rs.core.HttpHeaders headers,
                                        @Context
                                        javax.servlet.http.HttpServletRequest request)
                                          throws javax.ws.rs.WebApplicationException

Adding metadata fields to item. If metadata key is in item, it will be added, NOT REPLACED!

Parameters:

itemId - Id of item in DSpace.

metadata - List of metadata fields, which will be added into item.

headers - If you want to access to item under logged user into context. In headers must be set header "rest-dspace-token" with passed token from login method.

Returns:

It returns status code OK(200) if all was ok. UNAUTHORIZED(401) if user is not allowed to write to item. NOT_FOUND(404) if id of item is incorrect.

Throws:

javax.ws.rs.WebApplicationException - It is throw by these exceptions: SQLException, if was problem with reading from database or writing to database. AuthorizeException, if was problem with authorization to item fields. ContextException, if was problem with creating context of DSpace.

addItemBitstream

public Bitstream addItemBitstream(Integer itemId,
                         InputStream inputStream,
                         String name,
                         String description,
                         Integer groupId,
                         Integer year,
                         Integer month,
                         Integer day,
                         String user_ip,
                         String user_agent,
                         String xforwardedfor,
                         @Context
                         javax.ws.rs.core.HttpHeaders headers,
                         @Context
                         javax.servlet.http.HttpServletRequest request)
                           throws javax.ws.rs.WebApplicationException

Create bitstream in item.

Parameters:

itemId - Id of item in DSpace.

inputStream - Data of bitstream in inputStream.

headers - If you want to access to item under logged user into context. In headers must be set header "rest-dspace-token" with passed token from login method.

Returns:

Returns bitstream with status code OK(200). If id of item is invalid , it returns status code NOT_FOUND(404). If user is not allowed to write to item, UNAUTHORIZED(401).

Throws:

javax.ws.rs.WebApplicationException - It is thrown by these exceptions: SQLException, when was problem with reading/writing from/to database. AuthorizeException, when was problem with authorization to item and add bitstream to item. IOException, when was problem with creating file or reading from inpustream. ContextException. When was problem with creating context of DSpace.

updateItemMetadata

public javax.ws.rs.core.Response updateItemMetadata(Integer itemId,
                                           MetadataEntry[] metadata,
                                           String user_ip,
                                           String user_agent,
                                           String xforwardedfor,
                                           @Context
                                           javax.ws.rs.core.HttpHeaders headers,
                                           @Context
                                           javax.servlet.http.HttpServletRequest request)
                                             throws javax.ws.rs.WebApplicationException

Replace all metadata in item with new passed metadata.

Parameters:

itemId - Id of item in DSpace.

metadata - List of metadata fields, which will replace old metadata in item.

headers - If you want to access to item under logged user into context. In headers must be set header "rest-dspace-token" with passed token from login method.

Returns:

It returns status code: OK(200). NOT_FOUND(404) if item was not found, UNAUTHORIZED(401) if user is not allowed to write to item.

Throws:

javax.ws.rs.WebApplicationException - It is thrown by: SQLException, when was problem with database reading or writting, AuthorizeException when was problem with authorization to item and metadata fields. And ContextException, when was problem with creating context of DSpace.

deleteItem

public javax.ws.rs.core.Response deleteItem(Integer itemId,
                                   String user_ip,
                                   String user_agent,
                                   String xforwardedfor,
                                   @Context
                                   javax.ws.rs.core.HttpHeaders headers,
                                   @Context
                                   javax.servlet.http.HttpServletRequest request)
                                     throws javax.ws.rs.WebApplicationException

Delete item from DSpace. It delete bitstreams only from item bundle.

Parameters:

itemId - Id of item which will be deleted.

headers - If you want to access to item under logged user into context. In headers must be set header "rest-dspace-token" with passed token from login method.

Returns:

It returns status code: OK(200). NOT_FOUND(404) if item was not found, UNAUTHORIZED(401) if user is not allowed to delete item metadata.

Throws:

javax.ws.rs.WebApplicationException - It can be thrown by: SQLException, when was problem with database reading. AuthorizeException, when was problem with authorization to item.(read and delete) IOException, when was problem with deleting bitstream file. ContextException, when was problem with creating context of DSpace.

deleteItemMetadata

public javax.ws.rs.core.Response deleteItemMetadata(Integer itemId,
                                           String user_ip,
                                           String user_agent,
                                           String xforwardedfor,
                                           @Context
                                           javax.ws.rs.core.HttpHeaders headers,
                                           @Context
                                           javax.servlet.http.HttpServletRequest request)
                                             throws javax.ws.rs.WebApplicationException

Delete all item metadata.

Parameters:

itemId - Id of item in DSpace.

headers - If you want to access to item under logged user into context. In headers must be set header "rest-dspace-token" with passed token from login method.

Returns:

It returns status code: OK(200). NOT_FOUND(404) if item was not found, UNAUTHORIZED(401) if user is not allowed to delete item metadata.

Throws:

javax.ws.rs.WebApplicationException - It is thrown by three exceptions. SQLException, when was problem with reading item from database or editting metadata fields. AuthorizeException, when was problem with authorization to item. And ContextException, when was problem with creating context of DSpace.

deleteItemBitstream

public javax.ws.rs.core.Response deleteItemBitstream(Integer itemId,
                                            Integer bitstreamId,
                                            String user_ip,
                                            String user_agent,
                                            String xforwardedfor,
                                            @Context
                                            javax.ws.rs.core.HttpHeaders headers,
                                            @Context
                                            javax.servlet.http.HttpServletRequest request)
                                              throws javax.ws.rs.WebApplicationException

Delete bitstream from item bundle.

Parameters:

itemId - Id of item in DSpace.

headers - If you want to access to item under logged user into context. In headers must be set header "rest-dspace-token" with passed token from login method.

bitstreamId - Id of bitstream, which will be deleted from bundle.

Returns:

Return status code OK(200) if is all ok. NOT_FOUND(404) if item or bitstream was not found. UNAUTHORIZED(401) if user is not allowed to delete bitstream.

Throws:

javax.ws.rs.WebApplicationException - It is thrown, when: Was problem with edditting database, SQLException. Or problem with authorization to item, bundle or bitstream, AuthorizeException. When was problem with deleting file IOException. Or problem with creating context of DSpace, ContextException.

findItemsByMetadataField

public Item[] findItemsByMetadataField(MetadataEntry metadataEntry,
                              String expand,
                              String user_ip,
                              String user_agent,
                              String xforwardedfor,
                              @Context
                              javax.ws.rs.core.HttpHeaders headers,
                              @Context
                              javax.servlet.http.HttpServletRequest request)
                                throws javax.ws.rs.WebApplicationException

Find items by one metadada field.

Parameters:

metadataEntry - Metadata field to search by.

scheme - Scheme of metadata(key).

value - Value of metadata field.

headers - If you want to access the item as the user logged into context, header "rest-dspace-token" must be set to token value retrieved from the login method.

Returns:

Return array of found items.

Throws:

javax.ws.rs.WebApplicationException - Can be thrown: SQLException - problem with database reading. AuthorizeException - problem with authorization to item. IOException - problem with reading from metadata field. ContextException - problem with creating DSpace context.