Formatting applied to RoleHandler

This change tackles some vital formatting issues with RoleHandler.  The
following is done to the RoleHandler class to promote clarity and conformance
to project style:

1) Move the class documentation comment to the right location.  Add some
detailed information to the class comment concerning how to use the REST
endpoints for RoleHandler.

2) Add function documentation comments explaining their responsibilities.

3) Format in eclipse by clicking "format".

4) Fix any errors reported by "mvn checkstyle:checkstyle".

No actual code or functionality changes were made.  This is strictly a
formatting related patch.

Change-Id: I7a8a9343792d5384b1639010918d2ed8ecdaaa6a
Signed-off-by: Ryan Goulding <ryandgoulding@gmail.com>

diff --git a/aaa-idmlight/src/main/java/org/opendaylight/aaa/idm/rest/RoleHandler.java b/aaa-idmlight/src/main/java/org/opendaylight/aaa/idm/rest/RoleHandler.java
index 87ca513839637f91430b25193ea66b8db4f73110..34a60c0c480aa350e353a2d171629fcf01c91c54 100644 (file)
--- a/aaa-idmlight/src/main/java/org/opendaylight/aaa/idm/rest/RoleHandler.java
+++ b/aaa-idmlight/src/main/java/org/opendaylight/aaa/idm/rest/RoleHandler.java
@@ -8,12 +8,6 @@
 
 package org.opendaylight.aaa.idm.rest;
 
-/**
- *
- * @author peter.mellquist@hp.com
- *
- */
-
 import javax.ws.rs.Consumes;
 import javax.ws.rs.DELETE;
 import javax.ws.rs.GET;
