com.perforce.p4java.core.file
Interface IFileSpec

All Superinterfaces:

IFileOperationResult, IServerResource

All Known Subinterfaces:

IExtendedFileSpec

All Known Implementing Classes:

ExtendedFileSpec, FileSpec

public interface IFileSpec
extends IFileOperationResult

Defines the basic set of information and operations on a Perforce file under P4Java, and performs as the common currency for a lot of file-list based methods, usually encapsulated as Java lists as both input and output for common server and client file-based methods such as where, sync, add, etc.

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.

Field Summary

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.

Method Summary

FileAction	getAction() Returns the file action associated with this file, if any.
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.
int	getChangelistId() Get the ID of the changelist associated with this file spec.
java.lang.String	getClientName() Return the name of the client associated with this file spec, or null if not set or known.
FilePath	getClientPath() Convenience method for getPath(CLIENT).
java.lang.String	getClientPathString() Convenience method for getPathString(CLIENT).
java.io.InputStream	getContents(boolean noHeaderLine) 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() Return the end "from" revision of the last integration, if any.
int	getEndRevision() Get the end revision for this file spec, if any.
int	getEndToRev() Return the end "from" revision of the last integration, if any.
java.lang.String	getFileType() Returns the file type string for this file spec, or null if not known.
java.lang.String	getFromFile() Get the file this file spec was integrated from if any.
java.lang.String	getHowResolved() Return a string representation of how the last resolve happened.
java.lang.String	getLabel() Get the label string associated with this file spec, if any.
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() Get the other action.
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.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.
int	getStartFromRev() Return the start "from" revision of the last integration, if any.
int	getStartRevision() Get the start revision for this file spec, if any.
int	getStartToRev() Return the start "to" revision of the last integration, if any.
java.lang.String	getToFile() Get the "to" file for the integration, if it exists.
java.lang.String	getUserName() Return the Perforce user name of the file's owner, or null if this is not set or known.
int	getWorkRev() Get the work revision.
boolean	isLocked() Returns true if the associated file has been locked.
boolean	isUnmap() Return if this file spec is not mapped.
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	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	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	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	setToFile(java.lang.String pathStr) Set the to file for this file spec.
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().

Methods inherited from interface com.perforce.p4java.core.file.IFileOperationResult

getGenericCode, getOpStatus, getSeverityCode, getStatusMessage

Methods inherited from interface com.perforce.p4java.core.IServerResource

canRefresh, canUpdate, refresh, setServer, update

Field Detail

NO_FILE_REVISION

static final int NO_FILE_REVISION

Value that signals that no Perforce file revision is (currently) associated with a file spec.

Note that this is distinct from specifying "#none" or "#0" explicitly, which is dealt with by the NONE_FILE_REVISION below.

See Also:

Constant Field Values

NO_REVISION_STRING

static final java.lang.String NO_REVISION_STRING

String representation for the NO_FILE_REVISION value.

See Also:

Constant Field Values

NONE_REVISION

static final int NONE_REVISION

Value used to signal "none" file revision explicitly. Note that this is distinct from leaving a FileSpec's revision unspecified with NO_FILE_REVISION.

See Also:

Constant Field Values

NONE_REVISION_STRING

static final java.lang.String NONE_REVISION_STRING

The string used by the Perforce server to signal no revision specified.

See Also:

Constant Field Values

HEAD_REVISION

static final int HEAD_REVISION

The symbolic value used to signal the head revision.

See Also:

Constant Field Values

HEAD_REVISION_STRING

static final java.lang.String HEAD_REVISION_STRING

The string used by the Perforce server to signal a head revision.

See Also:

Constant Field Values

HAVE_REVISION

static final int HAVE_REVISION

The symbolic value used to signal the "have" revision.

See Also:

Constant Field Values

HAVE_REVISION_STRING

static final java.lang.String HAVE_REVISION_STRING

The string used by the Perforce server to signal a "have" revision.

See Also:

Constant Field Values

Method Detail

getPath

FilePath getPath(FilePath.PathType pathType)

Get the specific depot, client, local, or original Perforce file path associated with this file spec. Will be null if no such path exists for this file spec.

Parameters:

pathType - if null or PathType.ORIGINAL, return the original path for this file spec, otherwise return the specified path for this file spec.

Returns:

possibly-null file path

setPath

void setPath(FilePath path)

Set a Perforce file path associated with this file spec. If path or path.getPathType() is null, the passed-in path type is assumed to be ORIGINAL.

Parameters:

path - candidate file path; may be null.

setOriginalPath

void setOriginalPath(java.lang.String pathStr)

Convenience method for setPath(new FilePath(PathType.ORIGINAL, pathStr));

setDepotPath

void setDepotPath(java.lang.String pathStr)

Convenience method for setPath(new FilePath(PathType.DEPOT, pathStr));

setClientPath

void setClientPath(java.lang.String pathStr)

Convenience method for setPath(new FilePath(PathType.CLIENT, pathStr));

setLocalPath

void setLocalPath(java.lang.String pathStr)

Convenience method for setPath(new FilePath(PathType.LOCAL, pathStr));

