001/*
002        $Id: Permission.java 3207 2009-04-09 06:48:11Z gregory $
003
004        Copyright (C) 2006 Gregory Vincic, Olle Mansson
005        Copyright (C) 2007 Gregory Vincic
006
007        This file is part of Proteios.
008        Available at http://www.proteios.org/
009
010        Proteios is free software; you can redistribute it and/or modify it
011        under the terms of the GNU General Public License as published by
012        the Free Software Foundation; either version 2 of the License, or
013        (at your option) any later version.
014
015        Proteios is distributed in the hope that it will be useful, but
016        WITHOUT ANY WARRANTY; without even the implied warranty of
017        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
018        General Public License for more details.
019
020        You should have received a copy of the GNU General Public License
021        along with this program; if not, write to the Free Software
022        Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
023        02111-1307, USA.
024*/
025
026package org.proteios.core;
027
028import java.util.EnumSet;
029import java.util.Set;
030/**
031        This enumeration defined constants for permissions.
032        
033        @base.internal
034        Permissions are stored in the database as integers, which means that
035        a given set of permissions must be combined before they are saved.
036        We use the <code>grantValue</code> for this. This value is constructed
037        in such a way that some permissions implicitly activates other permissions
038        as follows:
039        <ul>
040        <li>READ -> 
041        <li>USE -> READ
042        <li>RESTRICTED_WRITE -> USE and READ
043        <li>WRITE -> RESTRICTED_WRITE, USE and READ
044        <li>DELETE -> WRITE, RESTRICTED_WRITE, USE and READ
045        <li>SET_OWNER -> WRITE, RESTRICTED_WRITE, USE and READ
046        <li>SET_PERMISSION -> WRITE, RESTRICTED_WRITE, USE and READ
047        </ul>
048        
049        The <code>denyValue</code> is only used by the {@link BasicItem#initPermissions(int, int)}
050        method when a subclass needs to deny a permission. This value is constructed 
051        in a similiar way:
052        <ul>
053        <li>READ -> USE, RESTRICTED_WRITE, WRITE, DELETE, SET_OWNER and SET_PERMISSION
054        <li>USE -> RESTRICTED_WRITE, WRITE, DELETE, SET_OWNER and SET_PERMISSION
055        <li>RESTRICTED_WRITE -> WRITE, DELETE, SET_OWNER and SET_PERMISSION
056        <li>WRITE -> DELETE, SET_OWNER and SET_PERMISSION
057        <li>DELETE -> 
058        <li>SET_OWNER -> 
059        <li>SET_PERMISSION -> 
060        </ul>
061
062        @author Nicklas
063        @version 2.0
064        @base.modified $Date: 2009-04-09 08:48:11 +0200 (Thu, 09 Apr 2009) $
065*/
066public enum Permission
067{
068        /**
069                This permission allows a user read information about an item.
070        */
071        READ(1, 1+2+4+8+16+32, "read"),
072        
073        /**
074                This permission allows a user to use/link to an item.
075        */
076        USE(1+2, 2+4+8+16+32, "use"),
077        
078        /**
079                This permission allows a user to update some information about an item.
080        */
081        RESTRICTED_WRITE(1+2+4, 4+8+16+32+64, "restricted write"),
082
083        /**
084                This permission allows a user update the information about an item.
085        */
086        WRITE(1+2+4+8, 8+16+32+64, "write"),
087        
088        /**
089                This permission allows a user delete an item.
090        */
091        DELETE(1+2+4+8+16, 16, "delete"),
092        
093        /**
094                This permission allows a user change the owner of an item.
095        */
096        SET_OWNER(1+2+4+8+32, 32, "change owner"),
097        
098        /**
099                This permission allows a user change the access permission to an item.
100        */
101        SET_PERMISSION(1+2+4+8+64, 64, "set permissions"),
102        
103        /**
104                This permission allows a user create new items.
105        */
106        CREATE(128, 128, "create"),
107        
108        /**
109                This permission denies a user access to an item. This permission can only be given
110                to {@link RoleKey}:s.
111        */
112        DENIED(256, 256, "denied"),
113        
114        /**
115                This permission allows a user to share an item to the {@link Group#EVERYONE}
116                group. This is a system permission and is only meaningful for the role key
117                for the {@link Item#SYSTEM} item.
118        */
119        SHARE_TO_EVERYONE(512, 512, "share to everyone"),
120
121        /**
122                This permission allows a user act as another user using the {@link
123                SessionControl#impersonateLogin(int, String)} method. This is a system 
124                permission and is only meaningful for the role key for the {@link Item#SYSTEM} 
125                item.
126        */
127        ACT_AS_ANOTHER_USER(1024, 1024, "act as another user");
128
129        private final int grantValue;
130        private final int denyValue;
131        private final String displayValue;
132        
133        /**
134                Constructor for Permission enums.
135        */
136        private Permission(int grantValue, int denyValue, String displayValue)
137        {
138                this.grantValue = grantValue;
139                this.denyValue = denyValue;
140                this.displayValue = displayValue;
141        }
142        private int grantValue()
143        {
144                return grantValue;
145        }
146        private int denyValue()
147        {
148                return denyValue;
149        }
150
151        @Override
152        public String toString()
153        {
154                return displayValue;
155        }
156
157        /**
158                Checks if the given <code>Permission</code> is granted by the 
159                <code>permissions</code> code.
160                @param permissions The permission combination
161                @param permission The permission to check
162        */
163        static boolean hasPermission(int permissions, Permission permission)
164        {
165                return (permissions & permission.grantValue()) == permission.grantValue();
166        }
167        
168        /**
169                Convert the given permission to the integer grant value.
170        */
171        static int grant(Permission permission)
172        {
173                return permission.grantValue();
174        }
175        
176        /**
177                Combine the given permissions and convert to the integer grant value.
178        */
179        static int grant(Permission... permissions)
180        {
181                int result = 0;
182                for (Permission p : permissions)
183                {
184                        result |= p.grantValue();
185                }
186                return result;
187        }
188
189        /**
190                Combine the given permission and convert to the integer grant value.
191        */
192        static int grant(Set<Permission> permissions)
193        {
194                int result = 0;
195                if (permissions != null)
196                {
197                        for (Permission p : permissions)
198                        {
199                                result |= p.grantValue();
200                        }
201                }
202                return result;
203        }
204        
205        /**
206                Convert the given permission to the integer deny value.
207        */
208        static int deny(Permission permission)
209        {
210                return permission.denyValue();
211        }
212
213        /**
214                Combine the given permissions and convert to the integer deny value.
215        */
216        static int deny(Permission... permissions)
217        {
218                int result = 0;
219                for (Permission p : permissions)
220                {
221                        result |= p.denyValue();
222                }
223                return result;
224        }
225
226        /**
227                Combine the given permission and convert to the integer deny value.
228        */
229        static int deny(Set<Permission> permissions)
230        {
231                int result = 0;
232                if (permissions != null)
233                {
234                        for (Permission p : permissions)
235                        {
236                                result |= p.denyValue();
237                        }
238                }
239                return result;
240        }
241
242        /**
243                Convert an integer value to a set of permissions.
244        */
245        static Set<Permission> fromInt(int permissions)
246        {
247                EnumSet<Permission> result = EnumSet.noneOf(Permission.class);
248                for (Permission p : Permission.values())
249                {
250                        if (hasPermission(permissions, p))
251                        {
252                                result.add(p);
253                        }
254                }
255                return result;
256        }
257
258}
259