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.

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 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 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 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 String HAVE_REVISION_STRING

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

See Also:

Constant Field Values

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(String pathStr)

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

setDepotPath

void setDepotPath(String pathStr)

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

setClientPath

void setClientPath(String pathStr)

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

setLocalPath

void setLocalPath(String pathStr)

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

getAnnotatedPathString

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

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,
                       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

String getOriginalPathString()

Convenience method for getPathString(ORIGINAL).

getDepotPath

FilePath getDepotPath()

Convenience method for getPath(DEPOT).

getDepotPathString

String getDepotPathString()

Convenience method for getPathString(DEPOT).

getClientPath

FilePath getClientPath()

Convenience method for getPath(CLIENT).

getClientPathString

String getClientPathString()

Convenience method for getPathString(CLIENT).

getLocalPath

FilePath getLocalPath()

Convenience method for getPath(LOCAL).

getLocalPathString

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

Date getDate()

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

setDate

void setDate(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

String getDiffStatus()

Get the diff status for this file spec.

setDiffStatus

void setDiffStatus(String status)

Set the diff status for this file spec.

getResolveType

String getResolveType()

Get the resolve type for this file spec.

setResolveType

void setResolveType(String resolveType)

Set the resolve type for this file spec.

getContentResolveType

String getContentResolveType()

Get the content resolve type for this file spec.

setContentResolveType

void setContentResolveType(String contentResolveType)

Set the content resolve type for this file spec.

getShelvedChange

int getShelvedChange()

Get the shelved change for this file spec.

setShelvedChange

void setShelvedChange(int shelvedChange)

Set the shelved change 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

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(String label)

Set the label associated with this file spec.

getFileType

String getFileType()

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

setFileType

void setFileType(String type)

Set the file type for this file spec.

getUserName

String getUserName()

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

setUserName

void setUserName(String userName)

Set the Perforce user name for this file spec.

getClientName

String getClientName()

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

setClientName

void setClientName(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

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

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

String toString()

Useful alias for getPreferredPathString().

Overrides:

toString in class Object

getFromFile

String getFromFile()

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

setFromFile

void setFromFile(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

String getToFile()

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

setToFile

void setToFile(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

String getHowResolved()

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

setHowResolved

void setHowResolved(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.

getBaseRev

int getBaseRev()

Get the base revision as reported by integ -o or equivalent. This may be NO_FILE_REVISION if no base revision exists.

setBaseRev

void setBaseRev(int rev)

Set the base revision on this object. Makes no sense for general users to call this.

getBaseName

String getBaseName()

Get the base name as reported by integ -o or equivalent. This may be null if no base name exists.

setBaseName

void setBaseName(String basename)

Set the base name on this object. Makes no sense for general users to call this.

getBaseFile

String getBaseFile()

Get the base file as reported by resolve -o or equivalent. This may be null if no base file exists.

setBaseFile

void setBaseFile(String basefile)

Set the base file on this object. Makes no sense for general users to call this.

getRevisionHistory

Map<IFileSpec,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

getRevisionHistory

Map<IFileSpec,List<IFileRevisionData>> getRevisionHistory(GetRevisionHistoryOptions opts)
                                                          throws P4JavaException

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 in the passed-in GetRevisionHistory object. If both are false, a short form of the description (prepared by the server) is returned.

Parameters:

opts - GetChangelistDiffs object describing optional parameters; if null, no options are set.

Returns:

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

Throws:

P4JavaException - if any error occurs in the processing of this method.

getAnnotations

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

getAnnotations

List<IFileAnnotation> getAnnotations(GetFileAnnotationsOptions opts)
                                     throws P4JavaException

Get the file annotations associated with this file.

Parameters:

opts - GetFileAnnotations object describing optional parameters; if null, no options are set.

Returns:

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

Throws:

P4JavaException - if any error occurs in the processing of this method.

getContents

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

getContents

InputStream getContents(GetFileContentsOptions opts)
                        throws P4JavaException

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 IOptionsServer.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:

opts - GetFileContents object describing optional parameters; if null, no options are set.

Returns:

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

Throws:

P4JavaException - if any error occurs in the processing of this method.

move

List<IFileSpec> move(int changelistId,
                     boolean listOnly,
                     boolean noClientMove,
                     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

move

List<IFileSpec> move(IFileSpec toFile,
                     MoveFileOptions opts)
                     throws P4JavaException

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:

toFile - the target file.

opts - GetFileContents object describing optional parameters; if null, no options are set.

Returns:

list of IFileSpec objects representing the results of this move.

Throws:

P4JavaException - if any error occurs in the processing of this method.