getAnnotatedPathString

java.lang.String getAnnotatedPathString(FilePath.PathType pathType)

Get an annotated string representation of a Perforce file path associated with this Perforce file spec. "Annotated" in this context means any known Perforce version / changelist (etc.) information is appended in standard Perforce format to the end of the returned string.

Parameters:

pathType - if null or PathType.ORIGINAL, return the original path for this file spec, otherwise return the specified path for this file spec.

Returns:

possibly-null annotated Perforce file path string representation.

getPathString

java.lang.String getPathString(FilePath.PathType pathType)

Get the unannotated path string for this Perforce file.

Parameters:

pathType - if null or PathType.ORIGINAL, return the original path for this file spec, otherwise return the specified path for this file spec.

Returns:

possibly-null non-annotated Perforce file path string representation.

setPathFromString

void setPathFromString(FilePath.PathType pathType,
                       java.lang.String pathStr)

Set a specific Perforce file path for this file spec from a passed-in string. Any file revision / changelist (etc.) information appended to the pathStr parameter is stripped off before the path is set.

Parameters:

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 string

getOriginalPath

FilePath getOriginalPath()

Convenience method for getPath(ORIGINAL).

getOriginalPathString

java.lang.String getOriginalPathString()

Convenience method for getPathString(ORIGINAL).

getDepotPath

FilePath getDepotPath()

Convenience method for getPath(DEPOT).

getDepotPathString

java.lang.String getDepotPathString()

Convenience method for getPathString(DEPOT).

getClientPath

FilePath getClientPath()

Convenience method for getPath(CLIENT).

getClientPathString

java.lang.String getClientPathString()

Convenience method for getPathString(CLIENT).

getLocalPath

FilePath getLocalPath()

Convenience method for getPath(LOCAL).

getLocalPathString

java.lang.String getLocalPathString()

Convenience method for getPathString(LOCAL).

getStartRevision

int getStartRevision()

Get the start revision for this file spec, if any. Returns NO_FILE_REVISION if the revision hasn't been set or is unknown.

setStartRevision

void setStartRevision(int rev)

Set the start revision for this file spec.

getEndRevision

int getEndRevision()

Get the end revision for this file spec, if any. Returns NO_FILE_REVISION if the revision hasn't been set or is unknown.

setEndRevision

void setEndRevision(int rev)

Set the end revision for this file spec.

getChangelistId

int getChangelistId()

Get the ID of the changelist associated with this file spec. Returns IChangelist.UNKNOWN if no changelist ID has been set.

setChangelistId

void setChangelistId(int id)

Set the changelist ID for this file spec.

getDate

java.util.Date getDate()

Get the Perforce date of this file spec. Returns null if no date has been set.

setDate

void setDate(java.util.Date date)

Set the date for this file spec.

isLocked

boolean isLocked()

Returns true if the associated file has been locked.

setLocked

void setLocked(boolean locked)

Set the locked status for this file spec.

getDiffStatus

java.lang.String getDiffStatus()

Get the diff status for this file spec.

setDiffStatus

void setDiffStatus(java.lang.String status)

Set the diff status for this file spec.

getAction

FileAction getAction()

Returns the file action associated with this file, if any. Returns null if no such action has been set.

setAction

void setAction(FileAction action)

Set the file action for this file spec.

getLabel

java.lang.String getLabel()

Get the label string associated with this file spec, if any. Returns null if no such label string has been set.

setLabel

void setLabel(java.lang.String label)

Set the label associated with this file spec.

getFileType

java.lang.String getFileType()

Returns the file type string for this file spec, or null if not known.

setFileType

void setFileType(java.lang.String type)

Set the file type for this file spec.

getUserName

java.lang.String getUserName()

Return the Perforce user name of the file's owner, or null if this is not set or known.

setUserName

void setUserName(java.lang.String userName)

Set the Perforce user name for this file spec.

getClientName

java.lang.String getClientName()

Return the name of the client associated with this file spec, or null if not set or known.

setClientName

void setClientName(java.lang.String clientName)

Set the Perforce client name for this file spec.

isUnmap

boolean isUnmap()

Return if this file spec is not mapped.

setUnmap

void setUnmap(boolean unmap)

Set the unmap status value for this file spec.

getPreferredPath

FilePath getPreferredPath()

Get the "preferred" path for this file spec. A file spec's preferred path is defined to be the path specified (in order) the original path, the depot path, the client path, or the local path.

Returns:

possibly-null preferred path

getAnnotatedPreferredPathString

java.lang.String getAnnotatedPreferredPathString()

Get the annotated "preferred" path string for this file spec. A file spec's preferred path is defined to be the path specified by (in order) the original path, the depot path, the client path, or the local path. This method appends any relevant revision / changelist (etc.) information to the path string if it exists.

Returns:

possibly-null annotated preferred path string.

getPreferredPathString

java.lang.String getPreferredPathString()

Get the (unannotated) "preferred" path string for this file spec. A file spec's preferred path is defined to be the path specified by (in order) the original path, the depot path, the client path, or the local path.

Returns:

