Groups (Apache Hadoop Common 3.5.0 API)
Description: declaration: package: org.apache.hadoop.security, class: Groups

Package org.apache.hadoop.security

# Class Groups

java.lang.Object
org.apache.hadoop.security.Groups

@LimitedPrivate({"HDFS","MapReduce"}) @Evolving public class Groups extends Object
A user-to-groups mapping service. `Groups` allows for server to get the various group memberships of a given user via the `getGroups(String)` call, thus ensuring a consistent user-to-groups mapping and protects against vagaries of different mappings on servers and clients in a Hadoop cluster.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Groups(Configuration conf)`
  `Groups(Configuration conf, Timer timer)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `cacheGroupsAdd(List<String> groups)`
  Add groups to cache
  `long`
  `getBackgroundRefreshException()`
  `long`
  `getBackgroundRefreshQueued()`
  `long`
  `getBackgroundRefreshRunning()`
  `long`
  `getBackgroundRefreshSuccess()`
  `List<String>`
  `getGroups(String user)`
  Deprecated.
  Use `getGroupsSet(String user)` instead.
  `Set<String>`
  `getGroupsSet(String user)`
  Get the group memberships of a given user.
  `static Groups`
  `getUserToGroupsMappingService()`
  Get the groups being used to map user-to-groups.
  `static Groups`
  `getUserToGroupsMappingService(Configuration conf)`
  Get the groups being used to map user-to-groups.
  `static Groups`
  `getUserToGroupsMappingServiceWithLoadedConfiguration(Configuration conf)`
  Create new groups used to map user-to-groups with loaded configuration.
  `void`
  `refresh()`
  Refresh all user-to-groups mappings.
  `static void`
  `reset()`

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### Groups

    public Groups(Configuration conf)

  - ### Groups

    public Groups(Configuration conf, Timer timer)

- ## Method Details

  - ### getGroups

    @Deprecated public List<String> getGroups(String user) throws IOException
    Deprecated.
    Use `getGroupsSet(String user)` instead.
    Get the group memberships of a given user. If the user's group is not cached, this method may block. Note this method can be expensive as it involves Set -> List conversion. For user with large group membership (i.e., > 1000 groups), we recommend using getGroupSet to avoid the conversion and fast membership look up via contains().
    Parameters:
      `user` - User's name
    Returns:
      the group memberships of the user as list
    Throws:
      `IOException` - if user does not exist

  - ### getGroupsSet

    public Set<String> getGroupsSet(String user) throws IOException
    Get the group memberships of a given user. If the user's group is not cached, this method may block. This provide better performance when user has large group membership via
    1) avoid set->list->set conversion for the caller UGI/PermissionCheck
    2) fast lookup using contains() via Set instead of List
    Parameters:
      `user` - User's name
    Returns:
      the group memberships of the user as set
    Throws:
      `IOException` - if user does not exist

  - ### getBackgroundRefreshSuccess

    public long getBackgroundRefreshSuccess()

  - ### getBackgroundRefreshException

    public long getBackgroundRefreshException()

  - ### getBackgroundRefreshQueued

    public long getBackgroundRefreshQueued()

  - ### getBackgroundRefreshRunning

    public long getBackgroundRefreshRunning()

  - ### refresh

    public void refresh()
    Refresh all user-to-groups mappings.

  - ### cacheGroupsAdd

    public void cacheGroupsAdd(List<String> groups)
    Add groups to cache
    Parameters:
      `groups` - list of groups to add to cache

  - ### getUserToGroupsMappingService

    public static Groups getUserToGroupsMappingService()
    Get the groups being used to map user-to-groups.
    Returns:
      the groups being used to map user-to-groups.

  - ### getUserToGroupsMappingService

    public static Groups getUserToGroupsMappingService(Configuration conf)
    Get the groups being used to map user-to-groups.
    Parameters:
      `conf` - configuration.
    Returns:
      the groups being used to map user-to-groups.

  - ### getUserToGroupsMappingServiceWithLoadedConfiguration

    @Private public static Groups getUserToGroupsMappingServiceWithLoadedConfiguration(Configuration conf)
    Create new groups used to map user-to-groups with loaded configuration.
    Parameters:
      `conf` - configuration.
    Returns:
      the groups being used to map user-to-groups.

  - ### reset

    @VisibleForTesting public static void reset()