com.buildforge.services.client.dbo
Class User

java.lang.Object
  extended by com.buildforge.services.client.dbo.User

public class User
extends java.lang.Object

An object representing a user within the Build Forge system. Users may be defined explicitly, or they may be instantiated automatically by the Build Forge system if proper LDAP credentials are supplied. A single user must be defined one way or the other, however; there is no mechanism for changing whether or not a user is defined by LDAP.

A user with Permission.UpdateUser can change any field that is not controlled by LDAP. A user may change her own password (provided she is not an LDAP user) and preferences such as her locale and her time zone even if she does not have Permission.UpdateUser. The Root User may edit his own record, but no other user is permitted to change it in any way.


Constructor Summary
User(APIClientConnection conn)
          Define a new user object.
 
Method Summary
 void addAccessGroup(int level)
          Grants this user direct membership in the specified access group.
 User create()
          Creates a new user as defined by this object.
 void delete()
          Deletes this user from the system.
 void deleteAccessGroup(int level)
          Revokes this user's direct membership in the specified access group.
static void deleteById(APIClientConnection conn, int userId)
          Deletes the user with the specified ID.
static java.util.List<User> findAll(APIClientConnection conn)
          Finds all users that are defined within the system.
static User findById(APIClientConnection conn, int userId)
          Finds a user by the user's ID, as supplied by the Build Forge system at the time the user was created.
static User findByLogin(APIClientConnection conn, java.lang.String login)
          Finds a user by the user's login.
 java.util.BitSet getAccessGroups(boolean direct)
          Retrieves a bit vector of the access groups for which this user has direct group membership.
 java.lang.String getDateFormat()
          The user's preferred date format.
 java.lang.String getEmail()
          The e-mail address of the user.
 boolean getLdap()
          Whether or not this user was defined by an LDAP domain.
 int getLevelHint()
          Returns the access group (level) that the Build Forge user interface should select by default when this user creates a new object that has an associated level.
 java.lang.String getLocale()
          The user's preferred locale.
 java.lang.String getLogin()
          The login name of the user.
 int getMaxBuilds()
          The maximum number of simultaneous builds for this user.
 java.lang.String getName()
          The full name of the user.
 boolean getPasswordExpired()
          Whether or not this user's password is currently expired.
 boolean getPasswordExpires()
          Whether or not this user's password ever expires.
 int getPasswordUpdated()
          Timestamp expressing when this user's password was last changed.
 java.util.EnumSet<Permission> getPermissions()
          Retrieves a canonical list of all the permissions that this user has been granted, whether through direct or indirect group membership.
 boolean getPriority()
          Whether or not this user is a high-priority login.
 java.lang.String getTimeZone()
          The user's preferred time zone.
 int getUserId()
          Returns the unique ID for this user, as provided by the Build Forge system when the user is created.
 void resetLicense()
          Revokes the license, if any, that was previously assigned to the user.
 void resetLogin()
          Forcefully terminates the user's current session, if there is one.
 void setData(java.lang.String data)
          Miscellaneous data that can be provided for integration with other systems.
 void setDateFormat(java.lang.String datefmt)
          Sets the user's preferred date format.
 void setEmail(java.lang.String email)
          Sets the e-mail address of the user.
 void setLdap(boolean ldap)
          Sets whether or not this user was defined by an LDAP domain.
 void setLevelHint(int level)
          Sets the user's access group (level) hint.
 void setLocale(java.lang.String locale)
          Sets the user's preferred locale.
 void setLogin(java.lang.String login)
          Sets the login name of the user.
 void setMaxBuilds(int maxbuilds)
          Sets the maximum number of simultaneous builds for this user.
 void setName(java.lang.String name)
          Sets the full name of the user.
 void setPassword(java.lang.String password)
          Sets the password for this user.
 void setPasswordExpires(boolean pexpire)
          Sets whether or not this user's password ever expires.
 void setPriority(boolean priority)
          Sets whether or not this user is a high-priority login.
 void setTimeZone(java.lang.String tzone)
          Sets the user's preferred time zone.
 java.lang.String toString()
           
 User update()
          Updates this existing user to use the modified values in this object.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

