Package org.apache.hadoop.security

Class Groups

java.lang.Object

org.apache.hadoop.security.Groups

@LimitedPrivate({"HDFS","MapReduce"})
@Evolving
public class Groups
extends java.lang.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(java.util.List<java.lang.String> groups)	Add groups to cache
long	getBackgroundRefreshException()
long	getBackgroundRefreshQueued()
long	getBackgroundRefreshRunning()
long	getBackgroundRefreshSuccess()
java.util.List<java.lang.String>	getGroups(java.lang.String user)	Deprecated. Use getGroupsSet(String user) instead.
java.util.Set<java.lang.String>	getGroupsSet(java.lang.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 Detail

Groups

public Groups(Configuration conf)

Groups

public Groups(Configuration conf,
              Timer timer)

Method Detail

getGroups

@Deprecated
public java.util.List<java.lang.String> getGroups(java.lang.String user)
                                           throws java.io.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:

java.io.IOException - if user does not exist

getGroupsSet

public java.util.Set<java.lang.String> getGroupsSet(java.lang.String user)
                                             throws java.io.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:

java.io.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(java.util.List<java.lang.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()