com.starteam
Class File

java.lang.Object
  com.starteam.TypedResource
      com.starteam.LiveObject
          com.starteam.TrackedObject
              com.starteam.VersionedObject
                  com.starteam.ViewMember
                      com.starteam.Item
                          com.starteam.File

All Implemented Interfaces:

ISecurable, Lockable, LockableObject, java.lang.Cloneable

public final class File
extends Item

Represents a StarTeam File item.

Nested Class Summary

static class	File.AddResult The class holds return information specific to the file add operation.
static class	File.CharacterSet The character set of a working file on disk.
static class	File.CheckInResult The class holds return information specific to the file checkin operation.
static class	File.CheckOutResult The class holds return information specific to the file checkout operation.
static class	File.Compression File compression level.
static interface	File.Digest The Digest interface specifies the necessary information to determine if a file on disk has changed from some checkpoint.
static class	File.EOLFormat The EOL format of a text file on disk.
static interface	File.Keyword A Keyword object that encapsulates information about a File keyword.
static class	File.KeywordFlag File keyword flag.
static class	File.KeywordReader Extends the java.io.Reader class to expand or unexpand keywords in a file or other data source.
static class	File.Result return information common to the file operations of add, checkin and checkout
static interface	File.Revision The Revision interface globally and uniquely identifies a specific revision of a StarTeam object.
static class	File.Status The current status of the file.
static class	File.StorageType The mechanism used to store this File content in the repository
static class	File.Stream Provides utility functions for manipulating File streams.
static class	File.SyncRecord a stock Sync Record Implementation to create sync records in syncdb
static class	File.Type The Type of File items.
static class	File.WebCacheFile File accessor for cached SDK Items contained objects are obtained from the artifact cache
static class	File.WebCacheWorkSpaceSync A serializable implementation of WorkspaceSync that can be used to calculate status through the WebCache Interfaces.
static interface	File.WorkspaceSync The WorkspaceSync interface specifies the pairing of the two important pieces of information needed to know what is on a user's local disk: Revision and Digest.

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

Item.WebCacheItem

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