@@ -36,133 +30,199 @@ import org.opendaylight.yang.gen.v1.config.aaa.authn.idmlight.rev151204.AAAIDMLi
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * REST application used to manipulate the H2 database roles table. The REST
+ * endpoint is <code>/auth/v1/roles</code>.
+ *
+ * The following provides examples of curl commands and payloads to utilize the
+ * roles REST endpoint:
+ *
+ * <b>Get All Roles</b>
+ * <code>curl -u admin:admin http://{HOST}:{PORT}/auth/v1/roles</code>
+ *
+ * <b>Get A Specific Role</b>
+ * <code>curl -u admin:admin http://{HOST}:{PORT}/auth/v1/roles/{id}</code>
+ *
+ * <b>Create A Role</b>
+ * <code>curl -u admin:admin -X POST -H "Content-Type: application/json" --data-binary {@literal @}role.json http://{HOST}:{PORT}/auth/v1/roles</code>
+ * An example of role.json:
+ * <code>{
+ *  "name":"IT Administrator",
+ *  "description":"A user role for IT admins"
+ * }</code>
+ *
+ * <b>Update A Role</b>
+ * <code>curl -u admin:admin -X PUT -H "Content-Type: application/json" --data-binary {@literal @}role.json http://{HOST}:{PORT}/auth/v1/roles/{id}</code>
+ * An example of role.json:
+ * <code>{
+ *  "name":"IT Administrator Limited",
+ *  "description":"A user role for IT admins who can only do one thing"
+ * }</code>
+ *
+ * @author peter.mellquist@hp.com
+ * @author Ryan Goulding (ryandgoulding@gmail.com)
+ */
 @Path("/v1/roles")
 public class RoleHandler {
-   private static Logger logger = LoggerFactory.getLogger(RoleHandler.class);
-
-   @GET
-   @Produces("application/json")
-   public Response getRoles() {
-      logger.info("get /roles");
-      Roles roles=null;
-      try {
-         roles = AAAIDMLightModule.getStore().getRoles();
-      }
-      catch (IDMStoreException se) {
-         return new IDMError(500,"internal error getting roles",se.getMessage()).response();
-      }
-      return Response.ok(roles).build();
-   }
-
-   @GET
-   @Path("/{id}")
-   @Produces("application/json")
-   public Response getRole(@PathParam("id") String id)  {
-      logger.info("get /roles/" + id);
-      Role role=null;
-
-      try {
-         role = AAAIDMLightModule.getStore().readRole(id);
-      }
-      catch(IDMStoreException se) {
-         return new IDMError(500,"internal error getting roles",se.getMessage()).response();
-      }
-
-      if (role==null) {
-         return new IDMError(404,"role not found id :" + id,"").response();
-      }
-      return Response.ok(role).build();
-   }
-
-   @POST
-   @Consumes("application/json")
-   @Produces("application/json")
-   public Response createRole(@Context UriInfo info,Role role) {
-      logger.info("Post /roles");
-      try {
-         // TODO: role names should be unique!
-         // name
-         if (role.getName()==null) {
-            return new IDMError(404,"name must be defined on role create","").response();
-         }
-         else if (role.getName().length()> IdmLightApplication.MAX_FIELD_LEN) {
-            return new IDMError(400,"role name max length is :" + IdmLightApplication.MAX_FIELD_LEN,"").response();
-         }
-
-         // domain
-         if (role.getDomainid()==null) {
-            return new IDMError(404,"The role's domain must be defined on role when creating a role.","").response();
-         }
-         else if (role.getDomainid().length()>IdmLightApplication.MAX_FIELD_LEN) {
-            return new IDMError(400,"role domain max length is :" + IdmLightApplication.MAX_FIELD_LEN,"").response();
-         }
-
-         // description
-         if (role.getDescription()==null) {
-            role.setDescription("");
-         }
-         else if (role.getDescription().length()>IdmLightApplication.MAX_FIELD_LEN) {
-            return new IDMError(400,"role description max length is :" + IdmLightApplication.MAX_FIELD_LEN,"").response();
-         }
-
-         role = AAAIDMLightModule.getStore().writeRole(role);
-      }
-      catch (IDMStoreException se) {
-         return new IDMError(500,"internal error creating role",se.getMessage()).response();
-      }
-
-      return Response.status(201).entity(role).build();
-   }
-
-   @PUT
-   @Path("/{id}")
-   @Consumes("application/json")
-   @Produces("application/json")
-   public Response putRole(@Context UriInfo info,Role role,@PathParam("id") String id) {
-      logger.info("put /roles/" + id);
-
-      try {
-         role.setRoleid(id);
-
-         // name
-         // TODO: names should be unique
-         if ((role.getName()!=null) && (role.getName().length()>IdmLightApplication.MAX_FIELD_LEN)) {
-            return new IDMError(400,"role name max length is :" + IdmLightApplication.MAX_FIELD_LEN,"").response();
-         }
-
-         // description
-         if ((role.getDescription()!=null) && (role.getDescription().length()>IdmLightApplication.MAX_FIELD_LEN)) {
-            return new IDMError(400,"role description max length is :" + IdmLightApplication.MAX_FIELD_LEN,"").response();
-         }
-
-         role = AAAIDMLightModule.getStore().updateRole(role);
-         if (role==null) {
-            return new IDMError(404,"role id not found :" + id,"").response();
-         }
-         IdmLightProxy.clearClaimCache();
-         return Response.status(200).entity(role).build();
-      }
-      catch (IDMStoreException se) {
-         return new IDMError(500,"internal error putting role",se.getMessage()).response();
-      }
-   }
-
-   @DELETE
-   @Path("/{id}")
-   public Response deleteRole(@Context UriInfo info,@PathParam("id") String id) {
-      logger.info("Delete /roles/" + id);
-
-      try {
-         Role role = AAAIDMLightModule.getStore().deleteRole(id);
-         if (role==null) {
-            return new IDMError(404,"role id not found :" + id,"").response();
-         }
-      }
-      catch (IDMStoreException se) {
-         return new IDMError(500,"internal error deleting role",se.getMessage()).response();
-      }
-      IdmLightProxy.clearClaimCache();
-      return Response.status(204).build();
-   }
+    private static final Logger LOG = LoggerFactory.getLogger(RoleHandler.class);
+
+    /**
+     * Extracts all roles.
+     *
+     * @return A response with all roles in the H2 database, or internal error if one is encountered
+     */
+    @GET
+    @Produces("application/json")
+    public Response getRoles() {
+        LOG.info("get /roles");
+        Roles roles = null;
+        try {
+            roles = AAAIDMLightModule.getStore().getRoles();
+        } catch (IDMStoreException se) {
+            return new IDMError(500, "internal error getting roles", se.getMessage()).response();
+        }
+        return Response.ok(roles).build();
+    }
+
+    /**
+     * Extract a specific role identified by <code>id</code>
+     *
+     * @param id the String id for the role
+     * @return A response with the role identified by <code>id</code>, or internal error if one is encountered
+     */
+    @GET
+    @Path("/{id}")
+    @Produces("application/json")
+    public Response getRole(@PathParam("id") String id) {
+        LOG.info("get /roles/{}", id);
+        Role role = null;
+
+        try {
+            role = AAAIDMLightModule.getStore().readRole(id);
+        } catch (IDMStoreException se) {
+            return new IDMError(500, "internal error getting roles", se.getMessage()).response();
+        }
+
+        if (role == null) {
+            return new IDMError(404, "role not found id :" + id, "").response();
+        }
+        return Response.ok(role).build();
+    }
+
+    /**
+     * Creates a role.
+     *
+     * @param info passed from Jersey
+     * @param role the role JSON payload
+     * @return A response stating success or failure of role creation, or internal error if one is encountered
+     */
+    @POST
+    @Consumes("application/json")
+    @Produces("application/json")
+    public Response createRole(@Context UriInfo info, Role role) {
+        LOG.info("Post /roles");
+        try {
+            // TODO: role names should be unique!
+            // name
+            if (role.getName() == null) {
+                return new IDMError(404, "name must be defined on role create", "").response();
+            } else if (role.getName().length() > IdmLightApplication.MAX_FIELD_LEN) {
+                return new IDMError(400, "role name max length is :"
+                        + IdmLightApplication.MAX_FIELD_LEN, "").response();
+            }
+
+            // domain
+            if (role.getDomainid() == null) {
+                return new IDMError(404,
+                        "The role's domain must be defined on role when creating a role.", "")
+                        .response();
+            } else if (role.getDomainid().length() > IdmLightApplication.MAX_FIELD_LEN) {
+                return new IDMError(400, "role domain max length is :"
+                        + IdmLightApplication.MAX_FIELD_LEN, "").response();
+            }
+
+            // description
+            if (role.getDescription() == null) {
+                role.setDescription("");
+            } else if (role.getDescription().length() > IdmLightApplication.MAX_FIELD_LEN) {
+                return new IDMError(400, "role description max length is :"
+                        + IdmLightApplication.MAX_FIELD_LEN, "").response();
+            }
+
+            role = AAAIDMLightModule.getStore().writeRole(role);
+        } catch (IDMStoreException se) {
+            return new IDMError(500, "internal error creating role", se.getMessage()).response();
+        }
+
+        return Response.status(201).entity(role).build();
+    }
+
+    /**
+     * Updates a specific role identified by <code>id</code>.
+     *
+     * @param info passed from Jersey
+     * @param role the role JSON payload
+     * @param id the String id for the role
+     * @return A response stating success or failure of role update, or internal error if one occurs
+     */
+    @PUT
+    @Path("/{id}")
+    @Consumes("application/json")
+    @Produces("application/json")
+    public Response putRole(@Context UriInfo info, Role role, @PathParam("id") String id) {
+        LOG.info("put /roles/{}", id);
+
+        try {
+            role.setRoleid(id);
+
+            // name
+            // TODO: names should be unique
+            if ((role.getName() != null)
+                    && (role.getName().length() > IdmLightApplication.MAX_FIELD_LEN)) {
+                return new IDMError(400, "role name max length is :"
+                        + IdmLightApplication.MAX_FIELD_LEN, "").response();
+            }
+
+            // description
+            if ((role.getDescription() != null)
+                    && (role.getDescription().length() > IdmLightApplication.MAX_FIELD_LEN)) {
+                return new IDMError(400, "role description max length is :"
+                        + IdmLightApplication.MAX_FIELD_LEN, "").response();
+            }
+
+            role = AAAIDMLightModule.getStore().updateRole(role);
+            if (role == null) {
+                return new IDMError(404, "role id not found :" + id, "").response();
+            }
+            IdmLightProxy.clearClaimCache();
+            return Response.status(200).entity(role).build();
+        } catch (IDMStoreException se) {
+            return new IDMError(500, "internal error putting role", se.getMessage()).response();
+        }
+    }
+
+    /**
+     * Delete a role.
+     *
+     * @param info passed from Jersey
+     * @param id the String id for the role
+     * @return A response stating success or failure of user deletion, or internal error if one occurs
+     */
+    @DELETE
+    @Path("/{id}")
+    public Response deleteRole(@Context UriInfo info, @PathParam("id") String id) {
+        LOG.info("Delete /roles/{}", id);
+
+        try {
+            Role role = AAAIDMLightModule.getStore().deleteRole(id);
+            if (role == null) {
+                return new IDMError(404, "role id not found :" + id, "").response();
+            }
+        } catch (IDMStoreException se) {
+            return new IDMError(500, "internal error deleting role", se.getMessage()).response();
+        }
+        IdmLightProxy.clearClaimCache();
+        return Response.status(204).build();
+    }
 
 }