com.starteam
Class Group

java.lang.Object
  com.starteam.TypedResource
      com.starteam.LiveObject
          com.starteam.TrackedObject
              com.starteam.Principal
                  com.starteam.Group

All Implemented Interfaces:

java.lang.Cloneable

public final class Group
extends Principal

This class represents a full StarTeam Group. New groups can be added to a StarTeam Server and existing groups can be modified through this class. All users can obtain Group information but only users with the appropriate permissions can access GroupAccount information.

See Also:

ServerAdministration.getGroups(), Permission.SERVER_ADMIN_USER_ACCOUNTS

Nested Class Summary

static class	Group.GroupType Defines the Types of a Group This property is new to 12.0+ servers
static class	Group.Type The Type of Group.
static class	Group.WebCacheGroup User accessor for cached SDK Users contained objects are obtained from the artifact cache

Nested classes/interfaces inherited from class com.starteam.Principal

Principal.WebCachePrincipal

Nested classes/interfaces inherited from class com.starteam.TrackedObject

TrackedObject.WebCacheTrackedObject

Nested classes/interfaces inherited from class com.starteam.LiveObject

LiveObject.WebCacheLiveObject

Nested classes/interfaces inherited from class com.starteam.TypedResource

TypedResource.BranchState

Field Summary

static Group	ADMINISTRATORS The built-in "Administrators" Group.
static Group	ALL_USERS The built-in "All Users" group.

Constructor Summary

Group(Server server)
Creates a new StarTeam Group object.

Method Summary

void	addPermission(Permission permission) Add this permission to the set of permissions for this Group.
Group	copy() Creates a copy of this GroupAccount object.
boolean	equals(java.lang.Object another) tests two groups for equality
User[]	fetchMembers(boolean bDescendants) Returns the users that belong to this group.
boolean	getCanRemove() Returns true if this Group and all of its descendants can be deleted without leaving any "orphan" users (i.e., users with no group membership).
java.lang.String	getDescription() Returns the group description.
java.lang.String	getDisplayName() Gets a short string that can be used to refer to this Group in an application's user interface.
java.lang.String	getFullName() Returns a qualified name for the group, showing both the group and its parents.
Group.GroupType	getGroupType() Gets the type (Team, User, Unknown) of this Group.
int	getID() Returns this group's integer identifier.
java.lang.String	getName() Returns the group name.
Group	getParent() Returns this groups's parent .
PermissionCollection	getPermissions() Returns the permissions for this group.
int	getPresentationID() Returns the unique integer identifier for this group.
Group.Type.PropertyCollection	getProperties() Returns the properties for the Group Type
Server	getServer() Returns the Server object to which this Group belongs.
Group[]	getSubGroups() Returns all of the sub-Groups for which this Group is the parent.
User[]	getUsers() Returns a list of User objects that directly belong to this group.
java.lang.Object	getValue(Property property) Return the value for the specified property.
int	hashCode() returns a unique hash for this instance
boolean	hasPermission(Permission permission) Returns true if this Group has the specified permission.
boolean	isAdministrator() Return true if this is the 'Administrators' Group.
boolean	isBuiltin() Return true if this is a builtin Group.
boolean	isDeleted() Returns true if the Group has been deleted.
boolean	isDirty() Returns true if any property has been modified from the original value (including properties set on new items).
boolean	isEqualTo(Group group) Compares two Group objects, and their member User IDs.
boolean	isMember(User user) Return true if the specified user can be considered a member of this Group.
boolean	isNew() Returns true if this Group has not yet been created on the Server.
boolean	isRoot() Returns true if this is a top-level group with no parent group.
void	remove() Removes this group from the StarTeam server, plus any direct or indirect subgroups of this group.
void	removePermission(Permission permission) Removes the specified permission from this Group.
void	setDescription(java.lang.String description) Changes the group description.
void	setGroupType(Group.GroupType type) Sets the type of this Group.
void	setName(java.lang.String name) Changes the group name.
void	setParent(Group parent) Change/Assign the parent for this group.
java.lang.Object	setValue(Property property, java.lang.Object value) Sets the value of the specified property and return the old value.
java.lang.String	toString() Returns the group name.
void	update() Persistently saves the changes to this Group in the server.

Methods inherited from class com.starteam.TrackedObject

getModifiedBy, getModifiedTime

Methods inherited from class com.starteam.LiveObject

getCreatedBy, getCreatedTime, toStarTeamURL

Methods inherited from class com.starteam.TypedResource

addToIntegerArray, getBooleanValue, getByteArrayValue, getCachedProperties, getContentValue, getDateTimeValue, getDateValue, getDoubleValue, getEnumDisplayName, getEnumeratedValues, getIntegerArrayValue, getIntegerValue, getLinkValue, getLongValue, getObjectID, getPossibleValues, getStringValue, getTimeSpanValue, getType, hasCachedProperties, hasValue, removeFromIntegerArray, setBooleanValue, setByteArrayValue, setContentValue, setDateTimeValue, setDateValue, setDoubleValue, setEnumeratedValue, setEnumeratedValues, setIntegerArrayValue, setIntegerValue, setLinkValue, setLongValue, setStringValue, setTimeSpanValue

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

