SecurityConstraint (Apache Tomcat 11.0.24 API Documentation)
Description: declaration: package: org.apache.tomcat.util.descriptor.web, class: SecurityConstraint

# Class SecurityConstraint

java.lang.Object
org.apache.tomcat.util.descriptor.web.XmlEncodingBase
org.apache.tomcat.util.descriptor.web.SecurityConstraint

All Implemented Interfaces:
  `Serializable`

public class SecurityConstraint extends XmlEncodingBase implements Serializable
Representation of a security constraint element for a web application, as represented in a `<security-constraint>` element in the deployment descriptor.

WARNING: It is assumed that instances of this class will be created and modified only within the context of a single thread, before the instance is made visible to the remainder of the application. After that, only read access is expected. Therefore, none of the read and write access within this class is synchronized.

See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `ROLE_ALL_AUTHENTICATED_USERS`
  Wildcard value that represents all authenticated users.
  `static final String`
  `ROLE_ALL_ROLES`
  Wildcard value that represents all roles.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SecurityConstraint()`
  Construct a new security constraint instance with default values.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addAuthRole(String authRole)`
  Add an authorization role, which is a role name that will be permitted access to the resources protected by this security constraint.
  `void`
  `addCollection(SecurityCollection collection)`
  Add a new web resource collection to those protected by this security constraint.
  `static SecurityConstraint[]`
  `createConstraints(ServletSecurityElement element, String urlPattern)`
  Convert a `ServletSecurityElement` to an array of `SecurityConstraint`(s).
  `boolean`
  `findAuthRole(String role)`
  Check a role.
  `String[]`
  `findAuthRoles()`
  Return the set of roles that are permitted access to the resources protected by this security constraint.
  `SecurityCollection`
  `findCollection(String name)`
  Return the web resource collection for the specified name, if any; otherwise, return `null`.
  `SecurityCollection[]`
  `findCollections()`
  Return all of the web resource collections protected by this security constraint.
  `static SecurityConstraint[]`
  `findUncoveredHttpMethods(SecurityConstraint[] constraints, boolean denyUncoveredHttpMethods, Log log)`
  Find HTTP methods that are not covered by the given security constraints.
  `boolean`
  `getAllRoles()`
  Was the "all roles" wildcard included in this authentication constraint?
  `boolean`
  `getAuthConstraint()`
  Return the authorization constraint present flag for this security constraint.
  `boolean`
  `getAuthenticatedUsers()`
  Was the "all authenticated users" wildcard included in this authentication constraint?
  `String`
  `getDisplayName()`
  Get the display name of this security constraint.
  `String`
  `getUserConstraint()`
  Return the user data constraint for this security constraint.
  `boolean`
  `included(String uri, String method)`
  Check if the constraint applies to a URI and method.
  `void`
  `removeAuthRole(String authRole)`
  Remove the specified role from the set of roles permitted to access the resources protected by this security constraint.
  `void`
  `removeCollection(SecurityCollection collection)`
  Remove the specified web resource collection from those protected by this security constraint.
  `void`
  `setAuthConstraint(boolean authConstraint)`
  Set the authorization constraint present flag for this security constraint.
  `void`
  `setCharset(Charset charset)`
  Set the character encoding of the XML source used to populate this object.
  `void`
  `setDisplayName(String displayName)`
  Set the display name of this security constraint.
  `void`
  `setUserConstraint(String userConstraint)`
  Set the user data constraint for this security constraint.
  `String`
  `toString()`
  Return a String representation of this security constraint.
  `void`
  `treatAllAuthenticatedUsersAsApplicationRole()`
  Called in the unlikely event that an application defines a role named "**".

  ### Methods inherited from class XmlEncodingBase

  `getCharset`

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### ROLE_ALL_ROLES

    public static final String ROLE_ALL_ROLES
    Wildcard value that represents all roles.
    See Also:
      - Constant Field Values

  - ### ROLE_ALL_AUTHENTICATED_USERS

    public static final String ROLE_ALL_AUTHENTICATED_USERS
    Wildcard value that represents all authenticated users.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### SecurityConstraint

    public SecurityConstraint()
    Construct a new security constraint instance with default values.

