Package org.dspace.rest

Class ItemsResource

  • @Path("/items")
public class ItemsResource
extends Resource
    Class which provide all CRUD methods over items.
    Author:
    Rostislav Novak (Computing and Information Centre, CTU in Prague)

    • Field Detail

      • collectionService

        protected org.dspace.content.service.CollectionService collectionService

      • itemService

        protected org.dspace.content.service.ItemService itemService

      • authorizeService

        protected org.dspace.authorize.service.AuthorizeService authorizeService

      • bitstreamService

        protected org.dspace.content.service.BitstreamService bitstreamService

      • bitstreamFormatService

        protected org.dspace.content.service.BitstreamFormatService bitstreamFormatService

      • bundleService

        protected org.dspace.content.service.BundleService bundleService

      • resourcePolicyService

        protected org.dspace.authorize.service.ResourcePolicyService resourcePolicyService

      • groupService

        protected org.dspace.eperson.service.GroupService groupService

    • Constructor Detail

      • ItemsResource

        public ItemsResource()

    • Method Detail

      • getItem

        @GET
@Path("/{item_id}")
@Produces({"application/json","application/xml"})
public Item getItem​(@PathParam("item_id")
                    String itemId,
                    @QueryParam("expand")
                    String expand,
                    @QueryParam("userIP")
                    String user_ip,
                    @QueryParam("userAgent")
                    String user_agent,
                    @QueryParam("xforwardedfor")
                    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".
        user_ip - User's IP address.
        user_agent - User agent string (specifies browser used and its version).
        xforwardedfor - When accessed via a reverse proxy, the application sees the proxy's IP as the source of the request. The proxy may be configured to add the "X-Forwarded-For" HTTP header containing the original IP of the client so that the reverse-proxied application can get the client's IP.
        headers - If you want to access the item as the user logged into the context. The value of the "rest-dspace-token" header must be set with passed token from login method.
        request - Servlet's HTTP request object.
        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

        @GET
@Produces({"application/json","application/xml"})
public Item[] getItems​(@QueryParam("expand")
                       String expand,
                       @QueryParam("limit") @DefaultValue("100")
                       Integer limit,
                       @QueryParam("offset") @DefaultValue("0")
                       Integer offset,
                       @QueryParam("userIP")
                       String user_ip,
                       @QueryParam("userAgent")
                       String user_agent,
                       @QueryParam("xforwardedfor")
                       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:
        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".
        limit - How many items in array will be. Default value is 100.
        offset - On which index will array start. Default value is 0.
        user_ip - User's IP address.
        user_agent - User agent string (specifies browser used and its version).
        xforwardedfor - When accessed via a reverse proxy, the application sees the proxy's IP as the source of the request. The proxy may be configured to add the "X-Forwarded-For" HTTP header containing the original IP of the client so that the reverse-proxied application can get the client's IP.
        headers - If you want to access the item as the user logged into the context. The value of the "rest-dspace-token" header must be set with passed token from login method.
        request - Servlet's HTTP request object.
        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

        @GET
@Path("/{item_id}/metadata")
@Produces({"application/json","application/xml"})
public MetadataEntry[] getItemMetadata​(@PathParam("item_id")
                                       String itemId,
                                       @QueryParam("userIP")
                                       String user_ip,
                                       @QueryParam("userAgent")
                                       String user_agent,
                                       @QueryParam("xforwardedfor")
                                       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.
        user_ip - User's IP address.
        user_agent - User agent string (specifies browser used and its version).
        xforwardedfor - When accessed via a reverse proxy, the application sees the proxy's IP as the source of the request. The proxy may be configured to add the "X-Forwarded-For" HTTP header containing the original IP of the client so that the reverse-proxied application can get the client's IP.
        headers - If you want to access the item as the user logged into the context. The value of the "rest-dspace-token" header must be set with passed token from login method.
        request - Servlet's HTTP request object.
        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

        @GET
@Path("/{item_id}/bitstreams")
@Produces({"application/json","application/xml"})
public Bitstream[] getItemBitstreams​(@PathParam("item_id")
                                     String itemId,
                                     @QueryParam("limit") @DefaultValue("20")
                                     Integer limit,
                                     @QueryParam("offset") @DefaultValue("0")
                                     Integer offset,
                                     @QueryParam("userIP")
                                     String user_ip,
                                     @QueryParam("userAgent")
                                     String user_agent,
                                     @QueryParam("xforwardedfor")
                                     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 paged.
        Parameters:
        itemId - Id of item in DSpace.
        limit - How many items will be in array.
        offset - On which index will start array.
        user_ip - User's IP address.
        user_agent - User agent string (specifies browser used and its version).
        xforwardedfor - When accessed via a reverse proxy, the application sees the proxy's IP as the source of the request. The proxy may be configured to add the "X-Forwarded-For" HTTP header containing the original IP of the client so that the reverse-proxied application can get the client's IP.
        headers - If you want to access the item as the user logged into the context. The value of the "rest-dspace-token" header must be set with passed token from login method.
        request - Servlet's HTTP request object.
        Returns:
        Return paged 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

        @POST
@Path("/{item_id}/metadata")
@Consumes({"application/json","application/xml"})
public javax.ws.rs.core.Response addItemMetadata​(@PathParam("item_id")
                                                 String itemId,
                                                 List<MetadataEntry> metadata,
                                                 @QueryParam("userIP")
                                                 String user_ip,
                                                 @QueryParam("userAgent")
                                                 String user_agent,
                                                 @QueryParam("xforwardedfor")
                                                 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.
        user_ip - User's IP address.
        user_agent - User agent string (specifies browser used and its version).
        xforwardedfor - When accessed via a reverse proxy, the application sees the proxy's IP as the source of the request. The proxy may be configured to add the "X-Forwarded-For" HTTP header containing the original IP of the client so that the reverse-proxied application can get the client's IP.
        headers - If you want to access the item as the user logged into the context. The value of the "rest-dspace-token" header must be set with passed token from login method.
        request - Servlet's HTTP request object.
        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

        @POST
@Path("/{item_id}/bitstreams")
public Bitstream addItemBitstream​(@PathParam("item_id")
                                  String itemId,
                                  InputStream inputStream,
                                  @QueryParam("name")
                                  String name,
                                  @QueryParam("description")
                                  String description,
                                  @QueryParam("groupId")
                                  String groupId,
                                  @QueryParam("year")
                                  Integer year,
                                  @QueryParam("month")
                                  Integer month,
                                  @QueryParam("day")
                                  Integer day,
                                  @QueryParam("userIP")
                                  String user_ip,
                                  @QueryParam("userAgent")
                                  String user_agent,
                                  @QueryParam("xforwardedfor")
                                  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:
        name - Btstream name to set.
        description - Btstream description to set.
        groupId - ResourcePolicy group (allowed to READ).
        year - ResourcePolicy start date year.
        month - ResourcePolicy start date month.
        day - ResourcePolicy start date day.
        itemId - Id of item in DSpace.
        inputStream - Data of bitstream in inputStream.
        user_ip - User's IP address.
        user_agent - User agent string (specifies browser used and its version).
        xforwardedfor - When accessed via a reverse proxy, the application sees the proxy's IP as the source of the request. The proxy may be configured to add the "X-Forwarded-For" HTTP header containing the original IP of the client so that the reverse-proxied application can get the client's IP.
        headers - If you want to access the item as the user logged into the context. The value of the "rest-dspace-token" header must be set with passed token from login method.
        request - Servlet's HTTP request object.
        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

        @PUT
@Path("/{item_id}/metadata")
@Consumes({"application/json","application/xml"})
public javax.ws.rs.core.Response updateItemMetadata​(@PathParam("item_id")
                                                    String itemId,
                                                    MetadataEntry[] metadata,
                                                    @QueryParam("userIP")
                                                    String user_ip,
                                                    @QueryParam("userAgent")
                                                    String user_agent,
                                                    @QueryParam("xforwardedfor")
                                                    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.
        user_ip - User's IP address.
        user_agent - User agent string (specifies browser used and its version).
        xforwardedfor - When accessed via a reverse proxy, the application sees the proxy's IP as the source of the request. The proxy may be configured to add the "X-Forwarded-For" HTTP header containing the original IP of the client so that the reverse-proxied application can get the client's IP.
        headers - If you want to access the item as the user logged into the context. The value of the "rest-dspace-token" header must be set with passed token from login method.
        request - Servlet's HTTP request object.
        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

        @DELETE
@Path("/{item_id}")
public javax.ws.rs.core.Response deleteItem​(@PathParam("item_id")
                                            String itemId,
                                            @QueryParam("userIP")
                                            String user_ip,
                                            @QueryParam("userAgent")
                                            String user_agent,
                                            @QueryParam("xforwardedfor")
                                            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.
        user_ip - User's IP address.
        user_agent - User agent string (specifies browser used and its version).
        xforwardedfor - When accessed via a reverse proxy, the application sees the proxy's IP as the source of the request. The proxy may be configured to add the "X-Forwarded-For" HTTP header containing the original IP of the client so that the reverse-proxied application can get the client's IP.
        headers - If you want to access the item as the user logged into the context. The value of the "rest-dspace-token" header must be set with passed token from login method.
        request - Servlet's HTTP request object.
        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

        @DELETE
@Path("/{item_id}/metadata")
public javax.ws.rs.core.Response deleteItemMetadata​(@PathParam("item_id")
                                                    String itemId,
                                                    @QueryParam("userIP")
                                                    String user_ip,
                                                    @QueryParam("userAgent")
                                                    String user_agent,
                                                    @QueryParam("xforwardedfor")
                                                    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.
        user_ip - User's IP address.
        user_agent - User agent string (specifies browser used and its version).
        xforwardedfor - When accessed via a reverse proxy, the application sees the proxy's IP as the source of the request. The proxy may be configured to add the "X-Forwarded-For" HTTP header containing the original IP of the client so that the reverse-proxied application can get the client's IP.
        headers - If you want to access the item as the user logged into the context. The value of the "rest-dspace-token" header must be set with passed token from login method.
        request - Servlet's HTTP request object.
        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 - Thrown by three exceptions. SQLException, when there was a problem reading item from database or editing metadata fields. AuthorizeException, when there was a problem with authorization to item. And ContextException, when there was a problem with creating a DSpace context.

      • deleteItemBitstream

        @DELETE
@Path("/{item_id}/bitstreams/{bitstream_id}")
public javax.ws.rs.core.Response deleteItemBitstream​(@PathParam("item_id")
                                                     String itemId,
                                                     @PathParam("bitstream_id")
                                                     String bitstreamId,
                                                     @QueryParam("userIP")
                                                     String user_ip,
                                                     @QueryParam("userAgent")
                                                     String user_agent,
                                                     @QueryParam("xforwardedfor")
                                                     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.
        bitstreamId - Id of bitstream, which will be deleted from bundle.
        user_ip - User's IP address.
        user_agent - User agent string (specifies browser used and its version).
        xforwardedfor - When accessed via a reverse proxy, the application sees the proxy's IP as the source of the request. The proxy may be configured to add the "X-Forwarded-For" HTTP header containing the original IP of the client so that the reverse-proxied application can get the client's IP.
        headers - If you want to access the item as the user logged into the context. The value of the "rest-dspace-token" header must be set with passed token from login method.
        request - Servlet's HTTP request object.
        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

        @POST
@Path("/find-by-metadata-field")
@Produces({"application/json","application/xml"})
public Item[] findItemsByMetadataField​(MetadataEntry metadataEntry,
                                       @QueryParam("expand")
                                       String expand,
                                       @QueryParam("userIP")
                                       String user_ip,
                                       @QueryParam("userAgent")
                                       String user_agent,
                                       @QueryParam("xforwardedfor")
                                       String xforwardedfor,
                                       @Context
                                       javax.ws.rs.core.HttpHeaders headers,
                                       @Context
                                       javax.servlet.http.HttpServletRequest request)
                                throws javax.ws.rs.WebApplicationException
        Find items by one metadata field.
        Parameters:
        metadataEntry - Metadata field to search by.
        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".
        user_ip - User's IP address.
        user_agent - User agent string (specifies browser used and its version).
        xforwardedfor - When accessed via a reverse proxy, the application sees the proxy's IP as the source of the request. The proxy may be configured to add the "X-Forwarded-For" HTTP header containing the original IP of the client so that the reverse-proxied application can get the client's IP.
        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.
        request - Servlet's HTTP request object.
        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.