Merge pull request #401 from wwelling/checkstyles

Add checkstyles

Author: wwtamu

.github/pull_request_template.md

@@ -1,15 +1,14 @@
 # Description
-> Please provide only as much detail as needed to justify the changes.
+> Please provide as much detail as needed to explain the changes.
 
 # Supporting Material
-> Please provide the links necessary to support the claims made in description above.
+> Please provide any links, screenshots, etc. as necessary to support the description.
 
 # Additional Comments
 > Please provide any additional feedback here.
 
 # Helper Checklist (optional)
 > Please ensure the following has been completed.
 
-- [ ] Changes reviewed and are acceptable to the best of your understanding.
-- [ ] Changes are documented where necessary.
-- [ ] Contacted code owners to evaluate.
+- [ ] Changes are documented to the best of your understanding.
+- [ ] Changes are reviewed and accepted.

checkstyles.xml

@@ -19,6 +19,19 @@
 
   <description>VIVO Scholars Middleware</description>
 
+  <organization>
+    <name>Texas A&amp;M University Libraries</name>
+    <url>https://library.tamu.edu</url>
+  </organization>
+
+  <developers>
+
+  </developers>
+
+  <contributors>
+
+  </contributors>
+
   <licenses>
     <license>
       <name>MIT</name>
@@ -29,9 +42,15 @@
 
   <properties>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+
+    <jena.version>4.9.0</jena.version>
     <liquibase.version>4.23.2</liquibase.version>
     <log4j2.version>2.17.2</log4j2.version>
-    <jena.version>4.9.0</jena.version>
+
+    <maven-checkstyle-plugin.version>3.3.1</maven-checkstyle-plugin.version>
+
+    <springdoc.version>2.0.0</springdoc.version>
+
     <solr.version>9.1.1</solr.version>
   </properties>
 
@@ -106,7 +125,19 @@
       <groupId>org.springframework.data</groupId>
       <artifactId>spring-data-rest-hal-explorer</artifactId>
     </dependency>
-    
+
+    <dependency>
+      <groupId>org.springdoc</groupId>
+      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+      <version>${springdoc.version}</version>
+    </dependency>
+
+    <dependency>
+      <groupId>org.springdoc</groupId>
+      <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
+      <version>${springdoc.version}</version>
+    </dependency>
+
     <dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-core</artifactId>
@@ -315,6 +346,31 @@
 
     <plugins>
 
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-checkstyle-plugin</artifactId>
+        <version>${maven-checkstyle-plugin.version}</version>
+        <configuration>
+          <excludes>org/springframework/**/*</excludes>
+          <configLocation>checkstyles.xml</configLocation>
+          <consoleOutput>true</consoleOutput>
+          <violationSeverity>warning</violationSeverity>
+          <failOnViolation>true</failOnViolation>
+          <failsOnError>true</failsOnError>
+          <linkXRef>false</linkXRef>
+          <skip>false</skip>
+        </configuration>
+        <executions>
+          <execution>
+            <id>validate</id>
+            <phase>prepare-package</phase>
+            <goals>
+              <goal>check</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+
       <!-- USE: mvn liquibase:generateChangeLog -->
       <plugin>
         <groupId>org.liquibase</groupId>

pom.xml

@@ -5,20 +5,27 @@
 import static edu.tamu.scholars.middleware.auth.AuthConstants.PASSWORD_MIN_LENGTH;
 import static edu.tamu.scholars.middleware.discovery.DiscoveryConstants.EXPORT_INDIVIDUAL_KEY;
 
-import java.util.TimeZone;
-
 import javax.annotation.PostConstruct;
 
+import java.util.TimeZone;
+
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 import org.springframework.scheduling.annotation.EnableScheduling;
+import org.springframework.scheduling.annotation.Scheduled;
 
 import edu.tamu.scholars.middleware.auth.config.AuthConfig;
 import edu.tamu.scholars.middleware.auth.config.PasswordConfig;
 import edu.tamu.scholars.middleware.config.model.ExportConfig;
 import edu.tamu.scholars.middleware.config.model.MiddlewareConfig;
+import edu.tamu.scholars.middleware.discovery.service.IndexService;
 
