From: Aron Roberts Date: Mon, 10 Aug 2009 20:05:08 +0000 (+0000) Subject: CSPACE-336: ID service now accepts POST requests, rather than GET requests, to genera... X-Git-Url: https://git.aero2k.de/?a=commitdiff_plain;h=2856ebfdcdc6767908f937db447dd62f5a4a1ba8;p=tmp%2Fjakarta-migration.git CSPACE-336: ID service now accepts POST requests, rather than GET requests, to generate and return new IDs. --- diff --git a/services/id/service/src/main/java/org/collectionspace/services/id/IDResource.java b/services/id/service/src/main/java/org/collectionspace/services/id/IDResource.java index 7f4729d8e..f90cfd5e7 100644 --- a/services/id/service/src/main/java/org/collectionspace/services/id/IDResource.java +++ b/services/id/service/src/main/java/org/collectionspace/services/id/IDResource.java @@ -1,8 +1,4 @@ /** - * IDResource - * - * Resource class to handle requests to the ID Service. - * * This document is a part of the source code and related artifacts * for CollectionSpace, an open source collections management system * for museums and related institutions: @@ -18,11 +14,7 @@ * You may obtain a copy of the ECL 2.0 License at * https://source.collectionspace.org/collection-space/LICENSE.txt * - * Based on work by Richard Millet and Sanjay Dalal. - * - * $LastChangedBy$ - * $LastChangedRevision$ - * $LastChangedDate$ + * Based in part on work by Richard Millet and Sanjay Dalal. */ package org.collectionspace.services.id; @@ -31,6 +23,7 @@ import javax.ws.rs.Consumes; import javax.ws.rs.GET; import javax.ws.rs.Path; import javax.ws.rs.PathParam; +import javax.ws.rs.POST; import javax.ws.rs.Produces; import javax.ws.rs.core.MediaType; import javax.ws.rs.core.Response; @@ -41,12 +34,21 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; // Set the base path component for URLs that access this service. -@Path("/ids") +@Path("/idgenerators") // Identify the default MIME media types consumed and produced by this service. @Consumes(MediaType.APPLICATION_XML) @Produces(MediaType.APPLICATION_XML) +/** + * IDResource + * + * Resource class to handle requests to the ID Service. + * + * $LastChangedBy$ + * $LastChangedRevision$ + * $LastChangedDate$ + */ public class IDResource { final Logger logger = LoggerFactory.getLogger(IDResource.class); @@ -68,58 +70,68 @@ public class IDResource { ////////////////////////////////////////////////////////////////////// /** - * Returns the next available ID associated with a specified ID pattern. - * - * @param csid An identifier for an ID pattern. + * Generates and returns a new ID, from the specified ID generator. * - * @return The next available ID associated with the specified ID pattern. - * - * @TODO: We're currently using simple integer IDs to identify ID patterns - * in this initial iteration. + * @param csid An identifier for an ID generator. * - * To uniquely identify ID patterns in production, we'll need to handle - * both CollectionSpace IDs (csids) - a form of UUIDs/GUIDs - and some - * other form of identifier to be determined, such as URLs or URNs. + * @return A new ID from the specified ID generator. */ - @GET - // @TODO: Temporary during early testing. - // To be changed to a POST request, and most likely to a different URL. - // E.g. /idpatterns/{identifier}/ids - @Path("/next/patterns/{csid}") - // @TODO: Temporary during testing; to be changed to return XML + @POST + @Path("/{csid}/ids") @Produces("text/plain") - public Response getNextID(@PathParam("csid") String csid) { + public Response newID(@PathParam("csid") String csid) { - logger.debug("> in getNextID(String)"); + logger.debug("> in newID(String)"); + + // @TODO The JavaDoc description reflects an as-yet-to-be-carried out + // refactoring, in which the highest object type in the ID service + // is that of an IDGenerator, some or all of which may be composed + // of IDParts. Some IDGenerators generate IDs based on patterns, + // which may be composed in part of incrementing numeric or alphabetic + // components, while others may not (e.g. UUIDs, web services-based + // responses). + + // @TODO We're currently using simple integer IDs to identify ID generators + // in this initial iteration. + // + // To uniquely identify ID generators in production, we'll need to handle + // both CollectionSpace IDs (csids) - a form of UUIDs/GUIDs - and some + // other form of identifier to be determined, such as URLs or URNs. + + // @TODO We're currently returning IDs in plain text. Identify whether + // there is a requirement to return an XML representation, and/or any + // other representations. - // Unless the 'response' variable is explicitly initialized here, the - // compiler gives the error: "variable response might not have been initialized." + // Unless the 'response' variable is explicitly initialized here, + // the compiler gives the error: "variable response might not have + // been initialized." Response response = null; response = response.ok().build(); - String nextId = ""; + String newId = ""; try { - // Retrieve the next ID for the requested pattern, + // Obtain a new ID from the specified ID generator, // and return it in the entity body of the response. - nextId = service.nextID(csid); + newId = service.newID(csid); - if (nextId == null || nextId.equals("")) { + if (newId == null || newId.equals("")) { response = Response.status(Response.Status.INTERNAL_SERVER_ERROR) .entity("ID Service returned null or empty ID").type(MediaType.TEXT_PLAIN).build(); return response; } response = Response.status(Response.Status.OK) - .entity(nextId).type(MediaType.TEXT_PLAIN).build(); + .entity(newId).type(MediaType.TEXT_PLAIN).build(); - // @TODO: Return an XML-based error results format with the + // @TODO Return an XML-based error results format with the // responses below. - // @TODO: An IllegalStateException often indicates an overflow + // @TODO An IllegalStateException often indicates an overflow // of an IDPart. Consider whether returning a 400 Bad Request // status code is still warranted, or whether returning some other // status would be more appropriate. + } catch (IllegalStateException ise) { response = Response.status(Response.Status.BAD_REQUEST) .entity(ise.getMessage()).type(MediaType.TEXT_PLAIN).build(); diff --git a/services/id/service/src/main/java/org/collectionspace/services/id/IDService.java b/services/id/service/src/main/java/org/collectionspace/services/id/IDService.java index eafd628a1..e8c7dbd10 100644 --- a/services/id/service/src/main/java/org/collectionspace/services/id/IDService.java +++ b/services/id/service/src/main/java/org/collectionspace/services/id/IDService.java @@ -1,8 +1,4 @@ /** - * IDService - * - * Interface for the methods of the ID Service. - * * This document is a part of the source code and related artifacts * for CollectionSpace, an open source collections management system * for museums and related institutions: @@ -17,16 +13,19 @@ * * You may obtain a copy of the ECL 2.0 License at * https://source.collectionspace.org/collection-space/LICENSE.txt + */ + +package org.collectionspace.services.id; + +/** + * IDService * - * Based on work by Richard Millet and Sanjay Dalal. + * Interface for the ID Service. * * $LastChangedBy$ * $LastChangedRevision$ * $LastChangedDate$ */ - -package org.collectionspace.services.id; - public interface IDService { // ---------------------------------------- @@ -37,11 +36,11 @@ public interface IDService { // Read single object - // Returns the next ID associated with a specified ID pattern. - public String nextID(String csid) + // Generates and returns a new ID from the specified ID generator. + public String newID(String csid) throws IllegalArgumentException, IllegalStateException; - // Returns the last generated ID associated with a specified ID pattern. + // Returns the last-generated ID associated with the specified ID generator. public String getLastID(String csid) throws IllegalArgumentException, IllegalStateException; @@ -51,6 +50,8 @@ public interface IDService { // ID Patterns // ---------------------------------------- + // @TODO Change this to IDGenerators in the next refactoring. + // Create // Adds a new ID pattern. diff --git a/services/id/service/src/main/java/org/collectionspace/services/id/IDServiceJdbcImpl.java b/services/id/service/src/main/java/org/collectionspace/services/id/IDServiceJdbcImpl.java index 85bfc3b49..451cc7216 100644 --- a/services/id/service/src/main/java/org/collectionspace/services/id/IDServiceJdbcImpl.java +++ b/services/id/service/src/main/java/org/collectionspace/services/id/IDServiceJdbcImpl.java @@ -1,9 +1,4 @@ /** - * IDServiceJdbcImpl - * - * Implementation of portions of the ID Service that use JDBC - * for persistence of IDPatterns, IDParts, and ID values. - * * This document is a part of the source code and related artifacts * for CollectionSpace, an open source collections management system * for museums and related institutions: @@ -18,12 +13,6 @@ * * You may obtain a copy of the ECL 2.0 License at * https://source.collectionspace.org/collection-space/LICENSE.txt - * - * Based on work by Richard Millet and Sanjay Dalal. - * - * $LastChangedBy$ - * $LastChangedRevision$ - * $LastChangedDate$ */ // @TODO: Revise exception handling to return custom Exceptions, @@ -41,14 +30,11 @@ // a new IDPattern and returning its next ID. As a result, // the generated IDs may well duplicate other, previously-generated IDs. // -// When we start storing IDPatterns and IDs in a database, the +// When we start storing ID generators and IDs in a database, the // the current ID associated with each pattern will be stored // and modified in a single location. // -// At that point, we'll also need to add code to ensure that only -// one IDPattern object is instantiated for each stored pattern, -// at initialization or reset time, as well as to handle concurrent -// requests. +// At that point, we'll also need to add code to handle concurrent requests. // @TODO: Verify access (public, protected, or private) to service methods. @@ -73,16 +59,27 @@ import java.sql.Statement; import org.slf4j.Logger; import org.slf4j.LoggerFactory; +/** + * IDServiceJdbcImpl + * + * Manages the storage of ID generators and persistence of their + * current state, via a JDBC interface to an underlying database. + * + * $LastChangedBy$ + * $LastChangedRevision$ + * $LastChangedDate$ + */ public class IDServiceJdbcImpl implements IDService { final Logger logger = LoggerFactory.getLogger(IDServiceJdbcImpl.class); // @TODO Get the JDBC driver classname and database URL from configuration; // better yet, substitute Hibernate for JDBC for accessing database-managed persistence. - // + // @TODO: Remove any hard-coded dependencies on MySQL. - // + // @TODO: Determine how to restrict access to ID-related tables by role. + final String JDBC_DRIVER_CLASSNAME = "com.mysql.jdbc.Driver"; final String DATABASE_URL = "jdbc:mysql://localhost:3306/cspace"; final String DATABASE_USERNAME = "test"; @@ -97,33 +94,33 @@ public class IDServiceJdbcImpl implements IDService { ////////////////////////////////////////////////////////////////////// /** - * Returns the next ID associated with a specified ID pattern. + * Generates and returns a new ID associated with a specified ID generator. * * This method has an intentional side-effect: it sets the - * current ID of that ID pattern to the just-generated ID. + * current ID of that ID generator to the just-generated ID. * - * @param csid An identifier for an ID pattern. - * - * @return The next ID associated with the specified ID pattern. - * - * @TODO: Implement logic to check for ID availability, after generating - * a candidate ID. + * @param csid An identifier for an ID generator. * - * @TODO: We're currently using simple integer IDs to identify ID patterns - * in this initial iteration. - * - * To uniquely identify ID patterns in production, we'll need to handle - * both CollectionSpace IDs (csids) - a form of UUIDs/GUIDs - and some - * other form of identifier to be determined, such as URLs or URNs. - * - * @TODO: Add checks for authorization to perform this operation. + * @return A new ID associated with the specified ID generator. */ - public String nextID(String csid) throws + public String newID(String csid) throws IllegalArgumentException, IllegalStateException { - logger.debug("> in nextID"); - - String nextId = ""; + logger.debug("> in newID"); + + // @TODO Where relevant, implement logic to check for ID availability, + // after generating a candidate ID. + + // @TODO We're currently using simple integer IDs to identify ID patterns + // in this initial iteration. + // + // To uniquely identify ID patterns in production, we'll need to handle + // both CollectionSpace IDs (csids) - a form of UUIDs/GUIDs - and some + // other form of identifier to be determined, such as URLs or URNs. + // + // @TODO: Add checks for authorization to perform this operation. + + String newId = ""; String lastId = ""; if (csid == null || csid.equals("")) { @@ -159,22 +156,23 @@ public class IDServiceJdbcImpl implements IDService { lastId = getLastID(csid); // If there was no last generated ID associated with this pattern, - // get the current ID generated by the pattern as the 'next' ID. + // get the current ID generated by the ID generator as the 'new' ID. if (lastId == null || lastId.equals("")) { - nextId = pattern.getCurrentID(); + newId = pattern.getCurrentID(); - // Otherwise, generate the 'next' ID for this pattern, based on the last ID. - // (This also sets the current ID for the pattern to this just-generated 'next' ID.) + // Otherwise, generate a new ID, potentially based on the last ID. + // (This also sets the current ID of the ID generator's state + // to this just-generated 'new' ID.) } else { - nextId = pattern.nextID(lastId); + newId = pattern.nextID(lastId); } - // Store the 'next' ID as the last-generated ID for this pattern. - updateLastID(csid, nextId); + // Store the 'new' ID as the last-generated ID for this pattern. + updateLastID(csid, newId); - // Store the new state of this ID Pattern, reflecting that one of its - // parts may have had its value updated as a result of the generation - // of this 'next' ID. + // Store the new state of this ID generator, reflecting that + // one of its parts may possibly have had its value updated as + // a result of the generation of this 'new' ID. updateIDPattern(csid, pattern); } catch (IllegalArgumentException e ) { @@ -183,7 +181,7 @@ public class IDServiceJdbcImpl implements IDService { throw e; } - return nextId; + return newId; }