long	computeCompareMD5(java.io.File workingFile, MD5 md5) Derives an MD5 signature of this file's working file on disk, if it were to be stored in the StarTeam repository.
void	convertArchive(boolean useDeltaStorage, int compressionLevel) This method causes the server to convert all versions stored in the archives associated with the file to the storage parameters specified.
void	convertToNativeIIArchive(boolean bDeleteOldArchives) Convert this File's archives to Native II format.
static File	create(Folder prnt) Create a File in the specified parent folder.
boolean	deleteLocalFile(java.io.File file) Deletes the specified local file and has the side effect of deleting sync information from the server about the file.
void	deleteSyncInfo(java.io.File file) Removes sync information from this File object's Server.
java.lang.String	getArchiveName() The file name of this file's archive file in the vault.
File.Keyword[]	getBlankKeywords() Returns an array of the default StarTeam keywords.
File.CharacterSet	getCharacterSet() Gets the character set used by this file.
File.Compression	getCompression() Gets the compression level of the archive file in the vault.
DateTime	getContentModifiedTime() Gets the "last modified" time of the working file when it was checked in to create this version.
int	getContentVersion() Gets the content version number for this file.
java.lang.String	getDescription() Returns the description of this file.
File.EOLFormat	getEOLFormat() Gets the end-of-line format used by this file's working files on disk.
java.lang.String	getExtension() Returns the file name extension.
File.WorkspaceSync	getFileSyncInfo(MD5 compareMD5, long compareSize, MD5 syncMD5, long syncSize, DateTime syncTime) Attempts to determine what version of the file is actually on disk.
java.lang.String	getFullName() Returns the concatenation of this file's name with the working directory of the file's parent folder.
int	getHiveID() Gets the ID of the hive where the archive file is stored in the vault.
File.KeywordFlag	getKeywordFlag() returns the KeywordFlag property value for this File
File.Status	getLastKnownStatus() Returns the last known status of the default working file relative to the file in the repository, using only information provided by the client during the last status update operation.
LocalFileSystemPropertyProvider	getLocalFileSystemPropertyProvider() Returns the registered provider for local file properties and synchronization status.
MD5	getMD5() The MD5 of the file contents for this version.
File	getMergeVersion() Returns a revision from this file's history that represents the most recent common ancestor of this file with the last known revision on disk.
java.lang.String	getName() Returns the name of this file.
File.Type.PropertyCollection	getProperties() Gets the PropertyCollection for this File.
long	getSize() The size of this file in the repository.
File.Status	getSmartStatus() Gets the status of the default working file relative to the latest version of this file in the repository.
File.Status	getSmartStatus(java.io.File file) Gets the status of the given working file relative to the latest version of this file in the repository.
File.Status	getStatus() Gets the status of the default working file relative to the latest version of this file in the repository.
File.Status	getStatus(java.io.File file) Gets the status of the given working file relative to the latest version of this file in the repository.
File.Status	getStatus(long size, DateTime lastModified) Returns the status of the default working file relative to the file in the repository, using the given size and last modified date of the file.
File.Status	getStatus(MD5 md5) Returns the status of the default working file relative to the file in the repository, using the given size MD5 signature of the file.
File.Status	getStatusNow() refresh the status information from the server and return it
int	getSyncBranchVersion() Gets the branch version of the last known revision of this file on disk.
int	getSyncContentVersion() Gets the content version of the last known revision of this file on disk.
MD5	getSyncMD5() Gets the MD5 of this file's last known revision on disk.
DateTime	getSyncModifiedTime() Gets the working file modified time of the last known revision of this file on disk.
long	getSyncSize() Gets the working file size of the last known revision of this file on disk.
int	getSyncViewVersion() Gets the view version of the last known revision of this file on disk.
boolean	getUsesKeywords() Tells whether or not this file will use keyword expansion.
int	getVaultVersion() Returns the vault version number for this file.
DateTime	getWorkingFileModifiedTime() Gets the local working file's modified time.
java.lang.String	getWorkingFileName() Gets the name of the local working file.
java.lang.String	getWorkingFilePath() Gets the full path to the local working file.
long	getWorkingFileSize() Gets the local working file's size, in bytes.
boolean	isBinary() Tells whether this file (in the repository) has been determined to be a binary file.
boolean	isExecutable() Determines whether or not this file has been marked executable in the repository.
static boolean	isFileContentMixedEOL(java.io.File f) Returns true if the file contains a mixed set of CRs, LFs and/or CRLF's Files that contain this pattern are automatically treated as BINARY files iff the Server Configuration Option MixedEOLAsBinary is set to true.
static boolean	isInSyncByMD5(java.io.File file, File.WorkspaceSync syncInfo) Determines whether or not the given file has the MD5 signature indicated in the given WorkspaceSync record.
static boolean	isInSyncByTime(java.io.File file, File.WorkspaceSync syncInfo) Determines whether or not the given file has the size and last modified date indicated in the given WorkspaceSync record.
boolean	isSyncInRevisionHistory() Determines whether or not the last known revision of this file on disk is somewhere in the file's linear revision history.
boolean	isSyncKnown() Determines whether or not information about the last known version on disk is available.
boolean	isUnicode() Tells whether this file (in the repository) has been determined to be a UNICODE file.
boolean	isWorkingFileAvailable() Determines whether or not the local working file exists on disk.
boolean	isWorkingFileExecutable() Determines whether or not the local working file is executable.
java.io.File	moveLocalFile(java.io.File fromFile, java.lang.String toFolderPath) Moves the local file to the specified folder and has the side effect of moving the status information from the original file to the newly created one Deletes the original file and it's status information at the end of the move
void	removeAndDeleteLocal() Removes the file item from its parent folder.
void	rename(java.lang.String newName) Renames this file to a new name along with the side effect of changing the corresponding local file's name as well.
void	resyncStatus(MD5 compareMD5, long compareSize, MD5 syncMD5, long syncSize, DateTime syncTime) Attempts to update the repository information about what version of the file is actually on disk.
void	setCharacterSet(File.CharacterSet s) Sets the character set used by this file.
void	setContentModifiedTime(DateTime time) Sets this file's content modification time.
void	setDescription(java.lang.String description) Sets the description of this file.
void	setEOLFormat(File.EOLFormat format) Sets the end-of-line format used by this file's working files on disk.
void	setExecutable(boolean isExecutable) Change this file executable marking in the repository.
void	setLocalFileSystemPropertyProvider(LocalFileSystemPropertyProvider provider) Registers a provider for local file properties and synchronization status.
void	setName(java.lang.String name) Sets a new name for this file.
java.lang.String	toString() Returns the name of this file.
File.Status	updateStatus() Attempts to update the repository information about what version of the file is actually on disk.
static void	updateStatus(File[] files, LocalFileSystemPropertyProvider aProvider) This method sets the status for each file item in an array.
void	updateStatus(long size, DateTime lastModified) Updates the server's status information to reflect the fact that the local file's content has the given size and last modified date.
void	updateStatus(long fileSize, DateTime lastModified, MD5 signature) Updates the server's status information to reflect the fact that the local file's content has the given size, last modified date, and MD5 signature.
void	updateStatus(MD5 signature) Updates the server's status information to reflect the fact that the local file's content has the given MD5 signature.
void	updateStatusAfterMerge() Updates the status information to reflect the fact that the local file's contents were derived from this file's contents.

Methods inherited from class com.starteam.Item

copy, deleteMergePoint, getCommonAncestor, getDebugString, getDisplayableProperties, getItemID, getMergeHistory, getNewRevisionComment, getParentContainer, getParentFolder, getParentFolderHierarchy, getParentFolderName, getParentFolderPath, getParentFolderQualifiedName, getSharedChangePackages, getSharedTraces, isEqualTo, isReverseShareRecommended, moveTo, recordMergePoint, remove, resolve, resolveMergePoint, resolveMergePointEx, reverseShareTo, reverseShareTo, shareTo, smartShareTo

Methods inherited from class com.starteam.ViewMember

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, getParentRevision, getPresentationID, getRights, getRootObjectID, getShare, getShare, getTraces, getValue, getView, getViewMemberRevisions, getViewVersion, getVMID, hashCode, hasPermissions, isBookmarked, isBranchable, isDeleted, isDisembodied, isEqualTo, isReadOnly, isRootShare, isUnread, lockExclusive, lockExclusive, lockNonExclusive, modifyBookmark, modifyReadStatus, putLock, setAttachments, setBehavior, setBranchOnChange, setComment, setExternalID, setExternalURL, setFixedConfiguration, setFloatingConfiguration, setRights, setValue, unlock, update, 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, isDirty, 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

