Provide APIs to manipulate users and groups

Description

Users

Since 12.2RC1 Concepts:

• This API is independent from where the users are stored (in wiki pages, etc). This allows plugging other implementations to store the users elsewhere than in wiki pages (the default).
• This API supports properties for the Guest and SuperAdmin user (i.e. even though these users do not have wiki pages for them, they still have properties, which are currently pre-defined and immutable).
• A user is pointed to with a UserReference. There are 3 special user references:
  • SuperAdminUserReference#INSTANCE: points to the SuperAdmin user
  • GuestUserReference#INSTANCE: points to the Guest user (i.e. not logged-in user)
  • CurrentUserReference#INSTANCE: special reference pointing to the current user
• The User class represents a User and provides different methods (typed and untyped) to access the various configuration options for the user.
  • Example of typed API: User#showHiddenDocuments()
  • Example of untyped API: User#getProperty('showHiddenDocuments')
• To get a User object, you use a UserResolver. For example from a Java component:
  @Inject
  private UserResolver<UserReference> userResolver;
  ...
  User currentUser = userResolver.resolve(CurrentUserReference.INSTANCE);
• To test if a User is the SuperAdmin user, you'll write:
  ...
  User user = userResolver.resolve(...);
  if (SuperAdminUserReference.INSTANCE == user.getUserReference()) {
     ...
  }
• UserManager: Component to perform CUD operations (the R from CRUD is done with the UserResolver). Right now, only offers an exist() method, as in:
  @Inject
  private UserManager userManager;
  ...
  userManager.exists(CurrentUserReference.INSTANCE);

Full API in the javadoc.

Configuration

The UserConfiguration component provides a way to access the User module's configuration from Java.

It's possible to configure the default preferences for the Super Admin and Guest users. This is done through the xwiki.properties configuration file:

History

There are various APIs in XWiki for retrieving user properties. A lot of them are historical and old and shouldn't be used. Here are all possibilities:

1. Direct XWiki.XWikiUsers XObject access: This is totally not recommended and you shouldn't do that. Use this API instead.
2. XWiki#getUserPreference(): Gets a user property and if it doesn't exist fallback to looking in the current space's WebPreferences and if it doesn't exist, fallback to looking in the current wiki's XWikiPreferences. It has been retrofitted to call this User API and is thus safe to use. However if all you need is to get a user's properties use this User API instead.
3. com.xpn.xwiki.user.api.XWikiUser & XWikiContext#getXWikiUser(): Old API, based on users stored in wiki pages and part of oldcore. Shouldn't be used.
4. user ConfigurationSource: Low-level and untyped API for getting user properties. It's recommended to not use it because 1) it's not typed and 2) it only supports users stored in wiki documents (except for SuperAdmin and Guest users).
5. User: This new API described on this page: This is the recommended API to use!

Bridge

The following explanations can help you bride from old APIs to the new API.

• If you need to convert an old XWikiUser to a new User object you can do it like this:
  @Inject
  private UserResolver<XWikiUser> userResolver;
  ...
  XWikiUser oldXWikiUser = ...
  User user = userResolver.resolve(oldXWikiUser);
• If you need to get a UserReference from a DocumentReference you'll need a UserReferenceResolver. For example:
  @Inject
  private UserReferenceResolver<DocumentReference> userReferenceResolver;
  ...
  DocumentReference documentReference = ...
  UserReference reference = userReferenceResolver.resolve(documentReference);
• If you need to get a UserReference from a user represented as String, you can write:

  Example 1:

  @Inject
  private UserReferenceResolver<String> userReferenceResolver;
  ...
  UserReference reference = userReferenceResolver.resolve("XWiki.superadmin");

  Example 2: user reference without the space

  @Inject
  private UserReferenceResolver<String> userReferenceResolver;
  ...
  UserReference reference = userReferenceResolver.resolve("superadmin");

  Example 3: User in a specific wiki

  @Inject
  private UserReferenceResolver<String> userReferenceResolver;
  ...
  UserReference reference = userReferenceResolver.resolve("SomeUser", new WikiReference("somewiki"));
  // OR
  UserReference reference = userReferenceResolver.resolve("somewiki:XWiki.SomeUser");

Groups

The org.xwiki.user.group.GroupManager component allows getting information about the groups and their members.

Everything you request trough this component is cached for fast access.

Member's groups

Group's members