com.starbase.starteam
Class Label

java.lang.Object
  |
  +--com.starbase.starteam.CacheRef
        |
        +--com.starbase.starteam.Label

All Implemented Interfaces:

java.lang.Cloneable

public class Label

extends CacheRef

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

Field Summary

static int	NEXT_BUILD_ID The value of this field is the "magic" value to provide for Item properties such as a ChangeRequest's "Addressed In" whose value represents a label ID.
static int	SCOPE_ITEM_AND_CONTENTS When applying a label to a folder you can specify the scope of the operation.
static int	SCOPE_ITEM_ONLY When applying a label to a folder you can specify the scope of the operation.
static int	SCOPE_ITEM_TREE When applying a label to a folder you can specify the scope of the operation.

Constructor Summary

Label(View view, java.lang.String name, java.lang.String description)
Deprecated. Use View.createRevisionLabel() instead.

Label(View view, java.lang.String name, java.lang.String description, boolean isBuildLabel)
Deprecated. Use View.createViewLabel() instead.

Label(View view, java.lang.String name, java.lang.String description, Label cloneFrom)
Deprecated. Use View.cloneViewLabel() or View.cloneRevisionLabel() instead.

Label(View view, java.lang.String name, java.lang.String description, OLEDate time, boolean isBuildLabel)
Deprecated. Use View.createViewLabel() instead.

Method Summary

void	attachItem(Item item, boolean recurse) Deprecated. Use attachToItem or attachToFolder.
void	attachItem(Item item, int objectID, OLEDate revisionTime, boolean recurse) Deprecated. Use one of attachToItem, attachToFolder, attachToItemRevision or attachToFolderRevision.
void	attachToFolder(Folder folder, int scope) Attaches the label to the specified folder.
void	attachToItem(Item item) Associate a new item with this label.
void	attachToItems(int[] itemIDs, ViewConfiguration configuration) Attach this label to the specified items as of the specified configuration.
Label	copy() Creates a copy of this Label object.
void	detachFromFolder(Folder item, int scope) Removes the label from the specified folder.
void	detachFromItems(int[] itemIDs) Detaches this label from a collection of items.
void	detachItem(Item item) Removes the label from the specified item.
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	getDescription() Returns the label's description.
int	getID() Returns this label's unique integer identifier.
int[]	getLabeledItemIDs(int[] itemIDs) 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.
int	getOwningProjectID() Returns the ID of the project that owns the view that owns this label.
int	getOwningViewID() Returns the ID of the view that owns this label.
OLEDate	getRevisionTime() Returns the label's revision time.
OLEDate	getTime() Returns the label's primary rollback time.
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, OLEDate 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(OLEDate time) Sets the label's primary rollback time.
java.lang.String	toDebugString() Returns a string containing various properties of this label.
java.lang.String	toString() Returns the name of the label.
void	update() Stores all changed to a new or modified label to the StarTeam repository.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

SCOPE_ITEM_ONLY

public static final int SCOPE_ITEM_ONLY

When applying a label to a folder you can specify the scope of the operation. This option applies the label to only the folder.

See Also:

Constant Field Values

SCOPE_ITEM_AND_CONTENTS

public static final int SCOPE_ITEM_AND_CONTENTS

When applying a label to a folder you can specify the scope of the operation. This option applies the label to the folder and its immediate contents.

See Also:

Constant Field Values

SCOPE_ITEM_TREE

public static final int SCOPE_ITEM_TREE

When applying a label to a folder you can specify the scope of the operation. This option applies the label to the folder and subfolder and all the items they contain.

See Also:

Constant Field Values

NEXT_BUILD_ID

public static final int NEXT_BUILD_ID

The value of this field is the "magic" value to provide for Item properties such as a ChangeRequest's "Addressed In" whose value represents a label ID. 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.

See Also:

Label.isBuildLabel(), PropertyNames.CR_ADDRESSED_IN, Constant Field Values

Constructor Detail

Label

public Label(View view,
             java.lang.String name,
             java.lang.String description,
             OLEDate time,
             boolean isBuildLabel)

Deprecated. Use View.createViewLabel() instead.

Creates a new "view label". It will not be saved on the server until update() is called. The label will not be locked.

