001 package users;
002
003 import java.io.Serializable;
004
005 import java.util.Locale;
006
007 /**
008 * Capabilities guard activities and restrict the users' options in an application.
009 *
010 * <p>A capability is an immutable object associated with a user, that either grants
011 * or denies the user a specific service. In an ideal object oriented world each service
012 * that is guarded by a specific capability will only be reachable via a method in
013 * the capability object. Different implementations (achieved via subclasses) would then
014 * either perform the service or take suitable measures to indicate denial.</p>
015 *
016 * <p>To achieve immutability it is vital that you do not offer any methods that allow
017 * for the state of the capability to be manipulated directly after the object has been
018 * created. Capabilities of different state shall only be achieved via the
019 * {@link #getToggled getToggled()} method.</p>
020 *
021 * <p>For convenience you may want to subclass {@link AbstractCapability} rather than implementing
022 * <code>Capability</code> directly, as that already takes care of the name management.</p>
023 *
024 * @see User
025 * @see UserManager
026 *
027 * @author Steffen Zschaler
028 * @version 2.0 05/05/1999
029 * @since v2.0
030 */
031 public interface Capability extends Serializable {
032
033 /**
034 * Get the name of this capability. This name will be used to programatically
035 * identify the capability. It must not change during the life of the capability
036 * object.
037 *
038 * @return the name of the capability
039 *
040 * @override Always
041 */
042 public String getName();
043
044 /**
045 * Get the display name for this capability according to the default locale.
046 *
047 * <p>The display name will be used when communicating with the user about the
048 * capability.</p>
049 *
050 * @return the display name according to the default locale.
051 *
052 * @override Always
053 */
054 public String getDisplayName();
055
056 /**
057 * Get the display name for this capability according to a locale.
058 *
059 * <p>The display name will be used when communicating with the user about the
060 * capability.</p>
061 *
062 * @param l the locale according to which the display name is to be returned.
063 *
064 * @return the display name according to a locale.
065 *
066 * @override Always
067 */
068 public String getDisplayName(Locale l);
069
070 /**
071 * Get information whether this capability grants or denies the right for the activity
072 * it guards.
073 *
074 * <p>This is only informational and should not be used to actually implement the
075 * service of guarding activities. Guarding should always be achieved by making the
076 * activity only available via methods of the Capability object.</p>
077 *
078 * @return true if this Capability grants rights.
079 *
080 * @override Always
081 */
082 public boolean isGranted();
083
084 /**
085 * Return a capability that is the inverse to this one. If this capability granted
086 * rights the returned one should deny them and vice-versa.
087 *
088 * <p>This is the only way to toggle the Grant State of a capability as they are immutable
089 * ojects. Immutability means in this case that you cannot simply say
090 * <code>capability.toggleGranted()</code> but have to create a new object to achieve
091 * the purpose. It may help to think of a capability as something like an opera ticket
092 * that is given to someone and must be explicitly demanded back to invalidate it.</p>
093 *
094 * @return the inverse to this capability.
095 *
096 * @override Always
097 */
098 public Capability getToggled();
099 }