001package jmri; 002 003import java.util.Locale; 004 005/** 006 * A manager for permissions. 007 * 008 * @author Daniel Bergqvist (C) 2024 009 */ 010public interface PermissionManager { 011 012 /** 013 * Listener for when the JMRI user login and logout. 014 */ 015 interface LoginListener { 016 017 /** 018 * The JMRI user has either logged in or logged out. 019 * @param isLogin true if the user has logged in, false otherwise. 020 */ 021 void loginLogout(boolean isLogin); 022 } 023 024 /** 025 * Add a new role. 026 * @param name the name of the role 027 * @return the new role 028 * @throws RoleAlreadyExistsException if the role already exists 029 */ 030 Role addRole(String name) 031 throws RoleAlreadyExistsException; 032 033 /** 034 * Removes a role. 035 * @param name the name of the role 036 * @throws RoleDoesNotExistException if the role doesn't exist 037 */ 038 void removeRole(String name) 039 throws RoleDoesNotExistException; 040 041 /** 042 * Add a new user. 043 * @param username the username 044 * @param password the password 045 * @return the new user 046 * @throws UserAlreadyExistsException if the username already exists 047 */ 048 User addUser(String username, String password) 049 throws UserAlreadyExistsException; 050 051 /** 052 * Removes a role. 053 * @param username the username 054 * @throws UserDoesNotExistException if the user doesn't exist 055 */ 056 void removeUser(String username) 057 throws UserDoesNotExistException; 058 059 /** 060 * Change an user's password. 061 * @param newPassword the new password 062 * @param oldPassword the old password 063 */ 064 void changePassword(String newPassword, String oldPassword); 065 066 /** 067 * Login locally to JMRI. 068 * @param username the username 069 * @param password the password 070 * @return true if login was successful, false otherwise 071 */ 072 boolean login(String username, String password); 073 074 /** 075 * Login remotely to JMRI. 076 * This is for the web server, WiThrottle server, and other remote 077 * connections. 078 * @param sessionId the session ID. If empty string, a new session ID will 079 * be created. 080 * @param locale the locale to be used for messages. 081 * @param username the username 082 * @param password the password 083 * @return true if successful, false otherwise 084 */ 085 boolean remoteLogin(StringBuilder sessionId, Locale locale, String username, 086 String password); 087 088 /** 089 * Logout locally from JMRI. 090 */ 091 void logout(); 092 093 /** 094 * Logout remotely from JMRI. 095 * This is for the web server, WiThrottle server, and other remote 096 * connections. 097 * @param sessionId the session ID 098 */ 099 void remoteLogout(String sessionId); 100 101 /** 102 * Is an user logged in locally? 103 * @return true if any user except guest is logged in, false otherwise. 104 */ 105 boolean isLoggedIn(); 106 107 /** 108 * Is an user logged in locally? 109 * @param sessionId the session ID 110 * @return true if any user except guest is logged in to this session, 111 * false otherwise. 112 */ 113 boolean isRemotelyLoggedIn(String sessionId); 114 115 /** 116 * Is the user username the current user? 117 * @param username the username to check 118 * @return true if the current user is username, false otherwise. 119 */ 120 boolean isCurrentUser(String username); 121 122 /** 123 * Is the user 'user' the current user? 124 * @param user the user to check 125 * @return true if the current user is 'user', false otherwise. 126 */ 127 boolean isCurrentUser(User user); 128 129 /** 130 * Get the current username. 131 * @return the username of the user that's currently logged in or null if 132 * no user is logged in. 133 */ 134 String getCurrentUserName(); 135 136 /** 137 * Is the current user allowed to change his password? 138 * @return true if a user has logged in and that user is permitted to change 139 * his password, false otherwise 140 */ 141 boolean isCurrentUserPermittedToChangePassword(); 142 143 /** 144 * Is the user 'username' the guest user? 145 * @param username the username to check 146 * @return true if 'username' is the guest user 147 */ 148 boolean isAGuestUser(String username); 149 150 /** 151 * Is the user 'user' the guest user? 152 * @param user the user to check 153 * @return true if 'user' is the guest user 154 */ 155 boolean isAGuestUser(User user); 156 157 /** 158 * Add a login listener. 159 * @param listener the listener 160 */ 161 void addLoginListener(LoginListener listener); 162 163 /** 164 * Is the permission manager enabled? 165 * @return true if it's enabled, false otherwise. 166 */ 167 boolean isEnabled(); 168 169 /** 170 * Set if the permission manager should be enabled or not. 171 * @param enabled true if it should be enabled, false otherwise. 172 */ 173 void setEnabled(boolean enabled); 174 175 /** 176 * Get if empty passwords is allowed. 177 * @return true if empty passwords is allowed, false otherwise. 178 */ 179 boolean isAllowEmptyPasswords(); 180 181 /** 182 * Set if empty passwords should be allowed. 183 * @param value true if empty passwords should be allowed, false otherwise. 184 */ 185 void setAllowEmptyPasswords(boolean value); 186 187 /** 188 * Has the current user permission? 189 * @param permission the permission to check 190 * @param minValue the minimum value 191 * @return true if the user has the permission, false otherwise 192 */ 193 boolean hasAtLeastPermission(Permission permission, PermissionValue minValue); 194 195 /** 196 * Has the current user of this session permission? 197 * @param sessionId the session ID 198 * @param permission the permission to check 199 * @param minValue the minimum value 200 * @return true if the user has the permission, false otherwise 201 */ 202 boolean hasAtLeastRemotePermission(String sessionId, Permission permission, PermissionValue minValue); 203 204 /** 205 * Checks if the current user has the permission. 206 * If not, show a message dialog if not headless. Otherwise log a message. 207 * @param permission the permission to check 208 * @param minValue the minimum value 209 * @return true if the user has the permission, false otherwise 210 */ 211 boolean ensureAtLeastPermission(Permission permission, PermissionValue minValue); 212 213 /** 214 * Register a permission owner. 215 * @param owner the owner 216 */ 217 void registerOwner(PermissionOwner owner); 218 219 /** 220 * Register a permission. 221 * @param permission the permission 222 */ 223 void registerPermission(Permission permission); 224 225 /** 226 * Store permission settings. 227 */ 228 void storePermissionSettings(); 229 230 231 public static class RoleAlreadyExistsException extends JmriException { 232 public RoleAlreadyExistsException() { 233 super(Bundle.getMessage("PermissionManager_RoleAlreadyExistsException")); 234 } 235 } 236 237 public static class RoleDoesNotExistException extends JmriException { 238 public RoleDoesNotExistException() { 239 super(Bundle.getMessage("PermissionManager_RoleDoesNotExistException")); 240 } 241 } 242 243 public static class UserAlreadyExistsException extends JmriException { 244 public UserAlreadyExistsException() { 245 super(Bundle.getMessage("PermissionManager_UserAlreadyExistsException")); 246 } 247 } 248 249 public static class UserDoesNotExistException extends JmriException { 250 public UserDoesNotExistException() { 251 super(Bundle.getMessage("PermissionManager_UserDoesNotExistException")); 252 } 253 } 254 255 public static class BadUserOrPasswordException extends JmriException { 256 public BadUserOrPasswordException() { 257 super(Bundle.getMessage("PermissionManager_BadUserOrPasswordException")); 258 } 259 } 260 261 public static class BadPasswordException extends JmriException { 262 public BadPasswordException() { 263 super(Bundle.getMessage("PermissionManager_BadPasswordException")); 264 } 265 } 266 267}