001: /*
002: * File : $Source: /usr/local/cvs/opencms/src/org/opencms/security/CmsPrincipal.java,v $
003: * Date : $Date: 2008-02-27 12:05:29 $
004: * Version: $Revision: 1.6 $
005: *
006: * This library is part of OpenCms -
007: * the Open Source Content Management System
008: *
009: * Copyright (c) 2002 - 2008 Alkacon Software GmbH (http://www.alkacon.com)
010: *
011: * This library is free software; you can redistribute it and/or
012: * modify it under the terms of the GNU Lesser General Public
013: * License as published by the Free Software Foundation; either
014: * version 2.1 of the License, or (at your option) any later version.
015: *
016: * This library is distributed in the hope that it will be useful,
017: * but WITHOUT ANY WARRANTY; without even the implied warranty of
018: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
019: * Lesser General Public License for more details.
020: *
021: * For further information about Alkacon Software, please see the
022: * company website: http://www.alkacon.com
023: *
024: * For further information about OpenCms, please see the
025: * project website: http://www.opencms.org
026: *
027: * You should have received a copy of the GNU Lesser General Public
028: * License along with this library; if not, write to the Free Software
029: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
030: */
031:
032: package org.opencms.security;
033:
034: import org.opencms.db.CmsDbEntryNotFoundException;
035: import org.opencms.file.CmsGroup;
036: import org.opencms.file.CmsObject;
037: import org.opencms.file.CmsUser;
038: import org.opencms.main.CmsException;
039: import org.opencms.main.OpenCms;
040: import org.opencms.util.CmsStringUtil;
041: import org.opencms.util.CmsUUID;
042:
043: import java.util.Iterator;
044: import java.util.List;
045: import java.util.Locale;
046:
047: /**
048: * Common methods shared among user and group principals,
049: * also contains several utility functions to deal with principal instances.<p>
050: *
051: * @author Alexander Kandzior
052: *
053: * @version $Revision: 1.6 $
054: *
055: * @since 6.2.0
056: */
057: public abstract class CmsPrincipal implements I_CmsPrincipal,
058: Comparable {
059:
060: /** The description of this principal. */
061: protected String m_description;
062:
063: /** The flags of this principal. */
064: protected int m_flags;
065:
066: /** The unique id of this principal. */
067: protected CmsUUID m_id;
068:
069: /** The fully qualified name of this principal. */
070: protected String m_name;
071:
072: /**
073: * Empty constructor for subclassing.<p>
074: */
075: protected CmsPrincipal() {
076:
077: // empty constructor for subclassing
078: }
079:
080: /**
081: * Filters out all principals with flags greater than <code>{@link I_CmsPrincipal#FLAG_CORE_LIMIT}</code>.<p>
082: *
083: * The given parameter list is directly modified, so the returned list is the same object as the input list.<p>
084: *
085: * @param principals a list of <code>{@link CmsPrincipal}</code> objects
086: *
087: * @return the filtered principal list
088: */
089: public static List filterCore(List principals) {
090:
091: Iterator it = principals.iterator();
092: while (it.hasNext()) {
093: CmsPrincipal p = (CmsPrincipal) it.next();
094: if (p.getFlags() > I_CmsPrincipal.FLAG_CORE_LIMIT) {
095: it.remove();
096: }
097: }
098: return principals;
099: }
100:
101: /**
102: * Filters out all principals that do not have the given flag set,
103: * but leaving principals with flags less than <code>{@link I_CmsPrincipal#FLAG_CORE_LIMIT}</code> untouched.<p>
104: *
105: * The given parameter list is directly modified, so the returned list is the same object as the input list.<p>
106: *
107: * @param principals a list of <code>{@link CmsPrincipal}</code> objects
108: * @param flag the flag for filtering
109: *
110: * @return the filtered principal list
111: */
112: public static List filterCoreFlag(List principals, int flag) {
113:
114: Iterator it = principals.iterator();
115: while (it.hasNext()) {
116: CmsPrincipal p = (CmsPrincipal) it.next();
117: if ((p.getFlags() > I_CmsPrincipal.FLAG_CORE_LIMIT)
118: && ((p.getFlags() & flag) != flag)) {
119: it.remove();
120: }
121: }
122: return principals;
123: }
124:
125: /**
126: * Filters out all principals that do not have the given flag set.<p>
127: *
128: * The given parameter list is directly modified, so the returned list is the same object as the input list.<p>
129: *
130: * @param principals the list of <code>{@link CmsPrincipal}</code> objects
131: * @param flag the flag for filtering
132: *
133: * @return the filtered principal list
134: */
135: public static List filterFlag(List principals, int flag) {
136:
137: Iterator it = principals.iterator();
138: while (it.hasNext()) {
139: CmsPrincipal p = (CmsPrincipal) it.next();
140: if ((p.getFlags() & flag) != flag) {
141: it.remove();
142: }
143: }
144: return principals;
145: }
146:
147: /**
148: * Returns the provided group name prefixed with <code>{@link I_CmsPrincipal#PRINCIPAL_GROUP}.</code>.<p>
149: *
150: * @param name the name to add the prefix to
151: * @return the provided group name prefixed with <code>{@link I_CmsPrincipal#PRINCIPAL_GROUP}.</code>
152: */
153: public static String getPrefixedGroup(String name) {
154:
155: StringBuffer result = new StringBuffer(name.length() + 10);
156: result.append(I_CmsPrincipal.PRINCIPAL_GROUP);
157: result.append('.');
158: result.append(name);
159: return result.toString();
160: }
161:
162: /**
163: * Returns the provided user name prefixed with <code>{@link I_CmsPrincipal#PRINCIPAL_USER}.</code>.<p>
164: *
165: * @param name the name to add the prefix to
166: * @return the provided user name prefixed with <code>{@link I_CmsPrincipal#PRINCIPAL_USER}.</code>
167: */
168: public static String getPrefixedUser(String name) {
169:
170: StringBuffer result = new StringBuffer(name.length() + 10);
171: result.append(I_CmsPrincipal.PRINCIPAL_USER);
172: result.append('.');
173: result.append(name);
174: return result.toString();
175: }
176:
177: /**
178: * Utility function to read a prefixed principal from the OpenCms database using the
179: * provided OpenCms user context.<p>
180: *
181: * The principal must be either prefixed with <code>{@link I_CmsPrincipal#PRINCIPAL_GROUP}.</code> or
182: * <code>{@link I_CmsPrincipal#PRINCIPAL_USER}.</code>.<p>
183: *
184: * @param cms the OpenCms user context to use when reading the principal
185: * @param name the prefixed principal name
186: *
187: * @return the principal read from the OpenCms database
188: *
189: * @throws CmsException in case the principal could not be read
190: */
191: public static I_CmsPrincipal readPrefixedPrincipal(CmsObject cms,
192: String name) throws CmsException {
193:
194: if (CmsStringUtil.isNotEmpty(name)) {
195: String upperCaseName = name.toUpperCase();
196: if (upperCaseName
197: .startsWith(I_CmsPrincipal.PRINCIPAL_GROUP)) {
198: // this principal is a group
199: String groupName = name
200: .substring(I_CmsPrincipal.PRINCIPAL_GROUP
201: .length() + 1);
202: return cms.readGroup(groupName);
203: } else if (upperCaseName
204: .startsWith(I_CmsPrincipal.PRINCIPAL_USER)) {
205: // this principal is a user
206: String userName = name
207: .substring(I_CmsPrincipal.PRINCIPAL_USER
208: .length() + 1);
209: return cms.readUser(userName);
210: }
211: }
212: // invalid principal name was given
213: throw new CmsDbEntryNotFoundException(Messages.get().container(
214: Messages.ERR_INVALID_PRINCIPAL_1, name));
215: }
216:
217: /**
218: * Utility function to read a principal by its id from the OpenCms database using the
219: * provided OpenCms user context.<p>
220: *
221: * @param cms the OpenCms user context to use when reading the principal
222: * @param id the id of the principal to read
223: *
224: * @return the principal read from the OpenCms database
225: *
226: * @throws CmsException in case the principal could not be read
227: */
228: public static I_CmsPrincipal readPrincipal(CmsObject cms, CmsUUID id)
229: throws CmsException {
230:
231: try {
232: // first try to read the principal as a user
233: return cms.readUser(id);
234: } catch (CmsException exc) {
235: // assume user does not exist
236: }
237: try {
238: // now try to read the principal as a group
239: return cms.readGroup(id);
240: } catch (CmsException exc) {
241: // assume group does not exist
242: }
243: // invalid principal name was given
244: throw new CmsDbEntryNotFoundException(Messages.get().container(
245: Messages.ERR_INVALID_PRINCIPAL_1, id));
246: }
247:
248: /**
249: * Utility function to read a principal of the given type from the OpenCms database using the
250: * provided OpenCms user context.<p>
251: *
252: * The type must either be <code>{@link I_CmsPrincipal#PRINCIPAL_GROUP}</code> or
253: * <code>{@link I_CmsPrincipal#PRINCIPAL_USER}</code>.<p>
254: *
255: * @param cms the OpenCms user context to use when reading the principal
256: * @param type the principal type
257: * @param name the principal name
258: *
259: * @return the principal read from the OpenCms database
260: *
261: * @throws CmsException in case the principal could not be read
262: */
263: public static I_CmsPrincipal readPrincipal(CmsObject cms,
264: String type, String name) throws CmsException {
265:
266: if (CmsStringUtil.isNotEmpty(type)) {
267: String upperCaseType = type.toUpperCase();
268: if (PRINCIPAL_GROUP.equals(upperCaseType)) {
269: // this principal is a group
270: return cms.readGroup(name);
271: } else if (PRINCIPAL_USER.equals(upperCaseType)) {
272: // this principal is a user
273: return cms.readUser(name);
274: }
275: }
276: // invalid principal type was given
277: throw new CmsDbEntryNotFoundException(Messages.get().container(
278: Messages.ERR_INVALID_PRINCIPAL_TYPE_2, type, name));
279: }
280:
281: /**
282: * Utility function to read a principal by its id from the OpenCms database using the
283: * provided OpenCms user context.<p>
284: *
285: * @param cms the OpenCms user context to use when reading the principal
286: * @param id the id of the principal to read
287: *
288: * @return the principal read from the OpenCms database
289: *
290: * @throws CmsException in case the principal could not be read
291: */
292: public static I_CmsPrincipal readPrincipalIncludingHistory(
293: CmsObject cms, CmsUUID id) throws CmsException {
294:
295: try {
296: // first try to read the principal as a user
297: return cms.readUser(id);
298: } catch (CmsException exc) {
299: // assume user does not exist
300: }
301: try {
302: // now try to read the principal as a group
303: return cms.readGroup(id);
304: } catch (CmsException exc) {
305: // assume group does not exist
306: }
307: try {
308: // at the end try to read the principal from the history
309: return cms.readHistoryPrincipal(id);
310: } catch (CmsException exc) {
311: // assume the principal does not exist at all
312: }
313: // invalid principal name was given
314: throw new CmsDbEntryNotFoundException(Messages.get().container(
315: Messages.ERR_INVALID_PRINCIPAL_1, id));
316: }
317:
318: /**
319: * @see java.lang.Comparable#compareTo(java.lang.Object)
320: */
321: public int compareTo(Object obj) {
322:
323: if ((this == obj) || this .equals(obj)) {
324: return 0;
325: }
326: I_CmsPrincipal that = (I_CmsPrincipal) obj;
327: return this .getName().compareTo(that.getName());
328: }
329:
330: /**
331: * @see java.lang.Object#equals(java.lang.Object)
332: */
333: public boolean equals(Object obj) {
334:
335: if (obj == this ) {
336: return true;
337: }
338: if (obj instanceof I_CmsPrincipal) {
339: if (m_id != null) {
340: return m_id.equals(((I_CmsPrincipal) obj).getId());
341: }
342: }
343: return false;
344: }
345:
346: /**
347: * @see org.opencms.security.I_CmsPrincipal#getDescription()
348: */
349: public String getDescription() {
350:
351: return m_description;
352: }
353:
354: /**
355: * Returns the display name of this principal including the organizational unit.<p>
356: *
357: * @param cms the cms context
358: * @param locale the locale
359: *
360: * @return the display name of this principal including the organizational unit
361: *
362: * @throws CmsException if the organizational unit could not be read
363: */
364: public String getDisplayName(CmsObject cms, Locale locale)
365: throws CmsException {
366:
367: return Messages.get().getBundle(locale).key(
368: Messages.GUI_PRINCIPAL_DISPLAY_NAME_2,
369: getSimpleName(),
370: OpenCms.getOrgUnitManager().readOrganizationalUnit(cms,
371: getOuFqn()).getDisplayName(locale));
372: }
373:
374: /**
375: * @see org.opencms.security.I_CmsPrincipal#getFlags()
376: */
377: public int getFlags() {
378:
379: return m_flags;
380: }
381:
382: /**
383: * @see org.opencms.security.I_CmsPrincipal#getId()
384: */
385: public CmsUUID getId() {
386:
387: return m_id;
388: }
389:
390: /**
391: * Returns the fully qualified name of this principal.<p>
392: *
393: * @return the fully qualified name of this principal
394: *
395: * @see java.security.Principal#getName()
396: */
397: public String getName() {
398:
399: return m_name;
400: }
401:
402: /**
403: * Returns the fully qualified name of the associated organizational unit.<p>
404: *
405: * @return the fully qualified name of the associated organizational unit
406: */
407: public String getOuFqn() {
408:
409: return CmsOrganizationalUnit.getParentFqn(m_name);
410: }
411:
412: /**
413: * @see org.opencms.security.I_CmsPrincipal#getPrefixedName()
414: */
415: public String getPrefixedName() {
416:
417: if (isUser()) {
418: return getPrefixedUser(getName());
419: } else if (isGroup()) {
420: return getPrefixedGroup(getName());
421: }
422: return getName();
423: }
424:
425: /**
426: * Returns the simple name of this organizational unit.
427: *
428: * @return the simple name of this organizational unit.
429: */
430: public String getSimpleName() {
431:
432: return CmsOrganizationalUnit.getSimpleName(m_name);
433: }
434:
435: /**
436: * @see java.lang.Object#hashCode()
437: */
438: public int hashCode() {
439:
440: if (m_id != null) {
441: return m_id.hashCode();
442: }
443: return CmsUUID.getNullUUID().hashCode();
444: }
445:
446: /**
447: * @see org.opencms.security.I_CmsPrincipal#isEnabled()
448: */
449: public boolean isEnabled() {
450:
451: return (getFlags() & I_CmsPrincipal.FLAG_DISABLED) == 0;
452: }
453:
454: /**
455: * @see org.opencms.security.I_CmsPrincipal#isGroup()
456: */
457: public boolean isGroup() {
458:
459: return (this instanceof CmsGroup);
460: }
461:
462: /**
463: * @see org.opencms.security.I_CmsPrincipal#isUser()
464: */
465: public boolean isUser() {
466:
467: return (this instanceof CmsUser);
468: }
469:
470: /**
471: * @see org.opencms.security.I_CmsPrincipal#setDescription(java.lang.String)
472: */
473: public void setDescription(String description) {
474:
475: m_description = description;
476: }
477:
478: /**
479: * @see org.opencms.security.I_CmsPrincipal#setEnabled(boolean)
480: */
481: public void setEnabled(boolean enabled) {
482:
483: if (enabled != isEnabled()) {
484: // toggle disabled flag if required
485: setFlags(getFlags() ^ I_CmsPrincipal.FLAG_DISABLED);
486: }
487: }
488:
489: /**
490: * @see org.opencms.security.I_CmsPrincipal#setFlags(int)
491: */
492: public void setFlags(int value) {
493:
494: m_flags = value;
495: }
496:
497: /**
498: * @see org.opencms.security.I_CmsPrincipal#setName(java.lang.String)
499: */
500: public void setName(String name) {
501:
502: checkName(CmsOrganizationalUnit.getSimpleName(name));
503: m_name = name;
504: }
505: }
|