Package 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 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));
        Parameters:
        pathStr - path

      • setDepotPath

        void setDepotPath​(java.lang.String pathStr)
        Convenience method for setPath(new FilePath(PathType.DEPOT, pathStr));
        Parameters:
        pathStr - path

      • setClientPath

        void setClientPath​(java.lang.String pathStr)
        Convenience method for setPath(new FilePath(PathType.CLIENT, pathStr));
        Parameters:
        pathStr - path

      • setLocalPath

        void setLocalPath​(java.lang.String pathStr)
        Convenience method for setPath(new FilePath(PathType.LOCAL, pathStr));
        Parameters:
        pathStr - path

      • 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).
        Returns:
        path

      • getOriginalPathString

        java.lang.String getOriginalPathString()
        Convenience method for getPathString(ORIGINAL).
        Returns:
        path

      • getDepotPath

        FilePath getDepotPath()
        Convenience method for getPath(DEPOT).
        Returns:
        depot path

      • getDepotPathString

        java.lang.String getDepotPathString()
        Convenience method for getPathString(DEPOT).
        Returns:
        depot path

      • getClientPath

        FilePath getClientPath()
        Convenience method for getPath(CLIENT).
        Returns:
        client path

      • getClientPathString

        java.lang.String getClientPathString()
        Convenience method for getPathString(CLIENT).
        Returns:
        client path

      • getLocalPath

        FilePath getLocalPath()
        Convenience method for getPath(LOCAL).
        Returns:
        local path

      • getLocalPathString

        java.lang.String getLocalPathString()
        Convenience method for getPathString(LOCAL).
        Returns:
        local path

      • getStartRevision

        int getStartRevision()
        Returns:
        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.
        Parameters:
        rev - revision

      • 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.
        Returns:
        revision

      • setEndRevision

        void setEndRevision​(int rev)
        Set the end revision for this file spec.
        Parameters:
        rev - revision

      • getChangelistId

        int getChangelistId()
        Get the ID of the changelist associated with this file spec. Returns IChangelist.UNKNOWN if no changelist ID has been set.
        Returns:
        change

      • setChangelistId

        void setChangelistId​(int id)
        Set the changelist ID for this file spec.
        Parameters:
        id - change

      • getDate

        java.util.Date getDate()
        Get the Perforce date of this file spec. Returns null if no date has been set.
        Returns:
        date

      • setDate

        void setDate​(java.util.Date date)
        Set the date for this file spec.
        Parameters:
        date - date

      • 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.
        Parameters:
        locked - locked

      • getDiffStatus

        java.lang.String getDiffStatus()
        Get the diff status for this file spec.
        Returns:
        diff status

      • setDiffStatus

        void setDiffStatus​(java.lang.String status)
        Set the diff status for this file spec.
        Parameters:
        status - status

      • getResolveType

        java.lang.String getResolveType()
        Returns:
        the resolve type for this file spec.

      • setResolveType

        void setResolveType​(java.lang.String resolveType)
        Set the resolve type for this file spec.
        Parameters:
        resolveType - resolve type

      • getContentResolveType

        java.lang.String getContentResolveType()
        Returns:
        the content resolve type for this file spec.

      • setContentResolveType

        void setContentResolveType​(java.lang.String contentResolveType)
        Set the content resolve type for this file spec.
        Parameters:
        contentResolveType - contentResolveType

      • getShelvedChange

        int getShelvedChange()
        Returns:
        the shelved change for this file spec.

      • setShelvedChange

        void setShelvedChange​(int shelvedChange)
        Set the shelved change for this file spec.
        Parameters:
        shelvedChange - shelvedChange

      • 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.
        Parameters:
        action - action

      • getLabel

        java.lang.String getLabel()
        Returns:
        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.
        Parameters:
        label - label

      • 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.
        Parameters:
        type - type

      • getUserName

        java.lang.String getUserName()
        Returns:
        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.
        Parameters:
        userName - userName

      • getClientName

        java.lang.String getClientName()
        Returns:
        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.
        Parameters:
        clientName - clientName

      • isUnmap

        boolean isUnmap()
        Returns:
        if this file spec is not mapped.

      • setUnmap

        void setUnmap​(boolean unmap)
        Set the unmap status value for this file spec.
        Parameters:
        unmap - unmap

      • 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()
        Returns:
        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.
        Parameters:
        pathStr - pathStr

      • getEndFromRev

        int getEndFromRev()
        Returns:
        the end "from" revision of the last integration, if any.

      • setEndFromRev

        void setEndFromRev​(int rev)
        Set the end from revision for this file spec.
        Parameters:
        rev - rev

      • getStartFromRev

        int getStartFromRev()
        Returns:
        the start "from" revision of the last integration, if any.

      • setStartFromRev

        void setStartFromRev​(int rev)
        Set the end from revision for this file spec.
        Parameters:
        rev - rev

      • getToFile

        java.lang.String getToFile()
        Returns:
        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.
        Parameters:
        pathStr - pathStr

      • getStartToRev

        int getStartToRev()
        Returns:
        the start "to" revision of the last integration, if any.

      • setStartToRev

        void setStartToRev​(int rev)
        Set the start to revision for this file spec.
        Parameters:
        rev - rev

      • getEndToRev

        int getEndToRev()
        Returns:
        the end "from" revision of the last integration, if any.

      • setEndToRev

        void setEndToRev​(int rev)
        Set the end to revision for this file spec.
        Parameters:
        rev - rev

      • getHowResolved

        java.lang.String getHowResolved()
        Returns:
        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.
        Parameters:
        howStr - howStr

      • getWorkRev

        int getWorkRev()
        Returns:
        the work revision.

      • setWorkRev

        void setWorkRev​(int rev)
        Set the work revision for this file spec.
        Parameters:
        rev - rev

      • getOtherAction

        FileAction getOtherAction()
        Returns:
        the other action. Returns null if no such action.

      • setOtherAction

        void setOtherAction​(FileAction action)
        Set the other action for this file spec.
        Parameters:
        action - action

      • getBaseRev

        int getBaseRev()
        Returns:
        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.
        Parameters:
        rev - rev

      • getBaseName

        java.lang.String getBaseName()
        Returns:
        the base name as reported by integ -o or equivalent. This may be null if no base name exists.

      • setBaseName

        void setBaseName​(java.lang.String basename)
        Set the base name on this object. Makes no sense for general users to call this.
        Parameters:
        basename - basename

      • getBaseFile

        java.lang.String getBaseFile()
        Returns:
        the base file as reported by resolve -o or equivalent. This may be null if no base file exists.

      • setBaseFile

        void setBaseFile​(java.lang.String basefile)
        Set the base file on this object. Makes no sense for general users to call this.
        Parameters:
        basefile - basefile

      • 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.
        contentHistory - if true, return the content history
        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

        java.util.Map<IFileSpec,​java.util.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

        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

      • getAnnotations

        java.util.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

        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

      • getContents

        java.io.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

        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

      • move

        java.util.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.

      • getRepoName

        java.lang.String getRepoName()

      • setRepoName

        void setRepoName​(java.lang.String repoName)

      • getSha

        java.lang.String getSha()

      • setSha

        void setSha​(java.lang.String sha)

      • getBranch

        java.lang.String getBranch()

      • setBranch

        void setBranch​(java.lang.String branch)

      • getBlobSha

        java.lang.String getBlobSha()

      • setBlobSha

        void setBlobSha​(java.lang.String sha)

      • getCommitSha

        java.lang.String getCommitSha()

      • setCommitSha

        void setCommitSha​(java.lang.String sha)

      • getTreeSha

        java.lang.String getTreeSha()

      • setTreeSha

        void setTreeSha​(java.lang.String sha)

      • getResolveTypes

        java.util.List<java.lang.String> getResolveTypes()

      • setResolveTypes

        void setResolveTypes​(java.util.List<java.lang.String> types)

      • getSyncTime

        long getSyncTime()

      • setSyncTime

        void setSyncTime​(long syncTime)