com.buildforge.services.client.dbo
Class AccessGroup

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

public final class AccessGroup
extends java.lang.Object

An object representing an access group within the Build Forge system. An access group is a collection of member users. It may also inherit the rights of other access groups within the system. Access groups are also used to identify the recipients of status messages from the console, such as when a build fails.

When a new user is created, by default that user will be a member of all access groups that are marked as defaults. For installations that use LDAP for user management, group membership in the LDAP domain may be used to identify initial group membership, but thereafter, group membership is managed by Build Forge.


Field Summary
static java.lang.Class<AccessGroup> CLASS
           
static java.util.regex.Pattern REGEX_NUMBER
           
 
Constructor Summary
AccessGroup(APIClientConnection conn)
          Define a new access group object.
 
Method Summary
 void addInheritedGroup(int groupId)
          Sets this access group to inherit users and permissions from another access group.
 void addMemberUser(int userId)
          Adds a user to this access group as a direct member.
 boolean checkPermission(Permission perm)
          Determines if a specific Permission is or is not already granted to this AccessGroup.
 AccessGroup create()
          Creates a new access group as defined by this object.
 void delete()
          Deletes this access group from the system.
static void deleteById(APIClientConnection conn, int level)
          Deletes the access group with the specified ID.
 void deleteInheritedGroup(int groupId)
          Sets this access group to stop inheriting users and permissions from another access group.
 void deleteMemberUser(int userId)
          Removes a user from direct membership in this access group.
static java.util.List<AccessGroup> findAll(APIClientConnection conn)
          Finds all access groups that are defined within the system.
static java.util.List<AccessGroup> findAllChildren(APIClientConnection conn, int parentLevel)
          Finds all access groups that are children of the provided AccessGroup's identifier.
static AccessGroup findById(APIClientConnection conn, int level)
          Finds an access groups by its identifier (level) as provided by the Build Forge system at the time the access group was created.
static AccessGroup findByName(APIClientConnection conn, java.lang.String name)
          Finds an access groups by its descriptive name, as supplied by the user that created it.
static java.util.BitSet findByUser(APIClientConnection conn, int userId, boolean direct)
          Finds all access groups for a user.
static java.util.BitSet findDefault(APIClientConnection conn)
          Finds all default access groups.
 int getControlLevel()
          Returns the access group ID (level) of the access group that controls this group.
 boolean getDefault()
          Returns whether or not this access group is granted by default.
 java.util.List<AccessGroup> getInheritedGroups()
          Retrieves a list of access groups from which this access group inherits users and permissions.
 java.lang.String getLdapDN()
          Returns the LDAP distinguished name that grants membership to new users.
 int getLevel()
          Returns the access group ID (level) of this access group.
 java.util.List<User> getMemberUsers()
          Retrieves a list of users who are direct members of this access group.
 java.lang.String getName()
          Returns the descriptive name of this access group, as supplied by the user at the time the access group was created.
 void grantPermission(Permission perm)
          Grants a specified permission to the members of this access group, as well as to all access groups that inherit from this one.
 java.util.EnumSet<Permission> listPermissions()
          Returns the complete list of Permissions that are granted to this AccessGroup and any AccessGroups from which this AccessGroup inherits.
 void revokePermission(Permission perm)
          Revokes the specified permission from the members of this access group, as well as from all access groups that inherit from this one.
 void setControlLevel(int controlLevel)
          Sets the ID of the control group for this access group.
 void setDefault(boolean def)
          Sets whether or not this access group is granted by default.
 void setLdapDN(java.lang.String dn)
          Sets the LDAP distinguished name for the LDAP group that implies default membership in this access group.
 void setName(java.lang.String name)
          Sets the descriptive name of this access group.
 java.lang.String toString()
           
 AccessGroup update()
          Updates this existing access group to use the modified values in this object.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

CLASS

public static final java.lang.Class<AccessGroup> CLASS

REGEX_NUMBER

public static final java.util.regex.Pattern REGEX_NUMBER
Constructor Detail

AccessGroup

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

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

findAll

public static java.util.List<AccessGroup> findAll(APIClientConnection conn)
                                           throws java.io.IOException,
                                                  ServiceException
Finds all access groups that are defined within the system.

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

findAllChildren