ALL_USERS

public static final Group ALL_USERS

The built-in "All Users" group. Note that this is a special group instance that should not be changed or attempted to be updated in any way. Note also that this is not a true Group, really more of a place holder for the group id and a non-translated, i.e. English only group name

ADMINISTRATORS

public static final Group ADMINISTRATORS

The built-in "Administrators" Group. Note that this is a special group instance that should not be changed or attempted to be updated in any way Note also that this is not a true Group, really more of a place holder for the group id and a non-translated, i.e. English only group name

Constructor Detail

Group

public Group(Server server)

Creates a new StarTeam Group object. It is initially not a subgroup of any existing group and one should call setParent to change this. The name is initially the empty string. To create this group in the StarTeam server you must call update.

Parameters:

server - the StarTeam Server to which this group belongs.

Method Detail

getProperties

public Group.Type.PropertyCollection getProperties()

Returns the properties for the Group Type

Returns:

the properties for the Group Type

isDirty

public boolean isDirty()

Returns true if any property has been modified from the original value (including properties set on new items). Modified properties are saved by a call to update().

Specified by:

isDirty in class Principal

Returns:

true if any of this item's properties have been modified locally and not yet saved.

fetchMembers

public User[] fetchMembers(boolean bDescendants)

Returns the users that belong to this group. The information is retrieved directly from the StarTeam Server, and is not cached. Requires admin privileges on 5.2 and earlier servers.

Parameters:

bDescendants - true = plus all descendants of group; false = this group only

Returns:

the Users who belong to this group.

copy

public Group copy()

Creates a copy of this GroupAccount object. Useful to applications that want to save a snapshot of the account information in a given state, for example, before calling ServerAdministration.refreshAccounts().

Returns:

A new copy of this GroupAccount object.

See Also:

Group.isEqualTo(Group)

isNew

public boolean isNew()

Returns true if this Group has not yet been created on the Server.

Specified by:

isNew in class Principal

Returns:

true if this Group has not yet been created on the Server.

isDeleted

public boolean isDeleted()

Returns true if the Group has been deleted.

Specified by:

isDeleted in class Principal

Returns:

true if the Group has been deleted.

toString

public java.lang.String toString()

Returns the group name.

Overrides:

toString in class TypedResource

Returns:

the group name.

getID

public int getID()

Returns this group's integer identifier.

Specified by:

getID in class Principal

Returns:

this group's integer identifier.

getPresentationID

public int getPresentationID()

Returns the unique integer identifier for this group. on pre 14.0 servers, it returns the groupID

Returns:

the unique integer identifier for this group.

getDisplayName

public java.lang.String getDisplayName()

Gets a short string that can be used to refer to this Group in an application's user interface.

Overrides:

getDisplayName in class TypedResource

Returns:

A short string that can be used to refer to this Group in an application's user interface.

getName

public java.lang.String getName()

Returns the group name.

Specified by:

getName in class Principal

Returns:

the group name.

See Also:

Group.getFullName()

setName

public void setName(java.lang.String name)

Changes the group name. You must call update to save this change.

Specified by:

setName in class Principal

Parameters:

name - the new name for the group.

See Also:

Group.update()

getFullName

public java.lang.String getFullName()

Returns a qualified name for the group, showing both the group and its parents.

Returns:

A qualified name for the group, showing both the group and its parents.

See Also:

Group.getName(), Group.getParent()

getDescription

public java.lang.String getDescription()

Returns the group description.

Returns:

the group description.

See Also:

ServerAdministration.getGroups()

setDescription

public void setDescription(java.lang.String description)

Changes the group description. You must call update to save this change.

Parameters:

description - the new description for the group.

See Also:

Group.update()

isRoot

public boolean isRoot()

Returns true if this is a top-level group with no parent group.

Returns:

true if this is a top-level group with no parent group.

See Also:

Group.getParent()

getParent

public Group getParent()

Returns this groups's parent . If the group is a top-level group then this may return null.

Returns:

the parent for this group.

See Also:

Group.isRoot()

setParent

public void setParent(Group parent)

Change/Assign the parent for this group. A newly created group requires a parent even if the parent is the All_USERS group. Subsequent modifications of the group may assign a NULL parent, in which case ,the group gets 'promoted' to be a root group

Parameters:

parent - the new parent for this group

See Also:

Group.isRoot()

getPermissions

public PermissionCollection getPermissions()

Returns the permissions for this group.

Returns:

the permissions for this group.

See Also:

Permission

hasPermission

public boolean hasPermission(Permission permission)

Returns true if this Group has the specified permission.

Parameters:

permission - the permission in question

Returns:

true if this Group has the specified permission.

See Also:

