### *** This interface provides Binary Compatibility only, not Source Compatibility ***

Package com.sas.services.user

# Interface UserServiceInterface

All Superinterfaces:
  `com.sas.entities.EntityKeyInterface`, `Remote`, `RemoteServiceInterface`, `ServiceNotificationBroadcasterInterface`

All Known Implementing Classes:
  `UserService`

@SASScope("ALL") @BinaryCompatibilityOnly public interface UserServiceInterface extends RemoteServiceInterface
The UserServiceInterface provides mechanisms for storing information about users and retrieving user information. Methods are provided to store and retrieve user contexts, retrieve user profile information, retrieve credential sets, and create new user contexts.

- ## Field Summary

  ### Fields inherited from interface com.sas.services.RemoteServiceInterface

  `CLASS_IDENTIFIER, CLASS_IDENTIFIER_1_1, CLASS_IDENTIFIER_1_2, CLASS_IDENTIFIER_SERVICE_TYPE, CLASS_IDENTIFIER_SERVICE_TYPE_1_1, CLASS_IDENTIFIER_SERVICE_TYPE_1_2`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ProfileInterface`
  `createProfile(UserContextInterface privUser, UserContextInterface user, String application)`
  Create a new profile.
  `ProfileInterface`
  `createProfile(UserContextInterface user, String application)`
  Create a new profile.
  `UserContextInterface`
  `fromByteArray(byte[] data)`
  Create a UserContext from a byte array returned from the `UserContext.toByteArray()` method.
  `RemoteCallbackHandler`
  `getChallengeCallbackHandler()`
  Get the object that will handle credential challenge callbacks.
  `boolean`
  `getGroupLoginEnabled()`
  Get the flag indicating if group logins are allowed to be used to create User Contexts.
  `List`
  `getGroups(UserContextInterface user)`
  Get all the groups that a user belongs to.
  `ProfileInterface`
  `getProfile(PersonInterface person, String application)`
  Get the profile for a Person object.
  `ProfileDomain`
  `getProfileDefinition(String application)`
  Get the profile definition for an application.
  `SummaryData`
  `getSummaryData(boolean includeDetails)`
  Get the summary data regarding the active users.
  `UserContextInterface`
  `getUser(UserContextInterface privUser, String user)`
  Get a user from the user service.
  `UserContextInterface`
  `getUser(String user)`
  Get a user from the user service.
  `int`
  `getUserCount()`
  Get the count of users that are currently logged in.
  `ProfileInterface`
  `loadProfile(UserContextInterface searchContext, UserContextInterface user, String application)`
  Get the profile object for the user from the searchContext's connected repositories.
  `ProfileInterface`
  `loadProfile(UserContextInterface user, String application)`
  Get the profile object for the user from the user's connected repositories.
  `void`
  `loadUserCredentials(UserContextInterface user)`
  Get credential sets for a user.
  `void`
  `loadUserCredentials(UserContextInterface searchContext, UserContextInterface user)`
  Get credential sets for a user.
  `UserContextInterface`
  `newAuthenticatedUser(Subject subject)`
  Create a new UserContext based on the Subject provided.
  `UserContextInterface`
  `newRemoteUser(SubjectMatter subject)`
  Create a new UserContext using a SubjectMatter object that is populated with the PFS principals and credentials of an authenticated user.
  `UserContextInterface`
  `newRemoteUser(SubjectMatter subject, Map advancedOptions)`
  Create a new UserContext using a SubjectMatter object that is populated with the PFS principals and credentials of an authenticated user.
  `UserContextInterface`
  `newUser(UserContextInterface privUser, String uid, String password, String domain)`
  Create a new user context given a privileged context, user id, password, and authentication domain.
  `UserContextInterface`
  `newUser(UserContextInterface privUser, String uid, String password, String domain, String clientSource, String appSource)`
  Create a new user context given a privileged context, user id, password, and authentication domain.
  `UserContextInterface`
  `newUser(UserContextInterface privUser, String uid, String password, String domain, String clientSource, String appSource, Map advancedOptions)`
  Create a new user context given a privileged context, user id, password, and authentication domain.
  `UserContextInterface`
  `newUser(UserContext privUser, String uid, String password, String domain)`
  Deprecated.
  Use the version that takes a UserContextInterface
  `UserContextInterface`
  `newUser(UserContext privUser, String uid, String password, String domain, String clientSource, String appSource)`
  Deprecated.
  Use the version that takes a UserContextInterface.
  `UserContextInterface`
  `newUser(UserContext privUser, String uid, String password, String domain, String clientSource, String appSource, Map advancedOptions)`
  Deprecated.
  Use the version that takes a UserContextInterface.
  `UserContextInterface`
  `newUser(String clientSource, String appSource)`
  Create a new UserContext based on the current OS identity of the user.
  `UserContextInterface`
  `newUser(String uid, String password, String domain)`
  Create a new user context given a user id, password, and authentication domain.
  `UserContextInterface`
  `newUser(String uid, String password, String domain, String clientSource, String appSource)`
  Create a new user context given a user id, password, and authentication domain.
  `UserContextInterface`
  `newUser(String clientSource, String appSource, Map advancedOptions)`
  Create a new UserContext based on the current OS identity of the user.
  `UserIdentityInterface`
  `newUserIdentity(Object principal, Object credential, String domain, String mechanism)`
  Return a new user identity object given the Pricipal, credential, domain, and authentication mechanism.
  `UserContextInterface`
  `newUserWithInfoService(UserContext privUser, String uid, String password, String domain, InformationServiceInterface infoService)`
  Deprecated.
  This method should no longer be used.
  `boolean`
  `removeUser(UserContextInterface user)`
  Remove a user from the user service.
  `void`
  `resetInternalPassword(String host, String port, String username, String oldPassword, String newPassword)`
  Reset a user's internal metadata password.
  `void`
  `setChallengeCallbackHandler(RemoteCallbackHandler handler)`
  Set the object that will be used to handle credential challenge callbacks.
  `void`
  `setGroupLoginEnabled(boolean groupLoginFlag)`
  Set the UserService to allow group logins to be used to create User Contexts.
  `void`
  `setUser(UserContextInterface user)`
  Add a user to the user service.
  `void`
  `userDestroyed(UserContextInterface user)`
  For internal use only.

  ### Methods inherited from interface com.sas.entities.EntityKeyInterface

  `getEntityKey, sameEntity, setEntityKey`

  ### Methods inherited from interface com.sas.services.RemoteServiceInterface

  `configure, destroy, getCreationTime, getServiceConfiguration, getServiceConfiguration, getServiceProxy, getServiceState, isAccessibleToRemoteClients, isExported, reconfigure, setServiceState`

  ### Methods inherited from interface com.sas.services.mgmt.ServiceNotificationBroadcasterInterface

  `addServiceObserver, notifyServiceObservers, removeAllServiceObservers, removeServiceObserver`

- ## Method Details

  - ### setUser

    void setUser(UserContextInterface user) throws RemoteException
    Add a user to the user service. If a UserContext already exists with the same key, the new user will be added to a List of users with that key. Since this can make things confusing to try keep track of who's who, it is strongly recommended that applications set the key on the UserContext to some unique value before calling the setUser method.

    Parameters:
      `user` - A new user context to add to the service.
    Throws:
      `RemoteException` - in the event of remote object failure.

  - ### removeUser

    boolean removeUser(UserContextInterface user) throws RemoteException
    Remove a user from the user service.

    Parameters:
      `user` - The user to remove.
    Returns:
      true if the user was found and removed, false otherwise.
    Throws:
      `RemoteException` - in the event of remote object failure.

  - ### getUser

    UserContextInterface getUser(String user) throws RemoteException
    Get a user from the user service. This method is protected using JAAS permissions. A UserContextPermission is required to read a UserContext. UserContextPermission can be granted globally to specific UserContext names if they are known in advance to be publicly available.

    Parameters:
      `user` - The user to retrieve. The string may be the name or key. The name is checked first. If it's found, the user is returned. If not, the key is searched.
    Returns:
      The user context, or null if not found.
    Throws:
      `RemoteException` - in the event of remote object failure.

  - ### getUser

    UserContextInterface getUser(UserContextInterface privUser, String user) throws RemoteException
    Get a user from the user service. This method is protected using JAAS permissions. A UserContextPermission is required to read a UserContext. UserContextPermission can be granted globally to specific UserContext names if they are known in advance to be publicly available.

    Parameters:
      `privUser` - A UserContext whose principals will be checked for permission to perform the getUser function. This can be null, but if the method is invoked remotely, it will always fail with a null UserContext.
      `user` - The user to retrieve. The string may be the name or key. The name is checked first. If it's found, the user is returned. If not, the key is searched.
    Returns:
      The user context, or null if not found.
    Throws:
      `RemoteException` - in the event of remote object failure.

  - ### newUserIdentity

    UserIdentityInterface newUserIdentity(Object principal, Object credential, String domain, String mechanism) throws RemoteException, ServiceException
    Return a new user identity object given the Pricipal, credential, domain, and authentication mechanism.

    Parameters:
      `principal` - An object (usually a string) that represents the user within a security domain.
      `credential` - An object that is used to authenticate a principal. Depending on the mechanism, this may be a password string, or a complex object such as a certificate.
      `domain` - A String representing a security domain. While this string is arbitrary, it should be consistent within an installation so that credential sets match with services.
      `mechanism` - A String that indicates the authentication mechanism to use, e.g., "simple", "Kerberos", etc.
    Returns:
      A new user identity.
    Throws:
      `ServiceException` - in the event of service object failure;
      `RemoteException` - in the event of remote object failure.

  - ### getGroups

    List getGroups(UserContextInterface user) throws ServiceException, RemoteException
    Get all the groups that a user belongs to. Search all the repositories the UserContext has a handle to to find groups.

    Parameters:
      `user` - The UserContext to find groups for.
    Returns:
      A List of `IdentityGroupInterface` objects that represent the groups the user is a member of.
    Throws:
      `ServiceException` - in the event of service object failure.
      `RemoteException` - in the event of remote object failure.

  - ### getProfileDefinition

    ProfileDomain getProfileDefinition(String application) throws ServiceException, RemoteException
    Get the profile definition for an application.

    Parameters:
      `application` - The application to get the profile definition for.
    Returns:
      A ProfileDomain object for the application, or null if none is defined.
    Throws:
      `ServiceException` - In the event of a service failure.
      `RemoteException` - in the event of a network problem.

  - ### loadProfile

    ProfileInterface loadProfile(UserContextInterface user, String application) throws RemoteException, ServiceException
    Get the profile object for the user from the user's connected repositories. The initialization information should describe how to retrieve the information, and the user should have access to the required repository(s) before making this call.

    Parameters:
      `user` - The user to retrieve the profile for.
      `application` - The name of the application requesting profile information.
    Returns:
      User's profile obtained from the user's connected repositories.
    Throws:
      `ServiceException` - in the event of Platform Service failure.
      `RemoteException` - in the event of remote object failure.

  - ### loadProfile

    ProfileInterface loadProfile(UserContextInterface searchContext, UserContextInterface user, String application) throws RemoteException, ServiceException
    Get the profile object for the user from the searchContext's connected repositories. The initialization information should describe how to retrieve the information, and the user should have access to the required repository(s) before making this call. This method allows a client to use one context (possibly privileged) to search for profile information for another user.

    Parameters:
      `searchContext` - The UserContext to use to search for the profile information.
      `user` - The user to retrieve the profile for.
      `application` - The name of the application requesting profile information.
    Returns:
      User's profile obtained from the search context's connected repositories.
    Throws:
      `ServiceException` - in the event of Service failure.
      `RemoteException` - in the event of remote object failure.

  - ### createProfile

    ProfileInterface createProfile(UserContextInterface user, String application) throws ServiceException, RemoteException
    Create a new profile. This will create the new repository entry, and return the ProfileInterface to the user.

    Parameters:
      `user` - The UserContextInterface of the user for whom the Profile is being created.
      `application` - The application string for the new profile.
    Returns:
      The new ProfileInterface.
    Throws:
      `ServiceException` - in the event of a service failure.
      `RemoteException` - in the event of network failure.

  - ### createProfile

    ProfileInterface createProfile(UserContextInterface privUser, UserContextInterface user, String application) throws ServiceException, RemoteException
    Create a new profile. This will create the new repository entry, and return the ProfileInterface to the user.

    Parameters:
      `privUser` - A privileged user context to use to create the new profile entry in the repository.
      `user` - The UserContextInterface of the user for whom the Profile is being created.
      `application` - The application string for the new profile.
    Returns:
      The new ProfileInterface.
    Throws:
      `ServiceException` - in the event of a service failure.
      `RemoteException` - in the event of network failure.

  - ### loadUserCredentials

    void loadUserCredentials(UserContextInterface user) throws ServiceException, RemoteException
    Get credential sets for a user. The service performs a search for the credentials and creates appropriate identities and adds them to the user context.

    Parameters:
      `user` - The user context to use to search and update with identities.
    Throws:
      `ServiceException` - In the event of a repository failure.
      `RemoteException` - in the event of remote object failure.

  - ### getProfile

    ProfileInterface getProfile(PersonInterface person, String application) throws ServiceException, RemoteException
    Get the profile for a Person object. This method is intended for use when an application has a Person object representing a person that's not actively using the application, but may have profile data that affects a current user's interaction with them. A primary use is going to be getting the URL for the personal repository from the profile when publishing to a DAV subscriber.

    Parameters:
      `person` - The person to retrieve the profile for.
      `application` - The application whose profile you want.
    Returns:
      A profile object for the person and application requested, or null if it doesn't exist.
    Throws:
      `ServiceException` - In the event of a repository failure.
      `RemoteException` - in the event of a network error.

  - ### loadUserCredentials

    void loadUserCredentials(UserContextInterface searchContext, UserContextInterface user) throws ServiceException, RemoteException
    Get credential sets for a user. The service performs a search for the credentials and creates appropriate identities and adds them to the user context. This methood uses the searchContext to perform the search, and updates user with the identities found. Since credential information is so sensitive, normally, the user's context is used to search the repositories so access control can restrict access to credentials the user is allowed to read.

    Parameters:
      `searchContext` - The user context to use to perform the search. The repository connections in this context will be used for the search(s).
      `user` - The user context to update with any identities found in the repository(s).
    Throws:
      `ServiceException` - In the event of a repository failure.
      `RemoteException` - in the event of remote object failure.

  - ### newUser

    UserContextInterface newUser(String clientSource, String appSource) throws ServiceException, RemoteException, UserInitializationException
    Create a new UserContext based on the current OS identity of the user.
    Parameters:
      `clientSource` - A String (normally an IP address) that indicates the client location that initiated the login request.
      `appSource` - A String that identifies the application that is initiating the request. This should either be the main Java class name or an identifiable application name.
    Returns:
      An authenticated and initialized UserContext for the current user.
    Throws:
      `UserInitializationException` - in the event of possibly recoverable exceptions during UserContext initialization.
      `ServiceException` - if an unrecoverable exception occurs.
      `RemoteException` - in the event of a network error.

  - ### newUser

    UserContextInterface newUser(String clientSource, String appSource, Map advancedOptions) throws ServiceException, RemoteException, UserInitializationException
    Create a new UserContext based on the current OS identity of the user.
    Parameters:
      `clientSource` - A String (normally an IP address) that indicates the client location that initiated the login request.
      `appSource` - A String that identifies the application that is initiating the request. This should either be the main Java class name or an identifiable application name.
      `advancedOptions` - Map<String, Object> of advanced options.
    Returns:
      An authenticated and initialized UserContext for the current user.
    Throws:
      `UserInitializationException` - in the event of possibly recoverable exceptions during UserContext initialization.
      `ServiceException` - if an unrecoverable exception occurs.
      `RemoteException` - in the event of a network error.

  - ### newUser

    UserContextInterface newUser(String uid, String password, String domain) throws RemoteException, ServiceException, UserInitializationException
    Create a new user context given a user id, password, and authentication domain. This method will create the user context, a new user identity, and attempt to authenticate the user. If the identity fails to authenticate, a ServiceException will be thrown.

    Parameters:
      `uid` - The user ID for the new user
      `password` - The password for the new user.
      `domain` - The authentication domain for the user.
    Returns:
      A new UserContextInterface for the user.
    Throws:
      `UserInitializationException` - in the event of possibly recoverable exceptions during UserContext initialization.
      `ServiceException` - in the event of service failure.
      `RemoteException` - in the event of remote object failure.

  - ### newUser

    UserContextInterface newUser(String uid, String password, String domain, String clientSource, String appSource) throws RemoteException, ServiceException, UserInitializationException
    Create a new user context given a user id, password, and authentication domain. This method will create the user context, a new user identity, and attempt to authenticate the user. If the identity fails to authenticate, a ServiceException will be thrown.

    Parameters:
      `uid` - The user ID for the new user
      `password` - The password for the new user.
      `domain` - The authentication domain for the user.
      `clientSource` - A String (normally an IP address) that indicates the client location that initiated the login request.
      `appSource` - A String that identifies the application that is initiating the request. This should either be the main Java class name or an identifiable application name.
    Returns:
      A new UserContextInterface for the user.
    Throws:
      `UserInitializationException` - in the event of possibly recoverable exceptions during UserContext initialization.
      `ServiceException` - in the event of service failure.
      `RemoteException` - in the event of remote object failure.

  - ### newUser

    UserContextInterface newUser(UserContext privUser, String uid, String password, String domain) throws RemoteException, ServiceException, UserInitializationException
    Deprecated.
    Use the version that takes a UserContextInterface
    Create a new user context given a privileged context, user id, password, and authentication domain. This method will create the user context, a new user identity, and attempt to authenticate the user. If the identity fails to authenticate, a ServiceException will be thrown.

    Parameters:
      `privUser` - The user context to use to search for credentials that the user himself may not be allowed to see. This may be null in order to use the user's own authenticated connection to search for credentials.
      `uid` - The user ID for the new user
      `password` - The password for the new user.
      `domain` - The authentication domain for the user. A null domain will cause a ServiceException to be thrown.
    Returns:
      A new UserContextInterface for the user.
    Throws:
      `UserInitializationException` - in the event of possibly recoverable exceptions during UserContext initialization.
      `ServiceException` - if an unrecoverable exception occurs.
      `RemoteException` - in the event of a network error.

  - ### newUser

    UserContextInterface newUser(UserContextInterface privUser, String uid, String password, String domain) throws RemoteException, ServiceException, UserInitializationException
    Create a new user context given a privileged context, user id, password, and authentication domain. This method will create the user context, a new user identity, and attempt to authenticate the user. If the identity fails to authenticate, a ServiceException will be thrown.

    Parameters:
      `privUser` - The user context to use to search for credentials that the user himself may not be allowed to see. This may be null in order to use the user's own authenticated connection to search for credentials.
      `uid` - The user ID for the new user
      `password` - The password for the new user.
      `domain` - The authentication domain for the user. A null domain will cause a ServiceException to be thrown.
    Returns:
      A new UserContextInterface for the user.
    Throws:
      `UserInitializationException` - in the event of possibly recoverable exceptions during UserContext initialization.
      `ServiceException` - if an unrecoverable exception occurs.
      `RemoteException` - in the event of a network error.

  - ### newUser

    UserContextInterface newUser(UserContext privUser, String uid, String password, String domain, String clientSource, String appSource) throws RemoteException, ServiceException, UserInitializationException
    Deprecated.
    Use the version that takes a UserContextInterface.
    Create a new user context given a privileged context, user id, password, and authentication domain. This method will create the user context, a new user identity, and attempt to authenticate the user. If the identity fails to authenticate, a ServiceException will be thrown.

    Parameters:
      `privUser` - The user context to use to search for credentials that the user himself may not be allowed to see. This may be null in order to use the user's own authenticated connection to search for credentials.
      `uid` - The user ID for the new user
      `password` - The password for the new user.
      `domain` - The authentication domain for the user. A null domain will cause a ServiceException to be thrown.
      `clientSource` - A String (normally an IP address) that indicates the client location that initiated the login request.
      `appSource` - A String that identifies the application that is initiating the request. This should either be the main Java class name or an identifiable application name.
    Returns:
      A new UserContextInterface for the user.
    Throws:
      `UserInitializationException` - in the event of possibly recoverable exceptions during UserContext initialization.
      `ServiceException` - if an unrecoverable exception occurs.
      `RemoteException` - in the event of a network error.

  - ### newUser

    UserContextInterface newUser(UserContextInterface privUser, String uid, String password, String domain, String clientSource, String appSource) throws RemoteException, ServiceException, UserInitializationException
    Create a new user context given a privileged context, user id, password, and authentication domain. This method will create the user context, a new user identity, and attempt to authenticate the user. If the identity fails to authenticate, a ServiceException will be thrown.

    Parameters:
      `privUser` - The user context to use to search for credentials that the user himself may not be allowed to see. This may be null in order to use the user's own authenticated connection to search for credentials.
      `uid` - The user ID for the new user
      `password` - The password for the new user.
      `domain` - The authentication domain for the user. A null domain will cause a ServiceException to be thrown.
      `clientSource` - A String (normally an IP address) that indicates the client location that initiated the login request.
      `appSource` - A String that identifies the application that is initiating the request. This should either be the main Java class name or an identifiable application name.
    Returns:
      A new UserContextInterface for the user.
    Throws:
      `UserInitializationException` - in the event of possibly recoverable exceptions during UserContext initialization.
      `ServiceException` - if an unrecoverable exception occurs.
      `RemoteException` - in the event of a network error.

  - ### newUser

    UserContextInterface newUser(UserContext privUser, String uid, String password, String domain, String clientSource, String appSource, Map advancedOptions) throws RemoteException, ServiceException, UserInitializationException
    Deprecated.
    Use the version that takes a UserContextInterface.
    Create a new user context given a privileged context, user id, password, and authentication domain. This method will create the user context, a new user identity, and attempt to authenticate the user. If the identity fails to authenticate, a ServiceException will be thrown.

    Parameters:
      `privUser` - The user context to use to search for credentials that the user himself may not be allowed to see. This may be null in order to use the user's own authenticated connection to search for credentials.
      `uid` - The user ID for the new user
      `password` - The password for the new user.
      `domain` - The authentication domain for the user. A null domain will cause a ServiceException to be thrown.
      `clientSource` - A String (normally an IP address) that indicates the client location that initiated the login request.
      `appSource` - A String that identifies the application that is initiating the request. This should either be the main Java class name or an identifiable application name.
      `advancedOptions` - Map<String, Object> of advanced options.
    Returns:
      A new UserContextInterface for the user.
    Throws:
      `UserInitializationException` - in the event of possibly recoverable exceptions during UserContext initialization.
      `ServiceException` - if an unrecoverable exception occurs.
      `RemoteException` - in the event of a network error.

  - ### newUser

    UserContextInterface newUser(UserContextInterface privUser, String uid, String password, String domain, String clientSource, String appSource, Map advancedOptions) throws RemoteException, ServiceException, UserInitializationException
    Create a new user context given a privileged context, user id, password, and authentication domain. This method will create the user context, a new user identity, and attempt to authenticate the user. If the identity fails to authenticate, a ServiceException will be thrown.

    Parameters:
      `privUser` - The user context to use to search for credentials that the user himself may not be allowed to see. This may be null in order to use the user's own authenticated connection to search for credentials.
      `uid` - The user ID for the new user
      `password` - The password for the new user.
      `domain` - The authentication domain for the user. A null domain will cause a ServiceException to be thrown.
      `clientSource` - A String (normally an IP address) that indicates the client location that initiated the login request.
      `appSource` - A String that identifies the application that is initiating the request. This should either be the main Java class name or an identifiable application name.
      `advancedOptions` - Map<String, Object> of advanced options.
    Returns:
      A new UserContextInterface for the user.
    Throws:
      `UserInitializationException` - in the event of possibly recoverable exceptions during UserContext initialization.
      `ServiceException` - if an unrecoverable exception occurs.
      `RemoteException` - in the event of a network error.

  - ### newUserWithInfoService

    UserContextInterface newUserWithInfoService(UserContext privUser, String uid, String password, String domain, InformationServiceInterface infoService) throws RemoteException, ServiceException, UserInitializationException
    Deprecated.
    This method should no longer be used. In order for the platform to effectively direct requests in a clustered environment, the Discovery Service needs to be able to select the correct available service rather than having the client specify one.
    Create a new user context given a user id, password, and authentication domain. This method will create the user context, a new user identity, and attempt to authenticate the user. If the identity fails to authenticate, a ServiceException will be thrown.

    Parameters:
      `privUser` - The user context to use to search for credentials that the user himself may not be allowed to see. This may be null in order to use the user's authenticated connection to look for credentials.
      `uid` - The user ID for the new user
      `password` - The password for the new user.
      `domain` - The authentication domain for the user. A null domain will cause a ServiceException to be thrown.
      `infoService` - A handle to an InformationService to use to make any repository connections.
    Returns:
      A new UserContextInterface for the user.
    Throws:
      `ServiceException` - For authentication failure, or unrecoverable service failure.
      `UserInitializationException` - if an error occurs, but the UserContext may still be useful.
      `RemoteException` - in the event of a network error.

  - ### newRemoteUser

    UserContextInterface newRemoteUser(SubjectMatter subject) throws RemoteException, ServiceException, UserInitializationException
    Create a new UserContext using a SubjectMatter object that is populated with the PFS principals and credentials of an authenticated user. This should generally not be used directly, but through the SubjectAuthenticator newAuthenticatedUser method.
    Parameters:
      `subject` - A SubjectMatter object with the principals and credentials.
    Returns:
      Authenticated user context
    Throws:
      `RemoteException` - In the event of remote object failure.
      `ServiceException` - If a service level exception occurs.
      `UserInitializationException` - If a recoverable exception occurs setting up the UserContext.

  - ### newRemoteUser

    UserContextInterface newRemoteUser(SubjectMatter subject, Map advancedOptions) throws RemoteException, ServiceException, UserInitializationException
    Create a new UserContext using a SubjectMatter object that is populated with the PFS principals and credentials of an authenticated user. This should generally not be used directly, but through the SubjectAuthenticator newAuthenticatedUser method.
    Parameters:
      `subject` - A SubjectMatter object with the principals and credentials.
      `advancedOptions` - Map<String, Object> of advanced options.
    Returns:
      Authenticated user context
    Throws:
      `RemoteException` - In the event of remote object failure.
      `ServiceException` - If a service level exception occurs.
      `UserInitializationException` - If a recoverable exception occurs setting up the UserContext.

  - ### newAuthenticatedUser

    UserContextInterface newAuthenticatedUser(Subject subject) throws RemoteException, ServiceException, UserInitializationException
    Create a new UserContext based on the Subject provided. In order for this to make much sense, the subject should have been authenticated using one of the Foundation Services login modules. This call will not work across a remote interface because the objects contained in the Subject (the principals and credentials) will not be serialized across a remote boundary. Clients should use the SubjectAuthenticator.newAuthenticatedUser method which will work across remote object boundaries.
    Parameters:
      `subject` - A javax.security.auth.Subject to use to create a new UserContext. If the subject is null, the current subject from the AccessController context will be used (set from a doAs). If that's null, a ServiceException will be thrown.
    Returns:
      An initialized UserContext.
    Throws:
      `ServiceException` - if a service error occurs.
      `UserInitializationException` - if there's a recoverable error during UserContext initialization.
      `RemoteException` - in the event of remote object failure.

  - ### setChallengeCallbackHandler

    void setChallengeCallbackHandler(RemoteCallbackHandler handler) throws RemoteException
    Set the object that will be used to handle credential challenge callbacks.

    Parameters:
      `handler` - The credential callback handler. This object will have to be an implementation of the javax.security.auth.callback.CallbackHandler interface.
    Throws:
      `RemoteException` - In the event of a remote failure.

  - ### getChallengeCallbackHandler

    RemoteCallbackHandler getChallengeCallbackHandler() throws RemoteException
    Get the object that will handle credential challenge callbacks.

    Returns:
      The callback handler
    Throws:
      `RemoteException` - in the event of a remote failure.

  - ### getUserCount

    int getUserCount() throws ServiceException, RemoteException
    Get the count of users that are currently logged in.
    Returns:
      The number of active users in the UserService.
    Throws:
      `ServiceException` - if a service level error occurs.
      `RemoteException` - In the event of remote object failure.

  - ### setGroupLoginEnabled

    void setGroupLoginEnabled(boolean groupLoginFlag) throws ServiceException, RemoteException
    Set the UserService to allow group logins to be used to create User Contexts.
    Parameters:
      `groupLoginFlag` - True to allow group logins, false to prevent them. The default at initialization is to disallow group logins.
    Throws:
      `ServiceException` - If a service level error occurs.
      `RemoteException` - In the event of remote object failure.

  - ### getGroupLoginEnabled

    boolean getGroupLoginEnabled() throws ServiceException, RemoteException
    Get the flag indicating if group logins are allowed to be used to create User Contexts.
    Returns:
      true if group logins are allowed, false otherwise.
    Throws:
      `ServiceException` - If a service level error occurs.
      `RemoteException` - In the event of remote object failure.

  - ### getSummaryData

    SummaryData getSummaryData(boolean includeDetails) throws ServiceException, RemoteException
    Get the summary data regarding the active users.
    Parameters:
      `includeDetails` - If true, the active user details and failure detail data will be included.
    Returns:
      A List of `SummaryData` objects.
    Throws:
      `ServiceException` - If a service level error occurs.
      `RemoteException` - In the event of remote object failure.

  - ### fromByteArray

    UserContextInterface fromByteArray(byte[] data) throws ServiceException, RemoteException
    Create a UserContext from a byte array returned from the `UserContext.toByteArray()` method.
    Parameters:
      `data` -
    Returns:
      A UserContext created from the byte array data.
    Throws:
      `ServiceException` - If a service level exception occurs.
      `RemoteException` - In the event of remote object failure.

  - ### resetInternalPassword

    void resetInternalPassword(String host, String port, String username, String oldPassword, String newPassword) throws ServiceException, RemoteException
    Reset a user's internal metadata password. This will work even for an expired password,
    Parameters:
      `host` - The DNS hostname where the metadata server is running.
      `port` - The IP port the metadata server is listening on.
      `username` - The Name of the Person whose internal password is being reset.
      `oldPassword` - The old internal password.
      `newPassword` - The new internal password.
    Throws:
      `ServiceException` - In the event of communication failure, or an error resetting the password.
      `RemoteException` - In the event of remote object failure.

  - ### userDestroyed

    void userDestroyed(UserContextInterface user) throws ServiceException, RemoteException
    For internal use only.
    Parameters:
      `user` - A user being destroyed.
    Throws:
      `ServiceException` - In case of service error.
      `RemoteException` - In the event of remote object failure.