User

public User(APIClientConnection conn)
Define a new user object. The user does not exist until after it has been created using the create() method.

Parameters:
conn - the services layer connection that the user object should use when submitting requests
Method Detail

findAll

public static java.util.List<User> findAll(APIClientConnection conn)
                                    throws java.io.IOException,
                                           ServiceException
Finds all users that are defined within the system. The password fields are not returned by the server.

Parameters:
conn - the API client connection to use
Returns:
the list of users
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the request fails

findById

public static User findById(APIClientConnection conn,
                            int userId)
                     throws java.io.IOException,
                            ServiceException
Finds a user by the user's ID, as supplied by the Build Forge system at the time the user was created.

Parameters:
conn - the API client connection to use
userId - the user ID to find
Returns:
the user, or null if no such user exists
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the request fails

findByLogin

public static User findByLogin(APIClientConnection conn,
                               java.lang.String login)
                        throws java.io.IOException,
                               ServiceException
Finds a user by the user's login. This value is supplied either by the administrator that defined the user, or by LDAP during the user's first login.

Parameters:
conn - the API client connection to use
login - the user's login name
Returns:
the user, or null if no such user exists
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the request fails

create

public User create()
            throws java.io.IOException,
                   ServiceException
Creates a new user as defined by this object.

Restrictions: Requires Permission.AddUser. The new user is granted all default access groups, except for those to which the caller has neither direct nor indirect membership to the control level for that access group. It is not possible to explicitly create an LDAP user. The user's login, username, and password must be set, and the login and username must be unique within the Build Forge system.

Returns:
the newly created user
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the request fails

update

public User update()
            throws java.io.IOException,
                   ServiceException
Updates this existing user to use the modified values in this object.

Restrictions: Requires Permission.UpdateUser unless the user is editing her own user record, in which case the changes are restricted to a subset of the fields. Although LDAP users may be updated, it is not possible to change a user's status as an LDAP or non-LDAP user. Additionally, the fields that are supplied by LDAP may not be changed. The user's login name and username must both remain unique within the Build Forge system. See the individual set methods for each field for further information about how changes to that field are restricted.

Returns:
the updated access group
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the request fails

delete

public void delete()
            throws java.io.IOException,
                   ServiceException
Deletes this user from the system.

Restrictions: Requires Permission.DeleteUser. The privileged Root User may not be deleted.

Side-effects: Any builds owned by this user become owned by SYSTEM, as do any system log messages that were reported for this user. All scheduler entries that the user created are destroyed.

Throws:
java.io.IOException
ServiceException

deleteById

public static void deleteById(APIClientConnection conn,
                              int userId)
                       throws java.io.IOException,
                              ServiceException
Deletes the user with the specified ID.

Restrictions: As for delete()

Side-effects: As for delete()

Parameters:
conn - the connection to use for the request
level - the user ID of the user to delete
Throws:
java.io.IOException
ServiceException

resetLicense

public void resetLicense()
                  throws java.io.IOException,
                         ServiceException
Revokes the license, if any, that was previously assigned to the user. Thereafter, the license is free to be claimed by the first user that requires it.

Restrictions: Only the Root User is permitted to revoke user licenses.

Side-effects: The user's current session (if any) is invalidated. The resetLicense() method can be thought of as a more drastic version of resetLogin().

Throws:
java.io.IOException
ServiceException

resetLogin

public void resetLogin()
                throws java.io.IOException,
                       ServiceException
Forcefully terminates the user's current session, if there is one.

Restrictions: Only the Root User is permitted to terminate user sessions.

Throws:
java.io.IOException
ServiceException

getPermissions