create

public static File create(Folder prnt)

Create a File in the specified parent folder. When the file name property is set, there is an expectation that there is a working file on disk with this name, whose working path maps to the folder path of the specified parent folder

Parameters:

prnt - the parent folder

Returns:

a new File Object.

getFullName

public java.lang.String getFullName()

Returns the concatenation of this file's name with the working directory of the file's parent folder. This should return the full path to this file's working location on disk.

Returns:

the local file path to this file

Throws:

DisembodiedException - if this File is disembodied

See Also:

ViewMember.isDisembodied()

getProperties

public File.Type.PropertyCollection getProperties()

Gets the PropertyCollection for this File.

Returns:

the PropertyCollection for this File

getName

public java.lang.String getName()

Returns the name of this file. This is the name only--contrast with getFullName.

Returns:

the name of this file

See Also:

File.getFullName(), LiveObject.Type.NameProperty, File.Type.PropertyCollection.NAME

setName

public void setName(java.lang.String name)

Sets a new name for this file. To persist the change in the repository you must call update().

Parameters:

name - the new name of this file

See Also:

ViewMember.update(), LiveObject.Type.NameProperty, File.Type.PropertyCollection.NAME

getDescription

public java.lang.String getDescription()

Returns the description of this file.

Returns:

the description of this file

See Also:

LiveObject.Type.DescriptionProperty.NAME

setDescription

public void setDescription(java.lang.String description)

Sets the description of this file. To actually change the description in the repository you must call update() or one of the checkin methods.

Parameters:

description - the new description of this file

See Also:

LiveObject.Type.DescriptionProperty.NAME, ViewMember.update()

getVaultVersion

public int getVaultVersion()

Returns the vault version number for this file. The vault revision number is really an implementation detail of the StarTeam vault and the value of this property is not of much general use.

Returns:

the vault version number for this file

See Also:

File.Type.VaultVersionProperty

getContentVersion

public int getContentVersion()

Gets the content version number for this file. The first revision of any file item will have a value of 1 for this property. The value only changes when a new revision of the file is checked-in for which the file contents or the file name has changed. This value does not increment if only meta properties are modified (for example, the description). When a file item branches the value of this property does not revert to 1 but rather continues to increase as new revisions are added. This value is maintained in order to make status computation easier and more "accurate" (for example, a file should not need checkout if only its description changed).

Returns:

The content version number for this file

See Also:

File.Type.ContentVersionProperty, File.Type.PropertyCollection.CONTENT_VERSION, File.getStatus()

getContentModifiedTime

public DateTime getContentModifiedTime()

Gets the "last modified" time of the working file when it was checked in to create this version. Note that this value comes from the local machine where the checkin occured.

Returns:

The "last modified" time of the working file when this revision was checked in.

See Also:

File.Type.PropertyCollection.CONTENT_MODIFIFIED_TIME, File.setContentModifiedTime(DateTime)

setContentModifiedTime

public void setContentModifiedTime(DateTime time)

Sets this file's content modification time. You need to call update to persist this information. Note that the content modification time is automatically set by CheckinManager if file content is added or changed, from the file on disk last modified time However, this api may be explicitly used if an application chooses to update file properties directly without any content change

Parameters:

time - the content modification time for this file

See Also:

File.Type.PropertyCollection.CONTENT_MODIFIFIED_TIME, File.getContentModifiedTime()

getSize

public long getSize()

The size of this file in the repository. Note that this may be different than the size of the local file if end-of-line conversion or keyword expansion is used.

Returns:

the size of this file in the repository

See Also:

File.Type.SizeProperty, File.Type.PropertyCollection.SIZE

getArchiveName

public java.lang.String getArchiveName()

The file name of this file's archive file in the vault.

Returns:

The file name of this file's archive file in the vault.

See Also:

File.Type.ArchiveNameProperty, File.Type.PropertyCollection.ARCHIVE_NAME

getHiveID

public int getHiveID()

Gets the ID of the hive where the archive file is stored in the vault.

Returns:

The ID of the hive where the archive file is stored in the vault.

See Also:

File.Type.HiveProperty, File.Type.PropertyCollection.HIVE

getKeywordFlag

public File.KeywordFlag getKeywordFlag()

returns the KeywordFlag property value for this File

Returns:

the value of the KeywordFlag property

See Also:

File.Type.KeywordFlagProperty, File.Type.PropertyCollection.KEYWORD_FLAG

getMD5

public MD5 getMD5()

The MD5 of the file contents for this version. This is the value for the file contents in the repository which may differ from that of the corresponding file on disk if end-of-line or keyword expansion has been applied.

Returns:

the MD5 has bytes of the repository contents of this file

See Also:

File.Type.MD5Property, File.Type.PropertyCollection.MD5, MD5

getCompression

public File.Compression getCompression()

Gets the compression level of the archive file in the vault.

Returns:

The compression level of the archive file in the vault.

See Also:

File.Compression, File.Type.CompressionProperty, File.Type.PropertyCollection.COMPRESSION

getMergeVersion

public File getMergeVersion()

Returns a revision from this file's history that represents the most recent common ancestor of this file with the last known revision on disk. It may return null if the status is Unknown or if the sync version is not from the same version graph.

Returns:

