public interface IFileSpec extends IFileOperationResult
The various IFileSpec methods generally correspond closely to the similarly-named fields or attributes given in the general Perforce documentation, and will not be discussed in great detail here. Note that many of them are only set in response to a specific server or client method call, and, in general, only the file's path needs to be set to be usable as input to these methods. Conversely, some of the fields defined below are only relevant for integration actions, resolve results, etc.
The main complexity in this interface is the variety of file spec paths and associated gubbins: in general, a Perforce file specification can have all four or none of depot, client, and local paths plus an "original" path (see below) valid (or some such combination), and the IFileSpec methods allow you to create specifications from a specific type of path, and / or to specify which paths in the specification are valid -- see the IFileSpecPathSpec enum defined below. "Original" file paths are the paths used to create the file spec in the first place, and are generally used as the preferred path for operations (but see below). File specs may not even have original paths, and / or may have all four path types set, depending on the circumstances of the file spec's creation and subsequent history.
Additionally, the getPreferedPath() method allows a user to retrieve the "correct" path based on a simple set of rules if you've lost track of which path is valid.
IFileSpec may be extended for other uses (see e.g. IExtendedFileSpec as used by the IServer.getExtendedFiles() method.
Note that although IFileSpec (indirectly) extends the IServerResource interface, current implementations are not refreshable, updateable, or completable, and isComplete() will currently always return true.
Note also that the field setter methods below have local effect only.
Modifier and Type | Field and Description |
---|---|
static int |
HAVE_REVISION
The symbolic value used to signal the "have" revision.
|
static java.lang.String |
HAVE_REVISION_STRING
The string used by the Perforce server to signal a "have" revision.
|
static int |
HEAD_REVISION
The symbolic value used to signal the head revision.
|
static java.lang.String |
HEAD_REVISION_STRING
The string used by the Perforce server to signal a head revision.
|
static int |
NO_FILE_REVISION
Value that signals that no Perforce file revision is (currently)
associated with a file spec.
|
static java.lang.String |
NO_REVISION_STRING
String representation for the NO_FILE_REVISION value.
|
static int |
NONE_REVISION
Value used to signal "none" file revision explicitly.
|
static java.lang.String |
NONE_REVISION_STRING
The string used by the Perforce server to signal no revision specified.
|
Modifier and Type | Method and Description |
---|---|
FileAction |
getAction() |
java.lang.String |
getAnnotatedPathString(FilePath.PathType pathType)
Get an annotated string representation of a Perforce file
path associated with this Perforce file spec.
|
java.lang.String |
getAnnotatedPreferredPathString()
Get the annotated "preferred" path string for this file spec.
|
java.util.List<IFileAnnotation> |
getAnnotations(DiffType wsOptions,
boolean allResults,
boolean useChangeNumbers,
boolean followBranches)
Get the file annotations associated with this file.
|
java.util.List<IFileAnnotation> |
getAnnotations(GetFileAnnotationsOptions opts)
Get the file annotations associated with this file.
|
java.lang.String |
getBaseFile() |
java.lang.String |
getBaseName() |
int |
getBaseRev() |
java.lang.String |
getBlobSha() |
java.lang.String |
getBranch() |
int |
getChangelistId()
Get the ID of the changelist associated with this file spec.
|
java.lang.String |
getClientName() |
FilePath |
getClientPath()
Convenience method for getPath(CLIENT).
|
java.lang.String |
getClientPathString()
Convenience method for getPathString(CLIENT).
|
java.lang.String |
getCommitSha() |
java.lang.String |
getContentResolveType() |
java.io.InputStream |
getContents(boolean noHeaderLine)
Get the contents of this specific Perforce file revision from the Perforce
depot as an InputStream.
|
java.io.InputStream |
getContents(GetFileContentsOptions opts)
Get the contents of this specific Perforce file revision from the Perforce
depot as an InputStream.
|
java.util.Date |
getDate()
Get the Perforce date of this file spec.
|
FilePath |
getDepotPath()
Convenience method for getPath(DEPOT).
|
java.lang.String |
getDepotPathString()
Convenience method for getPathString(DEPOT).
|
java.lang.String |
getDiffStatus()
Get the diff status for this file spec.
|
int |
getEndFromRev() |
int |
getEndRevision()
Get the end revision for this file spec, if any.
|
int |
getEndToRev() |
java.lang.String |
getFileType() |
java.lang.String |
getFromFile() |
java.lang.String |
getHowResolved() |
java.lang.String |
getLabel() |
FilePath |
getLocalPath()
Convenience method for getPath(LOCAL).
|
java.lang.String |
getLocalPathString()
Convenience method for getPathString(LOCAL).
|
FilePath |
getOriginalPath()
Convenience method for getPath(ORIGINAL).
|
java.lang.String |
getOriginalPathString()
Convenience method for getPathString(ORIGINAL).
|
FileAction |
getOtherAction() |
FilePath |
getPath(FilePath.PathType pathType)
Get the specific depot, client, local, or original Perforce file path
associated with this file spec.
|
java.lang.String |
getPathString(FilePath.PathType pathType)
Get the unannotated path string for this Perforce file.
|
FilePath |
getPreferredPath()
Get the "preferred" path for this file spec.
|
java.lang.String |
getPreferredPathString()
Get the (unannotated) "preferred" path string for this file spec.
|
java.lang.String |
getRepoName() |
java.lang.String |
getResolveType() |
java.util.List<java.lang.String> |
getResolveTypes() |
java.util.Map<IFileSpec,java.util.List<IFileRevisionData>> |
getRevisionHistory(GetRevisionHistoryOptions opts)
Get the revision history of this Perforce file.
|
java.util.Map<IFileSpec,java.util.List<IFileRevisionData>> |
getRevisionHistory(int maxRevs,
boolean contentHistory,
boolean includeInherited,
boolean longOutput,
boolean truncatedLongOutput)
Get the revision history of this Perforce file.
|
java.lang.String |
getSha() |
int |
getShelvedChange() |
int |
getStartFromRev() |
int |
getStartRevision() |
int |
getStartToRev() |
long |
getSyncTime() |
java.lang.String |
getToFile() |
java.lang.String |
getTreeSha() |
java.lang.String |
getUserName() |
int |
getWorkRev() |
boolean |
isLocked() |
boolean |
isUnmap() |
java.util.List<IFileSpec> |
move(IFileSpec toFile,
MoveFileOptions opts)
Move this file if it's already opened for edit or add (the fromFile) to the destination
file (the toFile).
|
java.util.List<IFileSpec> |
move(int changelistId,
boolean listOnly,
boolean noClientMove,
java.lang.String fileType,
IFileSpec toFile)
Move this file if it's already opened for edit or add (the fromFile) to the destination
file (the toFile).
|
void |
setAction(FileAction action)
Set the file action for this file spec.
|
void |
setBaseFile(java.lang.String basefile)
Set the base file on this object.
|
void |
setBaseName(java.lang.String basename)
Set the base name on this object.
|
void |
setBaseRev(int rev)
Set the base revision on this object.
|
void |
setBlobSha(java.lang.String sha) |
void |
setBranch(java.lang.String branch) |
void |
setChangelistId(int id)
Set the changelist ID for this file spec.
|
void |
setClientName(java.lang.String clientName)
Set the Perforce client name for this file spec.
|
void |
setClientPath(java.lang.String pathStr)
Convenience method for setPath(new FilePath(PathType.CLIENT, pathStr));
|
void |
setCommitSha(java.lang.String sha) |
void |
setContentResolveType(java.lang.String contentResolveType)
Set the content resolve type for this file spec.
|
void |
setDate(java.util.Date date)
Set the date for this file spec.
|
void |
setDepotPath(java.lang.String pathStr)
Convenience method for setPath(new FilePath(PathType.DEPOT, pathStr));
|
void |
setDiffStatus(java.lang.String status)
Set the diff status for this file spec.
|
void |
setEndFromRev(int rev)
Set the end from revision for this file spec.
|
void |
setEndRevision(int rev)
Set the end revision for this file spec.
|
void |
setEndToRev(int rev)
Set the end to revision for this file spec.
|
void |
setFileType(java.lang.String type)
Set the file type for this file spec.
|
void |
setFromFile(java.lang.String pathStr)
Set the from file for this file spec.
|
void |
setHowResolved(java.lang.String howStr)
Set the "how resolved" string for this file spec.
|
void |
setLabel(java.lang.String label)
Set the label associated with this file spec.
|
void |
setLocalPath(java.lang.String pathStr)
Convenience method for setPath(new FilePath(PathType.LOCAL, pathStr));
|
void |
setLocked(boolean locked)
Set the locked status for this file spec.
|
void |
setOriginalPath(java.lang.String pathStr)
Convenience method for setPath(new FilePath(PathType.ORIGINAL, pathStr));
|
void |
setOtherAction(FileAction action)
Set the other action for this file spec.
|
void |
setPath(FilePath path)
Set a Perforce file path associated with this file spec.
|
void |
setPathFromString(FilePath.PathType pathType,
java.lang.String pathStr)
Set a specific Perforce file path for this file spec from a passed-in
string.
|
void |
setRepoName(java.lang.String repoName) |
void |
setResolveType(java.lang.String resolveType)
Set the resolve type for this file spec.
|
void |
setResolveTypes(java.util.List<java.lang.String> types) |
void |
setSha(java.lang.String sha) |
void |
setShelvedChange(int shelvedChange)
Set the shelved change for this file spec.
|
void |
setStartFromRev(int rev)
Set the end from revision for this file spec.
|
void |
setStartRevision(int rev)
Set the start revision for this file spec.
|
void |
setStartToRev(int rev)
Set the start to revision for this file spec.
|
void |
setSyncTime(long syncTime) |
void |
setToFile(java.lang.String pathStr)
Set the to file for this file spec.
|
void |
setTreeSha(java.lang.String sha) |
void |
setUnmap(boolean unmap)
Set the unmap status value for this file spec.
|
void |
setUserName(java.lang.String userName)
Set the Perforce user name for this file spec.
|
void |
setWorkRev(int rev)
Set the work revision for this file spec.
|
java.lang.String |
toString()
Useful alias for getPreferredPathString().
|
getGenericCode, getOpStatus, getRawCode, getSeverityCode, getStatusMessage, getSubCode, getSubSystem, getUniqueCode
canRefresh, canUpdate, clearRawFields, complete, getRawField, getRawFields, hasRawField, refresh, setRawField, setRawFields, setServer, update, update, update
static final int NO_FILE_REVISION
Note that this is distinct from specifying "#none" or "#0" explicitly, which is dealt with by the NONE_FILE_REVISION below.
static final java.lang.String NO_REVISION_STRING
static final int NONE_REVISION
static final java.lang.String NONE_REVISION_STRING
static final int HEAD_REVISION
static final java.lang.String HEAD_REVISION_STRING
static final int HAVE_REVISION
static final java.lang.String HAVE_REVISION_STRING
FilePath getPath(FilePath.PathType pathType)
pathType
- if null or PathType.ORIGINAL, return the original
path for this file spec, otherwise return the specified
path for this file spec.void setPath(FilePath path)
path
- candidate file path; may be null.void setOriginalPath(java.lang.String pathStr)
pathStr
- pathvoid setDepotPath(java.lang.String pathStr)
pathStr
- pathvoid setClientPath(java.lang.String pathStr)
pathStr
- pathvoid setLocalPath(java.lang.String pathStr)
pathStr
- pathjava.lang.String getAnnotatedPathString(FilePath.PathType pathType)
pathType
- if null or PathType.ORIGINAL, return the original
path for this file spec, otherwise return the specified
path for this file spec.java.lang.String getPathString(FilePath.PathType pathType)
pathType
- if null or PathType.ORIGINAL, return the original
path for this file spec, otherwise return the specified
path for this file spec.void setPathFromString(FilePath.PathType pathType, java.lang.String pathStr)
pathType
- if null or PathType.ORIGINAL, sets the original
path for this file spec, otherwise sets the specified
path for this file spec.pathStr
- possibly-null, possibly-annotated path stringFilePath getOriginalPath()
java.lang.String getOriginalPathString()
FilePath getDepotPath()
java.lang.String getDepotPathString()
FilePath getClientPath()
java.lang.String getClientPathString()
FilePath getLocalPath()
java.lang.String getLocalPathString()
int getStartRevision()
void setStartRevision(int rev)
rev
- revisionint getEndRevision()
void setEndRevision(int rev)
rev
- revisionint getChangelistId()
void setChangelistId(int id)
id
- changejava.util.Date getDate()
void setDate(java.util.Date date)
date
- dateboolean isLocked()
void setLocked(boolean locked)
locked
- lockedjava.lang.String getDiffStatus()
void setDiffStatus(java.lang.String status)
status
- statusjava.lang.String getResolveType()
void setResolveType(java.lang.String resolveType)
resolveType
- resolve typejava.lang.String getContentResolveType()
void setContentResolveType(java.lang.String contentResolveType)
contentResolveType
- contentResolveTypeint getShelvedChange()
void setShelvedChange(int shelvedChange)
shelvedChange
- shelvedChangeFileAction getAction()
void setAction(FileAction action)
action
- actionjava.lang.String getLabel()
void setLabel(java.lang.String label)
label
- labeljava.lang.String getFileType()
void setFileType(java.lang.String type)
type
- typejava.lang.String getUserName()
void setUserName(java.lang.String userName)
userName
- userNamejava.lang.String getClientName()
void setClientName(java.lang.String clientName)
clientName
- clientNameboolean isUnmap()
void setUnmap(boolean unmap)
unmap
- unmapFilePath getPreferredPath()
java.lang.String getAnnotatedPreferredPathString()
java.lang.String getPreferredPathString()
java.lang.String toString()
toString
in class java.lang.Object
java.lang.String getFromFile()
void setFromFile(java.lang.String pathStr)
pathStr
- pathStrint getEndFromRev()
void setEndFromRev(int rev)
rev
- revint getStartFromRev()
void setStartFromRev(int rev)
rev
- revjava.lang.String getToFile()
void setToFile(java.lang.String pathStr)
pathStr
- pathStrint getStartToRev()
void setStartToRev(int rev)
rev
- revint getEndToRev()
void setEndToRev(int rev)
rev
- revjava.lang.String getHowResolved()
void setHowResolved(java.lang.String howStr)
howStr
- howStrint getWorkRev()
void setWorkRev(int rev)
rev
- revFileAction getOtherAction()
void setOtherAction(FileAction action)
action
- actionint getBaseRev()
void setBaseRev(int rev)
rev
- revjava.lang.String getBaseName()
void setBaseName(java.lang.String basename)
basename
- basenamejava.lang.String getBaseFile()
void setBaseFile(java.lang.String basefile)
basefile
- basefilejava.util.Map<IFileSpec,java.util.List<IFileRevisionData>> getRevisionHistory(int maxRevs, boolean contentHistory, boolean includeInherited, boolean longOutput, boolean truncatedLongOutput) throws ConnectionException, RequestException, AccessException
Note that the revision history returned may contain more than one file if the includeInherited option is true; this is why the return is a map (keyed on depot file path) of revision lists rather than a simple list.
Behavior is undefined if both longOutput and truncatedLongOutput are true. If both are false, a short form of the description (prepared by the server) is returned.
maxRevs
- if positive, return at most maxRev revisions for this file.contentHistory
- if true, return the content historyincludeInherited
- if true, causes inherited file history to be returned as well.longOutput
- if true, return the full descriptions associated with each revisiontruncatedLongOutput
- if true, return only the first 250 characters of each description.ConnectionException
- if the Perforce server is unreachable or is not
connected.RequestException
- if the Perforce server encounters an error during
its processing of the requestAccessException
- if the Perforce server denies access to the callerjava.util.Map<IFileSpec,java.util.List<IFileRevisionData>> getRevisionHistory(GetRevisionHistoryOptions opts) throws P4JavaException
Note that the revision history returned may contain more than one file if the includeInherited option is true; this is why the return is a map (keyed on depot file path) of revision lists rather than a simple list.
Behavior is undefined if both longOutput and truncatedLongOutput are true in the passed-in GetRevisionHistory object. If both are false, a short form of the description (prepared by the server) is returned.
opts
- GetChangelistDiffs object describing optional parameters; if null, no
options are set.P4JavaException
- if any error occurs in the processing of this method.java.util.List<IFileAnnotation> getAnnotations(DiffType wsOptions, boolean allResults, boolean useChangeNumbers, boolean followBranches) throws ConnectionException, RequestException, AccessException
wsOptions
- DiffType describing the white space option to be used; if null,
use default (no options), otherwise must be one of the whitespace
options defined by the isWsOption method on DiffType.allResults
- if true, include both deleted files and lines no longer present
at the head revisionuseChangeNumbers
- if true, annotate with change numbers rather than
revision numbers with each linefollowBranches
- if true, follow branches.ConnectionException
- if the Perforce server is unreachable or is not
connected.RequestException
- if the Perforce server encounters an error during
its processing of the requestAccessException
- if the Perforce server denies access to the callerjava.util.List<IFileAnnotation> getAnnotations(GetFileAnnotationsOptions opts) throws P4JavaException
opts
- GetFileAnnotations object describing optional parameters; if null, no
options are set.P4JavaException
- if any error occurs in the processing of this method.java.io.InputStream getContents(boolean noHeaderLine) throws ConnectionException, RequestException, AccessException
You should close the InputStream after use in order to release any underlying stream-related resources. Failure to do this may lead to the proliferation of temp files or long-term memory wastage or even leaks.
noHeaderLine
- if true, suppresses the initial line that displays the file name
and revisionConnectionException
- if the Perforce server is unreachable or is not
connected.RequestException
- if the Perforce server encounters an error during
its processing of the requestAccessException
- if the Perforce server denies access to the callerjava.io.InputStream getContents(GetFileContentsOptions opts) throws P4JavaException
You should close the InputStream after use in order to release any underlying stream-related resources. Failure to do this may lead to the proliferation of temp files or long-term memory wastage or even leaks.
opts
- GetFileContents object describing optional parameters; if null, no
options are set.P4JavaException
- if any error occurs in the processing of this method.java.util.List<IFileSpec> move(int changelistId, boolean listOnly, boolean noClientMove, java.lang.String fileType, IFileSpec toFile) throws ConnectionException, RequestException, AccessException
Note that the status of this file once the move has been performed may be indeterminate; you should discard this file and use the file returned, if any, or at least test this file's status.
Note that this operation is not supported on servers earlier than 2009.1; any attempt to use this on earlier servers will result in a RequestException with a suitable message. Similarly, not all underlying IServer implementations will work with this either, and will also result in a suitable RequestException.
changelistId
- if not IChangelist.UNKNOWN, the files are opened in the numbered
pending changelist instead of the 'default' changelist.listOnly
- if true, don't actually perform the move, just return what would
happen if the move was performednoClientMove
- if true, bypasses the client file rename. See main IServer
moveFiles comments for restrictions.fileType
- if not null, the file is reopened as that filetype.toFile
- the target file.ConnectionException
- if the Perforce server is unreachable or is not
connected.RequestException
- if the Perforce server encounters an error during
its processing of the requestAccessException
- if the Perforce server denies access to the callerjava.util.List<IFileSpec> move(IFileSpec toFile, MoveFileOptions opts) throws P4JavaException
Note that the status of this file once the move has been performed may be indeterminate; you should discard this file and use the file returned, if any, or at least test this file's status.
Note that this operation is not supported on servers earlier than 2009.1; any attempt to use this on earlier servers will result in a RequestException with a suitable message. Similarly, not all underlying IServer implementations will work with this either, and will also result in a suitable RequestException.
toFile
- the target file.opts
- GetFileContents object describing optional parameters; if null, no
options are set.P4JavaException
- if any error occurs in the processing of this method.java.lang.String getRepoName()
void setRepoName(java.lang.String repoName)
java.lang.String getSha()
void setSha(java.lang.String sha)
java.lang.String getBranch()
void setBranch(java.lang.String branch)
java.lang.String getBlobSha()
void setBlobSha(java.lang.String sha)
java.lang.String getCommitSha()
void setCommitSha(java.lang.String sha)
java.lang.String getTreeSha()
void setTreeSha(java.lang.String sha)
java.util.List<java.lang.String> getResolveTypes()
void setResolveTypes(java.util.List<java.lang.String> types)
long getSyncTime()
void setSyncTime(long syncTime)