public static java.util.List<AccessGroup> findAllChildren(APIClientConnection conn,
                                                          int parentLevel)
                                                   throws java.io.IOException,
                                                          ServiceException
Finds all access groups that are children of the provided AccessGroup's identifier.

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

findDefault

public static java.util.BitSet findDefault(APIClientConnection conn)
                                    throws java.io.IOException,
                                           ServiceException
Finds all default access groups. This returns a list of all access groups for which getDefault() returns true. These access groups are granted to users by default. This method does not take into account any additional access groups that may be granted by LDAP.

Parameters:
conn - the API client connection to use
Returns:
the bit vector of the access group IDs (levels) of the access groups which are marked to be granted by default
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the request fails

findByUser

public static java.util.BitSet findByUser(APIClientConnection conn,
                                          int userId,
                                          boolean direct)
                                   throws java.io.IOException,
                                          ServiceException
Finds all access groups for a user. Whether the result includes all groups or just those for which the user is a direct member is controlled by the direct option.

Parameters:
conn - the API client connection to use
userId - the user ID of the user for which to retrieve the list of groups
direct - if true, then only the groups to which the user has direct access are included; if false then any groups the user has inherited are also included.
Returns:
the bit vector of the access group IDs (levels) of the access groups to which this user has access
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the request fails

findById

public static AccessGroup findById(APIClientConnection conn,
                                   int level)
                            throws java.io.IOException,
                                   ServiceException
Finds an access groups by its identifier (level) as provided by the Build Forge system at the time the access group was created.

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

findByName

public static AccessGroup findByName(APIClientConnection conn,
                                     java.lang.String name)
                              throws java.io.IOException,
                                     ServiceException
Finds an access groups by its descriptive name, as supplied by the user that created it.

Parameters:
conn - the API client connection to use
name - the descriptive name of the access group to find
Returns:
the access group with the specified name, or null if no such access group exists
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the request fails

grantPermission

public void grantPermission(Permission perm)
                     throws java.io.IOException,
                            ServiceException
Grants a specified permission to the members of this access group, as well as to all access groups that inherit from this one.

Restrictions: Requires Permission.UpdatePermMember, as well as direct or indirect membership in the control level of this access group.

Parameters:
perm - the permission to grant
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the request fails

revokePermission

public void revokePermission(Permission perm)
                      throws java.io.IOException,
                             ServiceException
Revokes the specified permission from the members of this access group, as well as from all access groups that inherit from this one. Note that member users and inheriting groups may retain the permission if it is supplied by another access group.

Restrictions: Requires Permission.UpdatePermMember, as well as direct or indirect membership in the control level of this access group.

Parameters:
perm - the permission to revoke
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the request fails

checkPermission

public boolean checkPermission(Permission perm)
                        throws java.io.IOException,
                               ServiceException
Determines if a specific Permission is or is not already granted to this AccessGroup. Retrictions: Requires direct or indirect membership in the control level of this access group.

Parameters:
perm - the permission to check
Returns:
true if this access group has been granted the specified Permission or false if it has not
Throws:
java.io.IOException
ServiceException

listPermissions

public java.util.EnumSet<Permission> listPermissions()
                                              throws java.io.IOException,
                                                     ServiceException
Returns the complete list of Permissions that are granted to this AccessGroup and any AccessGroups from which this AccessGroup inherits. Retrictions: Requires direct or indirect membership in the control level of this access group.

Returns:
the complete list of Permissions that are granted to this AccessGroup and any AccessGroups from which this AccessGroup inherits.
Throws:
java.io.IOException
ServiceException

getMemberUsers

public java.util.List<User> getMemberUsers()
                                    throws java.io.IOException,
                                           ServiceException
Retrieves a list of users who are direct members of this access group. Note that this list does not include users that are indirect members of this group by virtue of the fact that they are members of a group that inherits from it.

Returns:
the list of direct member users
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the request fails

addMemberUser

public void addMemberUser(int userId)
                   throws java.io.IOException,
                          ServiceException
Adds a user to this access group as a direct member.

Restrictions: Requires either Permission.AddAccessMember or Permission.UpdateAccessMember, as well as direct or indirect membership in the control level of this access group.

