DataHandler update
[staff/due1/sed-hs15-srs-purple.git] / src / main / java / ch / bfh / ti / srs / controller / UserController.java
index aeceff9..7073c7e 100644 (file)
@@ -33,7 +33,7 @@ public class UserController {
        }\r
        \r
        /**\r
-        * Sets the DataHandler implementation for this Controller, must be set before using all other methods!\r
+        * Sets the <code>DataHandler</code> implementation for this Controller, must be set before using all other methods!\r
         * \r
         * @param dh    DataHandler implementation (i.e. DataHandlerForExcel)\r
         */\r
@@ -42,14 +42,14 @@ public class UserController {
        }\r
        \r
        /**\r
-        * Tries to logIn a user with the given credentials\r
+        * Tries to log in a <code>User</code> with the given credentials\r
         * \r
-        * @param userName                                      username\r
-        * @param password                                      the stored password for the given username\r
-        * @return                                                      <code>true</code> if the user could log in successfully;\r
-        *                                                                      <code>false</code> eighter the username or the password was not correct.\r
-        * @throws Exception                            no datahandler set or thrown by datahandler\r
-        * @throws AlreadyBoundException        a user is already logged in\r
+        * @param userName                                      user name\r
+        * @param password                                      the stored password for the given user name\r
+        * @return                                                      <code>True</code> if the user could log in successfully,\r
+        *                                                                      <code>False</code> either the username or the password was not correct.\r
+        * @throws Exception                            no <code>DataHandler</code> set\r
+        * @throws AlreadyBoundException        a <code>User</code> is already logged in\r
         */\r
        public boolean logIn(String userName, String password) throws Exception{\r
                if(dh == null) throw new Exception("No DataHandler set");\r
@@ -63,9 +63,9 @@ public class UserController {
        }\r
        \r
        /**\r
-        * Logs out the current user, throws exception if no user is logged in\r
+        * Logs out the current logged user\r
         * \r
-        * @throws Exception eighter no datahandler is set or no user is logged in\r
+        * @throws Exception either no <code>DataHandler</code> is set or no user is logged in\r
         */\r
        public void logOut() throws Exception{\r
                if(dh == null) throw new Exception("No DataHandler set");\r
@@ -76,12 +76,12 @@ public class UserController {
        /**\r
         * Registers a new user to the current DataHandler\r
         * \r
-        * @param userName              Username\r
-        * @param password              Plaintext password\r
-        * @param email                 E-Mail address\r
-        * @param name                  Name\r
-        * @param lastname              Lastname\r
-        * @throws Exception    eighter no datahandler is set or user could not be added to the userlist\r
+        * @param userName              unique user name\r
+        * @param password              plain-text password\r
+        * @param email                 e-mail address\r
+        * @param name                  name\r
+        * @param lastname              last name\r
+        * @throws Exception    no <code>DataHandler</code> set\r
         */\r
        public void addUser(String userName, String password, String email, String name, String lastname) throws Exception{\r
                if(dh == null) throw new Exception("No DataHandler set");\r
@@ -93,11 +93,11 @@ public class UserController {
        }\r
 \r
        /**\r
-        * @deprecated use getLoggedUser\r
-        * Gets the username of the current user, use getLoggedUser\r
+        * Gets the user name of the current user\r
         * \r
-        * @return      Username        unique username\r
-        * @throws      Exception       no datahandler is set\r
+        * @deprecated                  use <code>getLoggedUser().getUserName()</code>\r
+        * @return                              user name\r
+        * @throws      Exception       no <code>DataHandler</code> is set\r
         */\r
        @Deprecated \r
        public String getLoggedUserName() throws Exception{\r
@@ -106,9 +106,9 @@ public class UserController {
        }\r
 \r
        /**\r
-        * @deprecated use getLoggedUser\r
         * Gets the mail address of the current user\r
         * \r
+        * @deprecated use <code>getLoggedUser().getMail()</code>\r
         * @return      Mail address\r
         * @throws      Exception       no user is logged in\r
         */\r
@@ -119,9 +119,9 @@ public class UserController {
        }\r
 \r
        /**\r
-        * @deprecated use getLoggedUser\r
         * Gets the first name of the current user\r
         * \r
+        * @deprecated use <code>getLoggedUser().getName()</code>\r
         * @return      First name\r
         * @throws      Exception       no user is logged in\r
         */\r
@@ -132,9 +132,9 @@ public class UserController {
        }\r
 \r
        /**\r
-        * @deprecated use getLoggedUser\r
         * Gets the last name of the current user\r
         * \r
+        * @deprecated use <code>getLoggedUser().getLastName()</code>\r
         * @return      Last name\r
         * @throws      Exception       no user is logged in\r
         */\r
@@ -144,22 +144,35 @@ public class UserController {
                return currentUser.getLastname();\r
        }\r
        \r
+       /**\r
+        * Gets the current logged <code>User</code>\r
+        * \r
+        * @return      current <code>User</code>, or <code>null</code> if no <code>User</code> is logged in\r
+        */\r
        public User getLoggedUser(){\r
                if(currentUser == null) return null;\r
                return currentUser;\r
        }\r
        \r
+       /**\r
+        * Searches the set DataHandler for a specific <code>User</code>\r
+        * \r
+        * @param userName              <code>User</code>\r
+        * @return                              clone of <code>User</code>\r
+        * @throws Exception    No <code>DataHandler</code> is set\r
+        */\r
        public User getUser(String userName) throws Exception{\r
                if(dh == null) throw new Exception("No DataHandler set");\r
                return dh.findUser(userName).clone();\r
        }\r
        \r
        /**\r
-        * Returns all reservations overlapping the given dateRange in a List\r
+        * Returns all reservations overlapping the given dateRange in a <code>Map</code>\r
         * \r
-        * @param       dateRange\r
-        * @return      <code>Map</code> if list is empty, no overlapping reservation could be found\r
-        * @throws      Exception       no user is logged in\r
+        * @param       dateRange       time span\r
+        * @return                              <code>Key</code> reservation, \r
+        *                                              <code>Value</code> is editable\r
+        * @throws      Exception       no <code>User</code> is logged in or no <code>DataHandler</code> is set\r
         */\r
        public Map<Reservation, Boolean> getReservationsInDateRange(DateRange dateRange) throws Exception{\r
                if(dh == null) throw new Exception("No DataHandler set");\r
@@ -177,10 +190,10 @@ public class UserController {
        /**\r
         * Returns the reservation or null if no reservation was found\r
         * \r
-        * @param id universal unique idendifier\r
-        * @return      <code>Reservation</code> copy of reservation with given id\r
-        *                      <code>null</code> no reservation with this id found\r
-        * @throws Exception\r
+        * @param id                    reservation identifier\r
+        * @return                              <code>Reservation</code> copy of reservation with given id, \r
+        *                                              <code>null</code> no reservation with this id found\r
+        * @throws Exception    No DataHandler set or id null\r
         */\r
        public Reservation getReservation(UUID id) throws Exception{\r
                if(dh == null) throw new Exception("No DataHandler set");\r
@@ -190,11 +203,11 @@ public class UserController {
        }\r
        \r
        /**\r
-        * Returns the reservations of the given user, if null returns the reservations of the current logged in user\r
+        * Returns the reservations of the given user\r
         * \r
-        * @param user                          user you want the reservations of\r
-        * @return                                      List of reservations copies of a specific user\r
-        * @throws Exception            eighter no datahandler is set or no user is logged in while user param = null\r
+        * @param user                          Owner, if <code>null</code> returns the reservations of the current logged in user\r
+        * @return                                      <code>List</code> of reservation copies of the given owner\r
+        * @throws Exception            either no <code>DataHandler</code> is set or no user is logged in while user param = null\r
         */\r
        public Map<Reservation, Boolean> getUserReservations(User user) throws Exception{\r
                if(dh == null) throw new Exception("No DataHandler set");\r
@@ -213,13 +226,17 @@ public class UserController {
        }\r
        \r
        /**\r
-        * @param groupId               groupId of the searched reservations group, throws Exception if groupId is null\r
-        * @return      <code>List</code> reservation copies of a group\r
-        * @throws Exception    eighter no datahandler is set or groupId is null\r
+        * Returns <code>Map</code> of reservation group (recurring reservations)\r
+        * \r
+        * @param groupId                                       group identifier\r
+        * @return                                                      <code>Key</code> reservation, \r
+        *                                                                      <code>Value</code> is editable\r
+        * @throws IllegalArgumentException     groupId is null\r
+        * @throws Exception                            no <code>DataHandler</code> set\r
         */\r
        public Map<Reservation, Boolean> getReservationGroup(UUID groupId) throws Exception{\r
                if(dh == null) throw new Exception("No DataHandler set");\r
-               if(groupId == null) throw new Exception("groupId has to be defined");\r
+               if(groupId == null) throw new IllegalArgumentException("groupId has to be defined");\r
                \r
                // Could be swapped out to private method for better performance (just check currentUser once)\r
                // and easier code maintenance\r
@@ -229,22 +246,24 @@ public class UserController {
                }\r
                return returnSet;\r
        }\r
-       \r
 \r
        /**\r
-        * @param user\r
-        * @param resource\r
-        * @param dateRangeList\r
-        * @param remark\r
-        * @return\r
-        * @throws Exception\r
+        * Makes a reservation in the current set DataHandler\r
+        * \r
+        * @param user                                                  user owning the reservation\r
+        * @param resource                                              resource to reserve\r
+        * @param dateRangeList                                 <code>List</code> of DateRanges defining when the resource is occupied\r
+        * @param remark                                                public remark for the reservation\r
+        * @return                                                              <code>Set</code> of Reservations that overlap an already stored reservation (conflict), if not empty no reservation was saved\r
+        * @throws IllegalArgumentException             <code>resource</code> or <code>dateRangeList</code> is null, or <code>dateRangeList</code> is empty\r
+        * @throws Exception                                    thrown by <code>DataHandler</code>\r
         */\r
        public Set<Reservation> makeReservation(User user, Resource resource, List<DateRange> dateRangeList, String remark) throws Exception\r
        {\r
                if(user == null) user = currentUser;\r
-               if(resource == null) throw new Exception("Resource must be definded");\r
-               if(dateRangeList == null) throw new Exception("dateRangeList can not be null");\r
-               if(dateRangeList.isEmpty()) throw new Exception("dateRangeList empty");\r
+               if(resource == null) throw new IllegalArgumentException("Resource must be definded");\r
+               if(dateRangeList == null) throw new IllegalArgumentException("dateRangeList can not be null");\r
+               if(dateRangeList.isEmpty()) throw new IllegalArgumentException("dateRangeList empty");\r
                \r
                Set<Reservation> invalidReservations = new HashSet<Reservation>();\r
                UUID groupId = UUID.randomUUID();\r
@@ -260,6 +279,15 @@ public class UserController {
                else return invalidReservations;\r
        }\r
        \r
+       /**\r
+        * Replaces the given reservation in the set DataHandler referring to the reservationid\r
+        * \r
+        * @param reservation                           Copy of the reservation to edit\r
+        * @return                                                      <code>True</code> Changes saved, \r
+        *                                                                      <code>False</code> Changes could not be saved\r
+        * @throws IllegalArgumentException     if reservation param is null\r
+        * @throws Exception                            if no <code>DataHandler</code> is set or the logged user is not authorized\r
+        */\r
        public boolean changeReservation(Reservation reservation) throws Exception\r
        {\r
                if(dh == null) throw new Exception("No DataHandler set");\r
@@ -269,6 +297,15 @@ public class UserController {
                return dh.editReservation(reservation);\r
        }\r
        \r
+       /**\r
+        * Deletes the given reservation in the set <code>DataHandler</code> referring to the reservation id\r
+        * \r
+        * @param reservation                           Copy of the reservation to edit\r
+        * @return                                                      <code>True</code> Changes saved\r
+        *                                                                      <code>False</code> Changes could not be saved\r
+        * @throws IllegalArgumentException     if reservation is null\r
+        * @throws Exception                            if no <code>DataHandler</code> is set, no <code>User</code> is logged in or logged <code>User</code> is not authorized\r
+        */\r
        public boolean deleteReservation(Reservation reservation) throws Exception\r
        {\r
                if(dh == null) throw new Exception("No DataHandler set");\r
@@ -278,6 +315,13 @@ public class UserController {
                return dh.deleteReservation(reservation);\r
        }\r
        \r
+       \r
+       /**\r
+        * Returns all stored resources of the set DataHandler\r
+        * \r
+        * @return                              <code>List</code> of resources\r
+        * @throws Exception    no <code>DataHandler</code> is set\r
+        */\r
        public List<Resource> getResources() throws Exception{\r
                if(dh == null) throw new Exception("No DataHandler set");\r
                List<Resource> resourceList = new ArrayList<Resource>();\r