001    package users;
002    
003    import java.util.Locale;
004    import java.util.ResourceBundle;
005    
006    /**
007     * Convenience class implementing basic capability behavior.
008     *
009     * <p>For convenience you can derive all your capability classes from
010     * <code>AbstractCapability</code>, which will manage names and display names.</p>
011     *
012     * @author Steffen Zschaler
013     * @version 2.0 05/05/1999
014     * @since v2.0
015     */
016    public abstract class AbstractCapability implements Capability {
017    
018        /**
019         * The name of the capability.
020         *
021         * <p><strong>IMMUTABLE</strong></p>
022         *
023         * @serial
024         */
025        private final String m_sName;
026    
027        /**
028         * Create a new capability with a given name.
029         *
030         * @param sName the name of the capability.
031         */
032        public AbstractCapability(String sName) {
033            super();
034    
035            m_sName = sName;
036        }
037    
038        // Capability interface methods
039    
040        /**
041         * Get the capability's name.
042         *
043         * @override Never
044         *
045         * @return the capability's name.
046         */
047        public String getName() {
048            return m_sName;
049        }
050    
051        /**
052         * Get the display name of this capability using the default locale.
053         *
054         * <p>This is identical to</p>
055         *
056         * <pre>
057         * &nbsp; getDisplayName (Locale.getDefault());
058         * </pre>
059         *
060         * @override Never
061         *
062         * @return the display name of this capability according to the default locale.
063         */
064        public String getDisplayName() {
065            return getDisplayName(Locale.getDefault());
066        }
067    
068        /**
069         * Get the display name of this capability according to a locale. You can set the base name of the resource
070         * bundle to be used by calling {@link #setDisplayNameResourceBundleName}.
071         *
072         * @override Never
073         *
074         * @param l the locale according to which to get the display name
075         *
076         * @return the display name according to the locale.
077         */
078        public String getDisplayName(Locale l) {
079            return getCapabilityDisplayName(getName(), l);
080        }
081    
082        /**
083         * Return the grant state of this capability. This method is <i>abstract</i>
084         * and you'll have to redefine it in subclasses.
085         *
086         * @override Always
087         *
088         * @return true if this capability grants rights.
089         */
090        public abstract boolean isGranted();
091    
092        /**
093         * Get the capability that is the inverse to this one. This method is abstract and
094         * you'll have to redefine it in subclasses.
095         *
096         * @override Always
097         *
098         * @return the capability that is the inverse to this one.
099         */
100        public abstract Capability getToggled();
101    
102        // general object methods
103    
104        /**
105         * Return a string representation of this capability.
106         *
107         * <p>The format of the returned string is:</p>
108         *
109         * <p><i>display name</i> &lt;<i>name</i>&gt;: <i>grant state</i></p>
110         *
111         * @override Sometimes
112         *
113         * @return a string representation of this capability.
114         */
115        public String toString() {
116            return getDisplayName() + " <" + getName() + ">: " + isGranted();
117        }
118    
119        /**
120         * The resource bundle that contains the display names for the capabilities. CACHE.
121         */
122        private static ResourceBundle s_rbDisplayNames = null;
123        /**
124         * The least recently used locale for looking up display names.
125         */
126        private static Locale s_lLRU = null;
127    
128        /**
129         * The base name for the resource bundles containing the capabilities' display names.
130         */
131        private static String s_sBaseName = null;
132    
133        /**
134         * Get a capabilities display name depending on a locale. This will lookup the capability's display name
135         * in the resource bundle specified through {@link #setDisplayNameResourceBundleName} and the locale.
136         * The key will be:
137         * <pre>capabilities.display_names.<i>sName</i></pre>
138         *
139         * @param sName the programmatical name of the capability
140         * @param l the locale that determines which resource bundle to use.
141         *
142         * @see java.util.ResourceBundle
143         */
144        private static final String getCapabilityDisplayName(String sName, Locale l) {
145            if (s_sBaseName != null) {
146                if (l != s_lLRU) {
147                    s_lLRU = l;
148    
149                    s_rbDisplayNames = ResourceBundle.getBundle(s_sBaseName, l);
150                }
151    
152                return s_rbDisplayNames.getString("capabilities.display_names." + sName);
153            }
154    
155            return sName;
156        }
157    
158        /**
159         * Set the base name for the resouce bundle that contains the capabilities' display names. The resource
160         * must contain a String for each Capability. The key for the String must be:
161         *
162         *  <code>capabilities.display_names.<i>capability_name</i></code>
163         */
164        public static final void setDisplayNameResourceBundleName(String sBaseName) {
165            s_sBaseName = sBaseName;
166            s_lLRU = null;
167        }
168    }