public java.util.EnumSet<Permission> getPermissions()
                                             throws java.io.IOException,
                                                    ServiceException
Retrieves a canonical list of all the permissions that this user has been granted, whether through direct or indirect group membership.

Returns:
the set of permissions that this user has
Throws:
java.io.IOException
ServiceException

getAccessGroups

public java.util.BitSet getAccessGroups(boolean direct)
                                 throws java.io.IOException,
                                        ServiceException
Retrieves a bit vector of the access groups for which this user has direct group membership. This method is equivilant to AccessGroup.findByUser(APIClientConnection,int,boolean) using this user's connection, this user's id, and direct as the arguments.

Parameters:
direct - if true, then only the groups to which the user has direct access are included; if false then the groups the user has inherited are also included.
Throws:
java.io.IOException
ServiceException

addAccessGroup

public void addAccessGroup(int level)
                    throws java.io.IOException,
                           ServiceException
Grants this user direct membership in the specified access group. This method is functionally equivilant to AccessGroup.addMemberUser(int).

Parameters:
level - the access group to which direct membership is granted
Throws:
java.io.IOException
ServiceException

deleteAccessGroup

public void deleteAccessGroup(int level)
                       throws java.io.IOException,
                              ServiceException
Revokes this user's direct membership in the specified access group. This method is functionally equivilant to AccessGroup.deleteMemberUser(int).

Parameters:
level - the access group for which direct membership is revoked
Throws:
java.io.IOException
ServiceException

getUserId

public int getUserId()
Returns the unique ID for this user, as provided by the Build Forge system when the user is created. This field is immutable.


getLevelHint

public int getLevelHint()
Returns the access group (level) that the Build Forge user interface should select by default when this user creates a new object that has an associated level. For example, when creating a new Project, the UI will initially select this value for its level.


getName

public java.lang.String getName()
The full name of the user. This is the field that the user interface will display when showing ownership of items such as scheduler entries.


getEmail

public java.lang.String getEmail()
The e-mail address of the user. The Build Forge system uses this e-mail address to send certain notifications of system-wide events. Nothing is sent by default, but projects, steps, and filter patterns can be configured to send e-mail notifications to all members of an access group. See those entries for more information.


getLogin

public java.lang.String getLogin()
The login name of the user. This is the value that must be entered by the user when authenticating with the Build Forge system, whether through the primary user interface, the services layer, or a plug-in.


getMaxBuilds

public int getMaxBuilds()
The maximum number of simultaneous builds for this user. If a user tries to create more than this many builds at once, the build creation will fail. A value of 0 may be used to disable this limit.


getPasswordUpdated

public int getPasswordUpdated()
Timestamp expressing when this user's password was last changed. Timestamps are stored as the number of seconds elapsed since midnight on January 1, 1970, UTC. Passwords are expired when getPasswordUpdated() is older (in days) than the pw_age system configuration parameter allows. A user must change the expired password to log in successfully.

Restrictions: This value can not be controlled directly. When a new password is set for a user, this value is automatically updated to the current time.


getPasswordExpires

public boolean getPasswordExpires()
Whether or not this user's password ever expires.


getPasswordExpired

public boolean getPasswordExpired()
Whether or not this user's password is currently expired. Passwords are expired when getPasswordUpdated() is older (in days) than the pw_age system configuration parameter allows. A user must change the expired password to log in successfully.

Restrictions: This value can not be controlled directly. When a new password is set for a user, this value is automatically cleared.


getTimeZone

public java.lang.String getTimeZone()
The user's preferred time zone. Use TimeZone.findAll(APIClientConnection) to list the supported time zones.


getDateFormat

public java.lang.String getDateFormat()
The user's preferred date format.


getPriority

public boolean getPriority()
Whether or not this user is a high-priority login. If a user with this flag attempts to log in, and if all user licenses are exhausted, then a license belonging to a low-priority user is reset (as if by resetLicense()) and granted to the high-priority user, instead.


