com.starteam
Class ChangePackage

java.lang.Object
  com.starteam.TypedResource
      com.starteam.LiveObject
          com.starteam.TrackedObject
              com.starteam.VersionedObject
                  com.starteam.ViewMember
                      com.starteam.ChangePackage

All Implemented Interfaces:

ISecurable, Lockable, LockableObject, java.lang.Cloneable

public final class ChangePackage
extends ViewMember

A ChangePackage represents a set of changes to a StarTeam view that together form a single logical change. A logical change might be a bug fix, enhancement, etc. The updates made by a ChangePackage are committed in a single, atomic transaction.

Nested Class Summary

static class	ChangePackage.SessionType The type of VCM or Checkin Session in whose context this Change Package was committed
static class	ChangePackage.State The current state of the change package.
static class	ChangePackage.Type The Type of the ChangePackage component.
static class	ChangePackage.WebCacheChangePackage ChangePackage accessor for cached SDK ChangePackages contained objects are obtained from the artifact cache

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

ViewMember.LockType, ViewMember.MyLock, ViewMember.ShareState, ViewMember.WebCacheViewMember

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

VersionedObject.WebCacheVersionedObject

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

Method Summary

ChangeCollection	getChanges() Gets the Change objects associated with this change package.
Transaction	getCommitTransaction() The transaction in which this change package was committed, or null if it hasn't been committed yet.
java.lang.String	getDescription() Provides a full description of the change package.
java.lang.String	getName() Each change package has a name that serves as a textual identification of the change package.
Label	getPostCommitRevisionLabel() The post-commit revision label, or null.
Label	getPostCommitViewLabel() The post-commit view label.
Label	getPreCommitRevisionLabel() The pre-commit revision label.
Label	getPreCommitViewLabel() The pre-commit view label.
Item	getProcessItem() returns the process item (if any) linked to this ChangePackage via a Trace
ChangePackage.Type.PropertyCollection	getProperties() Returns the property collection for the ChangePackage Type
ChangePackageCollection	getReplaySources() Gets the set of change packages from which the given one was derived.
ChangePackageCollection	getReplayTargets() Gets the set of change packages representing replayed instances of the given one.
User	getResponsibility() Gets the user who is currently responsible for this change package.
ChangePackage.SessionType	getSessionType() Defines the session type for the change package.
View	getSourceView() The source view for this change package.
ChangePackage.State	getState() Gets the current workflow state of the change package.
View	getTargetView() The target view for this change package.
java.lang.Object	getValue(Property property) Returns the value of the property.
boolean	isActive() Returns true if this is an active ChangePackage
boolean	isCommitted() Returns true if this is a committed ChangePackage
boolean	isDirty() Returns true if this change package has been modified, and requires an update() to save changes on the server.
boolean	isMyResponsibility() Returns true if the logged in user is responsible for this ChangePackage
ChangeSession	open() Opens the session associated with this change package.
ChangeSession	open(boolean isReadOnly) Opens the session associated with this change package.
ViewMemberCollection	resolve() Gets the item revisions from the target view in the state they were in at the time the change package was committed.
ChangeSession	restart() Open the session associated with this change package The session is opened for writing, and is ready to re-run a compare in the current context of the source and target views
ChangeSession	restore() Opens and restores an uncommitted session associated with this change package.
RollbackSession	rollback() rollback the contents of this change package on disk.
RollbackSession	rollback(Encoding enc) rollback the contents of this change package on disk.
void	setDescription(java.lang.String description) Provide a description for the change package
void	setResponsibility(User user) Set the user responsible for this change package
java.lang.String	toString() Returns the ChangePackage name.
void	update() Stores the underlying entity in the server.

Methods inherited from class com.starteam.ViewMember

copy, equals, findLinks, getAllLabels, getAllShares, getAttachedLabels, getAttachments, getBehavior, getCache, getComment, getDeletedBy, getDeletedTime, getDisplayValue, getDotNotation, getExclusiveLocker, getExternalID, getExternalURL, getFromHistory, getFromHistory, getFromHistory, getFromHistory, getHistory, getID, getIntegerArrayValue, getLocker, getMyLockType, getParentContainer, getParentRevision, getPresentationID, getRights, getRootObjectID, getShare, getShare, getTraces, getView, getViewMemberRevisions, getViewVersion, getVMID, hashCode, hasPermissions, isBookmarked, isBranchable, isDeleted, isDisembodied, isEqualTo, isReadOnly, isRootShare, isUnread, lockExclusive, lockExclusive, lockNonExclusive, modifyBookmark, modifyReadStatus, putLock, remove, setAttachments, setBehavior, setBranchOnChange, setComment, setExternalID, setExternalURL, setFixedConfiguration, setFloatingConfiguration, setRights, setValue, unlock, updateRevisionComment

