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}