com.starteam
Class Label

java.lang.Object
  com.starteam.TypedResource
      com.starteam.LiveObject
          com.starteam.TrackedObject
              com.starteam.Label

All Implemented Interfaces:

java.lang.Cloneable

public final class Label
extends TrackedObject

Represents a named configuration of ViewMembers. Labels may be applied to an entire View or to individual item versions.

Nested Class Summary

static class	Label.Scope When applying a label to a folder, the scope of the operation
static class	Label.Type The Type for Labels
static class	Label.WebCacheLabel View accessor for cached SDK views contained objects are obtained from the artifact cache

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 Label

NEXT_BUILD The value of this field is the "magic" value (-2) to provide for Item properties such as a ChangeRequest's "Addressed In" whose value represents a label.

Method Summary

void	attachTo(Folder folder, Label.Scope scope) Attaches the label to the specified folder.
void	attachTo(ViewMember vm) Associate a new viewMember with this label.
void	attachTo(ViewMemberCollection vmc) Associate a set of viewMembers with this label.
void	attachTo(ViewMemberCollection vmc, ViewConfiguration configuration) Attach this label to the specified items as of the specified configuration.
Label	copy() Creates a copy of this Label object.
void	detachFrom(Folder item, Label.Scope scope) Removes the label from the specified folder.
void	detachFrom(ViewMember vm) Removes the label from the specified viewMember.
void	detachFrom(ViewMemberCollection vmc) Detaches this label from a collection of items.
boolean	equals(java.lang.Object another) Returns true if the other object is a Label and has the same id (from getID()) and the same server object otherwise returns false.
java.lang.String	getDebugString() Returns a string containing various properties of this label.
User	getDeletedBy() Return the User who deleted this Label.
DateTime	getDeletedTime() Return the deleted time for this object.
java.lang.String	getDescription() Returns the label's description.
java.lang.String	getDisplayName() Gets a short string that can be used to refer to this label in an application's user interface.
int	getID() Returns this label's unique integer identifier.
ViewMemberCollection	getLabeledItems(ViewMemberCollection vmc) Determines which items from a given list have been labeled with this label in the current view.
java.lang.String	getName() Return's the label's name.
View	getOwningView() Returns the view that owns this label.
Label.Type.PropertyCollection	getProperties() Returns the properties of the label type
DateTime	getRevisionTime() Returns the label's revision time.
Server	getServer() Returns the server instance for this label
DateTime	getTime() Returns the label's primary rollback time.
java.lang.Object	getValue(Property property) Return the value for the specified property.
View	getView() Returns this label's View context.
int	hashCode() Return a hash code for this object.
boolean	isBuildLabel() Returns true if the label as being a StarTeam "Build" label.
boolean	isDeleted() Returns true if this label has been deleted.
boolean	isEqualTo(Label label) Compares two Label objects.
boolean	isLocked() Return true if the label is locked or frozen.
boolean	isModified() Returns true if this label has been modified but not yet saved.
boolean	isNew() Returns true if the label has not been created on the server (using update())
boolean	isRevisionLabel() Returns true if the label is a revision label.
boolean	isViewLabel() Returns true if the label is a view label.
void	moveItem(Item item) Associates the label with a different version of an item.
void	moveItem(Item item, int objectID, DateTime revisionTime) Associates the label with a different version of an item.
void	remove() Removes (deletes) this label from the view.
void	setDescription(java.lang.String description) Sets the label's description.
void	setLocked(boolean isLocked) Set the label's locked state.
void	setName(java.lang.String name) Sets the label's name.
void	setTime(DateTime time) Sets the label's primary rollback time.
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 name of the label.
void	update() Stores all changes to a new or modified label to the StarTeam repository.

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, isDirty, 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

NEXT_BUILD

public static final Label NEXT_BUILD

The value of this field is the "magic" value (-2) to provide for Item properties such as a ChangeRequest's "Addressed In" whose value represents a label. When this value is assigned to such a property the value will be automatically changed to the next build or workflow label that gets created. Note that this is a special label that should not be changed or attempted to be updated in any way

See Also:

Label.isBuildLabel()

Method Detail

getProperties

public Label.Type.PropertyCollection getProperties()

Returns the properties of the label type

Returns:

the properties of the label type

getServer