Methods inherited from class com.starteam.VersionedObject

getBranchRevision, getRevisionNumber, getViewVersion, isFromHistory

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, getDisplayName, getDoubleValue, getEnumDisplayName, getEnumeratedValues, getIntegerValue, getLinkValue, getLongValue, getObjectID, getPossibleValues, getServer, getStringValue, getTimeSpanValue, getType, hasCachedProperties, hasValue, isNew, 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

Methods inherited from interface com.starteam.ISecurable

getServer, getType

Method Detail

getProperties

public ChangePackage.Type.PropertyCollection getProperties()

Returns the property collection for the ChangePackage Type

Returns:

the property collection for the ChangePackage Type

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. also, Enable or Disable Changes attached to this change package.

Overrides:

update in class ViewMember

See Also:

Change.setEnabled(boolean)

isDirty

public boolean isDirty()

Returns true if this change package has been modified, and requires an update() to save changes on the server.

Overrides:

isDirty in class TypedResource

Returns:

true if this change package requires an update().

See Also:

ChangePackage.update()

getName

public java.lang.String getName()

Each change package has a name that serves as a textual identification of the change package. By default, StarTeam generates a name that contains a timestamp, which helps prevent duplicate names. This property is the primary descriptor of the change package object.

Returns:

String

getValue

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

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

Overrides:

getValue in class ViewMember

Parameters:

property - the desired property

Returns:

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

Throws:

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

NoSuchPropertyException

getProcessItem

public Item getProcessItem()

returns the process item (if any) linked to this ChangePackage via a Trace

getDescription

public java.lang.String getDescription()

Provides a full description of the change package. A typical use of the description is to provide documentation not available in the process item attached to the change package, such as notes to testers, reviewers, or developers.

Returns:

String

setDescription

public void setDescription(java.lang.String description)

Provide a description for the change package

Parameters:

description - a description for the change package

getSessionType

public ChangePackage.SessionType getSessionType()

Defines the session type for the change package. One of: Promote, Rebase, Replicate or Checkin.

Returns:

ChangePackage.SessionType

getSourceView

public View getSourceView()

The source view for this change package.

Returns:

View

getTargetView

public View getTargetView()

The target view for this change package.

Returns:

View

getState

public ChangePackage.State getState()

Gets the current workflow state of the change package.

Returns:

ChangePackage.State

getResponsibility

public User getResponsibility()

Gets the user who is currently responsible for this change package. Returns null if no one is currently responsible. Note that the responsible user may be a deleted user.

Returns:

User

setResponsibility

public void setResponsibility(User user)

Set the user responsible for this change package

Parameters:

user - the user responsible for this change package

isMyResponsibility

public boolean isMyResponsibility()

Returns true if the logged in user is responsible for this ChangePackage

Returns:

true if the logged in user is responsible for this ChangePackage

getCommitTransaction

public Transaction getCommitTransaction()

The transaction in which this change package was committed, or null if it hasn't been committed yet.

Returns:

Transaction

isActive

public boolean isActive()

Returns true if this is an active ChangePackage

Returns:

true if this is an active ChangePackage

isCommitted

public boolean isCommitted()

Returns true if this is a committed ChangePackage

Returns:

true if this is a committed ChangePackage

getPreCommitViewLabel

public Label getPreCommitViewLabel()

The pre-commit view label. This label shows the initial state of the target view, before any changes were committed.

Returns:

The pre-commit view label, or null if changes have not been committed or this label was not enabled when the changes were committed.

See Also:

Session.isPreCommitViewLabelEnabled

getPostCommitViewLabel

public Label getPostCommitViewLabel()

The post-commit view label. This label shows the state of the target view just after the changes are committed.

The label is created at the start of the commit, and is updated as each change is merged to the target view. The difference between the pre- and post-commit view labels shows exactly which items were changed in the target view.

Returns:

The post-commit view label, or null if changes have not been committed or this label was not enabled when the changes were committed.

See Also:

Session.isPostCommitViewLabelEnabled

getPreCommitRevisionLabel

public Label getPreCommitRevisionLabel()

The pre-commit revision label.

This label is attached only to items that are changed or removed during the commit. It is attached to the item revision that is current prior to making the change.

The label will be created during the commit transaction, if the option is enabled.

Returns:

The pre-commit revision label, or null if changes have not been committed or this label was not enabled when the changes were committed.

See Also:

Session.isPreCommitRevisionLabelEnabled

getPostCommitRevisionLabel

public Label getPostCommitRevisionLabel()

The post-commit revision label, or null.

This label is attached only to items that are changed during the commit. It is attached to the item revision that is current just after making the change.