Parameters:

view - The view in which this label will be created.

name - The label name.

description - The label description.

time - The as-of time for this view label.

isBuildLabel - True if the label is to be a build label.

See Also:

Label.isBuildLabel(), createViewLabel

Label

public Label(View view,
             java.lang.String name,
             java.lang.String description,
             boolean isBuildLabel)

Deprecated. Use View.createViewLabel() instead.

Creates a new "view label" attached to the current view configuration. The label will not be saved on the server until update() is called.

Parameters:

view - The view in which this label will be created.

name - The label name.

description - The label description.

isBuildLabel - True if the label is to be a build label.

See Also:

Label.isBuildLabel(), createViewLabel

Label

public Label(View view,
             java.lang.String name,
             java.lang.String description)

Deprecated. Use View.createRevisionLabel() instead.

Creates a new "revision label". It will not be saved on the server until update() is called.

Parameters:

view - the view in which this label will be created

name - the label name

description - the label description

See Also:

createRevisionLabel

Label

public Label(View view,
             java.lang.String name,
             java.lang.String description,
             Label cloneFrom)

Deprecated. Use View.cloneViewLabel() or View.cloneRevisionLabel() instead.

Creates a new label that is a "clone" of an existing label. The new label will be initialized to contain the same items as the label it was cloned from. It will not be saved on the server until update() is called.

Parameters:

view - the view in which this label will be created

name - the label name

description - the label description

cloneFrom - the label whose properties and members will be copied. For view labels, must reside in the same view.

See Also:

cloneViewLabel, cloneRevisionLabel

Method Detail

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.

See Also:

Label.isEqualTo(com.starbase.starteam.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 getOwningViewID() may differ.

Returns:

this label's View.

See Also:

View.fetchAllLabelsFromView(int, int)

getID

public int getID()

Returns this label's unique integer identifier.

Returns:

this label's unique integer identifier.

getOwningProjectID

public int getOwningProjectID()

Returns the ID of the project that owns the view that owns this label.

See Also:

View.fetchAllLabelsFromView(int, int)

getOwningViewID

public int getOwningViewID()

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

See Also:

View.fetchAllLabelsFromView(int, int)

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())

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.

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.

See Also:

PropertyNames.CR_ADDRESSED_IN

getTime

public OLEDate 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(OLEDate 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 OLEDate 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.

attachItem

public void attachItem(Item item,
                       int objectID,
                       OLEDate revisionTime,
                       boolean recurse)

Deprecated. Use one of attachToItem, attachToFolder, attachToItemRevision or attachToFolderRevision.

Associate a new item with this label.

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

recurse - if true will recursively attach the label to all sub items and folders.

See Also:

PropertyNames.OBJECT_ID, PropertyNames.MODIFIED_TIME, attachToItem, attachToFolder

attachItem

public void attachItem(Item item,
                       boolean recurse)

Deprecated. Use attachToItem or attachToFolder.

Associate a new item with this label. To attach a 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

recurse - if true will recursively attach the label to all sub items and folders.

See Also:

attachToItem, attachToFolder

attachToItem

public void attachToItem(Item item)

Associate a new item with this label. To attach a 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

attachToItems

public void attachToItems(int[] itemIDs,
                          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:

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

detachFromItems

public void detachFromItems(int[] itemIDs)

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

Parameters:

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

attachToFolder

public void attachToFolder(Folder folder,
                           int 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:

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,
                     OLEDate 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:

PropertyNames.OBJECT_ID, PropertyNames.MODIFIED_TIME, Item.getObjectID(), Item.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

detachItem

public void detachItem(Item item)

Removes the label from the specified item.

Parameters:

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

detachFromFolder

public void detachFromFolder(Folder item,
                             int 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

getLabeledItemIDs

public int[] getLabeledItemIDs(int[] itemIDs)

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

Parameters:

itemIDs - A list of item IDs.

Returns:

The subset of those IDs representing items that have been labeled with this label.

See Also:

Label.attachItem(Item, boolean)

update

public void update()

Stores all changed 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 need 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)

toDebugString

public java.lang.String toDebugString()

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 java.lang.Object

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.