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    }