getLocale

public java.lang.String getLocale()
The user's preferred locale.


getLdap

public boolean getLdap()
Whether or not this user was defined by an LDAP domain.

Restrictions: It is not possible to change whether or not a user is defined by LDAP. To replace an explicitly defined user with LDAP credentials, you must first delete the user or change the user's login name so that he will be found in LDAP instead of the Build Forge user database. To replace an LDAP user with an explicitly defined user, delete the LDAP user's entry and create the new user in its place before the user attempts to log in again.


setLevelHint

public void setLevelHint(int level)
Sets the user's access group (level) hint. For a full description of this field, see getLevelHint().

Restrictions: This value may be changed by the user herself, or by any user with Permission.UpdateUser.


setName

public void setName(java.lang.String name)
Sets the full name of the user. For a full description of this field, see getName().

Restrictions: This value must be set when creating a new user. It may subsequently be changed by any user with Permission.UpdateUser. This field is read-only for LDAP users.


setEmail

public void setEmail(java.lang.String email)
Sets the e-mail address of the user. For a full description of this field, see getEmail().

Restrictions: This value is optional. It may be be changed by any user with Permission.UpdateUser. This field is read-only for LDAP users.


setLogin

public void setLogin(java.lang.String login)
Sets the login name of the user. For a full description of this field, see getLogin().

Restrictions: This value must be set when creating a new user. It may subsequently be changed by any user with Permission.UpdateUser. This field is read-only for LDAP users.


setPassword

public void setPassword(java.lang.String password)
                 throws APIException
Sets the password for this user. This is the value that must be entered by the user when authenticating with the Build Forge system, whether through the primary user interface, the services layer, or a plug-in.

Restrictions: There is no corresponding get method for the password, as it is never returned by the services layer. This value must be set when creating a new user. It may subsequently be changed by any user with Permission.UpdateUser, but a user may change her own password even without that permission. This value can not be changed for LDAP users.

Throws:
APIException

setMaxBuilds

public void setMaxBuilds(int maxbuilds)
Sets the maximum number of simultaneous builds for this user. For a full description of this field, see getMaxBuilds().

Restrictions: This value may be changed by any user with Permission.UpdateUser.


setPasswordExpires

public void setPasswordExpires(boolean pexpire)
Sets whether or not this user's password ever expires.

Restrictions: This value may be changed by any user with Permission.UpdateUser.


setTimeZone

public void setTimeZone(java.lang.String tzone)
Sets the user's preferred time zone. Use TimeZone.findAll(APIClientConnection) to list the supported time zones.

Restrictions: This value may be changed by the user herself, or by any user with Permission.UpdateUser.


setDateFormat

public void setDateFormat(java.lang.String datefmt)
Sets the user's preferred date format.

Restrictions: This value may be changed by the user herself, or by any user with Permission.UpdateUser.


setPriority

public void setPriority(boolean priority)
Sets whether or not this user is a high-priority login. For a full description of this field, see getPriority().

Restrictions: This value may be changed by any user with Permission.UpdateUser.


setLocale

public void setLocale(java.lang.String locale)
Sets the user's preferred locale.

Restrictions: This value may be changed by the user herself, or by any user with Permission.UpdateUser.


setData

public void setData(java.lang.String data)
Miscellaneous data that can be provided for integration with other systems.

Restrictions: This value may be changed by any user with Permission.UpdateUser, but it is a write-only field.


setLdap

public void setLdap(boolean ldap)
Sets whether or not this user was defined by an LDAP domain.

Restrictions: This method is only useful for applications that are integrating directly with Build Forge. Users are not permitted to create an LDAP user directly or to change whether or not a user is defined by LDAP.

Parameters:
ldap - true to set this user to be controlled by LDAP, or false to let Build Forge control the user's credentials and characteristics (the default).

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object