package users; import java.io.Serializable; import java.util.Locale; /** * Capabilities guard activities and restrict the users' options in an application. * * <p>A capability is an immutable object associated with a user, that either grants * or denies the user a specific service. In an ideal object oriented world each service * that is guarded by a specific capability will only be reachable via a method in * the capability object. Different implementations (achieved via subclasses) would then * either perform the service or take suitable measures to indicate denial.</p> * * <p>To achieve immutability it is vital that you do not offer any methods that allow * for the state of the capability to be manipulated directly after the object has been * created. Capabilities of different state shall only be achieved via the * {@link #getToggled getToggled()} method.</p> * * <p>For convenience you may want to subclass {@link AbstractCapability} rather than implementing * <code>Capability</code> directly, as that already takes care of the name management.</p> * * @see User * @see UserManager * * @author Steffen Zschaler * @version 2.0 05/05/1999 * @since v2.0 */ public interface Capability extends Serializable { /** * Get the name of this capability. This name will be used to programatically * identify the capability. It must not change during the life of the capability * object. * * @return the name of the capability * * @override Always */ public String getName(); /** * Get the display name for this capability according to the default locale. * * <p>The display name will be used when communicating with the user about the * capability.</p> * * @return the display name according to the default locale. * * @override Always */ public String getDisplayName(); /** * Get the display name for this capability according to a locale. * * <p>The display name will be used when communicating with the user about the * capability.</p> * * @param l the locale according to which the display name is to be returned. * * @return the display name according to a locale. * * @override Always */ public String getDisplayName (Locale l); /** * Get information whether this capability grants or denies the right for the activity * it guards. * * <p>This is only informational and should not be used to actually implement the * service of guarding activities. Guarding should always be achieved by making the * activity only available via methods of the Capability object.</p> * * @return true if this Capability grants rights. * * @override Always */ public boolean isGranted(); /** * Return a capability that is the inverse to this one. If this capability granted * rights the returned one should deny them and vice-versa. * * <p>This is the only way to toggle the Grant State of a capability as they are immutable * ojects. Immutability means in this case that you cannot simply say * <code>capability.toggleGranted()</code> but have to create a new object to achieve * the purpose. It may help to think of a capability as something like an opera ticket * that is given to someone and must be explicitly demanded back to invalidate it.</p> * * @return the inverse to this capability. * * @override Always */ public Capability getToggled(); }