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();
}