- ## Method Details

  - ### getAllRoles

    public boolean getAllRoles()
    Was the "all roles" wildcard included in this authentication constraint?
    Returns:
      `true` if all roles

  - ### getAuthenticatedUsers

    public boolean getAuthenticatedUsers()
    Was the "all authenticated users" wildcard included in this authentication constraint?
    Returns:
      `true` if all authenticated users

  - ### getAuthConstraint

    public boolean getAuthConstraint()
    Return the authorization constraint present flag for this security constraint.
    Returns:
      `true` if this needs authorization

  - ### setAuthConstraint

    public void setAuthConstraint(boolean authConstraint)
    Set the authorization constraint present flag for this security constraint.
    Parameters:
      `authConstraint` - The new value

  - ### getDisplayName

    public String getDisplayName()
    Get the display name of this security constraint.
    Returns:
      the display name of this security constraint

  - ### setDisplayName

    public void setDisplayName(String displayName)
    Set the display name of this security constraint.
    Parameters:
      `displayName` - The new value

  - ### getUserConstraint

    public String getUserConstraint()
    Return the user data constraint for this security constraint.
    Returns:
      the user constraint

  - ### setUserConstraint

    public void setUserConstraint(String userConstraint)
    Set the user data constraint for this security constraint.
    Parameters:
      `userConstraint` - The new user data constraint

  - ### treatAllAuthenticatedUsersAsApplicationRole

    public void treatAllAuthenticatedUsersAsApplicationRole()
    Called in the unlikely event that an application defines a role named "**".

  - ### addAuthRole

    public void addAuthRole(String authRole)
    Add an authorization role, which is a role name that will be permitted access to the resources protected by this security constraint.
    Parameters:
      `authRole` - Role name to be added

  - ### setCharset

    public void setCharset(Charset charset)
    Description copied from class: `XmlEncodingBase`
    Set the character encoding of the XML source used to populate this object.
    Overrides:
      `setCharset` in class `XmlEncodingBase`
    Parameters:
      `charset` - The character encoding

  - ### addCollection

    public void addCollection(SecurityCollection collection)
    Add a new web resource collection to those protected by this security constraint.
    Parameters:
      `collection` - The new web resource collection

  - ### findAuthRole

    public boolean findAuthRole(String role)
    Check a role.
    Parameters:
      `role` - Role name to be checked
    Returns:
      `true` if the specified role is permitted access to the resources protected by this security constraint.

  - ### findAuthRoles

    public String[] findAuthRoles()
    Return the set of roles that are permitted access to the resources protected by this security constraint. If none have been defined, a zero-length array is returned (which implies that all authenticated users are permitted access).
    Returns:
      the roles array

  - ### findCollection

    public SecurityCollection findCollection(String name)
    Return the web resource collection for the specified name, if any; otherwise, return `null`.
    Parameters:
      `name` - Web resource collection name to return
    Returns:
      the collection

  - ### findCollections

    public SecurityCollection[] findCollections()
    Return all of the web resource collections protected by this security constraint. If there are none, a zero-length array is returned.
    Returns:
      the collections array

  - ### included

    public boolean included(String uri, String method)
    Check if the constraint applies to a URI and method.
    Parameters:
      `uri` - Context-relative URI to check
      `method` - Request method being used
    Returns:
      `true` if the specified context-relative URI (and associated HTTP method) are protected by this security constraint.

  - ### removeAuthRole

    public void removeAuthRole(String authRole)
    Remove the specified role from the set of roles permitted to access the resources protected by this security constraint.
    Parameters:
      `authRole` - Role name to be removed

  - ### removeCollection

    public void removeCollection(SecurityCollection collection)
    Remove the specified web resource collection from those protected by this security constraint.
    Parameters:
      `collection` - Web resource collection to be removed

  - ### toString

    public String toString()
    Return a String representation of this security constraint.
    Overrides:
      `toString` in class `Object`

  - ### createConstraints

    public static SecurityConstraint[] createConstraints(ServletSecurityElement element, String urlPattern)
    Convert a `ServletSecurityElement` to an array of `SecurityConstraint`(s).
    Parameters:
      `element` - The element to be converted
      `urlPattern` - The url pattern that the element should be applied to
    Returns:
      The (possibly zero length) array of constraints that are the equivalent to the input

  - ### findUncoveredHttpMethods

    public static SecurityConstraint[] findUncoveredHttpMethods(SecurityConstraint[] constraints, boolean denyUncoveredHttpMethods, Log log)
    Find HTTP methods that are not covered by the given security constraints.
    Parameters:
      `constraints` - The existing security constraints
      `denyUncoveredHttpMethods` - Whether to automatically create constraints for uncovered methods
      `log` - The log to use for reporting uncovered methods
    Returns:
      New security constraints for uncovered methods, or an empty array if all methods are covered