the most recent common ancestor of this file and the last known version of this file on disk.

Throws:

DisembodiedException - if this File is disembodied

See Also:

ViewMember.isDisembodied()

isBinary

public boolean isBinary()

Tells whether this file (in the repository) has been determined to be a binary file. StarTeam flags a file as "binary" if any null (0x0) characters are found in the file.

Returns:

true if this repository file has been determined to be binary

See Also:

FileUtils.isBinary(java.io.File)

isUnicode

public boolean isUnicode()

Tells whether this file (in the repository) has been determined to be a UNICODE file.

Returns:

true if this repository file has been determined to be UNICODE

See Also:

FileUtils.isUnicode(byte[], int)

getCharacterSet

public File.CharacterSet getCharacterSet()

Gets the character set used by this file.

Returns:

The character set used by this file, or null if it is unknown.

See Also:

File.isBinary(), File.isUnicode(), File.Type.CharacterSetProperty, File.Type.PropertyCollection.CHARACTER_SET

setCharacterSet

public void setCharacterSet(File.CharacterSet s)

Sets the character set used by this file. The character set is normally determined automatically if it has not yet been specified by the time the file is checked in.

Parameters:

s - The character set. May not be null.

See Also:

File.Type.CharacterSetProperty, File.Type.PropertyCollection.CHARACTER_SET

getEOLFormat

public File.EOLFormat getEOLFormat()

Gets the end-of-line format used by this file's working files on disk. Supported only on StarTeam Server version 11.0 and later; on earlier servers, the value is always reported as null.

Returns:

The end-of-line format, or null if it has not yet been initialized.

See Also:

File.EOLFormat, File.Type.EOLFormatProperty, File.Type.PropertyCollection.EOL_FORMAT

setEOLFormat

public void setEOLFormat(File.EOLFormat format)

Sets the end-of-line format used by this file's working files on disk. Supported only on StarTeam Server version 11.0 and later.

Parameters:

format - The end-of-line format. Must not be null.

isExecutable

public boolean isExecutable()

Determines whether or not this file has been marked executable in the repository. Note that this doesn't mean the working file on disk is executable.

Returns:

true if the file has been marked executable in the repository; false otherwise.

See Also:

File.Type.IsExecutableProperty, File.Type.PropertyCollection.IS_EXECUTABLE

setExecutable

public void setExecutable(boolean isExecutable)

Change this file executable marking in the repository. Note that this doesn't affect the working file on disk

Parameters:

isExecutable - true if the file has been marked executable in the repository; false otherwise.

See Also:

File.Type.IsExecutableProperty, File.Type.PropertyCollection.IS_EXECUTABLE

rename

public void rename(java.lang.String newName)

Renames this file to a new name along with the side effect of changing the corresponding local file's name as well. This method does the same work as update() but also maintains the status information so that the newly renamed file will have the same status it did prior to the renaming. Simply using setName() and update() will not change the local file name consequently status information would be lost. NOTE: in the case where a file already exists with the new name, but it is not the same file as the old one [e.g., on Unix systems where only the case of the filenames differ], the local file will not be renamed, to avoid loss of data for users.

Parameters:

newName - the file's new name

convertArchive

public void convertArchive(boolean useDeltaStorage,
                           int compressionLevel)

This method causes the server to convert all versions stored in the archives associated with the file to the storage parameters specified. This can not be called for a not-in-view file (an exception will be thrown). A new file revision will be created. Note that archive conversion is irreversible in the sense that the archive cannot be restored to its original state if it contained versions using mixed storage options. Note also that the archive conversion may be a fairly long operation depending on the number and size of versions stored in the archive files.

Parameters:

useDeltaStorage - true if the archive should use delta storage

compressionLevel - desired compression level. This value must be one of the possible values for the Compression enumerated property.

convertToNativeIIArchive

public void convertToNativeIIArchive(boolean bDeleteOldArchives)

Convert this File's archives to Native II format. Available starting with server release 7.0

Parameters:

bDeleteOldArchives - True if old archives should be deleted, otherwise false.

isFileContentMixedEOL

public static boolean isFileContentMixedEOL(java.io.File f)
                                     throws java.io.IOException

Returns true if the file contains a mixed set of CRs, LFs and/or CRLF's Files that contain this pattern are automatically treated as BINARY files iff the Server Configuration Option MixedEOLAsBinary is set to true. The algorithm results in a short walk through the file until two consecutive EOL characters of different types are encountered. The algorithm will walk the entire file if the pattern is not encountered, such as would be the case for a 'regular' binary file with embedded NULLs, ASCII or UNICODE files.

Parameters:

f - the file whose content is to be tested

Returns:

true if the file contains a mixed bag of EOL characters

Throws:

java.io.IOException - if the file cannot be opened or processed completely

updateStatus

public File.Status updateStatus()
                         throws java.io.IOException

Attempts to update the repository information about what version of the file is actually on disk. This method will send the MD5 checksum of the file to the server to see if the contents exactly match any known version of the file. If it does match then the StarTeam Server will use that information for status computation. If the contents do not match any known version then the server's status information will remain unchanged.

Example uses of this would be if you copied the file to its new location through the OS rather than StarTeam the file's status would be "Unknown" If the local file had the same contents as the tip version of the file in the repository then further status computations would report the file as "Current".

Returns:

