Package org.dspace.rest

Class CollectionsResource

  • @Path("/collections")
public class CollectionsResource
extends Resource
    This class provides all CRUD operation over collections.
    Author:
    Rostislav Novak (Computing and Information Centre, CTU in Prague)

    • Constructor Detail

      • CollectionsResource

        public CollectionsResource()

    • Method Detail

      • getCollection

        @GET
@Path("/{collection_id}")
@Produces({"application/json","application/xml"})
public Collection getCollection​(@PathParam("collection_id")
                                String collectionId,
                                @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
        Return instance of collection with passed id. You can add more properties through expand parameter.
        Parameters:
        collectionId - Id of collection in DSpace.
        expand - String in which is what you want to add to returned instance of collection. Options are: "all", "parentCommunityList", "parentCommunity", "items", "license" and "logo". If you want to use multiple options, it must be separated by commas.
        limit - Limit value for items in list in collection. Default value is 100.
        offset - Offset of start index in list of items of collection. 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 collection as the user logged into the context. The value of the "rest-dspace-token" header must be set to the token received from the login method response.
        request - Servlet's HTTP request object.
        Returns:
        Return instance of collection. It can also return status code NOT_FOUND(404) if id of collection is incorrect or status code UNATHORIZED(401) if user has no permission to read collection.
        Throws:
        javax.ws.rs.WebApplicationException - It is thrown when was problem with database reading (SQLException) or problem with creating context(ContextException). It is thrown by NOT_FOUND and UNATHORIZED status codes, too.

      • getCollections

        @GET
@Produces({"application/json","application/xml"})
public Collection[] getCollections​(@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
        Return array of all collections in DSpace. You can add more properties through expand parameter.
        Parameters:
        expand - String in which is what you want to add to returned instance of collection. Options are: "all", "parentCommunityList", "parentCommunity", "items", "license" and "logo". If you want to use multiple options, it must be separated by commas.
        limit - Limit value for items in list in collection. Default value is 100.
        offset - Offset of start index in list of items of collection. 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 collections as the user logged into the context. The value of the "rest-dspace-token" header must be set to the token received from the login method response.
        request - Servlet's HTTP request object.
        Returns:
        Return array of collection, on which has logged user permission to view.
        Throws:
        javax.ws.rs.WebApplicationException - It is thrown when was problem with database reading (SQLException) or problem with creating context(ContextException).

      • getCollectionItems

        @GET
@Path("/{collection_id}/items")
@Produces({"application/json","application/xml"})
public Item[] getCollectionItems​(@PathParam("collection_id")
                                 String collectionId,
                                 @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
        Return array of items in collection. You can add more properties to items with expand parameter.
        Parameters:
        collectionId - Id of collection 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".
        limit - Limit value for items in array. Default value is 100.
        offset - Offset of start index in array of items of collection. 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 collection as the user logged into the context. The value of the "rest-dspace-token" header must be set to the token received from the login method response.
        request - Servlet's HTTP request object.
        Returns:
        Return array of items, on which has logged user permission to read. It can also return status code NOT_FOUND(404) if id of collection is incorrect or status code UNATHORIZED(401) if user has no permission to read collection.
        Throws:
        javax.ws.rs.WebApplicationException - It is thrown when was problem with database reading (SQLException) or problem with creating context(ContextException). It is thrown by NOT_FOUND and UNATHORIZED status codes, too.

      • addCollectionItem

        @POST
@Path("/{collection_id}/items")
@Consumes({"application/json","application/xml"})
public Item addCollectionItem​(@PathParam("collection_id")
                              String collectionId,
                              Item item,
                              @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 item in collection. Item can be without filled metadata.
        Parameters:
        collectionId - Id of collection in which will be item created.
        item - Item filled only with metadata, other variables are ignored.
        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 collection as the user logged into the context. The value of the "rest-dspace-token" header must be set to the token received from the login method response.
        request - Servlet's HTTP request object.
        Returns:
        Return status code with item. Return status (OK)200 if item was created. NOT_FOUND(404) if id of collection does not exists. UNAUTHORIZED(401) if user have not permission to write items in collection.
        Throws:
        javax.ws.rs.WebApplicationException - It is thrown when was problem with database reading or writing (SQLException) or problem with creating context(ContextException) or problem with authorization to collection or IOException or problem with index item into browse index. It is thrown by NOT_FOUND and UNATHORIZED status codes, too.

      • updateCollection

        @PUT
@Path("/{collection_id}")
@Consumes({"application/json","application/xml"})
public javax.ws.rs.core.Response updateCollection​(@PathParam("collection_id")
                                                  String collectionId,
                                                  Collection collection,
                                                  @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
        Update collection. It replace all properties.
        Parameters:
        collectionId - Id of collection in DSpace.
        collection - Collection which will replace properties of actual collection.
        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 collection as the user logged into the context. The value of the "rest-dspace-token" header must be set to the token received from the login method response.
        request - Servlet's HTTP request object.
        Returns:
        Return response 200 if was everything all right. Otherwise 400 when id of community was incorrect or 401 if was problem with permission to write into collection.
        Throws:
        javax.ws.rs.WebApplicationException - It is thrown when was problem with database reading or writing. Or problem with authorization to collection. Or problem with creating context.

      • deleteCollection

        @DELETE
@Path("/{collection_id}")
@Consumes({"application/json","application/xml"})
public javax.ws.rs.core.Response deleteCollection​(@PathParam("collection_id")
                                                  String collectionId,
                                                  @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 collection.
        Parameters:
        collectionId - Id of collection 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 collection as the user logged into the context. The value of the "rest-dspace-token" header must be set to the token received from the login method response.
        request - Servlet's HTTP request object.
        Returns:
        Return response code OK(200) if was everything all right. Otherwise return NOT_FOUND(404) if was id of community or collection incorrect. Or (UNAUTHORIZED)401 if was problem with permission to community or collection.
        Throws:
        javax.ws.rs.WebApplicationException - Thrown if there was a problem with creating context or problem with database reading or writing. Or problem with deleting collection caused by IOException or authorization.

      • deleteCollectionItem

        @DELETE
@Path("/{collection_id}/items/{item_id}")
@Consumes({"application/json","application/xml"})
public javax.ws.rs.core.Response deleteCollectionItem​(@PathParam("collection_id")
                                                      String collectionId,
                                                      @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 in collection.
        Parameters:
        collectionId - Id of collection which will be deleted.
        itemId - Id of item in colletion.
        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 collection as the user logged into the context. The value of the "rest-dspace-token" header must be set to the token received from the login method response.
        request - Servlet's HTTP request object.
        Returns:
        It returns status code: OK(200). NOT_FOUND(404) if item or collection was not found, UNAUTHORIZED(401) if user is not allowed to delete item or permission to write into collection.
        Throws:
        javax.ws.rs.WebApplicationException - It can be thrown by: SQLException, when was problem with database reading or writting. AuthorizeException, when was problem with authorization to item or collection. IOException, when was problem with removing item. ContextException, when was problem with creating context of DSpace.

      • findCollectionByName

        @POST
@Path("/find-collection")
@Consumes({"application/json","application/xml"})
@Produces({"application/json","application/xml"})
public Collection findCollectionByName​(String name,
                                       @Context
                                       javax.ws.rs.core.HttpHeaders headers)
                                throws javax.ws.rs.WebApplicationException
        Search for first collection with passed name.
        Parameters:
        name - Name of collection.
        headers - If you want to access the collection as the user logged into the context. The value of the "rest-dspace-token" header must be set to the token received from the login method response.
        Returns:
        It returns null if collection was not found. Otherwise returns first founded collection.
        Throws:
        javax.ws.rs.WebApplicationException - A general exception a servlet can throw when it encounters difficulty.