/** * */ package com.perforce.p4java.client; import java.io.InputStream; import java.util.List; import com.perforce.p4java.core.IChangelist; import com.perforce.p4java.core.file.IFileSpec; import com.perforce.p4java.core.file.IntegrationOptions; 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.impl.generic.client.ClientView; import com.perforce.p4java.option.client.AddFilesOptions; import com.perforce.p4java.option.client.CopyFilesOptions; import com.perforce.p4java.option.client.DeleteFilesOptions; import com.perforce.p4java.option.client.EditFilesOptions; import com.perforce.p4java.option.client.GetDiffFilesOptions; import com.perforce.p4java.option.client.IntegrateFilesOptions; import com.perforce.p4java.option.client.LabelSyncOptions; import com.perforce.p4java.option.client.LockFilesOptions; import com.perforce.p4java.option.client.MergeFilesOptions; import com.perforce.p4java.option.client.PopulateFilesOptions; import com.perforce.p4java.option.client.ReconcileFilesOptions; import com.perforce.p4java.option.client.ReopenFilesOptions; import com.perforce.p4java.option.client.ResolveFilesAutoOptions; import com.perforce.p4java.option.client.ResolvedFilesOptions; import com.perforce.p4java.option.client.RevertFilesOptions; import com.perforce.p4java.option.client.ShelveFilesOptions; import com.perforce.p4java.option.client.SyncOptions; import com.perforce.p4java.option.client.UnshelveFilesOptions; import com.perforce.p4java.option.client.UnlockFilesOptions; import com.perforce.p4java.option.server.OpenedFilesOptions; import com.perforce.p4java.server.IServer; import com.perforce.p4java.server.callback.IStreamingCallback; /** * Extends the lightweight IClientSummary interface to provide a "heavyweight" Perforce * client object that has an associated Perforce client views and has the full panoply * of Perforce operations defined against it.<p> * * Perforce clients are described in detail elsewhere, but in summary, a Perforce client object * is returned from the Perforce server using one of the getClient(s) methods or by creating a * new Perforce client through the newClient server method. Some Perforce operations are done * through a Perforce client; some are associated with a Perforce client; and some are done * directly through the Perforce server itself.<p> * * IClient objects are complete, refreshable, and updateable (unlike IClientSummary objects, * which are not updateable). */ public interface IClient extends IClientSummary { /** * Get the Perforce client view associated with this client, if any. * * @return the Perforce client view associated with this client, if any; * null otherwise. */ ClientView getClientView(); /** * Set the Perforce client view associated with this client. * * @param clientView new Perforce client view for the client. */ void setClientView(ClientView clientView); /** * Return the IServer object representing the Perforce server associated with this * Perforce client. * * @return the IServer object representing the server associated with this * client, or null if no such server exists or has been set for this client. */ IServer getServer(); /** * Set the Perforce server associated with this client. * * @param server the IServer object representing the server associated with this * client, or null if there's no such server. */ void setServer(IServer server); /** * Sync a Perforce client workspace against the Perforce server.<p> * * Note that this method will fail (throw a RequestException) unless the client * is the associated IServer object's current client. * * @param fileSpecs files to be synchronized; if empty, synchronize all client files. * @param forceUpdate if true, forces resynchronization even if the client already has the file, and clobbers writable files. This flag doesn't affect open files. Corresponds to the p4 sync "-f" flag. * @param noUpdate causes sync not to update the client workspace, but to display what normally would be updated. Corresponds to the p4 sync "-n" flag. * @param clientBypass bypasses the client file update. It can be used to make the server believe that a client workspace already has the file. Corresponds to the p4 sync "-k" flag. * @param serverBypass populates the client workspace, but does not update the server to reflect those updates. Any file that is already synced or opened will be bypassed with a warning message. Corresponds to the p4 sync "-p" flag. * @return non-null list of affected files as IFileSpec elements * @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> sync(List<IFileSpec> fileSpecs, boolean forceUpdate, boolean noUpdate, boolean clientBypass, boolean serverBypass) throws ConnectionException, RequestException, AccessException; /** * Sync a Perforce client workspace against the Perforce server.<p> * * @see com.perforce.p4java.option.client.SyncOptions * * @param fileSpecs files to be synchronized; if empty, synchronize all client files. * @param syncOpts SyncOptions object describing sync options; see SyncOptions comments. * @return non-null list of affected files as IFileSpec elements * @throws P4JavaException if any processing errors occur during exection. */ List<IFileSpec> sync(List<IFileSpec> fileSpecs, SyncOptions syncOpts) throws P4JavaException; /** * Sync a Perforce client workspace against the Perforce server.<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> * * @see com.perforce.p4java.option.client.SyncOptions * * @since 2012.3 * * @param fileSpecs files to be synchronized; if empty, synchronize all client files. * @param syncOpts SyncOptions object describing sync options; see SyncOptions comments. * @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 processing errors occur during exection. */ void sync(List<IFileSpec> fileSpecs, SyncOptions syncOpts, IStreamingCallback callback, int key) throws P4JavaException; /** * Perform a label sync operation for this client. See the main Perforce * documentation for an explanation of the labelsync operation. * * @param fileSpecs if non-null, the list of files dor this operation * @param labelName non-null name of the label to be sync'd * @param noUpdate if true, just show what would result with the labelsync * rather than actually doing it * @param addFiles if true, add the files in fileSpecs to the label * @param deleteFiles if true, delete the files in fileSpecs from the label * @return non-null list of affected files as IFileSpec elements * @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> labelSync(List<IFileSpec> fileSpecs, String labelName, boolean noUpdate, boolean addFiles, boolean deleteFiles) throws ConnectionException, RequestException, AccessException; /** * Perform a label sync operation for this client. See the main Perforce * documentation for an explanation of the labelsync operation. * * @see com.perforce.p4java.option.client.LabelSyncOptions * * @param fileSpecs if non-null, the list of files for this operation * @param labelName non-null name of the label to be sync'd * @param opts possibly-null LabelSyncOptions object describing the * specific options for this call * @return non-null list of affected files as IFileSpec elements * @throws P4JavaException if an error occurs processing this method and its parameters */ List<IFileSpec> labelSync(List<IFileSpec> fileSpecs, String labelName, LabelSyncOptions opts) throws P4JavaException; /** * Create a new changelist for this Perforce client in the associated Perforce server. * The newly-created changelist has no files associated with it (regardless of * whether the passed-in changelist spec has files associated with it); if you * wish to add files to the new changelist, you need to do a reopen on them * explictly after the new changelist is returned.<p> * * The new changelist is returned if the command is successful; this changelist object * will include the new changelist ID. * * @param newChangelist non-null specification for the new changelist; if the * newChangelist's ID is not IChangelist.DEFAULT, it is ignored. * @return the new changelist, or null if there was an error or the new changelist * is inaccessible. * @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 */ IChangelist createChangelist(IChangelist newChangelist) throws ConnectionException, RequestException, AccessException; /** * Open one or more Perforce client workspace files for adding to the Perforce server. * * @param fileSpecs non-null list of files to be opened, in Perforce client or * depot or local path format. * @param noUpdate if true, don't actually do the open, just return the files that * would have been opened for addition. * @param changeListId if positive, the opened files are put into the pending * changelist identified by changeListId; this changelist must have been * previously created. If zero or negative, the file is opened in the 'default' * (unnumbered) changelist. * @param fileType if non-null, the files are added as that filetype. * See 'p4 help filetypes' to attempt to make any sense of Perforce file types. * @param useWildcards if true, filenames that contain wildcards are permitted. * See the main Perforce documentation for file adding for details. * @return a non-null but possibly-empty list of IFileSpec objects * representing the opened files. Not all fields in these specs * will be valid or set. * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws AccessException if the Perforce server denies access to the caller */ List<IFileSpec> addFiles(List<IFileSpec> fileSpecs, boolean noUpdate, int changeListId, String fileType, boolean useWildcards) throws ConnectionException, AccessException; /** * Open one or more Perforce client workspace files for adding to the Perforce server. * * @see com.perforce.p4java.option.client.AddFilesOptions * * @param fileSpecs non-null list of files to be opened, in Perforce client or * depot or local path format. * @param opts possibly-null AddFilesOptions object specifying method options. * @return a non-null but possibly-empty list of IFileSpec objects * representing the opened files. Not all fields in these specs * will be valid or set. * @throws P4JavaException if an error occurs processing this method and its parameters */ List<IFileSpec> addFiles(List<IFileSpec> fileSpecs, AddFilesOptions opts) throws P4JavaException; /** * Open one or more Perforce client workspace files for editing. * * @param fileSpecs non-null list of files to be opened, in Perforce client or * depot or local path format. * @param noUpdate if true, don't actually do the open, just return the files that * would have been opened for edit. * @param bypassClientUpdate if true, the edit bypasses any client file update. * Equivalent to the new 2009.2 and later "-k" option. If set true with * a Perforce server earlier than 2009.2, will produce a suitable * RequestException. Note: this option can cause havoc if you don't * use care... * @param changeListId if positive, the opened files are put into the pending * changelist identified by changeListId; this changelist must have been * previously created. If zero or negative, the file is opened in the 'default' * (unnumbered) changelist. * @param fileType if non-null, the file is opened as that filetype. * Otherwise, the filetype of the previous revision is reused. * If the filetype given is a partial filetype, that partial * filetype is combined with the previous revision's filetype. * See 'p4 help filetypes' to attempt to make any sense of this.. * @return a non-null but possibly-empty list of IFileSpec objects * representing the opened files. Not all fields in these specs * will be valid or set. * @throws RequestException if the Perforce server encounters an error during * its processing of the request * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws AccessException if the Perforce server denies access to the caller */ List<IFileSpec> editFiles(List<IFileSpec> fileSpecs, boolean noUpdate, boolean bypassClientUpdate, int changeListId, String fileType) throws RequestException, ConnectionException, AccessException; /** * Open one or more Perforce client workspace files for editing. * * @see com.perforce.p4java.option.client.EditFilesOptions * * @param fileSpecs non-null list of files to be opened, in Perforce client or * depot or local path format. * @param opts possibly-null EditFilesOptions object specifying method options. * @return a non-null but possibly-empty list of IFileSpec objects * representing the opened files. Not all fields in these specs * will be valid or set. * @throws P4JavaException if an error occurs processing this method and its parameters */ List<IFileSpec> editFiles(List<IFileSpec> fileSpecs, EditFilesOptions opts) throws P4JavaException; /** * Revert a open Perforce client workspace files back to the revision previously synced * from the Perforce depot, discarding any pending changelists or integrations that * have been made so far. * * @param fileSpecs non-null (but possibly-empty) list of files to be reverted * @param noUpdate if true, don't actually do the revert, just return the files that * would have been reverted * @param changeListId if positive, revert only those files in the pending changelist * given in changeListId. * @param revertOnlyUnchanged if true, revert only those files which are opened * for edit or integrate and are unchanged or missing. * @param noRefresh if true, bypass the client file refresh of the reverted files. * @return a non-null but possibly-empty list of IFileSpec objects * representing the reverted files. Not all fields in these specs * will be valid or set. * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws AccessException if the Perforce server denies access to the caller */ List<IFileSpec> revertFiles(List<IFileSpec> fileSpecs, boolean noUpdate, int changeListId, boolean revertOnlyUnchanged, boolean noRefresh) throws ConnectionException, AccessException; /** * Revert open Perforce client workspace files back to the revision previously synced * from the Perforce depot, discarding any pending changelists or integrations that * have been made so far. * * @see com.perforce.p4java.option.client.RevertFilesOptions * @param fileSpecs non-null (but possibly-empty) list of files to be reverted * @param opts possibly-null RevertFilesOptions object specifying method options. * @return a non-null but possibly-empty list of IFileSpec objects * representing the reverted files. Not all fields in these specs * will be valid or set. * @throws P4JavaException if an error occurs processing this method and its parameters */ List<IFileSpec> revertFiles(List<IFileSpec> fileSpecs, RevertFilesOptions opts) throws P4JavaException; /** * Open Perforce client workspace files for deletion from a Perforce depot. * * @param fileSpecs non-null list of files to be opened * @param changeListId if positive, the opened files are put into the pending * changelist identified by changeListId; this changelist must have been * previously created. If zero or negative, the file is opened in the 'default' * (unnumbered) changelist. * @param noUpdate if true, don't actually do the open, just return the files that * would have been opened for deletion. * @return a non-null but possibly-empty list of IFileSpec objects * representing the opened files. Not all fields in these specs * will be valid or set * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws AccessException if the Perforce server denies access to the caller */ List<IFileSpec> deleteFiles(List<IFileSpec> fileSpecs, int changeListId, boolean noUpdate) throws ConnectionException, AccessException; /** * Open Perforce client workspace files for deletion from a Perforce depot. * * @see com.perforce.p4java.option.client.DeleteFilesOptions * @param fileSpecs non-null list of files to be opened * @param opts possibly-null DeleteFilesOptions object specifying method options. * @return a non-null but possibly-empty list of IFileSpec objects * representing the opened files. Not all fields in these specs * will be valid or set * @throws P4JavaException if an error occurs processing this method and its parameters */ List<IFileSpec> deleteFiles(List<IFileSpec> fileSpecs, DeleteFilesOptions opts) throws P4JavaException; /** * If one or more Perforce file specs is passed-in, return the opened / locked status * of each file (if known) within an IFileSpec object; otherwise * return a list of all files known to be open for this Perforce client workspace.<p> * * The returned list can be modified with the other arguments as described below. * * @param fileSpecs if non-empty, determine the status of the specified * files; otherwise return all qualifying files known to be open * @param maxFiles if positive, return only the first maxFiles qualifying files. * @param changeListId if positive, return only files associated with the given * changelist ID. * @return non-null but possibly-empty list of qualifying open files. Not all fields * in individual file specs will be valid or make sense to be accessed. * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws AccessException if the Perforce server denies access to the caller */ List<IFileSpec> openedFiles(List<IFileSpec> fileSpecs, int maxFiles, int changeListId) throws ConnectionException, AccessException; /** * Return a list of files open for this client, optionally restricted to a * specific path and / or changelist.<p> * * Note that if a non-null OpenedFilesOptions object is passed to this method, * the object's clientName field is ignored and the name of the client whose * openedFiles method is being called is used instead; similarly, any * allClient options (a.k.a "-a" flags) are also ignored. * * @param fileSpecs if non-empty, determine the status of the specified * files; otherwise return all qualifying files known to be open * @param opts possibly-null OpenedFilesOptions object object specifying method options. * @return non-null but possibly-empty list of qualifying open files. Not all fields * in individual file specs will be valid or make sense to be accessed. * @throws P4JavaException if an error occurs processing this method and its parameters. */ List<IFileSpec> openedFiles(List<IFileSpec> fileSpecs, OpenedFilesOptions opts) throws P4JavaException; /** * Return a list of all Perforce-managed files and versions that the Perforce server * believes this Perforce client workspace has as of the latest sync. If fileSpecs * is given, this method returns, only information on those files is returned.<p> * * <b>Note that this method will return an empty list unless the client is the * IServer object's current client.</b><p> * * Only the depotFile, revision, clientPath, and localPath fields of the returned * file specs are guaranteed to be valid. * * @param fileSpecs file specs; if empty or null, return all qualifying files * @return non-null (but possibly empty) list of IFileSpec objects for the * passed-in arguments. * @throws ConnectionException if the Perforce server is unreachable or is not * connected.t * @throws AccessException if the Perforce server denies access to the caller */ List<IFileSpec> haveList(List<IFileSpec> fileSpecs) throws ConnectionException, AccessException; /** * For each of the passed-in file specs, show how the named file maps through * the client view.<p> * * <b>Note that this method will return an empty list unless the client is the * IServer object's current client.</b><p> * * The returned IFiles contain all three of the depot, client, and local * file paths of the corresponding fileSpec array element where appropriate, or the * usual server-generated error message if there was no corresponding mapping. The * main exception to this is the case when no filespecs are given (i.e. the fileSpecs * array is null or empty), when the mappings for '...' (all files in the current directory * and below) are returned (if they exist). * * @param fileSpecs a list of Perforce file specifications; can be empty or even * null (see explanation above). * @return a non-null (but possibly empty) list of IFileSpec for the input * filespecs. * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws AccessException if the Perforce server denies access to the caller */ List<IFileSpec> where(List<IFileSpec> fileSpecs) throws ConnectionException, AccessException; /** * Reopen Perforce files in a new changelist. * * @param fileSpecs non-null list of files to be reopened * @param changeListId the new changelist ID to be used * @param fileType if non-null, the file is reopened as that filetype. * If the filetype given is a partial filetype, that partial * filetype is combined with the current filetype. * See 'p4 help filetypes' to attempt to make any sense of this.. * @return list of IFileSpec for each specified file * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws AccessException if the Perforce server denies access to the caller */ List<IFileSpec> reopenFiles(List<IFileSpec> fileSpecs, int changeListId, String fileType) throws ConnectionException, AccessException; /** * Reopen Perforce files in a new changelist. * * @param fileSpecs non-null list of files to be reopened. * @param opts possibly-null ReopenFilesOptions object object specifying method options. * @return list of IFileSpec for each specified file. * @throws P4JavaException if an error occurs processing this method and its parameters. */ List<IFileSpec> reopenFiles(List<IFileSpec> fileSpecs, ReopenFilesOptions opts) throws P4JavaException; /** * Integrate ("merge") from one Perforce filespec to another. The semantics * of Perforce merges are complex and are not explained here; please consult * the main Perforce documentation for file merges and the IntegrationOptions * Javdoc comments for details of the less-commonly-used options. * * @param changeListId if not IChangelist.UNKNOWN, use this as the target changelist * @param showActionsOnly if true, don't actually do the integration, just return * the actions that would have been done * @param branchSpec if not null, use this as the integration branch specification * (as in the -b option to integ). * @param integOpts detailed integration objects. If null, the method will use default * option values as described for the IntegrationOptions constructor, * all of which are safe for straightforward merge use. * @param fromFile if not null, use this as the source Perforce filespec * @param toFile if not null, use this as the target Perforce filespec * @return non-null list of IFileSpec objects describing the intended or * actual integration actions. * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws AccessException if the Perforce server denies access to the caller */ List<IFileSpec> integrateFiles(int changeListId, boolean showActionsOnly, IntegrationOptions integOpts, String branchSpec, IFileSpec fromFile, IFileSpec toFile) throws ConnectionException, AccessException; /** * Integrate ("merge") from one Perforce filespec to another. The semantics * of Perforce merges are complex and are not explained here; please consult * the main Perforce documentation for file merges and the IntegrateFilesOptions * Javdoc comments for details of the less-commonly-used options. * * @see com.perforce.p4java.option.client.IntegrateFilesOptions * @param fromFile fromFile if not null, use this as the source Perforce filespec * @param toFile toFile if not null, use this as the target Perforce filespec * @param branchSpec if not null, use this as the integration branch specification * (as in the -b option to integ) * @param opts possibly-null IntegrateFilesOptions object specifying method options * @return non-null list of IFileSpec objects describing the intended or * actual integration actions * @throws P4JavaException if an error occurs processing this method and its parameters */ List<IFileSpec> integrateFiles(IFileSpec fromFile, IFileSpec toFile, String branchSpec, IntegrateFilesOptions opts) throws P4JavaException; /** * Integrate one set of files (the 'source') into another (the 'target'). * The semantics of Perforce integrate are complex and are not explained here; * please consult the main Perforce documentation for file integrations and * the IntegrateFilesOptions Javdoc comments for details of the less-commonly-used * options.<p> * * Note that depending on the specific options passed-in the fromFile can be * null or one file spec; the toFiles list can be null, one or more file specs. * * @since 2011.2 * @param fromFile if not null, use this as the source file. * @param toFiles if not null, use this as the list of target files. * @param opts possibly-null IntegrateFilesOptions object specifying method options. * @return non-null (but possibly empty) list of affected files and / or error messages. * @throws P4JavaException if an error occurs processing this method and its parameters. */ List<IFileSpec> integrateFiles(IFileSpec fromFile, List<IFileSpec> toFiles, IntegrateFilesOptions opts) throws P4JavaException; /** * Automatically resolve the results of a previousPerforce file integration.<p> * * Note that this is currently a very limited version of the full Perforce resolve feature, * corresponding only to (some of) the various auto-resolve features, meaning this method * will never invoke (or need to invoke) end user interaction. More extensive versions * of the resolve command will be surfaced as needed.<p> * * This method notionally returns an IFileSpec, as it's closely * related to the integ method and shares many of its return values, but * there are several limitations in the use of the returned IFileSpecs. * In general, what is returned from this method is a mixture of resolution * info messages (i.e. messages from the server that spell out what would * or did happen during the resolve), and "true" filespecs. In the latter * case, the filespec has a very limited set of valid fields: only client path, * from file, and the from revisions are guaranteed to be valid. In the former * case, since the info messages do NOT correspond one-to-one with the input * file specs that caused the messages, consumers need to explicitly search each * returned info message string for the relevant file path or name. This is an * unfortunate artifact of the Perforce server's implementation of this command.<p> * * Note: results and behavior are undefined if clashing or inconsistent options * are used with this method. In general, the behavior of (e.g.) setting both * acceptYours and acceptTheirs true will be whatever the Perforce server makes * of it (usually an error), but that's not guaranteed.... * * Note also that having safeMerge, acceptTheirs, acceptYours, and forceResolve * all set to false results in "-am" behavior. * * @param fileSpecs files to be resolved; if null or empty, all files marked as * needing resolution will be processed * @param safeMerge if true, only do "safe" resolves, as documented for the p4 "-as" option * @param acceptTheirs if true, automatically accept "their" changes, as documented * for the p4 "-at" option * @param acceptYours if true, automatically accept "your" changes, as documented * for the p4 "-ay" option * @param showActionsOnly if true, don't do the actual resolve, just return the * actions that would have been performed for the resolve * @param forceResolve forces auto-mode resolve to accept the merged file even if * there are conflicts. This option results in a merged file that may * contain Perforce conflict markers; these markers should be edited out * of the file manually before it's submitted (unless you actually want * them there...). * @return non-null but possibly-empty list of integration file specs for the resolve; * see note above on the semantics of this list. * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws AccessException if the Perforce server denies access to the caller */ List<IFileSpec> resolveFilesAuto(List<IFileSpec> fileSpecs, boolean safeMerge, boolean acceptTheirs, boolean acceptYours, boolean showActionsOnly, boolean forceResolve) throws ConnectionException, AccessException; /** * Automatically resolve the results of a previousPerforce file integration.<p> * * Note that this is currently a very limited version of the full Perforce resolve feature, * corresponding only to (some of) the various auto-resolve features, meaning this method * will never invoke (or need to invoke) end user interaction. More extensive versions * of the resolve command will be surfaced as needed.<p> * * This method notionally returns an IFileSpec, as it's closely * related to the integ method and shares many of its return values, but * there are several limitations in the use of the returned IFileSpecs. * In general, what is returned from this method is a mixture of resolution * info messages (i.e. messages from the server that spell out what would * or did happen during the resolve), and "true" filespecs. In the latter * case, the filespec has a very limited set of valid fields: only client path, * from file, and the from revisions are guaranteed to be valid. In the former * case, since the info messages do NOT correspond one-to-one with the input * file specs that caused the messages, consumers need to explicitly search each * returned info message string for the relevant file path or name. This is an * unfortunate artifact of the Perforce server's implementation of this command.<p> * * Note: results and behavior are undefined if clashing or inconsistent options * are used with this method. In general, the behavior of (e.g.) setting both * acceptYours and acceptTheirs true will be whatever the Perforce server makes * of it (usually an error), but that's not guaranteed.... * * Note also that having safeMerge, acceptTheirs, acceptYours, and forceResolve * all set to false in the associated ResolveFilesAutoOptions object results in * "-am" behavior. * * @see com.perforce.p4java.option.client.ResolveFilesAutoOptions * @param fileSpecs files to be resolved; if null or empty, all files marked as * needing resolution will be processed * @param opts possibly-null ResolveFilesAutoOptions object specifying method option * @return non-null but possibly-empty list of integration file specs for the resolve; * see note above on the semantics of this list * @throws P4JavaException if an error occurs processing this method and its parameters */ List<IFileSpec> resolveFilesAuto(List<IFileSpec> fileSpecs, ResolveFilesAutoOptions opts) throws P4JavaException; /** * Resolve a file integration by using the contents of the sourceStream InputStream * as the resolve result.<p> * * Note that this method assumes that the target and source resolve makes * sense, and does little or no sanity- or error-checking. In particular, it * will happily accept binary and text integration resolves whether they * make sense or not; you should check the getHowResolved() method on the * returned filespec to ensure that it did what you expected (typically this * means checking that it was resolved using the "edit from" resolution rather * than, say "ignored").<p> * * Use of this method will normally result in an integration edit record * in the target file's history whether you've actually done an edit or not, so * it is up to the consumer to weed out the various straight copy resolve cases * and only use this for cases of more complex merges that actually did involve * an edit (in reality or not).<p> * * Note that the IFileSpec returned will generally not have a * valid depot or client file paths -- you must use the toFile and fromFile methods * on the returns here. * * @param targetFile non-null file to be resolved. * @param sourceStream non-null InputStream containing the resolved file's new contents. * @return possibly-null IFileSpec representing the result of the resolve * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws AccessException if the Perforce server denies access to the caller * @throws RequestException if the Perforce server encounters an error during * its processing of the request */ IFileSpec resolveFile(IFileSpec targetFile, InputStream sourceStream) throws ConnectionException, RequestException, AccessException; /** * Resolve a file integration by using the contents of the sourceStream InputStream * as the resolve result.<p> * * Note that this method assumes that the target and source resolve makes * sense, and does little or no sanity- or error-checking. In particular, it * will happily accept binary and text integration resolves whether they * make sense or not; you should check the getHowResolved() method on the * returned filespec to ensure that it did what you expected (typically this * means checking that it was resolved using the "edit from" resolution rather * than, say "ignored").<p> * * Use of this method will normally result in an integration edit record * in the target file's history whether you've actually done an edit or not, so * it is up to the consumer to weed out the various straight copy resolve cases * and only use this for cases of more complex merges that actually did involve * an edit (in reality or not).<p> * * Note that the IFileSpec returned will generally not have a * valid depot or client file paths -- you must use the toFile and fromFile methods * on the returns here. * * @param targetFile non-null file to be resolved. * @param sourceStream non-null InputStream containing the resolved file's new contents. * @param useTextualMerge attempt a textual merge even for binary files * @param startFromRev oldest revision to be resolved, or -1 for no limit * @param endFromRev newest revision to be resolved, or -1 for no limit * @return possibly-null IFileSpec representing the result of the resolve * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws AccessException if the Perforce server denies access to the caller * @throws RequestException if the Perforce server encounters an error during * its processing of the request */ IFileSpec resolveFile(IFileSpec targetFile, InputStream sourceStream, boolean useTextualMerge, int startFromRev, int endFromRev) throws ConnectionException, RequestException, AccessException; /** * Return a list of files resolved but not submitted for this client. Note that * the returned list has only the localPath field set (i.e. depot, client, and * generic paths are not set). This reflects the returned values from the server * itself. * * @param fileSpecs optional filespecs to be processed * @param showBaseRevision if true, reports the revision used as the base during * resolve (this seems to have no effect). * @return list of files that have been resolved but not yet submitted * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws AccessException if the Perforce server denies access to the caller */ List<IFileSpec> resolvedFiles(List<IFileSpec> fileSpecs, boolean showBaseRevision) throws ConnectionException, AccessException; /** * Return a list of files resolved but not submitted for this client. Note that * the returned list has only the localPath field set (i.e. depot, client, and * generic paths are not set). This reflects the returned values from the server * itself. * * @see com.perforce.p4java.option.client.ResolvedFilesOptions * @param fileSpecs fileSpecs optional filespecs to be processed * @param opts possibly-null ResolveFilesAutoOptions object specifying method options * @return list of files that have been resolved but not yet submitted * @throws P4JavaException if an error occurs processing this method and its parameters */ List<IFileSpec> resolvedFiles(List<IFileSpec> fileSpecs, ResolvedFilesOptions opts) throws P4JavaException; /** * Lock an opened file against changelist submission.<p> * * The open files named are locked in the Perforce depot, preventing any * user other than the current user on the current client from * submitting changes to the files. If a file is already locked * then the lock request is rejected. If no file specs are given * then lock all files currently open in the changelist number given * if it is IChangelist.DEFAULT or > 0.<p> * * Note that the file specs returned are only partially filled out; the * Perforce server seems to only return path information for this command. * * @param fileSpecs candidate file specs * @param changeListId if IChangelist.DEFAULT or larger than zero, lock * all files associated this changelist ID * @return non-null but possibly-empty list of locked file specs or errors * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws AccessException if the Perforce server denies access to the caller */ List<IFileSpec> lockFiles(List<IFileSpec> fileSpecs, int changeListId) throws ConnectionException, AccessException; /** * Lock an opened file against changelist submission.<p> * * The open files named are locked in the Perforce depot, preventing any * user other than the current user on the current client from * submitting changes to the files. If a file is already locked * then the lock request is rejected. If no file specs are given * then lock all files currently open in the changelist number given * if it is IChangelist.DEFAULT or > 0.<p> * * Note that the file specs returned are only partially filled out; the * Perforce server seems to only return path information for this command. * * @see com.perforce.p4java.option.client.LockFilesOptions * @param fileSpecs candidate file specs * @param opts possibly-null LockFilesOptions object specifying method options * @return non-null but possibly-empty list of locked file specs or errors * @throws P4JavaException if an error occurs processing this method and its parameters */ List<IFileSpec> lockFiles(List<IFileSpec> fileSpecs, LockFilesOptions opts) throws P4JavaException; /** * Release locked files but leave them open.<p> * * If the files are open in a specific pending changelist other than * 'default', then the changeListId parameter is required to specify the * pending changelist. If no file name is given then all files in the * designated changelist are unlocked.<p> * * Note that the file specs returned are only partially filled out; the * Perforce server seems to only return path information for this command. * * @param fileSpecs candidate file specs * @param changeListId if IChangelist.DEFAULT or larger than zero, lock * all files associated this changelist ID * @param force force the lock on non-owned filespecs. Requires appropriate * permissions. * @return non-null but possibly-empty list of unlocked file specs or errors * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws AccessException if the Perforce server denies access to the caller */ List<IFileSpec> unlockFiles(List<IFileSpec> fileSpecs, int changeListId, boolean force) throws ConnectionException, AccessException; /** * Release locked files but leave them open.<p> * * Note that the file specs returned are only partially filled out; the * Perforce server seems to only return path information for this command. * * @param fileSpecs candidate file specs * @param opts possibly-null UnlockFilesOptions object specifying method options * @return non-null but possibly-empty list of unlocked file specs or errors * @throws P4JavaException if an error occurs processing this method and its parameters */ List<IFileSpec> unlockFiles(List<IFileSpec> fileSpecs, UnlockFilesOptions opts) throws P4JavaException; /** * Return a list of files that differ in some (arbitrarily complex) * way from depot. See the help documentation for the p4 diff command * using the "-sx" (-sa, -sl, etc.) options for a full discussion * of the options used below.<p> * * Note that this method returns lists of files, and is not useful * to get the diffs themselves (at least not directly).<p> * * Note that the diff status returned for the unopenedWithStatus option * is retrievable from the filespec with the getDiffStatus() method.<p> * * Note that you must have at least one of the various "-s" options set * to true. * * @param maxFiles * @param fileSpecs candidate file specs; may be null. * @param diffNonTextFiles include non-text files in the diff lists * @param openedDifferentMissing corresponds to the "-sa" option for the p4 command line. * @param openedForIntegrate corresponds to the "-sb" option for the p4 command line. * @param unopenedMissing corresponds to the "-sd" option for the p4 command line. * @param unopenedDifferent corresponds to the "-se" option for the p4 command line. * @param unopenedWithStatus corresponds to the "-sl" option for the p4 command line. * @param openedSame corresponds to the "-sr" option for the p4 command line. * @return non-null but possibly-empty list of qualifying filepecs. * @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> getDiffFiles(List<IFileSpec> fileSpecs, int maxFiles, boolean diffNonTextFiles, boolean openedDifferentMissing, boolean openedForIntegrate, boolean unopenedMissing, boolean unopenedDifferent, boolean unopenedWithStatus, boolean openedSame) throws ConnectionException, RequestException, AccessException; /** * Return a list of files that differ in some (arbitrarily complex) * way from depot. See the help documentation for the p4 diff command * using the "-sx" (-sa, -sl, etc.) options for a full discussion * of the options used below.<p> * * Note that this method returns lists of files, and is not useful * to get the diffs themselves (at least not directly).<p> * * Note that the diff status returned for the unopenedWithStatus option * is retrievable from the filespec with the getDiffStatus() method.<p> * * Note that you must have at least one of the various "-s" options set * to true. * * @param fileSpecs candidate file specs; may be null. * @param opts possibly-null GetDiffFilesOptions object specifying method options * @return non-null but possibly-empty list of qualifying filepecs. * @throws P4JavaException if an error occurs processing this method and its parameters */ List<IFileSpec> getDiffFiles(List<IFileSpec> fileSpecs, GetDiffFilesOptions opts) throws P4JavaException; /** * Shelve files in a changelist. * * @see com.perforce.p4java.option.client.ShelveFilesOptions * * @param fileSpecs list of files to be shelved; if null or empty, shelve all files * in the changelist * @param changelistId changelistId ID of the changelist containing the files to be shelved. * Can not be IChangelist.DEFAULT or IChangelist.UNKNOWN (both of * which will cause server usage errors to be returned if used). * @param opts possibly-null ShelveFilesOptions object specifying method options * @return non-null but possibly empty list of file specs representing the * server's response * @throws P4JavaException if an error occurs processing this method and its parameters */ List<IFileSpec> shelveFiles(List<IFileSpec> fileSpecs, int changelistId, ShelveFilesOptions opts) throws P4JavaException; /** * Unshelve file(s) from a shelf. * * @param fileSpecs list of files to be unshelved; if null or empty, shelve all files * in the changelist * @param sourceChangelistId id of changelist containing shelved files to unshelve * @param targetChangelistId id of changelist unshelved files will be placed in * @param opts possibly-null UnshelveFilesOptions object specifying method options * @return non-null but possibly empty list of file specs representing the * server's response * @throws P4JavaException if an error occurs processing this method and its parameters */ List<IFileSpec> unshelveFiles(List<IFileSpec> fileSpecs, int sourceChangelistId, int targetChangelistId, UnshelveFilesOptions opts) throws P4JavaException; /** * Update/replace/delete shelved file(s) from a pending changelist. * * @param changelistId ID of the changelist containing the files to be shelved. * Can not be IChangelist.DEFAULT or IChangelist.UNKNOWN (both of * which will cause server usage errors to be returned if used). * @param fileSpecs list of files to be shelved; if null or empty, shelve all files * in the changelist * @param forceUpdate if true, update the named shelved files. * @param replace if true, replace the named shelved files. * @param discard if truem discard the named shelved files. * @return non-null but possibly empty list of file specs representing the * server's response. * @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> shelveChangelist(int changelistId, List<IFileSpec> fileSpecs, boolean forceUpdate, boolean replace, boolean discard) throws ConnectionException, RequestException, AccessException; /** * Shelve the file(s) in a pending changelist.<p> * * This performs a 'p4 shelve -i' command when called. * * @param list non-null changelist to be shelved. * @return non-null but possibly empty list of file specs representing the * server's response. * @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> shelveChangelist(IChangelist list) throws ConnectionException, RequestException, AccessException; /** * Unshelve file(s) from a shelved changelist * * @param shelveChangelistId id of changelist containing shelved files to unshelve (-s) * @param fileSpecs optional list of file specs to limit unshelving to * @param clientChangelistId id of changelist to unshelve the files into (-c) * @param forceOverwrite force clobbering of files currently writeable but unopened (-f) * @param previewOnly don't actually unshelve but get the file specs that would be * unshelved (-n) * @return non-null but possibly empty list of file specs representing the * server's response. * @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> unshelveChangelist(int shelveChangelistId, List<IFileSpec> fileSpecs, int clientChangelistId, boolean forceOverwrite, boolean previewOnly) throws ConnectionException, RequestException, AccessException; /** * Submit a shelved changelist without transferring files or modifying the * workspace. The shelved change must be owned by the person submitting the * change, but the client may be different. However, files shelved to a * stream target may only be submitted by a stream client that is mapped to * the target stream. In addition, files shelved to a non-stream target * cannot be submitted by a stream client. To submit a shelved change, all * files in the shelved change must be up to date and resolved. No files may * be open in any workspace at the same change number. Client submit options * (ie revertUnchanged, etc) will be ignored. If the submit is successful, * the shelved change and files are cleaned up, and are no longer available * to be unshelved or submitted.<p> * * This performs a 'p4 submit -e shelvedChange#' command when called. * * @since 2013.2 * @param shelvedChangelistId * the shelved changelist to be submited. * @return non-null but possibly empty list of file specs representing the * server's response. * @throws P4JavaException if an error occurs processing this method and its parameters. */ List<IFileSpec> submitShelvedChangelist(int shelvedChangelistId) throws P4JavaException; /** * Schedule resolve and integration actions to make the target file identical to * the source file based only on the differences between the two (i.e. ignoring * prior integration history).<p> * * Corresponds to the 'p4 copy' command. * * @since 2011.1 * @param fromFile if not null, use this as the source file. * @param toFile if not null, use this as the target file. * @param branchSpec if not null, use this as the copy branch specification. * @param opts possibly-null CopyFilesOptions object specifying method options. * @return non-null (but possibly empty) list of affected files and / or error messages. * @throws P4JavaException if an error occurs processing this method and its parameters. */ List<IFileSpec> copyFiles(IFileSpec fromFile, IFileSpec toFile, String branchSpec, CopyFilesOptions opts) throws P4JavaException; /** * Copies one set of files (the 'source') into another (the 'target').<p> * * Note that depending on the specific options passed-in the fromFile can be * null or one file spec; the toFiles list can be null, one or more file specs. * The full semantics of this operation are found in the main 'p4 help copy' * documentation. * * @since 2011.2 * @param fromFile if not null, use this as the source file. * @param toFiles if not null, use this as the list of target files. * @param opts possibly-null CopyFilesOptions object specifying method options. * @return non-null (but possibly empty) list of affected files and / or error messages. * @throws P4JavaException if an error occurs processing this method and its parameters. */ List<IFileSpec> copyFiles(IFileSpec fromFile, List<IFileSpec> toFiles, CopyFilesOptions opts) throws P4JavaException; /** * Merges changes from one set of files (the 'source') into another (the 'target'). * It is a simplified form of the 'p4 integrate' command. The semantics of * Perforce merges are complex and are not explained here; please consult * the main Perforce documentation for file merges and the MergeFilesOptions * Javdoc comments for details of the less-commonly-used options.<p> * * Note that depending on the specific options passed-in the fromFile can be * null or one file spec; the toFiles list can be null, one or more file specs. * * @since 2011.2 * @param fromFile if not null, use this as the source file. * @param toFiles if not null, use this as the list of target files. * @param opts possibly-null MergeFilesOptions object specifying method options * @return non-null list of IFileSpec objects describing the intended or * actual merge actions * @throws P4JavaException if an error occurs processing this method and its parameters */ List<IFileSpec> mergeFiles(IFileSpec fromFile, List<IFileSpec> toFiles, MergeFilesOptions opts) throws P4JavaException; /** * Open files for add, delete, and/or edit to reconcile client with workspace * changes made outside of Perforce.<p> * * 'p4 reconcile' finds unopened files in a client's workspace and detects the * following:<p> * * 1. files in depot missing from workspace, but still on have list.<p> * 2. files on workspace that are not in depot.<p> * 3. files modified in workpace that are not opened for edit.<p> * * By default, the files matching each condition above in the path are reconciled * by opening files for delete (scenario 1), add (scenario 2), and/or edit (scenario 3). * The -e, -a, and -d flags may be used to limit to a subset of these operations. * If no file arguments are given, reconcile and status default to the current * working directory. * * @see com.perforce.p4java.option.client.ReconcileFilesOptions * * @since 2012.2 * @param fileSpecs non-null list of files to be opened, in Perforce client or * depot or local path format. * @param opts possibly-null ReconcileFilesOptions object specifying method options. * @return a non-null but possibly-empty list of IFileSpec objects * representing the opened files. Not all fields in these specs * will be valid or set. * @throws P4JavaException if an error occurs processing this method and its parameters */ List<IFileSpec> reconcileFiles(List<IFileSpec> fileSpecs, ReconcileFilesOptions opts) throws P4JavaException; /** * Branches a set of files (the 'source') into another depot location (the * 'target') in a single step. The new files are created immediately, without * requiring a 'p4 submit' or a client workspace.<p> * * Note that depending on the specific options passed-in the fromFile can be * null or one file spec; the toFiles list can be null, one or more file specs. * The full semantics of this operation are found in the main 'p4 help populate' * documentation. * * @since 2012.3 * @param fromFile if not null, use this as the source file. * @param toFiles if not null, use this as the list of target files. * @param opts possibly-null PopulateFilesOptions object specifying method options. * @return non-null (but possibly empty) list of affected files and / or error messages. * @throws P4JavaException if an error occurs processing this method and its parameters. */ List<IFileSpec> populateFiles(IFileSpec fromFile, List<IFileSpec> toFiles, PopulateFilesOptions opts) 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/client/IClient.java | |||||
#1 | 12541 | Matt Attaway | Initial add of the 14.1 p4java source code |