Status the status after the sync up, or NULL if the status cannot be predicted

Throws:

java.io.IOException - if an error occurs while reading the local file

DisembodiedException - if this File is disembodied

See Also:

ViewMember.isDisembodied(), File.getStatus()

resyncStatus

public void resyncStatus(MD5 compareMD5,
                         long compareSize,
                         MD5 syncMD5,
                         long syncSize,
                         DateTime syncTime)

Attempts to update the repository information about what version of the file is actually on disk.

This method is similar to updateStatus, except that information about the working file is provided explicitly by the caller. The working file itself is not used, and in fact does not need to be accessible. This is useful, for example, if the actual working file resides on a remote client workstation.

Parameters:

compareMD5 - The original MD5 signature of this file, as stored in the StarTeam repository. This is the signature that is compared against the signatures of the various revisions of this file, looking for a match. The compareMD5 signature may be different from the syncMD5 signature as a result of compensating for the effects of expanding keywords and performing end-of-line conversion on checkout. The compareMD5 signature is typically derived using File.Stream.computeCompareMD5().

compareSize - The original size of this file, as stored in the StarTeam repository. This may be different from syncSize as a result of compensating for the effects of expanding keywords and performing end-of-line conversion on checkout.

syncMD5 - The MD5 signature of the actual working file on disk. Typically derived using File.Stream.computeSyncMD5().

syncSize - The size of the actual working file on disk.

syncTime - The last modified date of the actual working file on disk.

Throws:

DisembodiedException - if this File is disembodied

See Also:

ViewMember.isDisembodied(), File.updateStatus(), File.getStatus(), File.Stream.computeCompareMD5(java.io.File, boolean, boolean, com.starteam.util.MD5), File.Stream.computeSyncMD5(java.io.File, com.starteam.util.MD5), File.Status

getFileSyncInfo

public File.WorkspaceSync getFileSyncInfo(MD5 compareMD5,
                                          long compareSize,
                                          MD5 syncMD5,
                                          long syncSize,
                                          DateTime syncTime)

Attempts to determine what version of the file is actually on disk.

This method is similar to resyncStatus, except that the status information is returned to the caller, rather than being cached with the Server object. This is useful for server-based applications running on behalf of a remote client, when running against a StarTeam server that supports client-managed status.

Parameters:

compareMD5 - The original MD5 signature of this file, as stored in the StarTeam repository. This is the signature that is compared against the signatures of the various revisions of this file, looking for a match. The compareMD5 signature may be different from the syncMD5 signature as a result of compensating for the effects of expanding keywords and performing end-of-line conversion on checkout. The compareMD5 signature is typically derived using File.Stream.computeCompareMD5().

compareSize - The original size of this file, as stored in the StarTeam repository. This may be different from syncSize as a result of compensating for the effects of expanding keywords and performing end-of-line conversion on checkout.

syncMD5 - The MD5 signature of the actual working file on disk. Typically derived using File.Stream.computeSyncMD5().

syncSize - The size of the actual working file on disk.

syncTime - The last modified date of the actual working file on disk.

Returns:

The file status information describing which version of the file is actually on disk. Returns null if the status information could not be determined.

Throws:

DisembodiedException - if this File is disembodied

See Also:

ViewMember.isDisembodied(), File.resyncStatus(com.starteam.util.MD5, long, com.starteam.util.MD5, long, com.starteam.util.DateTime), File.Stream.computeCompareMD5(java.io.File, boolean, boolean, com.starteam.util.MD5), File.Stream.computeSyncMD5(java.io.File, com.starteam.util.MD5), File.Status

removeAndDeleteLocal

public void removeAndDeleteLocal()
                          throws java.io.IOException

Removes the file item from its parent folder. Note that a file may be shared in another folder in the same or different view. This method will merely remove the one instance (or shared copy) that the method is called on. In addition, this method will delete the corresponding working file.

Throws:

java.io.IOException - if there is a problem deleting the local file

DisembodiedException - if this File is disembodied

See Also:

ViewMember.isDisembodied()

deleteLocalFile

public boolean deleteLocalFile(java.io.File file)
                        throws java.io.IOException

Deletes the specified local file and has the side effect of deleting sync information from the server about the file.

Parameters:

file - the local file to delete

Returns:

true if the file was deleted and false otherwise

Throws:

java.io.IOException - if the file is a directory or other error occurs trying to delete the file

DisembodiedException - if this File is disembodied

See Also:

ViewMember.isDisembodied()

moveLocalFile

public java.io.File moveLocalFile(java.io.File fromFile,
                                  java.lang.String toFolderPath)
                           throws java.io.IOException

Moves the local file to the specified folder and has the side effect of moving the status information from the original file to the newly created one Deletes the original file and it's status information at the end of the move

Parameters:

fromFile - the local file to be moved

toFolderPath - the folder to move it to.

Returns:

the file, after it has been moved to the new location

Throws:

java.io.IOException - if an unexpected error occurs in the process

deleteSyncInfo

public void deleteSyncInfo(java.io.File file)

Removes sync information from this File object's Server. Once it has been called the Status for file will be unknown. Use with caution.

Parameters:

file - the local file for which to delete status information

Throws:

DisembodiedException - if this File is disembodied

See Also:

ViewMember.isDisembodied()

updateStatus

public void updateStatus(long size,
                         DateTime lastModified)