The label will be created during the commit transaction, if the option is enabled.

Returns:

The post-commit revision label, or null if changes have not been committed or this label was not enabled when the changes were committed.

See Also:

Session.isPostCommitRevisionLabelEnabled

toString

public java.lang.String toString()

Returns the ChangePackage name.

Overrides:

toString in class TypedResource

Returns:

the ChangePackage name.

getChanges

public ChangeCollection getChanges()

Gets the Change objects associated with this change package.

The returned collection is read-only. If the change package has not yet been committed, then you may add Change objects to the collection indirectly, using add. You may also explicitly populate, refresh or discard the Change objects through the cache service.

Returns:

ChangeCollection

open

public ChangeSession open()

Opens the session associated with this change package.

If the session is committed, it is opened in read-only mode. Otherwise, an attempt is made to open the session for writing.

When opening a session for writing, an exclusive lock is obtained. The lock is optionally released when the session is closed.

Returns:

ChangeSession

See Also:

ChangePackage.open(boolean), ChangeSession.close()

restore

public ChangeSession restore()

Opens and restores an uncommitted session associated with this change package.

The returned session is in a disconnected state. Operations that do not require a connection to the server will succeed

Returns:

ChangeSession

See Also:

ChangePackage.open(boolean), ChangePackage.open(), ChangePackage.restart(), ChangeSession.close()

restart

public ChangeSession restart()

Open the session associated with this change package The session is opened for writing, and is ready to re-run a compare in the current context of the source and target views

Returns:

ChangeSession

See Also:

ChangePackage.open(), ChangePackage.open(boolean)

open

public ChangeSession open(boolean isReadOnly)

Opens the session associated with this change package.

Note that a committed session can only be opened in read-only mode. When opening a session for writing, an exclusive lock is obtained. The lock is optionally released when the session is closed.

Parameters:

isReadOnly - true to open this session in read-only mode; false to open it for writing.

Returns:

ChangeSession

See Also:

ChangePackage.open(), ChangeSession.close()

resolve

public ViewMemberCollection resolve()

Gets the item revisions from the target view in the state they were in at the time the change package was committed.

Returns:

ViewMemberCollection

getReplaySources

public ChangePackageCollection getReplaySources()

Gets the set of change packages from which the given one was derived.

Note: The information about replay relationships is not cached, and is therefore fairly expensive to retrieve. The ReplayGraph class provides a way to fetch the replay information for a set of change packages in bulk, and cache it.

Returns:

ChangePackageCollection

getReplayTargets

public ChangePackageCollection getReplayTargets()

Gets the set of change packages representing replayed instances of the given one.

Note: The information about replay relationships is not cached, and is therefore fairly expensive to retrieve. The ReplayGraph class provides a way to fetch the replay information for a set of change packages in bulk, and cache it.

Returns:

ChangePackageCollection

rollback

public RollbackSession rollback()
                         throws java.io.IOException

rollback the contents of this change package on disk. only committed change packages can be rolled back. i.e remove strictly the revision content of each file in this change package from the corresponding matching 'tip' file on disk. The outcome of the rollback is a set of files in the local working folders on disk which create the impression that this particular change package was not committed. If this change package resulted in a newly created file in the server, then this file will be removed from the disk. Similarly, if this change package resulted in a file deleted from the server, then this file will be brought back to the disk. (however, this is an expensive operation) Binary files cannot be rolled back, in the sense that the changes made in the context of a particular change package cannot be determined by the StarTeam SDK Merge Engine. This implementation will revert any binary files to the revision prior to this change package. All subsequent edits or changes will be lost. Note specifically that no changes are made to the server. The application developer or user should commit the changed files after testing and verification, (creating a new change package in the process).

Throws:

java.io.IOException

rollback

public RollbackSession rollback(Encoding enc)
                         throws java.io.IOException

rollback the contents of this change package on disk. only committed change packages can be rolled back. i.e remove strictly the revision content of each file in this change package from the corresponding matching 'tip' file on disk. The outcome of the rollback is a set of files in the local working folders on disk which create the impression that this particular change package was not committed. If this change package resulted in a newly created file in the server, then this file will be removed from the disk. Similarly, if this change package resulted in a file deleted from the server, then this file will be brought back to the disk. (however, this is an expensive operation) Binary files cannot be rolled back, in the sense that the changes made in the context of a particular change package cannot be determined by the StarTeam SDK Merge Engine. This implementation will revert any binary files to the revision prior to this change package. All subsequent edits or changes will be lost. Note specifically that no changes are made to the server. The application developer or user should commit the changed files after testing and verification, (creating a new change package in the process).

Parameters:

enc - The Encoding to use when merging the content. specify NULL to use the platform encoding by default

Throws:

java.io.IOException