Package com.spotfire.ws.pub

Interface UserDirectoryService

  • public interface UserDirectoryService
    A public SOAP web service for the TIBCO Spotfire Server User Directory.

    Authorization

    • All access to this service require an access token that is issued for the "api.soap.user-directory-service" scope.
    • Modifying operations also require the calling user (the OAuth 2.0 client principal) to be a member of the Administrator group.

    Important things to note

    • All modifying operations are atomic unless stated otherwise.
    • The domain name may be omitted where applicable, in which case the internal SPOTFIRE domain will be used instead.
    Since:
    5.5

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String SERVICE_SCOPE
      The OAuth 2.0 scope needed to access any operation in this service.

    • Field Detail

      • SERVICE_SCOPE

        static final java.lang.String SERVICE_SCOPE
        The OAuth 2.0 scope needed to access any operation in this service.
        Since:
        7.13
        See Also:
        Constant Field Values

    • Method Detail

      • getUserByName

        UserPrincipal getUserByName​(UserName userName)
                     throws UserDirectoryServiceException
        Returns the user principal with the given name (consisting of both a name component and a domain).
        Parameters:
        userName - the name of the user, must not be null
        Returns:
        the requested user, or null if no such user exists
        Throws:
        UserDirectoryServiceException - if the user name is null or if an unexpected error occurs

      • getGroupByName

        GroupPrincipal getGroupByName​(GroupName groupName)
                       throws UserDirectoryServiceException
        Returns the group principal with the given name (consisting of both a name component and a domain).
        Parameters:
        groupName - the name of the group, must not be null
        Returns:
        the requested group, or null if no such group exists
        Throws:
        UserDirectoryServiceException - if the group name is null or if an unexpected error occurs

      • searchUsers

        java.util.List<UserPrincipal> searchUsers​(java.lang.String searchExpression,
                                          int maxResults)
                                   throws UserDirectoryServiceException
        Returns all users, up to the specified upper limit, with names that matches the given search expression.

        The search expression should be a user name, or part thereof, with optional '?' (matches any single character) and '*' (matches zero or more characters) wildcards.

        Parameters:
        searchExpression - the search expression to match with the users' names, must not be null or empty
        maxResults - the maximum number of users to return, or a non-positive value if no limit should be imposed
        Returns:
        all users with names that matches the given search expression, in no particular order
        Throws:
        UserDirectoryServiceException - if the search expression is null or empty or if an unexpected error occurs

      • searchGroups

        java.util.List<GroupPrincipal> searchGroups​(java.lang.String searchExpression,
                                            int maxResults)
                                     throws UserDirectoryServiceException
        Returns all groups, up to the specified upper limit, with names that matches the given search expression.

        The search expression should be a group name, or part thereof, with optional '?' (matches any single character) and '*' (matches zero or more characters) wildcards.

        Parameters:
        searchExpression - the search expression to match with the groups' names
        maxResults - the maximum number of groups to return, or a non-positive value if no limit should be imposed
        Returns:
        all groups with names that matches the given search expression, in no particular order
        Throws:
        UserDirectoryServiceException - if the search expression is null or empty or if an unexpected error occurs

      • getImmediateGroups

        java.util.List<GroupPrincipal> getImmediateGroups​(PrincipalName principalName)
                                           throws UserDirectoryServiceException
        Returns the immediate groups that the given principal (user or group) is a member of.
        Parameters:
        principalName - the name of the principal, must not be null
        Returns:
        all immediate groups that the given principal is a member of, in no particular order
        Throws:
        UserDirectoryServiceException - if no principal with the given type and name exists or if an unexpected error occurs

      • getAllGroups

        java.util.List<GroupPrincipal> getAllGroups​(PrincipalName principalName)
                                     throws UserDirectoryServiceException
        Returns the groups (immediate or inherited) that the given principal (user or group) is a member of.
        Parameters:
        principalName - the name of the principal, must not be null
        Returns:
        all groups (immediate or inherited) that the given principal is a member of, in no particular order
        Throws:
        UserDirectoryServiceException - if no principal with the given type and name exists or if an unexpected error occurs

      • createUser

        UserPrincipal createUser​(java.lang.String username,
                         java.lang.String domainName,
                         java.lang.String displayName,
                         java.lang.String email,
                         java.lang.String password)
                  throws UserDirectoryServiceException
        Creates a new user. If the password is null the user will not be able to login when using Spotfire Database as authentication method.

        Authorization
        The calling user must be a member of the Administrator group.

        Parameters:
        username - the name of the user, must not be null or an empty string and must not exceed 50 characters
        domainName - the domain name, must not be null or an empty string and must not exceed 50 characters
        displayName - the display name, must not be null or an empty string and must not exceed 100 characters
        email - the e-mail address, may be null but must not be an empty string or an invalid e-mail address
        password - the new password, may be null but must not be an empty string
        Returns:
        the newly created user
        Throws:
        UserDirectoryServiceException - if the calling user doesn't have sufficient privileges, if the user name, the display name, the e-mail address or the password is invalid, if a user with the same name already exists in the same domain or if an unexpected error occurs

      • createGroup

        GroupPrincipal createGroup​(java.lang.String groupname,
                           java.lang.String displayName,
                           java.lang.String email)
                    throws UserDirectoryServiceException
        Creates a new group. Note that groups can only be created in the internal SPOTFIRE domain using this method. Groups may belong to other domains but only when created through LDAP group synchronization.

        Authorization
        The calling user must be a member of the Administrator group.

        Parameters:
        groupname - the name of the group, must not be null or an empty string and must not exceed 50 characters
        displayName - the display name, must not be null or an empty string and must not exceed 100 characters
        email - the e-mail address, may be null but must not be an empty string or an invalid e-mail address
        Returns:
        the newly created group
        Throws:
        UserDirectoryServiceException - if the calling user doesn't have sufficient privileges, if the group name, the display name or the e-mail address is invalid, if a group with the same name already exists in the same domain or if an unexpected error occurs

      • removePrincipals

        void removePrincipals​(java.util.List<PrincipalName> principalNames)
               throws UserDirectoryServiceException
        Removes the given principals (users and groups).

        Authorization
        The calling user must be a member of the Administrator group.

        Parameters:
        principalNames - the names of the principals to remove, may be empty in which case no changes will be made
        Throws:
        UserDirectoryServiceException - if the calling user doesn't have sufficient privileges or if an unexpected error occurs

      • setName

        void setName​(PrincipalName principalName,
             java.lang.String name)
      throws UserDirectoryServiceException
        Sets the name for the given principal (user or group).

        Authorization
        The calling user must be a member of the Administrator group.

        Parameters:
        principalName - the name of the principal to set the name for, must not be null
        name - the new name, must not be null or an empty string and must not exceed 50 characters
        Throws:
        UserDirectoryServiceException - if the calling user doesn't have sufficient privileges, if the principal doesn't exist, if the name is invalid, if another principal of the same type with the new name already exists in the same domain or if an unexpected error occurs

      • setDisplayName

        void setDisplayName​(PrincipalName principalName,
                    java.lang.String displayName)
             throws UserDirectoryServiceException
        Sets the display name for the given principal (user or group).

        Authorization
        The calling user must be a member of the Administrator group.

        Parameters:
        principalName - the name of the principal to set the display name for, must not be null
        displayName - the new display name, must not be null or an empty string and must not exceed 100 characters
        Throws:
        UserDirectoryServiceException - if the calling user doesn't have sufficient privileges, if the principal doesn't exist, if the display name is invalid or if an unexpected error occurs

      • setEmail

        void setEmail​(PrincipalName principalName,
              java.lang.String email)
       throws UserDirectoryServiceException
        Sets the e-mail address for the given principal (user or group).

        Authorization
        The calling user must be a member of the Administrator group.

        Parameters:
        principalName - the name of the principal to set the e-mail address for, must not be null
        email - the new e-mail address, may be null but must not be an empty string or an invalid e-mail address
        Throws:
        UserDirectoryServiceException - if the calling user doesn't have sufficient privileges, if the principal doesn't exist, if the e-mail address is invalid or if an unexpected error occurs

      • setPassword

        void setPassword​(UserName userName,
                 java.lang.String password)
          throws UserDirectoryServiceException
        Sets the password for the given user. If the password is null any existing password will be cleared and the user will not be able to login when using Spotfire Database as authentication method.

        Authorization
        The calling user must be a member of the Administrator group.

        Parameters:
        userName - the name of the user to set the password for, must not be null
        password - the new password, may be null but must not be an empty string
        Throws:
        UserDirectoryServiceException - if the calling user doesn't have sufficient privileges, if the user doesn't exist, if the password is invalid or if an unexpected error occurs

      • setUserEnabled

        void setUserEnabled​(UserName userName,
                    boolean enabled)
             throws UserDirectoryServiceException
        Enables or disables the given user.

        Authorization
        The calling user must be a member of the Administrator group.

        Parameters:
        userName - the name of the user to set the enabled flag for, must not be null
        enabled - the new value for the enabled flag
        Throws:
        UserDirectoryServiceException - if the calling user doesn't have sufficient privileges, if the user doesn't exist or if an unexpected error occurs

      • isMember

        boolean isMember​(GroupName groupName,
                 PrincipalName principalName)
          throws UserDirectoryServiceException
        Returns true if the given principal (user or group) is a member (immediate or otherwise) of the given group.
        Parameters:
        groupName - the name of the group to determine membership of, must not be null
        principalName - the name of the principal to determine membership for, must not be null
        Returns:
        true if the given principal is a member of the given group and false otherwise
        Throws:
        UserDirectoryServiceException - if the group or the principal doesn't exist or if an unexpected error occurs

      • addMembers

        void addMembers​(GroupName groupName,
                java.util.List<PrincipalName> memberNames)
         throws UserDirectoryServiceException
        Adds the given principals (users or groups) to the given group.

        Authorization
        The calling user must be a member of the Administrator group.

        Parameters:
        groupName - the name of the group which the principals should be added to
        memberNames - the names of the principals that should be added to the group
        Throws:
        UserDirectoryServiceException - if the calling user doesn't have sufficient privileges, if the group principal or any of the member principals doesn't exist or if an unexpected error occurs

      • removeMembers

        void removeMembers​(GroupName groupName,
                   java.util.List<PrincipalName> memberNames)
            throws UserDirectoryServiceException
        Removes the given principals (users or groups) from the given group.

        Authorization
        The calling user must be a member of the Administrator group.

        Parameters:
        groupName - the name of the group which the principals should be removed from
        memberNames - the names of the principals that should be removed from the group
        Throws:
        UserDirectoryServiceException - if the calling user doesn't have sufficient privileges, if the group principal doesn't exists or if an unexpected error occurs

      • setMembers

        void setMembers​(GroupName groupName,
                java.util.List<PrincipalName> memberNames)
         throws UserDirectoryServiceException
        Sets the given principals (users or groups) as members of the given group. Any existing members will be removed.

        Authorization
        The calling user must be a member of the Administrator group.

        Parameters:
        groupName - the name of the group for which the the members should be set
        memberNames - the names of the principals that should be set as members of the group
        Throws:
        UserDirectoryServiceException - if the calling user doesn't have sufficient privileges, if the group principal or any of the member principals doesn't exist or if an unexpected error occurs