Updates the server's status information to reflect the fact that the local file's content has the given size and last modified date.

The MD5 signature is assumed to be unknown, and any previously specified value will remain unchanged.

This is useful when the working file resides on a remote workstation, and the remote client is able to calculate the status parameters.

Parameters:

size - The size of the working file on disk.

lastModified - The last modified date of the working file.

Throws:

DisembodiedException - if this File is disembodied

See Also:

ViewMember.isDisembodied(), File.getStatus(), File.updateStatus(), File.resyncStatus(com.starteam.util.MD5, long, com.starteam.util.MD5, long, com.starteam.util.DateTime), File.Status

updateStatus

public void updateStatus(MD5 signature)

Updates the server's status information to reflect the fact that the local file's content has the given MD5 signature.

The file size and last modified date are assumed to be unknown. Any previously specified values will remain unchanged.

This is useful when the working file resides on a remote workstation, and the remote client is able to calculate the status parameters.

Parameters:

signature - The MD5 signature of the working file.

Throws:

DisembodiedException - if this File is disembodied

See Also:

ViewMember.isDisembodied(), File.getStatus(), File.updateStatus(), File.resyncStatus(com.starteam.util.MD5, long, com.starteam.util.MD5, long, com.starteam.util.DateTime), File.Status

updateStatus

public void updateStatus(long fileSize,
                         DateTime lastModified,
                         MD5 signature)

Updates the server's status information to reflect the fact that the local file's content has the given size, last modified date, and MD5 signature.

This is useful when the working file resides on a remote workstation, and the remote client is able to calculate the status parameters.

Parameters:

fileSize - The size of the working file on disk. A negative value indicates that the size is unknown.

lastModified - The last modified date of the working file. null indicates that the last modified date is unknown.

signature - The MD5 signature of the working file. null indicates that the signature is unknown. Use null DateTime to indicate last modified time is unknown.

Throws:

DisembodiedException - if this File is disembodied

See Also:

ViewMember.isDisembodied(), File.updateStatus(), File.resyncStatus(com.starteam.util.MD5, long, com.starteam.util.MD5, long, com.starteam.util.DateTime), File.Status

updateStatusAfterMerge

public void updateStatusAfterMerge()
                            throws java.io.IOException

Updates the status information to reflect the fact that the local file's contents were derived from this file's contents. You would most commonly want to call this after merging in changes. This file's status will be "Modified" after a call to this method if this file is the tip version of the file.

Throws:

java.io.IOException - if there are problems reading the local file

DisembodiedException - if this File is disembodied

See Also:

ViewMember.isDisembodied()

getSyncViewVersion

public int getSyncViewVersion()

Gets the view version of the last known revision of this file on disk.

Returns:

The view version of the last known revision of this file on disk, or -1 if unknown.

See Also:

File.Type.SyncViewVersionProperty, File.Type.PropertyCollection.SYNC_VIEW_VERSION, ViewMember.getViewVersion()

getStatus

public File.Status getStatus()
                      throws java.io.IOException

Gets the status of the default working file relative to the latest version of this file in the repository.

Status is determined by comparing the current size and last modified time with that of the last known revision on disk.

Returns:

The current status of this file.

Throws:

java.io.IOException - if an error occurs while reading the local file

See Also:

File.Status, File.getStatus(java.io.File file), File.getSmartStatus()

getStatus

public File.Status getStatus(java.io.File file)
                      throws java.io.IOException

Gets the status of the given working file relative to the latest version of this file in the repository.

Status is determined by comparing the current size and last modified time with that of the last known revision on disk.

Parameters:

file - The working file whose status is to be determined.

Returns:

The current status of this file.

Throws:

java.io.IOException - if an error occurs while reading the local file

See Also:

File.Status, File.getSmartStatus(java.io.File file)

getSmartStatus

public File.Status getSmartStatus()
                           throws java.io.IOException

Gets the status of the default working file relative to the latest version of this file in the repository.

Status is determined by comparing the current size and last modified time with that of the last known revision on disk. However, if the working file differs only in modified time, then the equivalent of an "Update Status" is performed. This gives a more accurate status in cases where the file content has not actually changed.

Returns:

The current status of this file.

Throws:

java.io.IOException - if an error occurs while reading the local file

See Also:

File.Status, File.getStatus()

getSmartStatus

public File.Status getSmartStatus(java.io.File file)
                           throws java.io.IOException

Gets the status of the given working file relative to the latest version of this file in the repository.

Status is determined by comparing the current size and last modified time with that of the last known revision on disk. However, if the working file differs only in modified time, then the equivalent of an "Update Status" is performed. This gives a more accurate status in cases where the file content has not actually changed.

Parameters:

file - The working file whose status is to be determined.

Returns:

The current status of this file.

Throws:

java.io.IOException - if an error occurs while reading the local file

See Also:

File.Status, File.getStatus(java.io.File file)

getStatusNow

public File.Status getStatusNow()
                         throws java.io.IOException

refresh the status information from the server and return it

Returns:

this file's status after refreshing status information from the server

Throws:

java.io.IOException - if there are any problems reading the local file

See Also:

File.Status

getLastKnownStatus

public File.Status getLastKnownStatus()

Returns the last known status of the default working file relative to the file in the repository, using only information provided by the client during the last status update operation. Assumes the working file is not available locally (for example, it might reside on a remote client workstation).