public Server getServer()

Returns the server instance for this label

Overrides:

getServer in class TypedResource

Returns:

Server the server instance for this label

copy

public Label copy()

Creates a copy of this Label object. Useful to applications that want to save a snapshot of the label in a given state, for example, before calling View.refreshLabels().

Returns:

A copy of this Label.

isEqualTo

public boolean isEqualTo(Label label)

Compares two Label objects.

Parameters:

label - The Label to be compared with this one.

Returns:

true if no differences were found.

See Also:

Label.copy()

getView

public View getView()

Returns this label's View context. This is really the view context in which operations on the label occur. It is possible to query a view for labels from a different view. In that case the value of getView() and getOwningView() may differ.

Returns:

this label's View.

See Also:

View.fetchAllLabels(View)

getID

public int getID()

Returns this label's unique integer identifier.

Overrides:

getID in class TypedResource

Returns:

this label's unique integer identifier.

getOwningView

public View getOwningView()

Returns the view that owns this label. This may be different from the view returned by getView() since it is possible to query for labels in other views

Returns:

the view that owns this label

See Also:

View.fetchAllLabels(View)

isModified

public boolean isModified()

Returns true if this label has been modified but not yet saved.

Returns:

true if this label has been modified but not yet saved.

See Also:

Label.update()

isNew

public boolean isNew()

Returns true if the label has not been created on the server (using update())

Overrides:

isNew in class TypedResource

Returns:

true if this resource has not yet been stored in the server.

See Also:

Label.update()

getName

public java.lang.String getName()

Return's the label's name. Label names must be unique within a view.

Returns:

the label's name.

getDisplayName

public java.lang.String getDisplayName()

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

Overrides:

getDisplayName in class TypedResource

Returns:

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

setName

public void setName(java.lang.String name)

Sets the label's name. Label names must be unique within a view.

Parameters:

name - the new label name

getDescription

public java.lang.String getDescription()

Returns the label's description.

Returns:

the label's description.

setDescription

public void setDescription(java.lang.String description)

Sets the label's description.

Parameters:

description - the new label description.

isBuildLabel

public boolean isBuildLabel()

Returns true if the label as being a StarTeam "Build" label. Change Requests that have an "AddressedIn" field value of next build will have this label assigned to that field when the label is created.

Returns:

true if this "view label" is a build label.

getTime

public DateTime getTime()

Returns the label's primary rollback time. This is only meaningful for view labels as opposed to revision labels.

Returns:

the label's primary rollback time.

setTime

public void setTime(DateTime time)

Sets the label's primary rollback time. When a view label is first created it specifies a view configuration as-of a specified time. This method sets that time.

Parameters:

time - the rollback time

getRevisionTime

public DateTime getRevisionTime()

Returns the label's revision time. This applies only to revision labels. The time specifies which revision of an item the label is attached to.

Returns:

the label's revision time.

isViewLabel

public boolean isViewLabel()

Returns true if the label is a view label. A view label applies to all items in the view.

Returns:

true if the label is a view label.

See Also:

Label.isRevisionLabel()

isRevisionLabel

public boolean isRevisionLabel()

Returns true if the label is a revision label. By default a revision label applies to no items in a view whereas a view label, when created, applies to all items in the view.

Returns:

true is the label is a revision label.

isDeleted

public boolean isDeleted()

Returns true if this label has been deleted.

Returns:

true if this label has been deleted.

isLocked

public boolean isLocked()

Return true if the label is locked or frozen. The item revision to which a locked label applies can not be modified.

Returns:

true if the label is locked or frozen.

setLocked

public void setLocked(boolean isLocked)

Set the label's locked state. You must call update()

Parameters:

isLocked - true if the label is to be locked or frozen.

attachTo

public void attachTo(ViewMember vm)

Associate a new viewMember with this label. To attach a label to a historical revision of a viewMember, first retrieve the appropriate revision from the viewMember's history (using, for example, viewMember.getFromHistory), then call this method with the resulting historical viewMember.

Parameters:

vm - the viewMember to which the label is to be attached

attachTo

public void attachTo(ViewMemberCollection vmc)

Associate a set of viewMembers with this label. To attach a label to historical revisions of a viewMember, first retrieve the appropriate revisions from the viewMember's history (using, for example, viewMember.getFromHistory), then call this method with the resulting historical viewMembers. Optimized to execute the least possible number of server commands