Parameters:
userId - the user ID (as returned by User.getUserId() of the user to add to this access group
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the request fails

deleteMemberUser

public void deleteMemberUser(int userId)
                      throws java.io.IOException,
                             ServiceException
Removes a user from direct membership in this access group. Note that the user may retain indirect membership in this access group if the user is still a member of another access group that inherits from this one.

Restrictions: Requires either Permission.DeleteAccessMember or Permission.UpdateAccessMember, as well as direct or indirect membership in the control level of this access group.

Parameters:
userId - the user ID (as returned by User.getUserId() of the user to remove from this access group
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the request fails

getInheritedGroups

public java.util.List<AccessGroup> getInheritedGroups()
                                               throws java.io.IOException,
                                                      ServiceException
Retrieves a list of access groups from which this access group inherits users and permissions.

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

addInheritedGroup

public void addInheritedGroup(int groupId)
                       throws java.io.IOException,
                              ServiceException
Sets this access group to inherit users and permissions from another access group.

Restrictions: Requires Permission.AddAccess, as well as direct or indirect membership in the control level of both access groups.

Parameters:
groupId - the access group id of the access group from which this group will now inherit users and permissions
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the request fails

deleteInheritedGroup

public void deleteInheritedGroup(int groupId)
                          throws java.io.IOException,
                                 ServiceException
Sets this access group to stop inheriting users and permissions from another access group.

Restrictions: Requires Permission.AddAccess, as well as direct or indirect membership in the control level of both access groups.

Parameters:
groupId - the access group id of the access group from which this group will no longer inherit users and permissions
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the request fails

create

public AccessGroup create()
                   throws java.io.IOException,
                          ServiceException
Creates a new access group as defined by this object.

Restrictions: Requires Permission.AddLevel and direct or indirect membership in the control level. The descriptive name of the access group must be unique.

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

update

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

Restrictions: Requires Permission.EditLevel and direct or indirect membership in the control level. The descriptive name of the access group must be unique.

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 access group from the system.

Restrictions: Requires Permission.DeleteAccess and direct or indirect membership in the control level. The access group must have been defined by a user; the access groups that are defined by Build Forge may not be deleted. There must not be any access groups that inherit from this group, nor may it have any direct member users. The access group must not be used as the access setting for any Build, Result, Step, BuildClass, Environment, Filter, Interface, Project, Selector, or Server.

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

deleteById

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

Restrictions: As for delete()

Parameters:
conn - the connection to use for the request
level - the access group ID of the access group to delete
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the request fails

getControlLevel

public int getControlLevel()
Returns the access group ID (level) of the access group that controls this group. In order to make changes to an access group, the user must have direct or indirect membership in its control group.


getDefault

public boolean getDefault()
Returns whether or not this access group is granted by default. Default access groups are automatically granted to new users in the system.


getLdapDN

public java.lang.String getLdapDN()
Returns the LDAP distinguished name that grants membership to new users. On systems where LDAP is configured, LDAP group membership can be used to determine the initial group membership for new users. For access groups that have a value set for this field, this membership is determined by whether or not the user is a member of the LDAP group with the specified distinguished name. Thereafter, the access group management is controlled by Build Forge, only; modifications to group membership in LDAP have no effect on Build Forge access membership.


getLevel

public int getLevel()
Returns the access group ID (level) of this access group. This is a unique identifier that is assigned by the Build Forge system when the access group is created. Users are not permitted to choose the ID, and a larger ID numbers does not necessarily imply increased access.


getName

public java.lang.String getName()
Returns the descriptive name of this access group, as supplied by the user at the time the access group was created.


setControlLevel

public void setControlLevel(int controlLevel)
Sets the ID of the control group for this access group.

Parameters:
controlLevel - the new control group for this access group
See Also:
getControlLevel()

setDefault

public void setDefault(boolean def)
Sets whether or not this access group is granted by default.

Parameters:
def - true to grant membership in this access group to new users, or false if membership should not be granted automatically.
See Also:
getDefault()

setLdapDN

public void setLdapDN(java.lang.String dn)
Sets the LDAP distinguished name for the LDAP group that implies default membership in this access group.

Parameters:
dn - the distinguished name of the LDAP group
See Also:
getLdapDN()

setName

public void setName(java.lang.String name)
Sets the descriptive name of this access group. The name must be unique.

Parameters:
name - the new descriptive name for the access group
See Also:
getName()

toString

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