Returns:

The status code for this file

getStatus

public File.Status getStatus(long size,
                             DateTime lastModified)

Returns the status of the default working file relative to the file in the repository, using the given size and last modified date of the file. Assumes the working file is not available locally (for example, it might reside on a remote client workstation).

Parameters:

size - The size of the working file on disk.

lastModified - The last modified date of the working file.

Returns:

The status code for this file.

See Also:

File.getStatus(), File.updateStatus(), File.resyncStatus(com.starteam.util.MD5, long, com.starteam.util.MD5, long, com.starteam.util.DateTime), File.Status

isInSyncByTime

public static boolean isInSyncByTime(java.io.File file,
                                     File.WorkspaceSync syncInfo)
                              throws java.io.IOException

Determines whether or not the given file has the size and last modified date indicated in the given WorkspaceSync record.

Parameters:

file - A working file.

syncInfo - File synchronization information.

Returns:

True if the given file is in sync with respect to size and last modified date; false otherwise.

Throws:

java.io.IOException

getStatus

public File.Status getStatus(MD5 md5)

Returns the status of the default working file relative to the file in the repository, using the given size MD5 signature of the file. Assumes the working file is not available locally (for example, it might reside on a remote client workstation).

Parameters:

md5 - The MD5 signature of the working file, or null if the signature is unknown or unchanged.

Returns:

The status code for this file.

See Also:

File.getStatus(), File.updateStatus(), File.resyncStatus(com.starteam.util.MD5, long, com.starteam.util.MD5, long, com.starteam.util.DateTime), File.Status

isInSyncByMD5

public static boolean isInSyncByMD5(java.io.File file,
                                    File.WorkspaceSync syncInfo)
                             throws java.io.IOException

Determines whether or not the given file has the MD5 signature indicated in the given WorkspaceSync record.

Parameters:

file - A working file.

syncInfo - File synchronization information.

Returns:

True if the given file is in sync with respect to MD5 signature; false otherwise.

Throws:

java.io.IOException

computeCompareMD5

public long computeCompareMD5(java.io.File workingFile,
                              MD5 md5)
                       throws java.io.IOException

Derives an MD5 signature of this file's working file on disk, if it were to be stored in the StarTeam repository.

Compensates for the effects of expanding keywords and performing end-of-line conversion on checkout.

Parameters:

workingFile - The working file whose MD5 is to be calculated, or null to use the default working file.

md5 - A newly initialized MD5 signature. On output, contains the MD5 signature calculated from the file's content, adjusted as determined by bUsesKeywords and bConvertEOL.

Returns:

The number of bytes in the as it would be stored in the StarTeam repository. #getMD5

Throws:

java.io.IOException

See Also:

File.resyncStatus(com.starteam.util.MD5, long, com.starteam.util.MD5, long, com.starteam.util.DateTime), File.Status

getBlankKeywords

public File.Keyword[] getBlankKeywords()

Returns an array of the default StarTeam keywords. All the keywords are "blank" meaning no values are filled in. This can be used to unexpand keywords in a file where the actual keyword values are not needed.

Returns:

an array of blank StarTeam keywords

See Also:

File.getUsesKeywords(), File.Keyword

getUsesKeywords

public boolean getUsesKeywords()

Tells whether or not this file will use keyword expansion. This is determined by looking at the project's keyword properties and this file's extension.

Returns:

true if this file uses keyword expansion

Throws:

DisembodiedException - if this File is disembodied

See Also:

ViewMember.isDisembodied()

toString

public java.lang.String toString()

Returns the name of this file.

Overrides:

toString in class Item

Returns:

the name of this file

getExtension

public java.lang.String getExtension()

Returns the file name extension. E.g. for "foo.txt" this would return "txt", for "foo" it would return the empty string.

Returns:

the file name extension.

See Also:

File.Type.ExtensionProperty.NAME

isSyncKnown

public boolean isSyncKnown()

Determines whether or not information about the last known version on disk is available. Returns true if we have information about the last known version on disk; false otherwise.

See Also:

File.Type.IsSyncKnownProperty, File.Type.PropertyCollection.IS_SYNC_KNOWN

isWorkingFileAvailable

public boolean isWorkingFileAvailable()

Determines whether or not the local working file exists on disk.

Returns:

true if the local working file exists on disk.

See Also:

File.Type.IsWorkingFileAvailableProperty, File.Type.PropertyCollection.IS_WORKING_FILE_AVAILABLE

isWorkingFileExecutable

public boolean isWorkingFileExecutable()
                                throws java.io.IOException

Determines whether or not the local working file is executable.

Returns:

true if the local working file is executable.

Throws:

java.io.IOException - if any file system error occurs.

See Also:

File.Type.IsWorkingFileExecutableProperty, File.Type.PropertyCollection.IS_WORKING_FILE_EXECUTABLE

getWorkingFileName

public java.lang.String getWorkingFileName()
                                    throws java.io.IOException

Gets the name of the local working file.

Returns:

The name of the local working file, as recognized by the local file system. On case insensitive platforms (like Windows), the working file name can differ in case from the file name property stored in the repository

Throws:

java.io.IOException - if any file system error occurs.

See Also:

File.Type.WorkingFileNameProperty, File.Type.PropertyCollection.WORKING_FILE_NAME

getWorkingFilePath

