/* * Copyright 2008 Perforce Software Inc., All Rights Reserved. */ package com.perforce.p4java.core; import java.io.InputStream; import java.util.List; import java.util.Locale; import com.perforce.p4java.core.file.DiffType; import com.perforce.p4java.core.file.IFileSpec; import com.perforce.p4java.exception.AccessException; import com.perforce.p4java.exception.ConnectionException; import com.perforce.p4java.exception.P4JavaException; import com.perforce.p4java.exception.RequestException; import com.perforce.p4java.option.changelist.SubmitOptions; import com.perforce.p4java.option.server.GetChangelistDiffsOptions; import com.perforce.p4java.server.callback.IStreamingCallback; /** * Describes a Perforce changelist.<p> * * 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.<p> * * 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. */ public interface IChangelist extends IServerResource, IChangelistSummary { /** * Value used to signal an unknown or unallocated changelist ID. */ int UNKNOWN = -1; /** * Value used to signal a default (pending) changelist */ int DEFAULT = 0; /** * Changelist types used when running a 'p4 changes' with the -s flag */ enum Type { PENDING, SUBMITTED, SHELVED; /** * Get a lower-case representation of the type; * note the use of the English locale here to work * around issues to do with things like Turkish language * encodings of dotted upper-case "i"'s... * * @see java.lang.Enum#toString() */ public String toString() { return super.toString().toLowerCase(Locale.ENGLISH); } } /** * Refresh this changelist directly from the server. All fields including the * files field are refreshed. Will fail with a UnimplementedError being * thrown if this changelist is not refreshable. * * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws RequestException if the Perforce server encounters an error during * its processing of the request * @throws AccessException if the Perforce server denies access to the caller */ void refresh() throws ConnectionException, RequestException, AccessException; /** * Update the Perforce server's version of this changelist. All known non-null fields * will be updated. Basically, when called with a refresh parameter of false, this is * a convenience method for the IServerResource update().<p> * * @param refresh if true, does a refresh() behind the scenes after a successful return. * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws RequestException if the Perforce server encounters an error during * its processing of the request * @throws AccessException if the Perforce server denies access to the caller * * @deprecated use update optionally followed by refresh() */ void updateOnServer(boolean refresh) throws ConnectionException, RequestException, AccessException; /** * Return a list of Perforce jobs IDs for jobs marked as associated with * this changelist. This method is relatively lightweight compared to the * getJobList method.<p> * * Note that "associated" here usually means "fixed", but that is not always * the case. * * @return non-null but potentially empty list of job ID strings * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws RequestException if the Perforce server encounters an error during * its processing of the request * @throws AccessException if the Perforce server denies access to the caller */ List<String> getJobIds() throws ConnectionException, RequestException, AccessException; /** * Return a cached list of job Id's associated with this changelist. This * method is not "live", meaning it's quick and cheap to call, but it does not * necessarily reflect the current jobs associated with the list on the Perforce * server -- it reflects only the jobs associated with the server when the changelist * object was retrieved from the server, or when the last live getJobIdList method * was called. Usually safe to call immediately after retrieving the changelist, * or soon after a live getJobIdList call. * * @return non-null but potentially empty list of job ID strings * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws RequestException if the Perforce server encounters an error during * its processing of the request * @throws AccessException if the Perforce server denies access to the caller */ List<String> getCachedJobIdList() throws ConnectionException, RequestException, AccessException; /** * Return a list of Perforce jobs marked as associated with * this changelist. This method is relatively heavyweight compared to the * getJobID method.<p> * * Note that "associated" here usually means "fixed", but that is not always * the case. * * @return non-null but potentially empty list of Perforce jobs * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws RequestException if the Perforce server encounters an error during * its processing of the request * @throws AccessException if the Perforce server denies access to the caller */ List<IJob> getJobs() throws ConnectionException, RequestException, AccessException; /** * Get the list of files associated with this changelist, optionally refreshing * the list from the server.<p> * * 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.<p> * * 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.<p> * * 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.<p> * * 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).<p> * * 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. * * @param refresh if true, get a new list from the server rather than return the * local copy. * @return a non-null (but possibly-empty) list of files known to be associated with * this changelist. * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws RequestException if the Perforce server encounters an error during * its processing of the request * @throws AccessException if the Perforce server denies access to the caller */ List<IFileSpec> getFiles(boolean refresh) throws ConnectionException, RequestException, AccessException; /** * Get an InputStream onto the file diffs associated with this changelist.<p> * * 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.<p> * * 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. * * @return InputStream onto the diff stream. Note that * while this stream will not be null, it may be empty. * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws RequestException if the Perforce server encounters an error during * its processing of the request * @throws AccessException if the Perforce server denies access to the caller */ InputStream getDiffs(DiffType diffType) throws ConnectionException, RequestException, AccessException; /** * Get an InputStream onto the file diffs associated with this changelist.<p> * * 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.<p> * * 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. * * @param opts GetChangelistDiffs object describing optional parameters; if null, no * options are set. * @return InputStream onto the diff stream. Note that * while this stream will not be null, it may be empty. * @throws P4JavaException if any error occurs in the processing of this method. */ InputStream getDiffsStream(GetChangelistDiffsOptions opts) throws P4JavaException; /** * Submit this changelist. Will fail with a suitable request exception if this * is not a pending changelist associated with the current client.<p> * * 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.<p> * * 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. * * @param reOpen if true, reopen the submitted files for editing after a successful submit. * @return list of affected file specs and / or info / error messages from the Perforce server * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws RequestException if the Perforce server encounters an error during * its processing of the request * @throws AccessException if the Perforce server denies access to the caller */ List<IFileSpec> submit(boolean reOpen) throws ConnectionException, RequestException, AccessException; /** * Submit this changelist and associate it with the passed-in jobs. * Will fail with a suitable request exception if this is not a pending * changelist associated with the current client.<p> * * 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.<p> * * 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.<p> * * 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). * * @param reOpen if true, reopen the submitted files for editing after a successful submit. * @param 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. * @param 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. * @return list of affected file specs and / or info / error messages from the Perforce server * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws RequestException if the Perforce server encounters an error during * its processing of the request * @throws AccessException if the Perforce server denies access to the caller */ List<IFileSpec> submit(boolean reOpen, List<String> jobIds, String jobStatus) throws ConnectionException, RequestException, AccessException; /** * Submit this changelist and associate it with any jobs in the passed-in options. * Will fail with a suitable request exception if this is not a pending * changelist associated with the current client.<p> * * 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.<p> * * 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.<p> * * 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). * * @param opts SubmitOptions object describing optional parameters; if null, no * options are set. * @return list of affected file specs and / or info / error messages from the Perforce server. * @throws P4JavaException if any error occurs in the processing of this method. */ List<IFileSpec> submit(SubmitOptions opts) throws P4JavaException; /** * Submit this changelist and associate it with any jobs in the passed-in options. * Will fail with a suitable request exception if this is not a pending * changelist associated with the current client.<p> * * 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.<p> * * @since 2012.3 * * @param opts SubmitOptions object describing optional parameters; if null, no * options are set. * @param callback a non-null IStreamingCallback to be used to process the incoming * results. * @param key an opaque integer key that is passed to the IStreamingCallback callback * methods to identify the action as being associated with this specific * call. * @throws P4JavaException if any error occurs in the processing of this method. */ void submit(SubmitOptions opts, IStreamingCallback callback, int key) throws P4JavaException; }
# | Change | User | Description | Committed | |
---|---|---|---|---|---|
#1 | 19903 | stuartrowe |
Branching //guest/perforce_software/p4java/... to //guest/stuartrowe/p4java/... |
||
//guest/perforce_software/p4java/r14.1/src/main/java/com/perforce/p4java/core/IChangelist.java | |||||
#1 | 12541 | Matt Attaway | Initial add of the 14.1 p4java source code |