public interface IChangelist extends IServerResource, IChangelistSummary
In general, changelists returned from the IServer.getChangelist method (and any convenience methods wrapping that method) will be complete, refreshable, and updateable, but changelists returned from other methods are not guaranteed to be any of those things.
Note that most of the field setter methods on this interface have local effect only (unless you call update()), and are mostly intended for de-novo changelist creation.
Modifier and Type | Interface and Description |
---|---|
static class |
IChangelist.Type
Changelist types used when running a 'p4 changes' with the -s flag
|
IChangelistSummary.Visibility
Modifier and Type | Field and Description |
---|---|
static int |
DEFAULT
Value used to signal a default (pending) changelist
|
static int |
UNKNOWN
Value used to signal an unknown or unallocated changelist ID.
|
Modifier and Type | Method and Description |
---|---|
java.util.List<java.lang.String> |
getCachedJobIdList()
Return a cached list of job Id's associated with this changelist.
|
java.io.InputStream |
getDiffs(DiffType diffType)
Get an InputStream onto the file diffs associated with this changelist.
|
java.io.InputStream |
getDiffsStream(GetChangelistDiffsOptions opts)
Get an InputStream onto the file diffs associated with this changelist.
|
java.util.List<IFileSpec> |
getFiles(boolean refresh)
Get the list of files associated with this changelist, optionally refreshing
the list from the server.
|
java.util.List<java.lang.String> |
getJobIds()
Return a list of Perforce jobs IDs for jobs marked as associated with
this changelist.
|
java.util.List<IJob> |
getJobs()
Return a list of Perforce jobs marked as associated with
this changelist.
|
void |
refresh()
Refresh this changelist directly from the server.
|
java.util.List<IFileSpec> |
submit(boolean reOpen)
Submit this changelist.
|
java.util.List<IFileSpec> |
submit(boolean reOpen,
java.util.List<java.lang.String> jobIds,
java.lang.String jobStatus)
Submit this changelist and associate it with the passed-in jobs.
|
java.util.List<IFileSpec> |
submit(SubmitOptions opts)
Submit this changelist and associate it with any jobs in the passed-in options.
|
void |
submit(SubmitOptions opts,
IStreamingCallback callback,
int key)
Submit this changelist and associate it with any jobs in the passed-in options.
|
void |
updateOnServer(boolean refresh)
Deprecated.
use update optionally followed by refresh()
|
canRefresh, canUpdate, clearRawFields, complete, getRawField, getRawFields, hasRawField, setRawField, setRawFields, setServer, update, update, update
getChangelistStream, getClientId, getDate, getDescription, getId, getStatus, getUsername, getVisibility, isShelved, setClientId, setDate, setDescription, setId, setShelved, setStatus, setUsername, setVisibility
static final int UNKNOWN
static final int DEFAULT
void refresh() throws ConnectionException, RequestException, AccessException
refresh
in interface IServerResource
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 callervoid updateOnServer(boolean refresh) throws ConnectionException, RequestException, AccessException
refresh
- if true, does a refresh() behind the scenes after a successful return.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<java.lang.String> getJobIds() throws ConnectionException, RequestException, AccessException
Note that "associated" here usually means "fixed", but that is not always the case.
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<java.lang.String> getCachedJobIdList() throws ConnectionException, RequestException, AccessException
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<IJob> getJobs() throws ConnectionException, RequestException, AccessException
Note that "associated" here usually means "fixed", but that is not always the case.
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> getFiles(boolean refresh) throws ConnectionException, RequestException, AccessException
If this is the first time this method has been called on this changelist, or if refresh is true, the file list is obtained from the server and copied locally to this object; otherwise, the local copy is returned.
Note that the actual file list is returned; this file list is guaranteed mutable and you can change it "live" (by, for example, deleting files from it (deleting files is, in fact, the only thing that makes sense from a Perforce point of view)). Such changes will only be reflected back to the server when a submit is done; adding files to this list results in undefined behavior.
The IFileSpec objects returned are not guaranteed to have any fields except depot path, version, and action valid (and, in fact, if it comes directly from the server, those are usually the only fields that are valid.
Note that the Perforce server side of the submit() processing expects all file lists to be in canonical depot path form; file specs in the associated submit file list that don't have a depot spec will be left untouched (this is a Perforce thing, not a P4Java thing).
This is one of the guaranteed "live" method on this interface, and will return the list as it exists when called (rather than when the underlying implementation object was created) if refresh is true. This can be an expensive method to evaluate, so don't use it willy-nilly.
refresh
- if true, get a new list from the server rather than return the
local copy.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.io.InputStream getDiffs(DiffType diffType) throws ConnectionException, RequestException, AccessException
This is one of the guaranteed "live" method on this interface, and will return the diff output as it exists when called (rather than when the underlying implementation object was created). This can be an expensive method to evaluate, and can generate reams and reams (and reams) of output, so don't use it willy-nilly.
You should remember to close the returned InputStream when finished with the stream, in order to release the underlying io resources. Failure to do this may leave temporary files lying around or cause inefficient memory usage.
diffType
- diff typeConnectionException
- 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 getDiffsStream(GetChangelistDiffsOptions opts) throws P4JavaException
This is one of the guaranteed "live" method on this interface, and will return the diff output as it exists when called (rather than when the underlying implementation object was created). This can be an expensive method to evaluate, and can generate reams and reams (and reams) of output, so don't use it willy-nilly.
You should remember to close the returned InputStream when finished with the stream, in order to release the underlying io resources. Failure to do this may leave temporary files lying around or cause inefficient memory usage.
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<IFileSpec> submit(boolean reOpen) throws ConnectionException, RequestException, AccessException
If the submit is successful, the status of the underlying changelist will be updated to reflect the new status. Other fields will not be automatically updated and need to be refreshed with the refresh() method if you need to access them live.
Note that the list of filespecs returned from the submit will contain only summary filespecs for successful files -- generally only the depot path, action, and revisions fields will be valid; other fields may be null or undefined depending on the server and client implementations. That is, do not rely on the returned filespec list for anything other than depot paths.
reOpen
- if true, reopen the submitted files for editing after a successful submit.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> submit(boolean reOpen, java.util.List<java.lang.String> jobIds, java.lang.String jobStatus) throws ConnectionException, RequestException, AccessException
If the submit is successful, the status of the underlying changelist will be updated to reflect the new status. Other fields will not be automatically updated and need to be refreshed with the refresh() method if you need to access them live.
Note that the list of filespecs returned from the submit will contain only summary filespecs for successful files -- generally only the depot path, action, and revisions fields will be valid; other fields may be null or undefined depending on the server and client implementations. That is, do not rely on the returned filespec list for anything other than depot paths.
Note also that any jobIds and / or job status arguments will override any jobIds already associated with this object on submission (i.e. jobs in the local object's job list).
reOpen
- if true, reopen the submitted files for editing after a successful submit.jobIds
- if non-null, contains a list of job IDs for jobs that will have their status
changed to fixed or "jobStatus", below. This list will override any existing
list attached to the changelist as a result of a refresh operation after
fixing a job, etc.jobStatus
- if jobIds is non-null, contains a string to which
the jobs in the jobIds list will be set on a successful submit; if
null the jobs will be marked fixed.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> submit(SubmitOptions opts) throws P4JavaException
If the submit is successful, the status of the underlying changelist will be updated to reflect the new status. Other fields will not be automatically updated and need to be refreshed with the refresh() method if you need to access them live.
Note that the list of filespecs returned from the submit will contain only summary filespecs for successful files -- generally only the depot path, action, and revisions fields will be valid; other fields may be null or undefined depending on the server and client implementations. That is, do not rely on the returned filespec list for anything other than depot paths.
Note also that any jobIds and / or job status arguments given to the SubmitOptions argument will override any jobIds already associated with this object on submission (i.e. jobs in the local object's job list).
opts
- SubmitOptions object describing optional parameters; if null, no
options are set.P4JavaException
- if any error occurs in the processing of this method.void submit(SubmitOptions opts, IStreamingCallback callback, int key) throws P4JavaException
Note that this method takes an IStreamingCallback parameter, and the results are sent to the user using the IStreamingCallback handleResult method; see the IStreamingCallback Javadoc for details. The payload passed to handleResult is usually the raw map gathered together deep in the RPC protocol layer, and the user is assumed to have the knowledge and technology to be able to parse it and use it.
opts
- SubmitOptions object describing optional parameters; if null, no
options are set.callback
- a non-null IStreamingCallback to be used to process the incoming
results.key
- an opaque integer key that is passed to the IStreamingCallback callback
methods to identify the action as being associated with this specific
call.P4JavaException
- if any error occurs in the processing of this method.