001package com.randomnoun.common.security;
002
003/* (c) 2013 randomnoun. All Rights Reserved. This work is licensed under a
004 * BSD Simplified License. (http://www.randomnoun.com/bsd-simplified.html)
005 */
006
007import java.io.IOException;
008import java.util.*;
009
010import com.randomnoun.common.security.User;
011
012/** Security loader object.
013 *
014 * <p>An instance of this class is responsible for serialising/deserialising
015 * security information to a persistent data store. The SecurityContext object
016 * will invoke methods in this class as appropriate. Initialisation properties
017 * can be passed to the SecurityLoader using a properties map in the SecurityContext
018 * constructor.
019 *
020 * 
021 * @author knoxg
022 */
023public interface SecurityLoader
024{
025    /**
026     * Initialise this security loader. This method will be invoked by the SecurityContext
027     * object on initialisation
028     *
029     * @param properties Initialisation properties for this loader.
030     */
031    public void initialise(Map<String, Object> properties);
032
033
034    // the loadAll() methods here were for the security editor UI, which I imagine
035    // I'm not going to implement again in the next few years. Could just remove it.
036    
037    /**
038     * Return a structured list of application specific Permission objects which is used to 
039     * preload the SecurityContext rolePermission cache. Each permission returned must be a 
040     * role-based Permission.
041     */
042    public List<Permission> loadAllRolePermissions()
043        throws IOException;
044
045    /**
046     * Return List of Permission objects associated with a particular role
047     */    
048    public List<Permission> loadRolePermissions(String role) 
049     throws IOException;
050
051
052    /**
053     * Return a list of Permission objects 
054     * associated with the roles possessed by a particular user.
055     * 
056     * Equivalent to appending the results of calling 
057     * {@link #loadRolePermissions(String)} for each role that a user
058     * is in.  
059     */         
060    public List<Permission> loadUserRolePermissions(User user) throws IOException;
061    
062            
063    /**
064     * Returns the list of permissions assigned to this user.
065     */
066    public List<Permission> loadUserPermissions(User user) throws IOException;
067
068        /**
069         * Returns the list of roles assigned to this user.
070         */
071        public List<String> loadUserRoles(User user) throws IOException;
072
073
074        /** Load a user. Will not load any role or permission data for that user.
075         * 
076         * <p>Will probably throw an IOException if the user doesn't exist.
077         * 
078         * @return a User object.
079         */
080        public User loadUser(long userId) throws IOException;
081        
082    /**
083     * Return a list of User objects representing all users contained in this
084     * security context. Permission information relating to that user is not
085     * populated unless the 'populatePermission' parameter is set to true.
086     *
087     * <p>The information returned by this function may be cached, depending
088     * on the initialisation properties of the security context.
089     *
090     * @return A List of Users.
091     */
092    public List<User> loadAllUsers()
093        throws IOException;
094
095    /**
096     * Return a List of all resources in this security context, identified
097     * by String.
098     *
099     * <p>The information returned by this function may be cached, depending
100     * on the initialisation properties of the security context.
101     *
102     * @return A List of resources.
103     */
104    public List<String> loadAllResources()
105        throws IOException;
106
107    /**
108     * Return a List of all activities in this security context for a given
109     * resource, identified by String.
110     *
111     * <p>The information returned by this function may be cached, depending
112     * on the initialisation properties of the security context.
113     *
114     * @param resourceName The resource we wish to retrieve activities for
115     *
116     * @return A List of activities.
117     */
118    public List<String> loadAllActivities(String resourceName)
119        throws IOException;
120
121    /**
122     * Return a List of all roles in this security context, identified
123     * by String.
124     *
125     * <p>The information returned by this function may be cached, depending
126     * on the initialisation properties of the security context.
127     *
128     * @return A List of Roles, just the name.
129     */
130    public List<String> loadAllRoles()
131        throws IOException;
132
133        /**
134         * Return a List of all permissions in this security context, as Permission objects.
135         * (User, role and criteria fields will be left blank in these objects).
136         *
137         * <p>The information returned by this function may be cached, depending
138         * on the initialisation properties of the security context.
139         *
140         * @return A List of Permission objects available to this application
141         */
142        public List<Permission> loadAllPermissions()
143                throws IOException;
144
145
146
147    /**
148     * Return a List of all roles in this security context. Each role is returned
149     * as a Map containing (by default) the keys roleId, roleName, description
150     *
151     * @return A List of Roles, in Map format.
152     */
153    public List<Map<String, Object>> loadAllRoleDetails()
154        throws IOException;
155        
156    /**
157     * Return a List of all users in this security context. Each user is returned
158     * as a Map containing (by default) the keys userId, name
159     *
160     * @return A List of Users, in Map format.
161     */
162    public List<Map<String, Object>> loadAllUserDetails()
163        throws IOException;    
164
165        /** Informs any delegate security contexts to reset themselves. */
166        public void resetSecurityContext() throws IOException;
167        
168    /** Persists the role and permission information recorded for this user to
169     * the database. Existing role and permission information in the database will be
170     * removed.
171     *
172     * @param user The user to persist
173     * @param permissions The permissions for this user
174     */
175    public void saveUserRolesAndPermissions(User user, List<String> roles, List<Permission> userPermissions)
176        throws IOException;
177
178    /** Persists the permission information for this role to
179     * the database. Existing permission information in the database will be
180     * removed.
181     *
182     * @param user The role to persist
183     * @param permissions The permissions for this role
184     */
185    public void saveRolePermissions(String role, List<Permission> rolePermissions)
186        throws IOException;
187                  
188}