possibly-null annotated preferred path string.

toString

java.lang.String toString()

Useful alias for getPreferredPathString().

Overrides:

toString in class java.lang.Object

getFromFile

java.lang.String getFromFile()

Get the file this file spec was integrated from if any. Returns null if no such file.

setFromFile

void setFromFile(java.lang.String pathStr)

Set the from file for this file spec.

getEndFromRev

int getEndFromRev()

Return the end "from" revision of the last integration, if any.

setEndFromRev

void setEndFromRev(int rev)

Set the end from revision for this file spec.

getStartFromRev

int getStartFromRev()

Return the start "from" revision of the last integration, if any.

setStartFromRev

void setStartFromRev(int rev)

Set the end from revision for this file spec.

getToFile

java.lang.String getToFile()

Get the "to" file for the integration, if it exists. Returns null otherwise.

setToFile

void setToFile(java.lang.String pathStr)

Set the to file for this file spec.

getStartToRev

int getStartToRev()

Return the start "to" revision of the last integration, if any.

setStartToRev

void setStartToRev(int rev)

Set the start to revision for this file spec.

getEndToRev

int getEndToRev()

Return the end "from" revision of the last integration, if any.

setEndToRev

void setEndToRev(int rev)

Set the end to revision for this file spec.

getHowResolved

java.lang.String getHowResolved()

Return a string representation of how the last resolve happened. Returns null if unknown or not relevant.

setHowResolved

void setHowResolved(java.lang.String howStr)

Set the "how resolved" string for this file spec.

getWorkRev

int getWorkRev()

Get the work revision.

setWorkRev

void setWorkRev(int rev)

Set the work revision for this file spec.

getOtherAction

FileAction getOtherAction()

Get the other action. Returns null if no such action.

setOtherAction

void setOtherAction(FileAction action)

Set the other action for this file spec.

getRevisionHistory

java.util.Map<IFileSpec,java.util.List<IFileRevisionData>> getRevisionHistory(int maxRevs,
                                                                              boolean contentHistory,
                                                                              boolean includeInherited,
                                                                              boolean longOutput,
                                                                              boolean truncatedLongOutput)
                                                                              throws ConnectionException,
                                                                                     RequestException,
                                                                                     AccessException

Get the revision history of this Perforce file.

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.

Parameters:

maxRevs - if positive, return at most maxRev revisions for this file.

includeInherited - if true, causes inherited file history to be returned as well.

longOutput - if true, return the full descriptions associated with each revision

truncatedLongOutput - if true, return only the first 250 characters of each description.

Returns:

a non-null map of lists of the revision data for the file.

Throws:

ConnectionException - if the Perforce server is unreachable or is not connected.

RequestException - if the Perforce server encounters an error during its processing of the request

AccessException - if the Perforce server denies access to the caller

getAnnotations

java.util.List<IFileAnnotation> getAnnotations(DiffType wsOptions,
                                               boolean allResults,
                                               boolean useChangeNumbers,
                                               boolean followBranches)
                                               throws ConnectionException,
                                                      RequestException,
                                                      AccessException

Get the file annotations associated with this file.

Parameters:

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 revision

useChangeNumbers - if true, annotate with change numbers rather than revision numbers with each line

followBranches - if true, follow branches.

Returns:

non-null (but possibly-empty) list of IFileAnnotation objects representing this file's version annotations.

Throws:

ConnectionException - if the Perforce server is unreachable or is not connected.

RequestException - if the Perforce server encounters an error during its processing of the request

AccessException - if the Perforce server denies access to the caller

getContents

java.io.InputStream getContents(boolean noHeaderLine)
                                throws ConnectionException,
                                       RequestException,
                                       AccessException

Get the contents of this specific Perforce file revision from the Perforce depot as an InputStream. Note that the contents are retrieved from the depot, not from the (possibly-changed) local Perforce client workspace copy). This method is basically a convenience wrapper for the IServer.getFileContents() method.

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.

Parameters:

noHeaderLine - if true, suppresses the initial line that displays the file name and revision

Returns:

a non-null but possibly-empty InputStream onto the file's contents.

Throws:

ConnectionException - if the Perforce server is unreachable or is not connected.

RequestException - if the Perforce server encounters an error during its processing of the request

AccessException - if the Perforce server denies access to the caller

move

java.util.List<IFileSpec> move(int changelistId,
                               boolean listOnly,
                               boolean noClientMove,
                               java.lang.String fileType,
                               IFileSpec toFile)
                               throws ConnectionException,
                                      RequestException,
                                      AccessException

Move this file if it's already opened for edit or add (the fromFile) to the destination file (the toFile). A file can be moved many times before it is submitted; moving it back to its original location will reopen it for edit. The full semantics of this operation (which can be confusing) are found in the main 'p4 help' documentation.

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.

Parameters:

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 performed

noClientMove - 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.

Returns:

list of IFileSpec objects representing the results of this move

Throws:

ConnectionException - if the Perforce server is unreachable or is not connected.

RequestException - if the Perforce server encounters an error during its processing of the request

AccessException - if the Perforce server denies access to the caller