public java.lang.String getWorkingFilePath()
                                    throws java.io.IOException

Gets the full path to the local working file.

Returns:

The full path to the local working file, as recognized by the local file system. On case insensitive platforms (like Windows), the working folder name can differ in case from the folder path property stored in the repository

Throws:

java.io.IOException - if any file system error occurs.

See Also:

File.Type.WorkingFilePathProperty, File.Type.PropertyCollection.WORKING_FILE_PATH

getWorkingFileModifiedTime

public DateTime getWorkingFileModifiedTime()
                                    throws java.io.IOException

Gets the local working file's modified time.

Returns:

The local working file's modified time, or VALUE_NOT_SET if the working file is missing.

Throws:

java.io.IOException

See Also:

File.Type.WorkingFileModifiedTimeProperty.NAME

getWorkingFileSize

public long getWorkingFileSize()

Gets the local working file's size, in bytes.

Returns:

The local working file's size, in bytes, or -1 if the file doesn't exist.

See Also:

File.Type.WorkingFileSizeProperty, File.Type.PropertyCollection.WORKING_FILE_SIZE

isSyncInRevisionHistory

public boolean isSyncInRevisionHistory()

Determines whether or not the last known revision of this file on disk is somewhere in the file's linear revision history.

For example, if the current revision of this file is "1.5.1.4", then the following revisions would be in the file's linear revision history: "1.0", "1.1", "1.2", "1.3", "1.4", "1.5", "1.5.1.0", "1.5.1.1", "1.5.1.2", "1.5.1.3", "1.5.1.4".

All other revisions would not be in the file's linear revision history..

Returns:

true if the last known revision of this file on disk is somewhere in the file's linear revision history.

getSyncBranchVersion

public int getSyncBranchVersion()

Gets the branch version of the last known revision of this file on disk.

The branch version is the final number in the notation. For example, the branch version of "1.1" is 1; the branch version of "1.2.4.7" is 7.

Returns:

The branch version of the last known revision of this file on disk, or -1 if unknown.

See Also:

File.Type.SyncBranchVersionProperty, File.Type.PropertyCollection.SYNC_BRANCH_VERSION

getSyncContentVersion

public int getSyncContentVersion()

Gets the content version of the last known revision of this file on disk.

Returns:

The content version of the last known revision of this file on disk, or -1 if unknown.

See Also:

File.Type.SyncContentVersionProperty, File.Type.PropertyCollection.SYNC_CONTENT_VERSION, File.getContentVersion()

getSyncSize

public long getSyncSize()

Gets the working file size of the last known revision of this file on disk. This is often different from the size of the file as stored in the StarTeam repository, due to the effects of keyword expansion and end-of-line conversion on the working file.

Returns:

The working file size of the last known revision of this file on disk, or -1 if unknown.

See Also:

File.Type.SyncSizeProperty, File.Type.PropertyCollection.SYNC_SIZE

getSyncModifiedTime

public DateTime getSyncModifiedTime()

Gets the working file modified time of the last known revision of this file on disk.

Returns:

The working modified time of the last known revision of this file on disk, or null if unknown.

See Also:

File.Type.SyncModifiedTimeProperty.NAME

getSyncMD5

public MD5 getSyncMD5()

Gets the MD5 of this file's last known revision on disk. This is often different from the MD5 of the file as stored in the StarTeam repository, due to the effects of keyword expansion and end-of-line conversion on the working file.

Returns:

The MD5 of this file's last known revision on disk, or null if the MD5 is unknown.

See Also:

File.Type.SyncMD5Property.NAME

setLocalFileSystemPropertyProvider

public void setLocalFileSystemPropertyProvider(LocalFileSystemPropertyProvider provider)

Registers a provider for local file properties and synchronization status. This provider could be used for caching local file properties like file size, date of last modification, and synchronization status. These can then be retrieved with minimal disk I/O operations. Another use could be for implementing virtual file system support. If an application registers a provider for local file properties, then calls to local file properties on this File Object will return their values through the provider. Hence, the provider implementation must be robust and unequivocally accurate.

Parameters:

provider - LocalFileSystemPropertyProvider provider, the file property provider to register for use by this File object.

See Also:

File.getStatus(), File.getWorkingFileName(), File.getWorkingFilePath(), File.getWorkingFileSize(), File.isWorkingFileExecutable()

getLocalFileSystemPropertyProvider

public LocalFileSystemPropertyProvider getLocalFileSystemPropertyProvider()

Returns the registered provider for local file properties and synchronization status.

Returns:

FilePropertyProvider provider, the file property provider to registered for use by this File object.

See Also:

File.setLocalFileSystemPropertyProvider(LocalFileSystemPropertyProvider)

updateStatus

public static void updateStatus(File[] files,
                                LocalFileSystemPropertyProvider aProvider)

This method sets the status for each file item in an array. It uses several techniques to optimize for speed. 1. It is assumed that all status helpers have the correct file attributes set. This avoids local disk access for checking file and folder existence, unless absolutely necessary. 2. The given array should contains all the files for one or more folders, with files of the same folder grouped together. This allows internal tests to be performed on a per folder basis. The caller is responsible for ensuring that files are grouped by folder, to take full advantage of the performance shortcuts being used. for files that have no provider.

Parameters:

files - the files to be processed for changed attributes.

aProvider - the LocalFileSystemPropertyProvider whose status needs updating