com.starbase.starteam
Class Item

java.lang.Object
  |
  +--com.starbase.starteam.CacheRef
        |
        +--com.starbase.starteam.NamedCacheRef
              |
              +--com.starbase.starteam.TypedResource
                    |
                    +--com.starbase.starteam.SimpleTypedResource
                          |
                          +--com.starbase.starteam.Item

All Implemented Interfaces:

java.lang.Cloneable, ISecurable, ISecurableObject

Direct Known Subclasses:

Audit, ChangeRequest, File, Folder, TreeItem

public class Item

extends SimpleTypedResource

implements ISecurableObject

Contextual reference to an object in a StarTeam repository. Items provide transparent access to the underlying entity (e.g., modifying the description of an item by calling Item.put("Description", "some text") actually modifies the Desription property of the underlying entity the Item references. An Item consists of the underlying entity and its context within a view. Therefore, an Item has direct knowledge of the items to which it is related. Items also maintain state information to determine if the underlying object is is new or modified relative to instances of the object stored in the repository. An Item also has a temporal aspect in that it represents a single development path (linear history) of the underlying object as of a moment in time.

Nested Class Summary

static interface

Item.LockType Defines the constants representing the valid lock operations on items.

Method Summary

void	acquireOwnership() Sets ownership of this securable object to the logged in user.
void	addAttachment(java.lang.String name, int attachmentID) Add new attachment information to this item.
Item	copy() Creates a copy of the Item and all of its properties.
int	createAttachment(java.lang.String name, java.io.InputStream source) Creates a new attachment and returns the new attachment ID.
int	createAttachmentFromFile(java.lang.String name, java.io.File source) Creates a new attachment and returns the new attachment ID.
static Item	createItem(java.lang.String typeName, Folder parent) This factory method will create a new StarTeam item of the specified type.
void	deleteMergePoint(MergePoint mergePoint) Deletes the specified merge point for this item.
void	discard() Discards all of the cached properties for this Item.
boolean	equals(java.lang.Object another) Returns true if the specified Object identifies the same exact Item.
java.lang.Object	get(java.lang.String propertyName) Returns the value of the named property.
AclEntry[]	getACL() Returns the Access Control List for this item.
Label[]	getAllLabels() Returns all labels attached to any version of this item.
Label[]	getAttachedLabels() Returns labels attached to any version of this item.
void	getAttachment(int attachmentID, java.io.OutputStream out) Retrieves the specified attachment and copies it to the specified output stream.
int[]	getAttachmentIDs() Returns the attachment IDs for this item.
java.lang.String[]	getAttachmentNames() Returns the attachment names for this item.
void	getAttachmentToFile(int attachmentID, java.io.File outFile) Retrieves the specified attachment and copies it to the specified output stream.
ItemBehavior	getBehavior() Returns ItemBehavior object associated with this Item.
static int	getBranchRevisionFromDotNotation(java.lang.String dotNotation) Computes the "branch revision" from the specified dot notation.
java.lang.Object	getByProperty(Property property) Returns the value of the specified property.
java.lang.Object	getByPropertyID(int propertyID) Returns the value of the specified property.
byte[]	getByteArray(java.lang.String propertyName) A convenience method for returning byte[] valued properties.
Property[]	getCachedProperties() Returns an array of Properties whose values are cached locally, i.e either retrieved from persistent store or set by the client
java.lang.String	getComment() Returns the comment describing this revision of the item.
Item	getCommonAncestor(Item other) Gets the most recent common ancestor between this item and the given item.
int	getCreatedBy() Returns the user ID of the user that created the first revision of the item.
OLEDate	getCreatedTime() Returns the time at which the first revision of the item was created.
OLEDate	getDeletedTime() For deleted items, returns the time the item was deleted.
int	getDeletedUserID() For deleted items, returns the UserID of the user who deleted the item.
java.lang.String	getDisplayValue(Property prop) Gets the value of a property in a form suitable for display.
java.lang.String	getDotNotation() Returns the dot notation identification of this version.
double	getDouble(java.lang.String propertyName) A convenience method for returning double valued properties.
java.lang.String	getEnumDisplayName(java.lang.String propertyName, int value) A convenience method for returning the display name for a given value of an enumerated property.
int	getFlag() Returns whether or not this item is "flagged" for the currently logged in user.
java.lang.String	getFlagDisplayName(int value) Returns a user-friendly display name for the given "Flag" value.
Item	getFromHistoryByDate(OLEDate date) Returns the most recent version of this item as of the specified date.
Item	getFromHistoryByLabelID(int labelID) Returns the specified version of this item based on the given label ID.
Item	getFromHistoryByVersion(int viewVersion) Returns the specified version of this item based on the view version number.
Item[]	getHistory() Returns the past versions of this item.
int	getID() Return the identifier for the Item.
int	getInt(java.lang.String propertyName) A convenience method for returning integer valued properties.
int[]	getIntArray(java.lang.String propertyName) A convenience method for returning int[] valued properties.
int	getItemID() Returns an identifier representing this item, that is, the underlying entity represented by this item in this specific context.
ItemRevision[]	getItemRevisions() Returns the Item revisions for this item.
int	getLocker() Returns the user ID of the user that has this item exclusively locked, or -1 if no one has it locked.
MergePoint[]	getMergeHistory() Returns the merge points for this item.
int	getModifiedBy() Returns the user ID of the user that created this revision of the item.
OLEDate	getModifiedTime() Returns the time at which this revision of the item was created.
int	getMyLock() Returns the lock status of this item for the currently logged in user.
java.lang.String	getNewRevisionComment() Returns the empty string.
int	getObjectID() Returns the object ID property for this item.
OLEDate	getOLEDate(java.lang.String propertyName) A convenience method for returning OLEDate valued properties.
int	getOwner() If there are no access rights explicitly assigned to this object, then the effective access rights come from a parent container.
ISecurableContainer	getParentContainer() If there are no access rights explicitly assigned to this object, then the effective access rights come from a parent container.
Folder	getParentFolder() Returns the folder in which this item exists.
java.lang.String	getParentFolderHierarchy() Gets the fully-qualified name of this item's parent folder.
java.lang.String	getParentFolderName() Returns the name of the item's parent folder.
java.lang.String	getParentFolderPath() Returns the working directory path for the item's parent folder.
java.lang.String	getParentFolderQualifiedName() Gets the fully-qualified name of this item's parent folder.
int	getParentRevision() Returns the revision number at which this item was branched.
int[]	getPossibleFlag() Returns the possible enum codes that are valid values for the "Flag" property.
int[]	getPossibleReadStatus() Returns the possible enum codes that are valid values for the ReadStatus property.
int[]	getPossibleValues(java.lang.String propertyName) A convenience method for returning an array of the possible values of an enumerated property.
PropertyNames	getPropertyNames() A convenience method for getting the PropertyNames object from the owning server for the associated Type.
int	getReadStatus() A flag indicating whether or not the user has read this item before.
java.lang.String	getReadStatusDisplayName(int value) Returns a user-friendly display name for the given ReadStatus value.
ItemReference	getReference(ViewConfiguration config) Returns the Item reference for this item, as of the configuration specified by the config argument, whether the item is live or deleted.
ItemReference[]	getReferences() Returns the Item references for this item.
int	getRevisionNumber() Returns the branch revision number for this item revision.
int	getRootObjectID() Returns the root object ID property for this item.
Server	getServer() Returns the server object to which this item belongs.
java.lang.String	getString(java.lang.String propertyName) A convenience method for returning String valued properties.
Type	getType() Returns the Type describing this item.
TypeNames	getTypeNames() A convenience method for getting the TypeNames object from the owning server for the associated Type.
View	getView() Returns the View in which this item exists.
int	getViewVersion() The version number of this item calculated by counting direct ancestors of this item from this version to the initial version.
static int	getViewVersionFromDotNotation(java.lang.String dotNotation) Computes the "view version" from the specified dot notation.
int	hashCode() Return a hashcode for this item.
boolean	hasPermission(int permissions) Returns true if desired permissions are granted
boolean	hasValues(java.lang.String[] propertyNames) Returns true if every property specified contains a value, either retrieved from persistent store or set by the client; otherwise, returns false.
boolean	isBranchable() Returns true if this item is a type that is branchable.
boolean	isDeleted() Determines whether or not this item has been deleted.
boolean	isDirty() Returns true if any property has been modified from the original value (including properties set on new items).
boolean	isDisembodied() A disembodied Item is one which does not have its full View and Folder context.
boolean	isEqualTo(Item item) Compares two Items.
boolean	isFromHistory() Determines whether or not this is a historical item obtained from the history.
boolean	isNew() Returns true if this item has not yet been stored in the server.
boolean	isRefreshRequired() Returns true if a refresh() operation might have resulted in any Item properties being updated; returns false if and only if it is known that the Item properties had not been changed since the last refresh.
boolean	isRefreshRequired(java.lang.String[] propertyNames) Returns true if a refresh() operation might have resulted in any of the given Item properties being updated; returns false if and only if it is known that the given Item properties had not been changed since the last refresh.
boolean	isReverseShareRecommended(Folder target) Determines whether share or reverse-share is the more appropriate operation when sharing this item to the given target folder.
boolean	isRootShare() Determines whether or not this item is the root share of its share tree.
void	lock() Obtains an exclusive lock on this item without attempting to break an existing lock.
void	modifyFlagForUser(boolean setFlagged) Modifies this item's flag for the logged-in user.
void	modifyReadStatusForUser(boolean bSetAsRead) Modifies this item's read status for the logged-in user.
void	move(Folder toFolder) Deprecated. Use moveTo().
void	moveTo(Folder toFolder) Moves this item to the specified folder.
void	populate() Ensures that all item properties have been populated.
void	populate(java.lang.String[] propertyNames) Ensures that the given item properties have been populated.
java.lang.Object	put(java.lang.String propertyName, java.lang.Object propertyValue) Sets the value of the property specified by propertyName.
java.lang.Object	putByPropertyID(int propertyID, java.lang.Object propertyValue) Sets the value of the property specified by propertyID.
void	putLock(int lockType, boolean breakLock) Sets the current user's lock for this item.
void	recordMergePoint(Item source) Records the merge point used to create this revision of the item with respect to the specified source item.
void	refresh() Updates cached properties to reflect recent changes made on the server.
void	refresh(java.lang.String[] propertyNames) Updates cached properties to reflect recent changes made on the server.
void	remove() Removes this item from its current folder.
void	removeAttachment(int attachmentID) Removes the specified attachment from this item.
MergePoint	resolveMergePoint(Item source) Returns the merge point used to create this revision of the item with respect to the specified source item.
Item	reverseShareTo(Folder toFolder) Transfers ownership of the root share of an item to a new view or folder, sharing a copy back to the original location.
void	setACL(AclEntry[] acl) Modify the Access Control List for this item.
void	setBehavior(ItemBehavior behavior) Changes the behavior of this item.
void	setBranchOnChange(boolean bBranchOnChange) Sets the "Branch On Change" behavior.
void	setComment(java.lang.String comment) Sets the comment describing this revision of the item.
void	setFixedConfig(ViewConfiguration config) Changes the behavior of this item such that it is fixed at the given configuration.
void	setFloatingConfig() Changes the behavior of this item to "floating".
Item	shareTo(Folder toFolder) Shares this item to a new folder.
Item	smartShareTo(Folder target) Shares or reverse-shares this item to the given target folder, as appropriate.
java.lang.String	toDebugString() Returns a String that is potentially useful while debugging.
java.lang.String	toString() Returns a string representation of this object.
void	unlock() Removes the current user's lock from this item.
void	update() Stores the underlying entity in the server.
void	updateRevisionComment(java.lang.String comment) This method changes the stored revision comment on the specified item revision.

Methods inherited from class com.starbase.starteam.TypedResource

addToIntArray, removeFromIntArray

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Method Detail

createItem

public static Item createItem(java.lang.String typeName,
                              Folder parent)

This factory method will create a new StarTeam item of the specified type. If the typeName is one of the predefined types: File, ChangeRequest, Folder, Topic or Task then the appropriate subclass of Item will be created and returned. Otherwise an instance of Item itself will be created. This is useful and nescessary in order to create new instances of custom items. (Custom items are typically created by third party vendors.)

Parameters:

typeName - the name of item type to be created

parent - the folder in which the new item will be created. This may not be null.

See Also:

TypeNames

copy

public Item copy()

Creates a copy of the Item and all of its properties. Does not copy the parent folder, type, etc. Useful to applications that want to save a snapshot of the Item in a given state, for example, before calling Item.refresh() or Folder.refreshItems().

Returns:

A copy of the Item and all of its properties.

See Also:

Item.isEqualTo(com.starbase.starteam.Item)

isEqualTo

public boolean isEqualTo(Item item)

Compares two Items. The items are considered equal if:

• They have the same Type. Types are compared by ClassID.
• They have the same ItemID, or are both new Items.
• They belong to the same view. Views are compared by ID.
• They both belong to the same folder. Folders are compared by ItemID. If both Items are themselves Folders, then they must have the same parent, or both be root folders without a parent. If both Items are disembodied, then the parent folder is not considered.
• For all Item properties, the property values must be equal for both Items.

Parameters:

item - The Item to be compared to this one.

Returns:

true if no differences were found.

See Also:

Item.copy()

getParentFolder

public Folder getParentFolder()

Returns the folder in which this item exists.

Returns:

the folder in which this item exists.

Throws:

DisembodiedItemException - if the Item is disembodied

See Also:

Item.isDisembodied()

move

public void move(Folder toFolder)

Deprecated. Use moveTo().

Moves this item to the specified folder. The item will be removed from its current folder.

Parameters:

toFolder - the new folder to which this item is to be moved.

Throws:

DisembodiedItemException - if the Item is disembodied

See Also:

Item.isDisembodied()

moveTo

public void moveTo(Folder toFolder)

Moves this item to the specified folder. The item will be removed from its current folder.

Parameters:

toFolder - the new folder to which this item is to be moved.

Throws:

DisembodiedItemException - if the Item is disembodied

See Also:

Item.isDisembodied()

isReverseShareRecommended

public boolean isReverseShareRecommended(Folder target)

Determines whether share or reverse-share is the more appropriate operation when sharing this item to the given target folder.

Parameters:

target - The target folder.

Returns:

true if a reverse-share is appropriate; false otherwise.

See Also:

Item.smartShareTo(com.starbase.starteam.Folder)

smartShareTo

public Item smartShareTo(Folder target)

Shares or reverse-shares this item to the given target folder, as appropriate. The new share uses a time-based configuration, and, if branchable, is set to branch on change.

Parameters:

target - The target folder.

Returns:

The shared item.

See Also:

Item.isReverseShareRecommended(com.starbase.starteam.Folder)

shareTo

public Item shareTo(Folder toFolder)

Shares this item to a new folder. The shared item will still exist in its original folder as well as in the new one.

If this is a deleted item, shareTo() will create a new item with the same properties, but in the state it was in prior to being deleted. This provides a way to recover content from the recycle bin.

Parameters:

toFolder - The new parent folder.

Returns:

The item object representing the newly shared item.

Throws:

DisembodiedItemException - if the Folder is disembodied.

See Also:

Item.isDisembodied(), Item.moveTo(com.starbase.starteam.Folder), Item.reverseShareTo(com.starbase.starteam.Folder), Item.isDeleted(), RecycleBin

reverseShareTo

public Item reverseShareTo(Folder toFolder)

Transfers ownership of the root share of an item to a new view or folder, sharing a copy back to the original location.

In its basic form, this is simply a move followed by a share. However, reverse share is permitted from a rolled-back view. This is supported by finding the corresponding item in the tip view configuration, and reverse sharing that one.

When reverse sharing from a rolled back view, it is possible that the desired item revision in the target is not the tip revision of the item being shared. The reverse share operation compensates for this by moving the item to the target, sharing it back to the source, and then rolling back the target by creating a new revision whose user-modifiable properties (and content, if applicable) match the desired revision.

Sharing replaces the original item in the source view with a new share of the same underlying object. Since this is a new item with a new item ID, it initially has no attached labels. The reverse share operation will attempt to apply the same labels to the corresponding revisions of the new item. However, the label operations may be unsuccessful (for example, because of access rights, or because a label may be frozen). Any server exceptions that occur while re-applying labels to the new share are silently ignored, and will not cause the reverse share operation to fail.

Parameters:

toFolder - The new parent folder.

Returns:

The item object representing the new item in the target folder.

Throws:

DisembodiedItemException - if either this item or the Folder is disembodied.

See Also:

Item.isDisembodied(), Item.moveTo(com.starbase.starteam.Folder), Item.shareTo(com.starbase.starteam.Folder), #reverseShareTo(Folder,View)

isRootShare

public boolean isRootShare()

Determines whether or not this item is the root share of its share tree.

Returns:

true if this item is the root share; false otherwise.

remove

public void remove()

Removes this item from its current folder. This is not quite a delete operation because other items might refer to the same underlying object.

isDeleted

public boolean isDeleted()

Determines whether or not this item has been deleted.

As of StarTeam 9.0, we can determine from an Item's properties whether or not it has been deleted. In older servers, we can only tell whether the remove() method was called on this Item.

Returns:

True if this item is known to have been deleted; false otherwise.

See Also:

SupportedFeatures.hasDeletedItems(), Item.getDeletedTime(), Item.getDeletedUserID()

getDeletedTime

public OLEDate getDeletedTime()

For deleted items, returns the time the item was deleted. For other items, returns DateTimeProperty.VALUE_NOT_SET.

Note that this method is supported for StarTeam Server 9.0 or later.

Returns:

The time when this item was deleted, or DateTimeProperty.VALUE_NOT_SET.

Throws:

java.lang.UnsupportedOperationException - if the StarTeam Server does not support deleted items.

See Also:

SupportedFeatures.hasDeletedItems(), PropertyNames.ITEM_DELETED_TIME, DateTimeProperty.VALUE_NOT_SET, Item.isDeleted(), Item.getDeletedUserID()

getDeletedUserID

public int getDeletedUserID()

For deleted items, returns the UserID of the user who deleted the item. For other items, returns ObjectProperty.VALUE_NOT_SET.

Note that this method is supported for StarTeam Server 9.0 or later.

Returns:

The UserID of the user who deleted this item, or ObjectProperty.VALUE_NOT_SET.

Throws:

java.lang.UnsupportedOperationException - if the StarTeam Server does not support deleted items.

See Also:

SupportedFeatures.hasDeletedItems(), PropertyNames.ITEM_DELETED_USER_ID, ObjectProperty.VALUE_NOT_SET, Item.isDeleted(), Item.getDeletedTime()

getReferences

public ItemReference[] getReferences()

Returns the Item references for this item. The references are based on the specific historical revision identified by this item using getObjectID() and getRevisionNumber().

Throws:

DisembodiedItemException - if the Item is disembodied

See Also:

Item.isDisembodied(), Item.getObjectID(), Item.getRevisionNumber()

getReference

public ItemReference getReference(ViewConfiguration config)

Returns the Item reference for this item, as of the configuration specified by the config argument, whether the item is live or deleted. Note that the ItemReference that is returned is "disembodied", containing no information about its parent or children.

Parameters:

config - the ItemConfig that describes the desired configuration, only "Current" and "Time" configurations are supported.

Returns:

the Item reference for this item, as of the configuration specified by the config argument, whether the item is live or deleted.

Throws:

DisembodiedItemException - if the Item is disembodied

See Also:

Item.isDisembodied(), ViewConfiguration

getItemRevisions

public ItemRevision[] getItemRevisions()

Returns the Item revisions for this item. The revisions are based on the specific historical revisions identified by this item using getObjectID() and the ViewConfiguration of the view to which it belongs.

Throws:

DisembodiedItemException - if the Item is disembodied

See Also:

Item.isDisembodied(), Item.getObjectID(), ViewConfiguration, ItemRevision

getItemID

public int getItemID()

Returns an identifier representing this item, that is, the underlying entity represented by this item in this specific context. This ID is different for each instance of one entity shared in two locations. For instance, a file "foo" is shared between the "source" folder and the "include" folder. Calling this method on the item "foo" contained in folder "source" yields a different ID than calling it on the item "foo" contained in folder "include". Therefore, this ID is not appropriately used as an identifier of the entity itself, rather it identifies an occurence of the entity in a view.

Returns:

the unique item ID for this item.

getID

public int getID()

Return the identifier for the Item.

Overrides:

getID in class SimpleTypedResource

Returns:

the identifier for the Item.

getObjectID

public int getObjectID()

Returns the object ID property for this item.

Returns:

The object ID for this item.

See Also:

PropertyNames.OBJECT_ID

isBranchable

public boolean isBranchable()

Returns true if this item is a type that is branchable.

Returns:

true if this item is a type that is branchable.

getRootObjectID

public int getRootObjectID()

Returns the root object ID property for this item. All items with the same root object ID were all derived from the same original item object. Item revisions with the same object ID are all on the same branch.

Returns:

The root object ID for this item.

See Also:

PropertyNames.ROOT_OBJECT_ID

getRevisionNumber

public int getRevisionNumber()

Returns the branch revision number for this item revision. The first revision in a branch starts with 0 (not 1).

Returns:

The branch revision number for this item.

See Also:

PropertyNames.REVISION_NUMBER

getParentRevision

public int getParentRevision()

Returns the revision number at which this item was branched. For example, if this number is 8, then the item's revision number in the parent view was 8 at the time the item was branched. The history would then show that revision 9 was the first revision in the current view. The ParentRevision is zero if this item was not inherited from the parent view.

Returns:

The revision number at which this item was branched.

See Also:

PropertyNames.PATH_REVISION

getLocker

public int getLocker()

Returns the user ID of the user that has this item exclusively locked, or -1 if no one has it locked.

Returns:

The user ID of the exclusive locker of this item.

See Also:

PropertyNames.EXCLUSIVE_LOCKER

getComment

public java.lang.String getComment()

Returns the comment describing this revision of the item.

Returns:

The comment describing this revision of the item.

See Also:

PropertyNames.COMMENT

setComment

public void setComment(java.lang.String comment)

Sets the comment describing this revision of the item.

Parameters:

comment - The comment for the next revision of this item.

getModifiedTime

public OLEDate getModifiedTime()

Returns the time at which this revision of the item was created.

Returns:

The time at which this revision of the item was created.

See Also:

PropertyNames.MODIFIED_TIME

getModifiedBy

public int getModifiedBy()

Returns the user ID of the user that created this revision of the item.

Returns:

The user ID of the user that created this revision of the item.

See Also:

PropertyNames.MODIFIED_USER_ID

getCreatedTime

public OLEDate getCreatedTime()

Returns the time at which the first revision of the item was created.

Returns:

The time at which the first revision of the item was created.

See Also:

PropertyNames.CREATED_TIME

getCreatedBy

public int getCreatedBy()

Returns the user ID of the user that created the first revision of the item.

Returns:

The user ID of the user that created the first revision of the item.

See Also:

PropertyNames.MODIFIED_USER_ID

getDotNotation

public java.lang.String getDotNotation()

Returns the dot notation identification of this version. The first version of an item added to the repository will have a dot notation of "1.0". Each new revision will increment the version number portion so the second revision would be "1.1". When an item branches a new branch number will be issued and revision will start counting from 0 again. For example, branching from version "1.2" might result in "1.2.5.0" after which the next version will be "1.2.5.1". The value 5 in the previous example was assigned by the server based on the number of branches already made from the revision being branched.

Returns:

The dot notation identification of this version.

See Also:

PropertyNames.DOTNOTATION

getViewVersion

public int getViewVersion()

The version number of this item calculated by counting direct ancestors of this item from this version to the initial version. The first revision will have a view version number of (1).

Returns:

The view version number of this item.

getViewVersionFromDotNotation

public static int getViewVersionFromDotNotation(java.lang.String dotNotation)

Computes the "view version" from the specified dot notation. The view version starts at 1, and increments for each new item revision. For example, the view version of "1.1" is 2; the view version of "1.2.4.7" is 11.

Parameters:

dotNotation - A dot notation.

Returns:

The corresponding view version.

See Also:

getViewVersion

getBranchRevisionFromDotNotation

public static int getBranchRevisionFromDotNotation(java.lang.String dotNotation)

Computes the "branch revision" from the specified dot notation. The branch revision is the final number in the notation. For example, the branch revision of "1.1" is 1; the branch revision of "1.2.4.7" is 7.

Parameters:

dotNotation - A dot notation.

Returns:

The corresponding branch revision.

getServer

public Server getServer()

Returns the server object to which this item belongs.

Returns:

the server object to which this item belongs.

getView

public View getView()

Returns the View in which this item exists. For a disembodied item this will be the View from which the Item was obtained and may not be the actual view in which the item exists.

Returns:

the View in which this item exists.

See Also:

Item.isDisembodied()

lock

public void lock()

Obtains an exclusive lock on this item without attempting to break an existing lock. A server exception will be thrown if the lock cannot be obtained.

See Also:

Item.LockType, Item.putLock(int, boolean)

unlock

public void unlock()

Removes the current user's lock from this item. If another user has an exclusive lock on the item this method will not remove that lock.

See Also:

Item.LockType, Item.putLock(int, boolean)

putLock

public void putLock(int lockType,
                    boolean breakLock)

Sets the current user's lock for this item. This method can be used to break another user's exclusive lock on the item. An exception will be thrown if a break is attempted for a user that does not have sufficient rights to break locks.

Parameters:

lockType - the type of lock to be obtained

breakLock - true if the server should break an exclusive lock

See Also:

Item.LockType

isFromHistory

public boolean isFromHistory()

Determines whether or not this is a historical item obtained from the history.

Returns:

true if this is a historical item obtained from the history.

getHistory

public Item[] getHistory()

Returns the past versions of this item.

Returns:

the past versions of this item.

getFromHistoryByVersion

public Item getFromHistoryByVersion(int viewVersion)

Returns the specified version of this item based on the view version number. Returns null if a version is not found matching the specified version number. The view version number starts with 1 for the first version of the item and monitonically increases for each new version of the item, even across branches.

Parameters:

viewVersion - The desired version of the item.

Returns:

The specified version of the item or null if not found.

See Also:

Item.getViewVersion(), Item.getHistory()

getFromHistoryByLabelID

public Item getFromHistoryByLabelID(int labelID)

Returns the specified version of this item based on the given label ID. Returns null if a version is not found that is associated with the given label ID.

Parameters:

labelID - The label ID to be used for finding the specified revision.

Returns:

The specified revision of the item, or null if no version of the item has the label attached.

See Also:

Label, Item.getHistory()

getFromHistoryByDate

public Item getFromHistoryByDate(OLEDate date)

Returns the most recent version of this item as of the specified date. Returns null if a version is not found that existed as of the given date.

Parameters:

date - The date specifying which historical version to return.

Returns:

The most recent version as of the specified date, or null if the date is prior to the first version of the item.

getAttachedLabels

public Label[] getAttachedLabels()

Returns labels attached to any version of this item. This includes both view labels and revision labels but does not include any deleted labels. The getAllLabels method may return deleted labels. This method is generally to be prefered over getAllLabels.

Returns:

an array of labels attached to any version of this item. Will not return null but an empty array if no labels are attached.

Throws:

DisembodiedItemException - if the Item is disembodied

See Also:

Item.isDisembodied()

getAllLabels

public Label[] getAllLabels()

Returns all labels attached to any version of this item. This includes both view labels and revision labels.

Returns:

an array of labels attached to any version of this item. Will not return null but an empty array if no labels are attached.

Throws:

DisembodiedItemException - if the Item is disembodied

See Also:

Item.isDisembodied()

equals

public boolean equals(java.lang.Object another)

Returns true if the specified Object identifies the same exact Item.

Overrides:

equals in class SimpleTypedResource

Parameters:

another - the object to be compared to for equality

Returns:

true if the specified object identifies the same item as this.

hashCode

public int hashCode()

Return a hashcode for this item.

Overrides:

hashCode in class SimpleTypedResource

Returns:

a hashcode for this item.

toString

public java.lang.String toString()

Returns a string representation of this object.

Overrides:

toString in class TypedResource

Returns:

a string representation of this object.

update

public void update()

Stores the underlying entity in the server. If the item is new it will be created otherwise an existing item will be modified.

toDebugString

public java.lang.String toDebugString()

Returns a String that is potentially useful while debugging.

Returns:

a debug string for this item

hasPermission

public boolean hasPermission(int permissions)

Returns true if desired permissions are granted

Specified by:

hasPermission in interface ISecurable

Parameters:

permissions - the desired permissions

Returns:

true if all the requested permissions are granted; false if at least one of the requested permissions is denied.

Throws:

DisembodiedItemException - if the Item is disembodied

See Also:

Item.isDisembodied(), Permission

getACL

public AclEntry[] getACL()

Returns the Access Control List for this item. This will return null if this item has not access control list.

Specified by:

getACL in interface ISecurable

Returns:

the access control list for this item. May return null.

Throws:

DisembodiedItemException - if the Item is disembodied

See Also:

Item.isDisembodied()

setACL

public void setACL(AclEntry[] acl)

Modify the Access Control List for this item. If the input parameter is null then the access control list will be dropped.

Specified by:

setACL in interface ISecurable

Parameters:

acl - the new access control list or null if to be dropped.

Throws:

DisembodiedItemException - if the Item is disembodied

See Also:

Item.isDisembodied()

getAttachment

public void getAttachment(int attachmentID,
                          java.io.OutputStream out)
                   throws java.io.IOException

Retrieves the specified attachment and copies it to the specified output stream.

Parameters:

attachmentID - the attachment ID to retrieve

out - the output to write to write the attachment to

Throws:

java.io.IOException - is any error occur writing to the output stream

createAttachment

public int createAttachment(java.lang.String name,
                            java.io.InputStream source)
                     throws java.io.IOException

Creates a new attachment and returns the new attachment ID.

Parameters:

name - the name of the attachment

source - the input stream source to use for the attachment contents

Returns:

the new attachment ID

Throws:

java.io.IOException - is any error occur trying to read from the source stream

getAttachmentToFile

public void getAttachmentToFile(int attachmentID,
                                java.io.File outFile)
                         throws java.io.IOException

Retrieves the specified attachment and copies it to the specified output stream.

Parameters:

attachmentID - the attachment ID to retrieve

outFile - the file in which to save the attachment

Throws:

java.io.IOException - is any error occur writing to the output stream

createAttachmentFromFile

public int createAttachmentFromFile(java.lang.String name,
                                    java.io.File source)
                             throws java.io.IOException

Creates a new attachment and returns the new attachment ID.

Parameters:

name - the name of the attachment

source - the file to use as the source for the attachment

Returns:

the new attachment ID

Throws:

java.io.IOException - is any error occur trying to read from the source stream

getAttachmentIDs

public int[] getAttachmentIDs()

Returns the attachment IDs for this item. If the item type does not support attachments (for example, File) then an exception will be thrown. To obtain the actual attachment you must call one of the getAttachment methods.

Returns:

the ids of all the attachments associated with this item

See Also:

Item.getAttachment(int, java.io.OutputStream), Item.getAttachmentToFile(int, java.io.File)

getAttachmentNames

public java.lang.String[] getAttachmentNames()

Returns the attachment names for this item. If the item type does not support attachments (for example, File) then an exception will be thrown.

Returns:

the names of all the attachments associated with this item

addAttachment

public void addAttachment(java.lang.String name,
                          int attachmentID)

Add new attachment information to this item. The attachment should have already been created with a call to a createAttachment method. This method simply updates the item's properties describing which attachments it has associated with it. The name can not contain a newline character. The changes made must be saved with a call to update().

Parameters:

name - the name of the attachment. The name cannot contain a newline character.

attachmentID - the id of the attachment being added

See Also:

Item.createAttachment(java.lang.String, java.io.InputStream), Item.createAttachmentFromFile(java.lang.String, java.io.File), PropertyNames.ATTACHMENT_COUNT, PropertyNames.ATTACHMENT_IDS, PropertyNames.ATTACHMENT_NAMES

removeAttachment

public void removeAttachment(int attachmentID)

Removes the specified attachment from this item. This will not actually delete the attachment, it will only disassociate it from this item. The associated attachment name is removed as well. The changes made must be saved with a call to update(). If the specified attachment ID is not associated with this item then an exception will be thrown.

Parameters:

attachmentID - the id of the attachment to remove

See Also:

Item.getAttachmentIDs(), PropertyNames.ATTACHMENT_COUNT, PropertyNames.ATTACHMENT_IDS, PropertyNames.ATTACHMENT_NAMES

getInt

public int getInt(java.lang.String propertyName)
           throws NoSuchPropertyException,
                  java.lang.ClassCastException

A convenience method for returning integer valued properties.

Overrides:

getInt in class SimpleTypedResource

Parameters:

propertyName - the name of the property to be retrieved

Returns:

the integer value of the specified property

Throws:

NoSuchPropertyException - if the named property does not exist

java.lang.ClassCastException - if the value of the specified property cannot be coerced to an integer type

See Also:

TypedResource.getInt(java.lang.String)

getString

public java.lang.String getString(java.lang.String propertyName)
                           throws NoSuchPropertyException,
                                  java.lang.ClassCastException

A convenience method for returning String valued properties.

Overrides:

getString in class SimpleTypedResource

Parameters:

propertyName - the name of the property to be retrieved

Returns:

the String value of the specified property

Throws:

NoSuchPropertyException - if the named property does not exist

java.lang.ClassCastException - if the value of the specified property cannot be coerced to a String type

See Also:

TypedResource.getString(java.lang.String)

getOLEDate

public OLEDate getOLEDate(java.lang.String propertyName)
                   throws NoSuchPropertyException,
                          java.lang.ClassCastException

A convenience method for returning OLEDate valued properties.

Overrides:

getOLEDate in class SimpleTypedResource

Parameters:

propertyName - the name of the property to be retrieved

Returns:

the String value of the specified property

Throws:

NoSuchPropertyException - if the named property does not exist

java.lang.ClassCastException - if the value of the specified property cannot be coerced to an OLEDate type

See Also:

TypedResource.getOLEDate(java.lang.String)

getDouble

public double getDouble(java.lang.String propertyName)
                 throws NoSuchPropertyException,
                        java.lang.ClassCastException

A convenience method for returning double valued properties.

Overrides:

getDouble in class SimpleTypedResource

Parameters:

propertyName - the name of the property to be retrieved

Returns:

the double value of the specified property

Throws:

NoSuchPropertyException - if the named property does not exist

java.lang.ClassCastException - if the value of the specified property cannot be coerced to a double type

See Also:

TypedResource.getDouble(java.lang.String)

getByteArray

public byte[] getByteArray(java.lang.String propertyName)
                    throws NoSuchPropertyException,
                           java.lang.ClassCastException

A convenience method for returning byte[] valued properties.

Overrides:

getByteArray in class SimpleTypedResource

Parameters:

propertyName - the name of the property to be retrieved

Returns:

the byte array value of the specified property

Throws:

NoSuchPropertyException - if the named property does not exist

java.lang.ClassCastException - if the value of the specified property cannot be coerced to a byte array type

See Also:

TypedResource.getByteArray(java.lang.String)

getIntArray

public int[] getIntArray(java.lang.String propertyName)
                  throws NoSuchPropertyException,
                         java.lang.ClassCastException

A convenience method for returning int[] valued properties.

Overrides:

getIntArray in class SimpleTypedResource

Parameters:

propertyName - the name of the property to be retrieved

Returns:

the int array value of the specified property

Throws:

NoSuchPropertyException - if the named property does not exist

java.lang.ClassCastException - if the value of the specified property cannot be coerced to an int array type

See Also:

TypedResource.getIntArray(java.lang.String)

getPropertyNames

public PropertyNames getPropertyNames()

A convenience method for getting the PropertyNames object from the owning server for the associated Type.

Overrides:

getPropertyNames in class SimpleTypedResource

Returns:

the PropertyNames object from this items' server object.

See Also:

TypedResource.getPropertyNames()

getTypeNames

public TypeNames getTypeNames()

A convenience method for getting the TypeNames object from the owning server for the associated Type.

Overrides:

getTypeNames in class SimpleTypedResource

Returns:

the TypeNames object from the owning server.

See Also:

TypedResource.getTypeNames()

getPossibleValues

public int[] getPossibleValues(java.lang.String propertyName)

A convenience method for returning an array of the possible values of an enumerated property.

Overrides:

getPossibleValues in class SimpleTypedResource

Parameters:

propertyName - the name of the property

Returns:

an array of the possible values for the indicated property

See Also:

Property.getEnumValues(), TypedResource.getPossibleValues(java.lang.String)

getEnumDisplayName

public java.lang.String getEnumDisplayName(java.lang.String propertyName,
                                           int value)

A convenience method for returning the display name for a given value of an enumerated property.

Overrides:

getEnumDisplayName in class SimpleTypedResource

Parameters:

propertyName - the name of the property

value - one of the possible enumerated values of the indicated property

Returns:

a user-friendly display name for the given value

See Also:

Property.getEnumDisplayName(int), TypedResource.getEnumDisplayName(java.lang.String, int)

resolveMergePoint

public MergePoint resolveMergePoint(Item source)

Returns the merge point used to create this revision of the item with respect to the specified source item. The source item cannot be null, must be of the same type as this item and reside in the same respoitory as this item.

Parameters:

source - the source Item that was the "merge" origin of the revision specified by this item.

Returns:

the merge point used to create this revision of the item with respect to the specified source item.

recordMergePoint

public void recordMergePoint(Item source)

Records the merge point used to create this revision of the item with respect to the specified source item. The source item cannot be null, must be of the same type as this item and reside in the same respoitory as this item.

Parameters:

source - the source Item that is to be the "merge" origin of the revision specified by this item.

deleteMergePoint

public void deleteMergePoint(MergePoint mergePoint)

Deletes the specified merge point for this item.

Parameters:

mergePoint - the merge point to be deleted

getMergeHistory

public MergePoint[] getMergeHistory()

Returns the merge points for this item.

getParentFolderName

public java.lang.String getParentFolderName()

Returns the name of the item's parent folder.

Returns:

the name of the item's parent folder.

See Also:

Item.getParentFolder(), Folder.getName()

getParentFolderPath

public java.lang.String getParentFolderPath()

Returns the working directory path for the item's parent folder.

Returns:

the working directory path for the item's parent folder.

See Also:

Item.getParentFolder(), Folder.getPath()

getParentFolderHierarchy

public java.lang.String getParentFolderHierarchy()

Gets the fully-qualified name of this item's parent folder. The names of all parent folders up to the root are included, separated by and terminated with the platform-specific path separator character.

Returns:

The fully-qualified name of this item's parent folder.

See Also:

Item.getParentFolder(), Folder.getFolderHierarchy(), ClientContext.getFilePathDelimiter(), #getParentFolderFullName

getParentFolderQualifiedName

public java.lang.String getParentFolderQualifiedName()

Gets the fully-qualified name of this item's parent folder. The names of all parent folders up to the root are included, separated by the backslash character on all platforms. There is no terminating backslash. This is the same format used for the "Folder Path" property.

Returns:

The fully-qualified name of this item's parent folder.

See Also:

Item.getParentFolder(), Folder.getQualifiedName(), PropertyNames.FOLDER_PATH, Item.getParentFolderHierarchy()

getDisplayValue

public java.lang.String getDisplayValue(Property prop)

Gets the value of a property in a form suitable for display.

Parameters:

prop - A property of this item.

Returns:

The value of the property in a form suitable for display.

getReadStatus

public int getReadStatus()

A flag indicating whether or not the user has read this item before. It is not supported for File objects.

Returns:

A flag indicating whether or not the user has read this item before.

See Also:

Item.getPossibleReadStatus(), Item.getReadStatusDisplayName(int), PropertyNames.READ_STATUS, Item.modifyReadStatusForUser(boolean)

modifyReadStatusForUser

public void modifyReadStatusForUser(boolean bSetAsRead)

Modifies this item's read status for the logged-in user. Note that this is an "immediate" command, i.e., no update() call is required. Note also that only the currently logged-in user is affected. The result of getReadStatus() after this call may not be changed because its value will be based on cached information. To get the most up to date property values you should first call discard() on the item. This is not supported for File or Folder items.

Parameters:

bSetAsRead - this item's new read status

See Also:

Item.getReadStatus(), PropertyNames.READ_STATUS_USER_LIST

getPossibleReadStatus

public int[] getPossibleReadStatus()

Returns the possible enum codes that are valid values for the ReadStatus property. This is really a convenience method for accessing Property.getEnumValues for this property.

Returns:

The possible values for the ReadStatus property.

See Also:

Item.getReadStatus(), Item.getReadStatusDisplayName(int), TypedResource.getPossibleValues(java.lang.String), PropertyNames.READ_STATUS, Item.modifyReadStatusForUser(boolean)

getReadStatusDisplayName

public java.lang.String getReadStatusDisplayName(int value)

Returns a user-friendly display name for the given ReadStatus value. This is really a convenience method for accessing TypedResource.getEnumDisplayName for this property.

Parameters:

value - The ReadStatus value to be converted to a display name.

Returns:

A user-friendly display name for the given ReadStatus value.

See Also:

Item.getReadStatus(), Item.getPossibleReadStatus(), TypedResource.getEnumDisplayName(java.lang.String, int), PropertyNames.READ_STATUS, Item.modifyReadStatusForUser(boolean)

getFlag

public int getFlag()

Returns whether or not this item is "flagged" for the currently logged in user. You can consider a flag to be like a bookmark.

Returns:

A value indicating whether or not the user has flagged this item.

See Also:

Item.getPossibleFlag(), Item.getFlagDisplayName(int), PropertyNames.FLAG, Item.modifyFlagForUser(boolean), PropertyEnums.FLAG_YES, PropertyEnums.FLAG_NO

modifyFlagForUser

public void modifyFlagForUser(boolean setFlagged)

Modifies this item's flag for the logged-in user. Note that this is an "immediate" command, i.e., no update() call is required. Note also that only the currently logged-in user is affected. The result of getFlag() after this call may not be changed because its value will be based on cached information. To get the most up to date property values you should first call discard() on the item. This is not supported for Folder items.

Parameters:

setFlagged - this item's new flag value

See Also:

Item.getFlag(), Item.getPossibleFlag(), Item.getFlagDisplayName(int), PropertyNames.FLAG

getPossibleFlag

public int[] getPossibleFlag()

Returns the possible enum codes that are valid values for the "Flag" property. This is really a convenience method for accessing Property.getEnumValues for this property.

Returns:

The possible values for the Flag property.

See Also:

Item.getFlag(), Item.getFlagDisplayName(int), TypedResource.getPossibleValues(java.lang.String), PropertyNames.FLAG, Item.modifyFlagForUser(boolean)

getFlagDisplayName

public java.lang.String getFlagDisplayName(int value)

Returns a user-friendly display name for the given "Flag" value. This is really a convenience method for accessing TypedResource.getEnumDisplayName for this property.

Parameters:

value - The Flag value to be converted to a display name.

Returns:

A user-friendly display name for the given Flag value.

See Also:

Item.getFlag(), Item.getPossibleFlag(), TypedResource.getEnumDisplayName(java.lang.String, int), PropertyNames.FLAG, Item.modifyFlagForUser(boolean)

getNewRevisionComment

public java.lang.String getNewRevisionComment()

Returns the empty string. Added only because the property is used for the Win32 client and might show up in a query or filter definition.

Returns:

the empty string.

getMyLock

public int getMyLock()

Returns the lock status of this item for the currently logged in user. It will be one of exclusive, non-exclusive, or none.

Returns:

the lock status of the item for the currently logged in user

See Also:

Item.LockType.EXCLUSIVE, Item.LockType.NONEXCLUSIVE, Item.LockType.UNLOCKED, PropertyNames.MY_LOCK

getBehavior

public ItemBehavior getBehavior()

Returns ItemBehavior object associated with this Item.

Returns:

ItemBehavior object associated with this Item

Throws:

DisembodiedItemException - if the Item is disembodied

See Also:

Item.isDisembodied()

setFloatingConfig

public void setFloatingConfig()

Changes the behavior of this item to "floating". The change is saved to the repository immediately; no call to update() is required.

Throws:

DisembodiedItemException - if the Item is disembodied.

See Also:

Item.setFixedConfig(com.starbase.starteam.ViewConfiguration), Item.setBehavior(com.starbase.starteam.ItemBehavior), Item.isDisembodied()

setFixedConfig

public void setFixedConfig(ViewConfiguration config)

Changes the behavior of this item such that it is fixed at the given configuration. The change is saved to the repository immediately; no call to update() is required.

Parameters:

config - The fixed configuration to be set.

Throws:

DisembodiedItemException - if the Item is disembodied.

See Also:

Item.setFloatingConfig(), Item.setBehavior(com.starbase.starteam.ItemBehavior), Item.isDisembodied()

setBranchOnChange

public void setBranchOnChange(boolean bBranchOnChange)

Sets the "Branch On Change" behavior.

Throws:

DisembodiedItemException - if the Item is disembodied

See Also:

Item.isDisembodied()

setBehavior

public void setBehavior(ItemBehavior behavior)

Changes the behavior of this item. The change is saved to the repository immediately; no call to update() is required.

Parameters:

behavior - The new behavior.

Throws:

DisembodiedItemException - if the Item is disembodied.

See Also:

Item.setFixedConfig(com.starbase.starteam.ViewConfiguration), Item.setFloatingConfig(), ItemBehavior, Item.isDisembodied()

updateRevisionComment

public void updateRevisionComment(java.lang.String comment)

This method changes the stored revision comment on the specified item revision. Its effects are immediate, there is no need to call update(). The changed revision is based on the item's object ID and revision number. This method may not be called on an item not yet stored in the repository.

Parameters:

comment - the new revision comment (may not be null)

See Also:

Item.getObjectID(), Item.getRevisionNumber()

isDisembodied

public boolean isDisembodied()

A disembodied Item is one which does not have its full View and Folder context. Consequently many Item operations are not supported. It is possible to get and set Item property values as well as get Item history for a disembodied item. The most common way to obtain a disembodied Item is through the Link APIs or the View methods getDisembodiedItem and getHistoryForItemID.

See Also:

View.getDisembodiedItem(int, com.starbase.starteam.Type), View.getHistoryForItemID(int, com.starbase.starteam.Type), Item.getView()

getType

public Type getType()

Returns the Type describing this item. This type object is the aggregate of the type of the underlying entity and the type object describing the context specific properties.

Specified by:

getType in interface ISecurable

Overrides:

getType in class SimpleTypedResource

Returns:

the type of this item.

See Also:

ISecurable.getParentContainer(), Type

get

public java.lang.Object get(java.lang.String propertyName)
                     throws NoSuchPropertyException

Returns the value of the named property. Retrieves value from persistent store if not already cached.

Overrides:

get in class SimpleTypedResource

Parameters:

propertyName - the name of the desired property

Returns:

the value of this property as a java.lang.Object

Throws:

NoSuchPropertyException - if the specified name does not represent a valid property for this item

See Also:

PropertyNames, Item.getByPropertyID(int), Item.getByProperty(com.starbase.starteam.Property)

getByPropertyID

public java.lang.Object getByPropertyID(int propertyID)
                                 throws NoSuchPropertyException

Returns the value of the specified property. Retrieves value from persistent store if not already cached.

Parameters:

propertyID - the internal ID of the desired property

Returns:

the value of this property as a java.lang.Object

Throws:

NoSuchPropertyException - if the specified ID does not represent a valid property for this item

See Also:

Item.get(java.lang.String), Item.getByProperty(com.starbase.starteam.Property)

getByProperty

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

Returns the value of the specified property. Retrieves value from persistent store if not already cached.

Parameters:

property - the desired property

Returns:

the value of this property as a java.lang.Object

Throws:

NoSuchPropertyException - if the specified property is not valid for this item

See Also:

Item.get(java.lang.String), Item.getByPropertyID(int)

getCachedProperties

public Property[] getCachedProperties()

Returns an array of Properties whose values are cached locally, i.e either retrieved from persistent store or set by the client

Returns:

Property[]

See Also:

hasValues(Property[])

put

public java.lang.Object put(java.lang.String propertyName,
                            java.lang.Object propertyValue)
                     throws java.lang.ClassCastException,
                            NoSuchPropertyException

Sets the value of the property specified by propertyName.

Overrides:

put in class SimpleTypedResource

Parameters:

propertyName - the name of the property to set

propertyValue - the value of the property to set

Returns:

the previous value of the specified property

Throws:

java.lang.ClassCastException - if the Object passed in is not an instance of a type appropriate for the specified property

NoSuchPropertyException - if no valid property of this item is identified by the string propertyName

putByPropertyID

public java.lang.Object putByPropertyID(int propertyID,
                                        java.lang.Object propertyValue)
                                 throws java.lang.ClassCastException,
                                        NoSuchPropertyException

Sets the value of the property specified by propertyID.

Overrides:

putByPropertyID in class SimpleTypedResource

Parameters:

propertyID - the integer ID of the property to set

propertyValue - the value of the property to set

Returns:

the previous value of the specified property

Throws:

java.lang.ClassCastException - if the Object passed in is not an instance of a type appropriate for the specified property

NoSuchPropertyException - if no valid property of this item is identified by the integer propertyID

See Also:

Property.getID()

hasValues

public boolean hasValues(java.lang.String[] propertyNames)

Returns true if every property specified contains a value, either retrieved from persistent store or set by the client; otherwise, returns false. A null properties array will be interpretted as meaning "all properties". Ignores any properties that are not cachable.

Parameters:

propertyNames - the names of the properties being checked for cached values

Returns:

true if all of the specified properties have cached values in this item.

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

Returns:

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

See Also:

Item.update()

isNew

public boolean isNew()

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

Returns:

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

See Also:

Item.update()

discard

public void discard()

Discards all of the cached properties for this Item. They will be re-fetched from the server on demand (even when MPX is enabled).

If the properties of an Item are changed, and discard() is called without first calling update(), the changes will be lost.

See Also:

Item.refresh()

populate

public void populate()

Ensures that all item properties have been populated. Does not ensure that the properties are up-to-date with respect to the latest information on the server.

See Also:

Item.populate(String[]), Item.refresh(), Item.discard()

populate

public void populate(java.lang.String[] propertyNames)

Ensures that the given item properties have been populated. Does not ensure that the properties are up-to-date with respect to the latest information on the server.

Parameters:

propertyNames - The properties to populate, or null to populate all properties.

See Also:

Item.populate(), Item.refresh(), Item.discard()

isRefreshRequired

public boolean isRefreshRequired()

Returns true if a refresh() operation might have resulted in any Item properties being updated; returns false if and only if it is known that the Item properties had not been changed since the last refresh. If MPX is not enabled, then isRefreshRequired() always returns true.

Returns:

true if Item properties may be out of date.

See Also:

Item.isRefreshRequired(String[]), Item.refresh(), Item.populate(), Server.enableMPX()

isRefreshRequired

public boolean isRefreshRequired(java.lang.String[] propertyNames)

Returns true if a refresh() operation might have resulted in any of the given Item properties being updated; returns false if and only if it is known that the given Item properties had not been changed since the last refresh. If MPX is not enabled, then isRefreshRequired() always returns true.

Parameters:

propertyNames - The item properties to be tested.

Returns:

true if Item properties may be out of date.

See Also:

Item.isRefreshRequired(), Item.refresh(), Item.populate(), Server.enableMPX()

refresh

public void refresh()

Updates cached properties to reflect recent changes made on the server. All properties are refreshed. If MPX is enabled, refresh() is optimized to avoid unnecessary server commands.

See Also:

Item.refresh(String[]), Item.isRefreshRequired(), Item.populate(), Item.discard(), Server.enableMPX()

refresh

public void refresh(java.lang.String[] propertyNames)

Updates cached properties to reflect recent changes made on the server. Only the given properties are refreshed. If MPX is enabled, refresh() is optimized to avoid unnecessary server commands.

Parameters:

propertyNames - The properties to be refreshed, or null to refresh all properties.

See Also:

Item.refresh(), Item.isRefreshRequired(), Item.populate(), Item.discard(), Server.enableMPX()

getCommonAncestor

public Item getCommonAncestor(Item other)

Gets the most recent common ancestor between this item and the given item. The common ancestor is taken from this item's history.

Parameters:

other - The item to be compared with this one.

Returns:

The most recent common ancestor between this item and the given item, or null if the two items have no common ancestor.

See Also:

Item.isBranchable()

getOwner

public int getOwner()

If there are no access rights explicitly assigned to this object, then the effective access rights come from a parent container. A RuntimeException will be thrown if SupportedFeature.hasObjectOwnership() returns false.

Specified by:

getOwner in interface ISecurableObject

Returns:

This object's parent container.

See Also:

SupportedFeatures.hasObjectOwnership()

acquireOwnership

public void acquireOwnership()

Sets ownership of this securable object to the logged in user. A RuntimeException will be thrown if SupportedFeature.hasObjectOwnership() returns false.

Specified by:

acquireOwnership in interface ISecurableObject

See Also:

SupportedFeatures.hasObjectOwnership()

getParentContainer

public ISecurableContainer getParentContainer()

If there are no access rights explicitly assigned to this object, then the effective access rights come from a parent container.

Specified by:

getParentContainer in interface ISecurable

Returns:

This object's parent container.

See Also:

ISecurableContainer