Parameters:

vmc - a collection of viewMembers to which the label will be attached

attachTo

public void attachTo(ViewMemberCollection vmc,
                     ViewConfiguration configuration)

Attach this label to the specified items as of the specified configuration. This is available only in server releases 4.1 and higher.

Parameters:

vmc - the collection of items to which the label should be attached

configuration - the view configuration specifying what revision to attach to (may not be null)

detachFrom

public void detachFrom(ViewMemberCollection vmc)

Detaches this label from a collection of items. This is available only in server releases 4.1 and higher.

Parameters:

vmc - the collection of items to which the label should be detached (may not be null)

attachTo

public void attachTo(Folder folder,
                     Label.Scope scope)

Attaches the label to the specified folder. For 4.0 servers a scope value other than Scope.ITEM_ONLY means attach to the full tree. All server releases beyond 4.0 support the scope parameter.

Parameters:

folder - the folder item to which the label is to be attached.

scope - for folder items this is the scope of the label detachment

See Also:

Label.Scope.ITEM_ONLY, Label.Scope.ITEM_AND_CONTENTS, Label.Scope.ITEM_TREE

moveItem

public void moveItem(Item item,
                     int objectID,
                     DateTime revisionTime)

Associates the label with a different version of an item.

Parameters:

item - the item to which the label is to be attached

objectID - the object ID of the item being labeled

revisionTime - the time specifying to which revision the label should be attached

See Also:

TypedResource.getObjectID(), TrackedObject.getModifiedTime()

moveItem

public void moveItem(Item item)

Associates the label with a different version of an item. To move the label to a historical revision of an item, first retrieve the appropriate revision from the item's history (using, for example, Item.getFromHistoryByDate), then call this method with the resulting historical item.

Parameters:

item - the item to which the label is to be attached

detachFrom

public void detachFrom(ViewMember vm)

Removes the label from the specified viewMember.

Parameters:

vm - the viewMember from which the label is to be removed.

detachFrom

public void detachFrom(Folder item,
                       Label.Scope scope)

Removes the label from the specified folder. For 4.0 servers a scope value other than Scope.ITEM_ONLY means detach from the full tree. All server releases beyond 4.0 support the scope parameter.

Parameters:

item - the folder item from which the label is to be removed.

scope - for folder items this is the scope of the label detachment

See Also:

Label.Scope.ITEM_ONLY, Label.Scope.ITEM_AND_CONTENTS, Label.Scope.ITEM_TREE

getLabeledItems

public ViewMemberCollection getLabeledItems(ViewMemberCollection vmc)

Determines which items from a given list have been labeled with this label in the current view.

Parameters:

vmc - A collection of items.

Returns:

The subset of those items that represent items which have been labeled with this label.

update

public void update()

Stores all changes to a new or modified label to the StarTeam repository. You can only change the name, description and lock/frozen state after the label has been created. If those properties have not been changed then this method will immediately return.

See Also:

Label.setName(java.lang.String), Label.setDescription(java.lang.String), Label.setLocked(boolean)

getDebugString

public java.lang.String getDebugString()

Returns a string containing various properties of this label.

Returns:

a string containing various properties of this label.

toString

public java.lang.String toString()

Returns the name of the label.

Overrides:

toString in class TypedResource

Returns:

the name of the label.

equals

public boolean equals(java.lang.Object another)

Returns true if the other object is a Label and has the same id (from getID()) and the same server object otherwise returns false.

Overrides:

equals in class java.lang.Object

Parameters:

another - the object being compared to

Returns:

true if the other object represents the same label as this one

hashCode

public int hashCode()

Return a hash code for this object.

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code for this object.

remove

public void remove()

Removes (deletes) this label from the view. It will still appear in the list of labels returned from the view but it will be marked as deleted.

getDeletedTime

public DateTime getDeletedTime()

Return the deleted time for this object.

Returns:

the deleted time for this object.

getDeletedBy

public User getDeletedBy()

Return the User who deleted this Label.

Returns:

the User who deleted this Label.

getValue

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

Return the value for the specified property.

Overrides:

getValue in class TypedResource

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.

Overrides:

setValue in class TypedResource

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