Adden user data completion and docs correction

buisnesslogic/src/main/java/com/plannaplan/api/UsosOauth1Service.java

@@ -2,6 +2,9 @@ package com.plannaplan.api;
 
 import com.github.scribejava.core.builder.api.DefaultApi10a;
 
+/**
+ * singleton class to sign usos api requests with oauth
+ */
 public class UsosOauth1Service extends DefaultApi10a {
 
     private static final String AUTHORIZE_URL = "https://usosapidemo.amu.edu.pl/services/oauth/authorize";
@@ -30,6 +33,12 @@ public class UsosOauth1Service extends DefaultApi10a {
         return InstanceHolder.INSTANCE;
     }
 
+    /**
+     * get instance withj scopes
+     * 
+     * @param scopes to get instance with
+     * @return UsosOauth1Service instance
+     */
     public static UsosOauth1Service instance(String... scopes) {
         return scopes == null || scopes.length == 0 ? instance() : new UsosOauth1Service(scopes);
     }

buisnesslogic/src/main/java/com/plannaplan/entities/Assignment.java

@@ -8,7 +8,8 @@ import javax.persistence.JoinColumn;
 import javax.persistence.ManyToOne;
 
 /**
- *  Entity of Assignment grouping of state associated about group_id and commision_id
+ * Entity of Assignment grouping of state associated about group_id and
+ * commision_id
  * 
  */
 
@@ -27,6 +28,7 @@ public class Assignment {
 
     /**
      * Assignment
+     * 
      * @param group            group we would like to assign
      * @param commision        commision that assignment belongs to
      * @param isPastAssignment is assignment past or no
@@ -38,6 +40,7 @@ public class Assignment {
 
     /**
      * Assignment
+     * 
      * @param group     group we would like to assign
      * @param commision commision that assignment belongs to
      */
@@ -50,6 +53,7 @@ public class Assignment {
 
     /**
      * Id getter
+     * 
      * @return id id of assignment
      */
 
@@ -68,6 +72,7 @@ public class Assignment {
 
     /**
      * isPastAssignment getter
+     * 
      * @return isPastAssignment
      */
     public boolean isPastAssignment() {
@@ -76,7 +81,8 @@ public class Assignment {
 
     /**
      * setter isPastAssignment
-     * @param isPastAssignment
+     * 
+     * @param isPastAssignment is assignment past or not
      */
     public void setPastAssignment(boolean isPastAssignment) {
         this.isPastAssignment = isPastAssignment;

buisnesslogic/src/main/java/com/plannaplan/entities/Groups.java

@@ -56,7 +56,6 @@ public class Groups {
         this.zajCykId = zajCykId;
     }
 
-
     /**
      * Groups
      * 
@@ -90,9 +89,10 @@ public class Groups {
      * @param day      day given to the groups
      * @param lecturer lecturer given to the groups
      * @param zajCykId number of class in the term
-     * @param gr_nr Number of class/course
+     * @param grNr     Number of class/course
      */
-    public Groups(int capacity, String room, Course course, int time, int endTime, WeekDay day, Lecturer lecturer, Integer zajCykId, Integer grNr) {
+    public Groups(int capacity, String room, Course course, int time, int endTime, WeekDay day, Lecturer lecturer,
+            Integer zajCykId, Integer grNr) {
         this(capacity, room, course, time, endTime, day, lecturer);
         this.zajCykId = zajCykId;
         this.grNr = grNr;
@@ -110,7 +110,8 @@ public class Groups {
      * @param zajCykId number of class in the term
      * @param grNr     Number of class/course
      */
-    public Groups(int capacity, String room, Course course, int time, WeekDay day, Lecturer lecturer, Integer zajCykId, Integer grNr) {
+    public Groups(int capacity, String room, Course course, int time, WeekDay day, Lecturer lecturer, Integer zajCykId,
+            Integer grNr) {
         this(capacity, room, course, time, time + DEFAULT_CLASS_TIME, day, lecturer);
         this.zajCykId = zajCykId;
         this.grNr = grNr;
@@ -141,32 +142,33 @@ public class Groups {
      * @param day      day given to the groups
      * @param lecturer lecturer given to the groups
      */
-    public void update(Integer capacity, String room, Course course, Integer time, Integer endTime, WeekDay day, Lecturer lecturer){
+    public void update(Integer capacity, String room, Course course, Integer time, Integer endTime, WeekDay day,
-        if (capacity != null){
+            Lecturer lecturer) {
+        if (capacity != null) {
             this.capacity = capacity;
         }
 
-        if (room != null){
+        if (room != null) {
             this.room = room;
         }
 
-        if (course != null){
+        if (course != null) {
             this.course = course;
         }
 
-        if (time != null){
+        if (time != null) {
             this.time = time;
         }
 
-        if (endTime != null){
+        if (endTime != null) {
             this.endTime = endTime;
         }
 
-        if (day != null){
+        if (day != null) {
             this.day = day;
         }
 
-        if (lecturer != null){
+        if (lecturer != null) {
             this.lecturer = lecturer;
         }
     }

buisnesslogic/src/main/java/com/plannaplan/entities/User.java

@@ -9,6 +9,7 @@ import javax.persistence.GeneratedValue;
 import javax.persistence.GenerationType;
 import javax.persistence.Id;
 
+import com.plannaplan.models.UserApiResponse;
 import com.plannaplan.types.UserRoles;
 
 /**
@@ -40,7 +41,7 @@ public class User {
      * @param name    name given to the user
      * @param surname surname given to the user
      * @param mail    mail given to the user
-     * @param role
+     * @param role    user's role
      */
     public User(String name, String surname, String mail, UserRoles role) {
         this.name = name;
@@ -55,7 +56,7 @@ public class User {
      * @param surname surname given to the user
      * @param mail    mail given to the user
      * @param usosId  id in the USOS system
-     * @param role
+     * @param role    user's role
      */
     public User(String name, String surname, String mail, String usosId, UserRoles role) {
         this(name, surname, mail, role);
@@ -188,6 +189,16 @@ public class User {
         return this.id;
     }
 
+    /**
+     * updates user entity with data got by UsosApiService::getUserData
+     * 
+     * @param usosData UserApiResponse model with needed data
+     */
+    public void updateWithUsosData(UserApiResponse usosData) {
+        this.name = usosData.getName();
+        this.surname = usosData.getSurname();
+    }
+
     /**
      * it checks if given ammount of time passed since last token usage. If not
      * retunr true and reset time otherwise return false and token won work anymore

buisnesslogic/src/main/java/com/plannaplan/repositories/UserRepository.java

@@ -36,6 +36,12 @@ import org.springframework.stereotype.Repository;
 @Repository
 public interface UserRepository extends JpaRepository<User, Long> {
     @Query("FROM User WHERE email = ?1 OR usosId = ?1")
+    /**
+     * return user by given authority
+     * 
+     * @param authority user usosId or email
+     * @return optional with user if found
+     */
     Optional<User> getByAuthority(@Param("authority") String authority);
 
     @Query("FROM User WHERE email = ?1")
@@ -51,6 +57,13 @@ public interface UserRepository extends JpaRepository<User, Long> {
     List<User> searchForUsers(@Param("query") String query);
 
     @Query("FROM User WHERE (name LIKE %?1% OR surname LIKE %?1%) AND role=?2")
+    /**
+     * search for user with given query
+     * 
+     * @param query string that will be matched to users name and surname
+     * @param role  limits results by role
+     * @return list opf results
+     */
     List<User> searchForUsers(@Param("query") String query, @Param("role") UserRoles role);
 
     @Query("FROM User WHERE role=?1")

buisnesslogic/src/main/java/com/plannaplan/services/GroupService.java

@@ -67,9 +67,9 @@ public class GroupService {
 
     /**
      * 
-     * @param assingemnts list of assingemnts you want to get taken places ammount
+     * @param assignments list of assignments you want to get taken places ammount
-     * @return HashMap<Long, Integer> where Long is group id and Integer is how many
+     * @return HashMap of Long to Integer where Long is group id and Integer is how
-     *         places in gorup is already taken
+     *         many places in gorup is already taken
      */
     public HashMap<Long, Integer> getTakenPlacesOfAssignments(List<Assignment> assignments) {
         return getTakenPlaces(assignments.stream().map(Assignment::getGroup).collect(Collectors.toList()));
@@ -78,8 +78,8 @@ public class GroupService {
     /**
      * 
      * @param groups list of groups you want to get taken places ammount
-     * @return HashMap<Long, Integer> where Long is group id and Integer is how many
+     * @return HashMap of Long to Integer where Long is group id and Integer is how
-     *         places in gorup is already taken
+     *         many places in gorup is already taken
      */
     public HashMap<Long, Integer> getTakenPlaces(List<Groups> groups) {
         HashMap<Long, Integer> response = new HashMap<>();

buisnesslogic/src/main/java/com/plannaplan/services/UserService.java

@@ -6,6 +6,7 @@ import java.util.UUID;
 
 import com.plannaplan.entities.User;
 import com.plannaplan.exceptions.UserNotFoundException;
+import com.plannaplan.models.UserApiResponse;
 import com.plannaplan.repositories.UserRepository;
 import com.plannaplan.types.UserRoles;
 
@@ -20,14 +21,33 @@ public class UserService {
     @Autowired
     private UserRepository repo;
 
+    @Autowired
+    private UsosApiService service;
+
     public UserService() {
         super();
     }
 
+    /**
+     * checks if user exist and return him or creates new one with student role
+     * otherwise
+     * 
+     * @param email  user email in usos
+     * @param usosId user id in usos
+     * @return user entity instace containing changes saved in database
+     */
     public User checkForUser(String email, String usosId) {
         return this.checkForUser(email, usosId, UserRoles.STUDENT);
     }
 
+    /**
+     * checks if user exist and creates new one if doesn't
+     * 
+     * @param email          user email in usos
+     * @param usosId         user id in usos
+     * @param roleIfNotExist role to be set in case user is not in database yet
+     * @return user entity instace containing changes saved in database
+     */
     public User checkForUser(String email, String usosId, UserRoles roleIfNotExist) {
         if (usosId == null) {
             Optional<User> user = this.repo.getByEmail(email.replace("\n", "").trim());
@@ -48,8 +68,20 @@ public class UserService {
         }
     }
 
+    /**
+     * generates token for user and if user don't have name in database it will
+     * attemp to obtain these from usos api and saves changes in database
+     * 
+     * @param authority user we want to login
+     * @return user with changed values after save in db
+     * @throws UserNotFoundException throwed if user doesn't exist
+     */
     public User login(User authority) throws UserNotFoundException {
         final String token = UUID.randomUUID().toString();
+        if ((authority.getName() == null || authority.getSurname() == null) && authority.getUsosId() != null) {
+            final UserApiResponse resp = this.service.getUserData(authority.getUsosId());
+            authority.updateWithUsosData(resp);
+        }
         try {
             authority.setToken(token);
             this.repo.save(authority);
@@ -59,16 +91,34 @@ public class UserService {
         return authority;
     }
 
+    /**
+     * sacves user to databse and return instatnce with id
+     * 
+     * @param user to be saved
+     * @return instatnce with bd id
+     */
     public User save(User user) {
         return this.repo.save(user);
     }
 
+    /**
+     * 
+     * @param email of user to be find
+     * @return user with given mail
+     * @throws UserNotFoundException throwed if user doesn't exist
+     */
     public User getUserByEmail(String email) throws UserNotFoundException {
         return this.repo.getByEmail(email.replace("\n", "").trim())
                 .orElseThrow(() -> new UserNotFoundException("Cannot find user with given authority"));
 
     }
 
+    /**
+     * return user by given authority
+     * 
+     * @param authority user usosId or email
+     * @return optional with user if found
+     */
     public Optional<User> getByAuthority(String authority) {
         return this.repo.getByAuthority(authority);
     }
@@ -77,6 +127,12 @@ public class UserService {
         return this.repo.getByToken(token);
     }
 
+    /**
+     * search for user with given query
+     * 
+     * @param query string that will be matched to users name and surname
+     * @return list opf results
+     */
     public List<User> searchForStudents(String query) {
         return this.repo.searchForUsers(query, UserRoles.STUDENT);
     }
@@ -93,7 +149,7 @@ public class UserService {
         return this.repo.getByRefreshToken(refreshToken);
     }
 
-    public boolean adminExists(){
+    public boolean adminExists() {
         return this.repo.getAllByRole(UserRoles.ADMIN).size() > 0;
     }
 

buisnesslogic/src/main/java/com/plannaplan/services/UsosApiService.java

@@ -19,10 +19,10 @@ import com.plannaplan.models.UserApiResponse;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.stereotype.Service;
 
-@Service
 /**
  * service to call usos api endpoints
  */
+@Service
 public class UsosApiService {
 
     private static final String NAME_FIELD = "first_name";