+/**
+ * Scholars middleware application and initialization.
+ * 
+ * <p>Enables {@link Scheduled} annotation used in {@link IndexService}.</p>
+ */
 @EnableScheduling
 @SpringBootApplication
 public class MiddlewareApplication {

src/main/java/edu/tamu/scholars/middleware/MiddlewareApplication.java

@@ -1,5 +1,12 @@
 package edu.tamu.scholars.middleware.auth;
 
+import edu.tamu.scholars.middleware.MiddlewareApplication;
+import edu.tamu.scholars.middleware.auth.details.CustomUserDetails;
+
+/**
+ * Application initialized constants for use at runtime statically.
+ * These are set in {@link MiddlewareApplication} and used in {@link CustomUserDetails}.
+ */
 public class AuthConstants {
 
     public static int PASSWORD_DURATION_IN_DAYS;

src/main/java/edu/tamu/scholars/middleware/auth/AuthConstants.java

@@ -3,15 +3,19 @@
 import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
+import javax.validation.Constraint;
+import javax.validation.Payload;
+
 import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
-import javax.validation.Constraint;
-import javax.validation.Payload;
-
+import edu.tamu.scholars.middleware.auth.model.User;
 import edu.tamu.scholars.middleware.auth.validator.EmailConstraintValidator;
 
+/**
+ * Annotation to declare validated {@link User} model email is available.
+ */
 @Documented
 @Target(FIELD)
 @Retention(RUNTIME)

src/main/java/edu/tamu/scholars/middleware/auth/annotation/AvailableEmail.java

@@ -3,15 +3,19 @@
 import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
+import javax.validation.Constraint;
+import javax.validation.Payload;
+
 import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
-import javax.validation.Constraint;
-import javax.validation.Payload;
-
+import edu.tamu.scholars.middleware.auth.model.User;
 import edu.tamu.scholars.middleware.auth.validator.PasswordConstraintValidator;
 
+/**
+ * Annotation to declare validated {@link User} model password is available.
+ */
 @Documented
 @Target(TYPE)
 @Retention(RUNTIME)

src/main/java/edu/tamu/scholars/middleware/auth/annotation/ValidPassword.java

@@ -3,6 +3,12 @@
 import org.springframework.boot.context.properties.ConfigurationProperties;
 import org.springframework.stereotype.Component;
 
+/**
+ * Injectable middleware configuration to specify properties relating to
+ * authentication and authorization.
+ *
+ * <p>See `middleware.auth` in src/main/resources/application.yml.</p>
+ */
 @Component
 @ConfigurationProperties(prefix = "middleware.auth")
 public class AuthConfig {

src/main/java/edu/tamu/scholars/middleware/auth/config/AuthConfig.java

@@ -3,6 +3,11 @@
 import org.springframework.boot.context.properties.ConfigurationProperties;
 import org.springframework.stereotype.Component;
 
+/**
+ * Injectable middleware auth configuration to specify password properties.
+ * 
+ * <p>See `middleware.auth.password` in src/main/resources/application.yml.</p>
+ */
 @Component
 @ConfigurationProperties(prefix = "middleware.auth.password")
 public class PasswordConfig {

src/main/java/edu/tamu/scholars/middleware/auth/config/PasswordConfig.java

@@ -3,6 +3,11 @@
 import org.springframework.boot.context.properties.ConfigurationProperties;
 import org.springframework.stereotype.Component;
 
+/**
+ * Injectable middleware auth configuration to specify token properties.
+ * 
+ * <p>See `middleware.auth.token` in src/main/resources/application.yml.</p>
+ */
 @Component
 @ConfigurationProperties(prefix = "middleware.auth.token")
 public class TokenConfig {

src/main/java/edu/tamu/scholars/middleware/auth/config/TokenConfig.java

@@ -6,6 +6,9 @@
 
 import edu.tamu.scholars.middleware.auth.model.User;
 
+/**
+ * Authentication controller returning the authenticated {@link User}.
+ */
 @RestController
 public class AuthController {
 

src/main/java/edu/tamu/scholars/middleware/auth/controller/AuthController.java

@@ -2,7 +2,11 @@
 
 import java.io.IOException;
 
+import com.fasterxml.jackson.core.JsonParseException;
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.JsonMappingException;
 import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.context.annotation.Lazy;
 import org.springframework.http.ResponseEntity;
 import org.springframework.validation.annotation.Validated;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -13,36 +17,53 @@
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
-import com.fasterxml.jackson.core.JsonParseException;
-import com.fasterxml.jackson.core.JsonProcessingException;
-import com.fasterxml.jackson.databind.JsonMappingException;
-
 import edu.tamu.scholars.middleware.auth.controller.exception.RegistrationException;
 import edu.tamu.scholars.middleware.auth.controller.request.Registration;
 import edu.tamu.scholars.middleware.auth.model.User;
 import edu.tamu.scholars.middleware.auth.service.RegistrationService;
 import edu.tamu.scholars.middleware.auth.validator.group.CompleteRegistration;
 import edu.tamu.scholars.middleware.auth.validator.group.SubmitRegistration;
 
+/**
+ * {@link User} registration controller.
+ * 
+ * <p>
+ * This controller provides ability to register a {@link User} through the following sequence of requests
+ * </p>
+ * 
+ * <ol>
+ * <li>Submit registration request; create disabled user, send email confirmation with link and token</li>
+ * <li>Confirm email registration; validate token and confirm user email</li>
+ * <li>Complete registration; update and activates user</li>
+ * </ol>
+ */
 @RestController
 @RequestMapping("/registration")
 public class RegistrationController {
 
+    @Lazy
     @Autowired
     private RegistrationService registrationService;
 
     @PostMapping
-    public ResponseEntity<Registration> submit(@RequestBody @Validated(SubmitRegistration.class) Registration registration) throws JsonProcessingException {
+    public ResponseEntity<Registration> submit(
+            @RequestBody @Validated(SubmitRegistration.class) Registration registration)
+            throws JsonProcessingException {
         return ResponseEntity.ok(registrationService.submit(registration));
     }
 
     @GetMapping
-    public ResponseEntity<Registration> confirm(@RequestParam(required = true) String key) throws JsonParseException, JsonMappingException, IOException, RegistrationException {
+    public ResponseEntity<Registration> confirm(
+            @RequestParam(required = true) String key)
+            throws JsonParseException, JsonMappingException, IOException, RegistrationException {
         return ResponseEntity.ok(registrationService.confirm(key));
     }
 
     @PutMapping
-    public ResponseEntity<User> complete(@RequestParam(required = true) String key, @RequestBody @Validated(CompleteRegistration.class) Registration registration) throws RegistrationException {
+    public ResponseEntity<User> complete(
+            @RequestParam(required = true) String key,
+            @RequestBody @Validated(CompleteRegistration.class) Registration registration)
+            throws RegistrationException {
         return ResponseEntity.ok(registrationService.complete(key, registration));
     }
 

src/main/java/edu/tamu/scholars/middleware/auth/controller/RegistrationController.java

@@ -10,15 +10,27 @@
 import org.springframework.web.bind.annotation.RestController;
 
 import edu.tamu.scholars.middleware.auth.controller.RegistrationController;
+import edu.tamu.scholars.middleware.auth.model.User;
 
+/**
+ * {@link User} registration controller advice to handle bad requests.
+ */
 @RestController
 @ControllerAdvice(assignableTypes = { RegistrationController.class })
 public class RegistrationAdvice {
 
+    // TODO: add logging
+    // TODO: handle registration exception and other exceptions thrown by the RegistrationController
+
     @ResponseStatus(BAD_REQUEST)
     @ExceptionHandler(MethodArgumentNotValidException.class)
-    public @ResponseBody String handleMethodArgumentNotValidException(MethodArgumentNotValidException exception) {
-        return exception.getBindingResult().getAllErrors().get(0).getDefaultMessage();
+    public @ResponseBody String handleMethodArgumentNotValidException(
+        MethodArgumentNotValidException exception
+    ) {
+        return exception.getBindingResult()
+            .getAllErrors()
+            .get(0)
+            .getDefaultMessage();
     }
 
     @ResponseStatus(BAD_REQUEST)

src/main/java/edu/tamu/scholars/middleware/auth/controller/advice/RegistrationAdvice.java

@@ -1,5 +1,11 @@
 package edu.tamu.scholars.middleware.auth.controller.exception;
 
+import edu.tamu.scholars.middleware.auth.model.User;
+import edu.tamu.scholars.middleware.auth.service.RegistrationService;
+
+/**
+ * {@link User} registration exception used by {@link RegistrationService}.
+ */
 public class RegistrationException extends Exception {
 
     private static final long serialVersionUID = 7712767291119883628L;