Java tutorial
/** * The contents of this file are subject to the license and copyright * detailed in the LICENSE and NOTICE files at the root of the source * tree and available online at * * http://www.dspace.org/license/ */ package org.dspace.rest; import java.io.IOException; import java.io.UnsupportedEncodingException; import java.sql.SQLException; import java.util.Iterator; import javax.servlet.ServletContext; import javax.ws.rs.Consumes; import javax.ws.rs.GET; import javax.ws.rs.POST; import javax.ws.rs.Path; import javax.ws.rs.Produces; import javax.ws.rs.core.*; import javax.ws.rs.core.Context; import org.apache.commons.lang3.StringUtils; import org.apache.log4j.Logger; import org.dspace.authenticate.AuthenticationMethod; import org.dspace.authenticate.ShibAuthentication; import org.dspace.authenticate.factory.AuthenticateServiceFactory; import org.dspace.authenticate.service.AuthenticationService; import org.dspace.eperson.EPerson; import org.dspace.eperson.factory.EPersonServiceFactory; import org.dspace.eperson.service.EPersonService; import org.dspace.rest.common.Status; import org.dspace.rest.exceptions.ContextException; import org.dspace.utils.DSpace; /** * Root of RESTful api. It provides login and logout. Also have method for * printing every method which is provides by RESTful api. * * @author Rostislav Novak (Computing and Information Centre, CTU in Prague) * */ @Path("/") public class RestIndex { protected EPersonService epersonService = EPersonServiceFactory.getInstance().getEPersonService(); private static Logger log = Logger.getLogger(RestIndex.class); /** * Return html page with information about REST api. It contains methods all * methods provide by REST api. * * @param servletContext * Context of the servlet container. * @return HTML page which has information about all methods of REST API. */ @GET @Produces(MediaType.TEXT_HTML) public String sayHtmlHello(@Context ServletContext servletContext) { // TODO Better graphics, add arguments to all methods. (limit, offset, item and so on) return "<html><title>DSpace REST - index</title>" + "<body>" + "<h1>DSpace REST API</h1>" + "Server path: " + servletContext.getContextPath() + "<h2>Index</h2>" + "<ul>" + "<li>GET / - Return this page.</li>" + "<li>GET /test - Return the string \"REST api is running\" for testing purposes.</li>" + "<li>POST /login - Method for logging into the DSpace RESTful API. You must post the parameters \"email\" and \"password\". Example: \"email=test@dspace&password=pass\". Returns a JSESSIONID cookie which can be used for future authenticated requests.</li>" + "<li>POST /logout - Method for logging out of the DSpace RESTful API. The request must include the \"rest-dspace-token\" token</li> header." + "</ul>" + "<h2>Communities</h2>" + "<ul>" + "<li>GET /communities - Return an array of all communities in DSpace.</li>" + "<li>GET /communities/top-communities - Returns an array of all top-leve communities in DSpace.</li>" + "<li>GET /communities/{communityId} - Returns a community with the specified ID.</li>" + "<li>GET /communities/{communityId}/collections - Returns an array of collections of the specified community.</li>" + "<li>GET /communities/{communityId}/communities - Returns an array of subcommunities of the specified community.</li>" + "<li>POST /communities - Create a new top-level community. You must post a community.</li>" + "<li>POST /communities/{communityId}/collections - Create a new collection in the specified community. You must post a collection.</li>" + "<li>POST /communities/{communityId}/communities - Create a new subcommunity in the specified community. You must post a community.</li>" + "<li>PUT /communities/{communityId} - Update the specified community.</li>" + "<li>DELETE /communities/{communityId} - Delete the specified community.</li>" + "<li>DELETE /communities/{communityId}/collections/{collectionId} - Delete the specified collection in the specified community.</li>" + "<li>DELETE /communities/{communityId}/communities/{communityId2} - Delete the specified subcommunity (communityId2) in the specified community (communityId).</li>" + "</ul>" + "<h2>Collections</h2>" + "<ul>" + "<li>GET /collections - Return all DSpace collections in array.</li>" + "<li>GET /collections/{collectionId} - Return a collection with the specified ID.</li>" + "<li>GET /collections/{collectionId}/items - Return all items of the specified collection.</li>" + "<li>POST /collections/{collectionId}/items - Create an item in the specified collection. You must post an item.</li>" + "<li>POST /collections/find-collection - Find a collection by name.</li>" + "<li>PUT /collections/{collectionId} </li> - Update the specified collection. You must post a collection." + "<li>DELETE /collections/{collectionId} - Delete the specified collection from DSpace.</li>" + "<li>DELETE /collections/{collectionId}/items/{itemId} - Delete the specified item (itemId) in the specified collection (collectionId). </li>" + "</ul>" + "<h2>Items</h2>" + "<ul>" + "<li>GET /items - Return a list of items.</li>" + "<li>GET /items/{item id} - Return the specified item.</li>" + "<li>GET /items/{item id}/metadata - Return metadata of the specified item.</li>" + "<li>GET /items/{item id}/bitstreams - Return bitstreams of the specified item.</li>" + "<li>POST /items/find-by-metadata-field - Find items by the specified metadata value.</li>" + "<li>POST /items/{item id}/metadata - Add metadata to the specified item.</li>" + "<li>POST /items/{item id}/bitstreams - Add a bitstream to the specified item.</li>" + "<li>PUT /items/{item id}/metadata - Update metadata in the specified item.</li>" + "<li>DELETE /items/{item id} - Delete the specified item.</li>" + "<li>DELETE /items/{item id}/metadata - Clear metadata of the specified item.</li>" + "<li>DELETE /items/{item id}/bitstreams/{bitstream id} - Delete the specified bitstream of the specified item.</li>" + "</ul>" + "<h2>Bitstreams</h2>" + "<ul>" + "<li>GET /bitstreams - Return all bitstreams in DSpace.</li>" + "<li>GET /bitstreams/{bitstream id} - Return the specified bitstream.</li>" + "<li>GET /bitstreams/{bitstream id}/policy - Return policies of the specified bitstream.</li>" + "<li>GET /bitstreams/{bitstream id}/retrieve - Return the contents of the specified bitstream.</li>" + "<li>POST /bitstreams/{bitstream id}/policy - Add a policy to the specified bitstream.</li>" + "<li>PUT /bitstreams/{bitstream id}/data - Update the contents of the specified bitstream.</li>" + "<li>PUT /bitstreams/{bitstream id} - Update metadata of the specified bitstream.</li>" + "<li>DELETE /bitstreams/{bitstream id} - Delete the specified bitstream from DSpace.</li>" + "<li>DELETE /bitstreams/{bitstream id}/policy/{policy_id} - Delete the specified bitstream policy.</li>" + "</ul>" + "<h2>Hierarchy</h2>" + "<ul>" + "<li>GET /hierarchy - Return hierarchy of communities and collections in tree form. Each object is minimally populated (name, handle, id) for efficient retrieval.</li>" + "</ul>" + "<h2>Metadata and Schema Registry</h2>" + "<ul>" + "<li>GET /registries/schema - Return the list of metadata schemas in the registry</li>" + "<li>GET /registries/schema/{schema_prefix} - Returns the specified metadata schema</li>" + "<li>GET /registries/schema/{schema_prefix}/metadata-fields/{element} - Returns the metadata field within a schema with an unqualified element name</li>" + "<li>GET /registries/schema/{schema_prefix}/metadata-fields/{element}/{qualifier} - Returns the metadata field within a schema with a qualified element name</li>" + "<li>POST /registries/schema/ - Add a schema to the schema registry</li>" + "<li>POST /registries/schema/{schema_prefix}/metadata-fields - Add a metadata field to the specified schema</li>" + "<li>GET /registries/metadata-fields/{field_id} - Return the specified metadata field</li>" + "<li>PUT /registries/metadata-fields/{field_id} - Update the specified metadata field</li>" + "<li>DELETE /registries/metadata-fields/{field_id} - Delete the specified metadata field from the metadata field registry</li>" + "<li>DELETE /registries/schema/{schema_id} - Delete the specified schema from the schema registry</li>" + "</ul>" + "<h2>Query/Reporting Tools</h2>" + "<ul>" + "<li>GET /reports - Return a list of report tools built on the rest api</li>" + "<li>GET /reports/{nickname} - Return a redirect to a specific report</li>" + "<li>GET /filters - Return a list of use case filters available for quality control reporting</li>" + "<li>GET /filtered-collections - Return collections and item counts based on pre-defined filters</li>" + "<li>GET /filtered-collections/{collection_id} - Return items and item counts for a collection based on pre-defined filters</li>" + "<li>GET /filtered-items - Retrieve a set of items based on a metadata query and a set of filters</li>" + "</ul>" + "</body></html> "; } /** * Method only for testing whether the REST API is running. * * @return String "REST api is running." */ @GET @Path("/test") public String test() { return "REST api is running."; } /** * Method to login a user into REST API. * * @return Returns response code OK and a token. Otherwise returns response * code FORBIDDEN(403). */ @POST @Path("/login") @Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML }) public Response login() { //If you can get here, you are authenticated, the actual login is handled by spring security return Response.ok().build(); } @GET @Path("/shibboleth-login") @Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML }) public Response shibbolethLogin() { //If you can get here, you are authenticated, the actual login is handled by spring security return Response.ok().build(); } @GET @Path("/login-shibboleth") @Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML }) public Response shibbolethLoginEndPoint() { org.dspace.core.Context context = null; try { context = Resource.createContext(); AuthenticationService authenticationService = AuthenticateServiceFactory.getInstance() .getAuthenticationService(); Iterator<AuthenticationMethod> authenticationMethodIterator = authenticationService .authenticationMethodIterator(); while (authenticationMethodIterator.hasNext()) { AuthenticationMethod authenticationMethod = authenticationMethodIterator.next(); if (authenticationMethod instanceof ShibAuthentication) { //TODO: Perhaps look for a better way of handling this ? org.dspace.services.model.Request currentRequest = new DSpace().getRequestService() .getCurrentRequest(); String loginPageURL = authenticationMethod.loginPageURL(context, currentRequest.getHttpServletRequest(), currentRequest.getHttpServletResponse()); if (StringUtils.isNotBlank(loginPageURL)) { currentRequest.getHttpServletResponse().sendRedirect(loginPageURL); } } } context.abort(); } catch (ContextException | SQLException | IOException e) { Resource.processException("Shibboleth endpoint error: " + e.getMessage(), context); } finally { if (context != null && context.isValid()) { context.abort(); } } return Response.ok().build(); } /** * Method to logout a user from DSpace REST API. Removes the token and user from * TokenHolder. * * @param headers * Request header which contains the header named * "rest-dspace-token" containing the token as value. * @return Return response OK, otherwise BAD_REQUEST, if there was a problem with * logout or the token is incorrect. */ @POST @Path("/logout") @Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML }) public Response logout(@Context HttpHeaders headers) { //If you can get here, you are logged out, this actual logout is handled by spring security return Response.ok().build(); } /** * Method to check current status of the service and logged in user. * * okay: true | false * authenticated: true | false * epersonEMAIL: user@example.com * epersonNAME: John Doe * @param headers * Request header which contains the header named * "rest-dspace-token" containing the token as value. * @return status the Status object with information about REST API * @throws UnsupportedEncodingException * The Character Encoding is not supported. */ @GET @Path("/status") @Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML }) public Status status(@Context HttpHeaders headers) throws UnsupportedEncodingException { org.dspace.core.Context context = null; try { context = Resource.createContext(); EPerson ePerson = context.getCurrentUser(); if (ePerson != null) { //DB EPerson needed since token won't have full info, need context EPerson dbEPerson = epersonService.findByEmail(context, ePerson.getEmail()); Status status = new Status(dbEPerson.getEmail(), dbEPerson.getFullName()); return status; } } catch (ContextException e) { Resource.processException("Status context error: " + e.getMessage(), context); } catch (SQLException e) { Resource.processException("Status eperson db lookup error: " + e.getMessage(), context); } finally { context.abort(); } //fallback status, unauth return new Status(); } }