Permission

addPermission

public void addPermission(Permission permission)

Add this permission to the set of permissions for this Group.

Parameters:

permission - the permission to add

See Also:

Permission

removePermission

public void removePermission(Permission permission)

Removes the specified permission from this Group.

Parameters:

permission - the permission to remove

See Also:

Permission

getServer

public Server getServer()

Returns the Server object to which this Group belongs.

Specified by:

getServer in class Principal

Returns:

the Server object to which this Group belongs.

setGroupType

public void setGroupType(Group.GroupType type)

Sets the type of this Group. This property is new to 12.0+ servers

Parameters:

type - The new status value for this project.

getGroupType

public Group.GroupType getGroupType()

Gets the type (Team, User, Unknown) of this Group. This property is new to 12.0+ servers

Returns:

type (Team, User, Unknown) of this Group

See Also:

Group.GroupType, Group.Type.TypeProperty, Group.Type.PropertyCollection.TYPE

getSubGroups

public Group[] getSubGroups()

Returns all of the sub-Groups for which this Group is the parent. The list may be empty but will never be null. The only way to change this list of sub groups is by modifying the parent Group of one of the children.

Returns:

the sub Groups of this Group

Throws:

ServerException - if the logged in user does not have appropriate permissions

See Also:

Group.setParent(com.starteam.Group), ServerAdministration.getGroups()

getUsers

public User[] getUsers()

Returns a list of User objects that directly belong to this group. The only way to change this list is through the User methods for adding and removing the User to a Group.

Returns:

the User objects directly belonging to this group.

Throws:

ServerException - if the logged in user does not have appropriate permissions

See Also:

User.addTo(com.starteam.Group), User.removeFrom(com.starteam.Group), ServerAdministration.getGroups()

isMember

public boolean isMember(User user)

Return true if the specified user can be considered a member of this Group. A user is defined to be a member of a Group if it is directly a member of the Group or recursively of any sub-Group of this Group., i.e. membership is implied

Parameters:

user - the user being checked for group membership

Returns:

true if the specified user ID is a member of this or any sub group

update

public void update()
            throws java.lang.IllegalStateException

Persistently saves the changes to this Group in the server. If the Group is new it will be added, otherwise it will be modified.

Specified by:

update in class Principal

Throws:

java.lang.IllegalStateException - if this is a new Group with no Parent assigned.

remove

public void remove()
            throws java.lang.IllegalStateException

Removes this group from the StarTeam server, plus any direct or indirect subgroups of this group. If the Group was never saved (isNew() returns true), if it is a builtin account, or if removing this group or any of its descendants would leave one or more users without any group membership, then an exception will be thrown. Note also that any affected Users will be updated, including any pending changes, as a side effect of this method.

Specified by:

remove in class Principal

Throws:

java.lang.IllegalStateException - if this Group was never saved, if it is a builtin account, or if removing it would result in a user having no group membership.

ServerException - if the logged in user does not have appropriate permissions

See Also:

ServerAdministration.getGroups(), Group.isNew()

getCanRemove

public boolean getCanRemove()

Returns true if this Group and all of its descendants can be deleted without leaving any "orphan" users (i.e., users with no group membership).

Returns:

true if this Group and all of its descendants can be deleted without leaving any users with no group membership.

isAdministrator

public boolean isAdministrator()

Return true if this is the 'Administrators' Group.

Returns:

true if this is the 'Administrators' Group.

isBuiltin

public boolean isBuiltin()

Return true if this is a builtin Group.

Returns:

true if this is a builtin Group.

getValue

public java.lang.Object getValue(Property property)
                          throws NoSuchPropertyException

Return the value for the specified property.

Specified by:

getValue in class Principal

Parameters:

property - the name of property to be retrieved

Returns:

the value of the specified property

Throws:

NoSuchPropertyException - if the named property does not exist

setValue

public java.lang.Object setValue(Property property,
                                 java.lang.Object value)
                          throws NoSuchPropertyException,
                                 java.lang.ClassCastException

Sets the value of the specified property and return the old value.

Specified by:

setValue in class Principal

Parameters:

property - the property to set

value - the new value to set for the specified property

Returns:

the old property value

Throws:

NoSuchPropertyException - if the named property does not exist

java.lang.ClassCastException - if the value is of the wrong type for the specified property

isEqualTo

public boolean isEqualTo(Group group)

Compares two Group objects, and their member User IDs. Requires admin privileges on 5.2 and earlier servers.

The parent Servers are not compared.

Parameters:

group - The Group to be compared with this one.

Returns:

true if no differences were found.

See Also:

Group.copy()

equals

public boolean equals(java.lang.Object another)

tests two groups for equality

Overrides:

equals in class java.lang.Object

Parameters:

another - the other group

Returns:

true of the two groups are equal

hashCode

public int hashCode()

returns a unique hash for this instance

Overrides:

hashCode in class java.lang.Object

Returns:

a unique hash for this instance