/* * Copyright 2008 Perforce Software Inc., All Rights Reserved. */ package com.perforce.p4java.server; import java.io.InputStream; import java.nio.charset.UnsupportedCharsetException; import java.util.List; import java.util.Map; import java.util.Properties; import com.perforce.p4java.admin.IDbSchema; import com.perforce.p4java.admin.IProtectionEntry; import com.perforce.p4java.client.IClient; import com.perforce.p4java.client.IClientSummary; import com.perforce.p4java.core.IBranchSpecSummary; import com.perforce.p4java.core.IChangelistSummary; import com.perforce.p4java.core.IFileDiff; import com.perforce.p4java.core.ILabelSummary; import com.perforce.p4java.core.IUser; import com.perforce.p4java.core.IUserSummary; import com.perforce.p4java.core.IBranchSpec; import com.perforce.p4java.core.IChangelist; import com.perforce.p4java.core.IDepot; import com.perforce.p4java.core.IFix; import com.perforce.p4java.core.IJob; import com.perforce.p4java.core.IJobSpec; import com.perforce.p4java.core.ILabel; import com.perforce.p4java.core.IServerProcess; import com.perforce.p4java.core.IUserGroup; import com.perforce.p4java.core.file.DiffType; import com.perforce.p4java.core.file.IExtendedFileSpec; import com.perforce.p4java.core.file.IFileAnnotation; import com.perforce.p4java.core.file.IFileRevisionData; import com.perforce.p4java.core.file.IFileSpec; import com.perforce.p4java.core.file.FileStatAncilliaryOptions; import com.perforce.p4java.core.file.FileStatOutputOptions; import com.perforce.p4java.exception.AccessException; import com.perforce.p4java.exception.ConfigException; import com.perforce.p4java.exception.ConnectionException; import com.perforce.p4java.exception.P4JavaException; import com.perforce.p4java.exception.RequestException; import com.perforce.p4java.option.server.DescribeOptions; import com.perforce.p4java.server.callback.ICommandCallback; import com.perforce.p4java.server.callback.IProgressCallback; import com.perforce.p4java.server.callback.ISSOCallback; import com.perforce.p4java.server.callback.IStreamingCallback; /** * Provides an interface onto a Perforce SCM server.<p> * * This is the main interface for Perforce services that are typically Perforce client * workspace-independent, or that affect entire Perforce depots or servers. Some of these * services are also available through various client, job, changelist, etc., interfaces * methods, but in general, most Perforce services are always available through methods * on this interface as well.<p> * * IServer interfaces for specific Perforce servers are issued by the P4Javs server factory * class, ServerFactory; the factory can return interfaces that use a small variety * of communication protocols to access the Perforce server. * * @see com.perforce.p4java.server.ServerFactory */ public interface IServer { /** * Return the Java properties associated with this server. The Properties * returned here are the actual properties used in the server and can be updated * through this method (i.e. the object is not just a copy). The interpretation * of the individual Properties are implementation-specific and not discussed * here. * * @return Properties object; may be empty but will not be null. */ Properties getProperties(); /** * Register a P4Java command callback with this Perforce server.<p> * * See the ICommandCallback javadocs for callback semantics. Note that only * one command callback can be active and registered for a given server at any * one time. * * @param callback ICommandCallback object to be registered; if null, command * callbacks are disabled. * @return the previous command callback, if it existed; null otherwise */ ICommandCallback registerCallback(ICommandCallback callback); /** * Register a P4Java command progress callback with this Perforce server.<p> * * See the IProgressCallback javadocs for callback semantics. Note that only * one progress callback can be active and registered for a given server at any * one time. * * @param callback IProgressCallback object to be registered; if null, progress * callbacks are disabled. * @return the previous progress callback, if it existed; null otherwise */ IProgressCallback registerProgressCallback(IProgressCallback callback); /** * Register a Perforce Single Sign On (SSO) callback and key for this server.<p> * * See the ISSOCallback Javadoc comments for an explanation of the SSO * callback feature; note that only one SSO callback can be active and * registered for a given P4Jserver object at any one time.<p> * * Note that SSO callbacks work only with the (default) pure Java (RPC) * protocol implementation. * * @param callback ISSOCallback object to be registered; if null, SSO * callbacks are disabled. * @param ssoKey opaque string to be passed untouched to the callback; can * be null, in which case null is passed in to the callback * @return the previous SSO callback, if it existed; null otherwise */ ISSOCallback registerSSOCallback(ISSOCallback callback, String ssoKey); /** * Return the current status of this server object. * * @return non-null ServerStatus representing the server status. */ ServerStatus getStatus(); /** * Set the Perforce server's charset to the passed-in charset name. The semantics * of this are described in the full Perforce documentation, but note that odd things * will happen if the named charset isn't recognized by both the JVM and the Perforce server * (i.e. "utf8" works fine, but bizarre variants may not). What constitutes a good * charset name, and whether or not the server recognises it, is somewhat fraught and * may involve retrieving the unicode counter and using the (printed) list of recognised * charsets. * * @param charsetName charset name; if null, resets the charset to "no charset". * @return true if the attempt to set the charset name succeeded; false otherwise. False * will only be returned if the JVM doesn't support the charset. (an exception * will be thrown if the server doesn't recognize it). * @throws UnsupportedCharsetException if the Perforce server doesn't * support or recognize the charset name. */ boolean setCharsetName(String charsetName) throws UnsupportedCharsetException; /** * Get the current charset name for the server connection. May be null, in which * case there is no associated character set. * * @return charset name associated with this server; may be null. */ String getCharsetName(); /** * Get the Perforce version number of the Perforce server associated with this * IServer object, if any. This will be in the form 20092 or 20073 (corresponding * to 2009.2 and 2007.3 respectively), but the version number will not be available * if you're not actually connected to a Perforce server. * * @return positive integer version number or -1 if not known or unavailable. */ int getServerVersionNumber(); /** * Returns whether the Perforce server associated with this IServer object * is case sensitive. * * @return - true if case sensitive, false if case insensitive. */ boolean isCaseSensitive(); /** * Return true if the underlying Perforce server supports Unicode (and is connected). * In this context "supporting unicode" simply means that the method was able to contact the * server and retrieve a "true" unicode-enabled status using the info command.<p> * * @return true iff the underlying server supports Unicode. * @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 */ boolean supportsUnicode() throws ConnectionException, RequestException, AccessException; /** * Return true IFF the underlying Perforce server supports the new 2009.1 * and later "smart move" command. Note that this returns whether the * server can support moves only at the time the server is first created; * it's entirely possible for the underlying server to change versions, etc., * under the user in the meanitme or over time. In any case, if you do try * to run a move command on such a server, the results will be safe, if not * entirely what you expected. As of 2010.2 it also possible for the server * to be configured to disable the move command, in which case this function * will return false. * * @return true iff the server supports the smart move command. * @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 */ boolean supportsSmartMove() throws ConnectionException, RequestException, AccessException; /** * Return an array of strings representing "known" charsets (e.g. "utf8" or * "utf32le".<p> * * Note that in this context, "known" simply means that Perforce servers supported by * this API can potentially recognize the charset name and (hopefully) act accordingly.<p> * * Charset support in Perforce is described in more detail in the main p4 * command documentation; in summary, although the list returned here is * comprehensive and quite impressive, unless the Perforce server is actually * primed to cope with Unicode (which, by default, they're not), the only * charset listed here that will work is "none"; furthermore, actual charset * support is somewhat idiosyncratic -- please refer to specific documentation * for guidance with this. You probably need to use this method in conjunction * with the supportsUnicode() method above. * * @return a non-null array of strings representing lower-case charset names * known to the server. */ String[] getKnownCharsets(); /** * Set the Perforce user name to be used with this server. This does not perform * any login or checking, just associates a user name with this session. Once * set, the user name is used with all commands where it makes sense.<p> * * Note that the auth ticket (if available) for this user will also be set * to this server instance. * * @param userName Perforce user name; can be null, which is interpreted * as "don't associate a user name with this server". */ void setUserName(String userName); /** * Set the server's Perforce authentication ticket to the passed-in string. * If the string is null, auth tickets won't be used when talking to the * associated Perforce server; otherwise, the auth ticket will be used to * authenticate against the Perforce server for each call to the server.<p> * * No checking is performed on the passed-in ticket, and any changes to * existing tickets can cause authentication failures, so you should * ensure the passed-in ticket is valid and makes sense for the current * context. * * @param authTicket possibly-null Perforce authentication ticket */ void setAuthTicket(String authTicket); /** * Return the current Perforce authentication ticket being used by * this server, if any. This ticket is not always guaranteed to be * currently valid, so reuse should be done carefully. * * @return possibly-null Perforce authentication ticket */ String getAuthTicket(); /** * Set the Perforce server's idea of each command's working directory. * This affects all commands on this server from this point on, and * the passed-in path should be both absolute and valid, otherwise * strange errors may appear from the server. If dirPath is null, * the Java VM's actual current working directory is used instead * (which is almost always a safe option unless you're using Perforce * alt roots).<p> * * Note: no checking is done at call time for correctness (or otherwise) * of the passed-in path. * * @param dirPath absolute path of directory to be used, or null */ void setWorkingDirectory(String dirPath); /** * Get the underlying server's notion of the current working directory. * If this method returns null, the server is using the JVM's current * working directory, typically available as the System user.dir * property. * * @return current working directory path, or null if not set */ String getWorkingDirectory(); /** * Return the user name currently associated with this server, if any. * User names are set using the setUserName method. * * @return the user name currently associated with this server, if any; * null otherwise. */ String getUserName(); /** * Connect to the Perforce server associated with this server object.<p> * * This method's detailed semantics depend on the underlying transport * implementation, but in general, it's intended to be called before * any attempt is made to issue a command to the associated Perforce * server. It's also intended to be called after any (intentional or * accidental) disconnect.<p> * * Note that certain implementations may try to request a client, etc., * on connection (in response to property values passed in through the * URL, etc.), which may cause a RequestException to be generated. * * @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 * @throws ConfigException if local I/O exception occurs */ void connect() throws ConnectionException, AccessException, RequestException, ConfigException; /** * Return true iff and the server object is connected to the associated * Perforce server.<p> * * The meaning of "connected" is generally dependent on the underlying * transport layer, but in general, if the server is not connected, * issuing server commands to the associated Perforce server will fail * with a connection exception. * * @return - true iff connected, false otherwise */ boolean isConnected(); /** * Disconnect from this Perforce server. Does not affect the current * IServer's current user, password, or client settings, but if you * later reconnect to the same Perforce server, you may also need to re-login.<p> * * This command should be run at the point at which this server is not * going to be used any more, and attempts to disconnect from the associated * server. "Disconnect" here has different meanings according to the underlying * transport mechanism, but in practice it will mean that attempting to use this * server object to issue Perforce commands will fail, usually with a * ConnectionException exception. */ void disconnect() throws ConnectionException, AccessException; /** * Log the current user (if any) in to a Perforce server, optionally * arranging to be logged in for all hosts.<p> * * Attempts to log in to the underlying Perforce server. If successful, * successive calls to server-side services will succeed until the session * is terminated by the server or the user logs out.<p> * * Behaviour is undefined if the server's user name attribute is null (but * will probably cause a NullPointerError with most implementations).<p> * * Login will work with the Perforce SSO (single sign-on) scheme: in this * case your password should be null, and the environment variable P4LOGINSSO * should point to an executable SSO script as described in p4 help undoc (help * for this is beyond the scope of this method doc, unfortunately, and the feature * is not well tested here, but it "works" in general...). * * @param password Perforce password; can be null if no password is needed (as * in the case of SSO logins) * @param allHosts if true, perform the equivalent of a "login -a" * @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 * @throws ConfigException if the p4tickets file could not be updated successfully */ void login(String password, boolean allHosts) throws ConnectionException, RequestException, AccessException, ConfigException; /** * Convenience method for login(password, false). * * @param password Perforce password; can be null if no password is needed (as * in the case of SSO logins) * * @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 * @throws ConfigException if the p4tickets file could not be updated successfully */ void login(String password) throws ConnectionException, RequestException, AccessException, ConfigException; /** * Return a string indicating the current login status; corresponds * to the p4 login -s command. The resulting string should be interpreted * by the caller, but is typically something like "User p4jtestsuper ticket * expires in 9 hours 42 minutes." or "'login' not necessary, no password set * for this user." or "Perforce password (P4PASSWD) invalid or unset." or * "Access for user 'p4jtestinvaliduser' has not been enabled by 'p4 protect'", * etc. * * @return non-null, but possibly-empty ticket / login status string. * Interpretation of this string is up to the caller. * @throws P4JavaException if any errors occur during the processing of * this command. */ String getLoginStatus() throws P4JavaException; /** * Log the current Perforce user out of a Perforce server session.<p> * * @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 * @throws ConfigException if the p4tickets file could not be updated successfully */ void logout() throws ConnectionException, RequestException, AccessException, ConfigException; /** * Return a snapshot set of data on the Perforce server associated with * this server interface. If the server has been disconnected, this method * will throw a suitable ConnectionException. * * @return non-null IServerInfo interface. * @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 */ IServerInfo getServerInfo() throws ConnectionException, RequestException, AccessException; /** * Get a list of all Perforce depots known to this Perforce server. * * @return non-null (but possibly empty) list of non-null IDepot * objects representing the underlying Perforce depots. * @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<IDepot> getDepots() throws ConnectionException, RequestException, AccessException; /** * Get the user details of a specific Perforce user from the Perforce server. * * @param userName if null, get the current user details, otherwise use the * passed-in user name. * @return IUser details for the user, or null if no such user is known. * @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 */ IUser getUser(String userName) throws ConnectionException, RequestException, AccessException; /** * Create a new Perforce user on the Perforce server. * * @param user non-null IUser defining the new user to be created. * @param force if true, force the creation of any named user; requires admin * privileges, * @return possibly-null status message string as returned from the 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 */ String createUser(IUser user, boolean force) throws ConnectionException, RequestException, AccessException; /** * Update a Perforce user on the Perforce server. * * @param user non-null IUser defining the user to be updated * @param force if true, force update for users other than the caller. Requires * super user / admin privileges (enforced by the server). * @return possibly-null status message string as returned from the 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 */ String updateUser(IUser user, boolean force) throws ConnectionException, RequestException, AccessException; /** * Delete a named Perforce user from the Perforce server. * * @param userName non-null name of the user to be deleted. * @param force if true, force deletion for users other than the caller. Requires * super user / admin privileges (enforced by the server). * @return possibly-null status message string as returned from the 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 */ String deleteUser(String userName, boolean force) throws ConnectionException, RequestException, AccessException; /** * Get a list of Perforce users known to this Perforce server. Note that * maxUsers and the user list are supposed to be mutually exclusive in * usage, but this is not enforced by P4Java as the restriction doesn't * make much sense and may be lifted in the Perforce server later.<p> * * Note that this implementation differs a bit from the p4 command line * version in that it simply doesn't return any output for unmatched users. * * @param userList if non-null, restrict output to users matching the passed-in * list of users. * @param maxUsers if positive, only return the first maxUsers users. * @return non-null (but possibly empty) list of non-null IUserSummary * objects representing the underlying Perforce users (if any). * @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<IUserSummary> getUsers(List<String> userList, int maxUsers) throws ConnectionException, RequestException, AccessException; /** * Get a list of Perforce user groups from the server.<p> * * Note that the Perforce server considers it an error to have both indirect and * displayValues parameters set true; this will cause the server to throw a * RequestException with an appropriate usage message. * * @param userOrGroupName if non-null, restrict the list to the specified group or username. * @param indirect if true, also displays groups that the specified user or group belongs * to indirectly via subgroups. * @param displayValues if true, display the MaxResults, MaxScanRows, MaxLockTime, * and Timeout values for the named group. * @param maxGroups if > 0, display only the first m results. * @return a non-zero but possibly-empty list of qualifying groups. * @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<IUserGroup> getUserGroups(String userOrGroupName, boolean indirect, boolean displayValues, int maxGroups) throws ConnectionException, RequestException, AccessException; /** * Get the named Perforce user group. Note that since the Perforce server usually * interprets asking for a non-existent group as equivalent to asking for a template * for a new user group, you will normally always get back a result here. It is * best to first use the getUserGroups method to see if the group exists, then * use this method to retrieve a specific group once you know it exists. * * @param name non-null group name. * @return IUserGroup representing the named user group if it exists on the server; * null otherwise (but see note in main comments above). * @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. */ IUserGroup getUserGroup(String name) throws ConnectionException, RequestException, AccessException; /** * Create a new Perforce user group on the Perforce server. * * @param group non-null IUserGroup to be created. * @return possibly-null status message string as returned from the 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. */ String createUserGroup(IUserGroup group) throws ConnectionException, RequestException, AccessException; /** * Update a Perforce user group on the Perforce server. * * @param group non-null user group to be updated. * @param updateIfOwner if true, allows a user without 'super' * access to modify the group only if that user is an * 'owner' of that group. * @return possibly-null status message string as returned from the 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. */ String updateUserGroup(IUserGroup group, boolean updateIfOwner) throws ConnectionException, RequestException, AccessException; /** * Delete a Perforce user group from the Perforce server. * * @param group non-null group to be deleted. * @return possibly-null status message string as returned from the 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. */ String deleteUserGroup(IUserGroup group) throws ConnectionException, RequestException, AccessException; /** * Get a list of Perforce protection entries for the passed-in arguments.<p> * * Note that the behavior of this method is unspecified when using clashing * options (e.g. having both userName and groupName set non-null). Consult the * main Perforce admin documentation for semantics and usage.<p> * * Note that the annotations in the file paths will be dropped. The reason is * the Perforce server 'protects' command requires a file list devoid of annotated * revision specificity. * * @param allUsers if true, protection lines for all users are displayed. * @param hostName only protection entries that apply to the given host (IP address) * are displayed. * @param userName protection lines Perforce user "userName" are displayed. * @param groupName protection lines for Perforce group "groupName" are displayed. * @param fileList if non-null, only those protection entries that apply to the * specified files are displayed. * @return non-null but possibly empty list of protection entries. * @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<IProtectionEntry> getProtectionEntries(boolean allUsers, String hostName, String userName, String groupName, List<IFileSpec> fileList) throws ConnectionException, RequestException, AccessException; /** * Get a list of IClientSummary objects for all Perforce clients known to this Perforce * server.<p> * * Note that this method returns light-weight IClientSummary objects rather than full * IClient objects; if you need the heavy-weight IClient objects, you should use getClient(). * * Note also that the returned IClient objects are not "complete", in the sense * that implementations are free to leave certain attributes null for performance * reasons. In general, at least the client's name, root, description, last modification * time are guaranteed correct. * * @param userName if not null, restrict listings to clients owned by the user 'userName' * @param queryString if not null, limits output to clients whose name matches the query * pattern passed-in. * Note this option does not work for earlier Perforce servers. * @param maxResults if > 0, restrict output to the first maxResults results. * @return non-null (but possibly empty) list of Client objects for Perforce clients * known to this 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<IClientSummary> getClients(String userName, String queryString, int maxResults) throws ConnectionException, RequestException, AccessException; /** * Get a list of Perforce labels, optionally tied to a specific set of files.<p> * * Note that the ILabel objects returned here do not have views associated with * them (i.e. the getViewMapping() method will return an empty list. If you need * to get the view mapping for a specific label, use the getLabel() method. * * @param user if non-null, limit labels to those owned by the named user * @param maxLabels if larger than zero, return only the first maxLabels * (or fewer) qualifying labels * @param nameFilter if not null, limits output to labels whose name matches * the nameFilter pattern, e.g. -e 'svr-dev-rel*' * @param fileList if not null, limits its report to labels that contain those files * @return non-null (but possibly-empty) list of qualifying Perforce labels * @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<ILabelSummary> getLabels(String user, int maxLabels, String nameFilter, List<IFileSpec> fileList) throws ConnectionException, RequestException, AccessException; /** * Get a specific named Perforce label.<p> * * Unlike the getLabelList method, the getViewMapping method on the returned * label will be valid. Note though that changes to the returned label or its * view will not be reflected on to the server unless the updateLabel method * is called with the label as an argument. * * @param labelName non-null label name * @return ILabel representing the associated Perforce label, or null if no * such label exists on the 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 */ ILabel getLabel(String labelName) throws ConnectionException, RequestException, AccessException; /** * Create a new Perforce label in the Perforce server. * * @param label non-null ILabel to be saved * @return non-null result message string from the Perforce server; this may include * form trigger output pre-pended and / or appended to the "normal" message. * @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 */ String createLabel(ILabel label) throws ConnectionException, RequestException, AccessException; /** * Update an existing Perforce label in the Perforce server. * * @param label non-null ILabel to be updated * @return non-null result message string from the Perforce server; this may include * form trigger output pre-pended and / or appended to the "normal" message. * @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 */ String updateLabel(ILabel label) throws ConnectionException, RequestException, AccessException; /** * Delete a named Perforce label from the Perforce server. * * @param labelName non-null label name * @param force if true, forces the deletion of any label; normally labels * can only be deleted by their owner * @return non-null result message string from the Perforce server; this may include * form trigger output pre-pended and / or appended to the "normal" message * @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 */ String deleteLabel(String labelName, boolean force) throws ConnectionException, RequestException, AccessException; /** * Tag files with a Perforce label. * * @param fileSpecs non-null list of files to be tagged. * @param labelName non-null label name to use for the tagging. * @param listOnly if true, don't do the actual tag, just return the list of files that * would have been tagged. * @param delete if true, delete the label tag from the files. * @return a non-null (but possibly empty) list of affected file specs * @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> tagFiles(List<IFileSpec> fileSpecs, String labelName, boolean listOnly, boolean delete) throws ConnectionException, RequestException, AccessException; /** * Get a list of all summary Perforce branch specs known to the Perforce server.<p> * * Note that the IBranchSpecSummary objects returned here do not have branch * view specs; you must call the getBranchSpec method on a specific branch to get * valid view specs for a branch. * * @param userName if non-null, limit qualifying branches to those owned by the named user. * @param nameFilter if non-null, limits output to branches whose name matches * the nameFilter pattern. * @param maxReturns if greater than zero, limit output to the first maxReturns * number of branches. * @return non-null (but possibly-empty) list of IBranchSpecSummary objects. * @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<IBranchSpecSummary> getBranchSpecs(String userName, String nameFilter, int maxReturns) throws ConnectionException, RequestException, AccessException; /** * Get a specific named Perforce branch spec from the Perforce server.<p> * Note that since the Perforce server usually interprets asking for a non-existent * branch spec as equivalent to asking for a template for a new branch spec, * you will normally always get back a result here. It is best to first use * the getBranchSpecList method to see if the branch spec exists, then * use this method to retrieve a specific branch spec once you know it exists. * * @param name non-null branch name * @return potentially-null IBranchSpec for the named Perforce branch spec. * @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 */ IBranchSpec getBranchSpec(String name) throws ConnectionException, RequestException, AccessException; /** * Create a new Perforce branch spec on the Perforce server. * * @param branchSpec non-null branch spec to be created. * @return non-null result message string from the Perforce server; this may include * form trigger output pre-pended and / or appended to the "normal" message. * @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 */ String createBranchSpec(IBranchSpec branchSpec) throws ConnectionException, RequestException, AccessException; /** * Update a Perforce branch spec on the Perforce server. * * @param branchSpec non-null branch spec to be updated. * @return non-null result message string from the Perforce server; this may include * form trigger output pre-pended and / or appended to the "normal" message. * @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 */ String updateBranchSpec(IBranchSpec branchSpec) throws ConnectionException, RequestException, AccessException; /** * Delete a named Perforce branch spec from the Perforce server. * * @param branchSpecName non-null branch spec name * @param force if true, forces the deletion of any branch; normally branches * can only be deleted by their owner * @return non-null result message string from the Perforce server; this may include * form trigger output pre-pended and / or appended to the "normal" message * @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 */ String deleteBranchSpec(String branchSpecName, boolean force) throws ConnectionException, RequestException, AccessException; /** * Return the Perforce client currently associated with this Perforce server, if any. * * @return IClient representing the current client, or null if no client * associated with this server. */ IClient getCurrentClient(); /** * Set the Perforce client associated with this server. * * @param client * @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 setCurrentClient(IClient client) throws ConnectionException, RequestException, AccessException; /** * Get an IClient object for a specific named Perforce client.<p> * * Note that (unfortunately) some implementations cannot detect * a non-existent client at this stage, and using the client returned in such circumstances * may cause errors down the road. * * @param clientName non-null Perforce client name. * @return IClient representing the specified Perforce client, or null if no such client. * @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 */ IClient getClient(String clientName) throws ConnectionException, RequestException, AccessException; /** * Convenience method for getClient(clientSummary.getName()). * * @param clientSummary non-null Perforce client summary object. * @return IClient representing the specified Perforce client, or null if no such client. * @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 */ IClient getClient(IClientSummary clientSummary) throws ConnectionException, RequestException, AccessException; /** * Get a template of a non-existent named Perforce client. This will only * return an IClient for clients that don't exist. This method is designed * to be able to get the server returned default values it uses when a * non-existent client is requested. * * @param clientName * non-null Perforce client name. * @return IClient representing the specified Perforce client, or null if * no such client. * @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 */ IClient getClientTemplate(String clientName) throws ConnectionException, RequestException, AccessException; /** * Get a template of a non-existent named Perforce client. This will only * return an IClient for clients that don't exist unless the allowExistent * parameter is set to true. This method is designed to be able to get the * server returned default values it uses when a non-existent client is * requested. * * @param clientName * non-null Perforce client name. * @param allowExistent * - true to return a client even if it exists * @return IClient representing the specified Perforce client, or null if * no such client. * @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 */ IClient getClientTemplate(String clientName, boolean allowExistent) throws ConnectionException, RequestException, AccessException; /** * Attempt to create a new Perforce client (a.k.a. "workspace") in the * Perforce server. The client should be fetched via * {@link #getClient(String)} after this call in order to obtain the full * client spec as the server may fill in defaults for missing fields in the * specified newClient. This method will return a server status message and * will throw an exception if the client was not created for various * reasons. Note that the server status message may have form trigger * output appended or prepended to it. * * @return non-null result message string from the Perforce server * @param newClient * non-null IClient defining the new Perforce client to be * created. * @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 */ String createClient(IClient newClient) throws ConnectionException, RequestException, AccessException; /** * Update an existing Perforce client on the current Perforce server. This client does * not need to be the current client, and no association with the passed-in client is * made by the server (i.e. it's not made the current client). * * @param client non-null IClient defining the Perforce client to be updated * @return possibly-null operation result message string 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 */ String updateClient(IClient client) throws ConnectionException, RequestException, AccessException; /** * Delete a Perforce client from a Perforce server. The effects this has on the client * and the server are not well-defined here, and you should probably consult the relevant * Perforce documentation for your specific case. In any event, you can cause quite * a lot of inconvenience (and maybe even damage) doing a forced delete without preparing * properly for it, especially if the client is the current client. * * @param clientName non-null name of the client to be deleted from the server. * @return possibly-null operation result message string from the Perforce server * @param force if true, tell the server to attempt to force the delete regardless of * the consequences. You're on your own with this one... * @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 */ String deleteClient(String clientName, boolean force) throws ConnectionException, RequestException, AccessException; /** * List all Perforce depot files known to the Perforce server that conform to the * passed-in wild-card file specification(s).<p> * * If client file names are given as file spec arguments the current Perforce client * view mapping is used to list the corresponding depot files, if the client and * view exist (if not, the results are undefined).<p> * * Normally, the head revision of each matching file is listed, but you can change * this by specifying specific revisions or revision ranges. If the file spec argument * includes a revision, then all files as of that revision are returned. If the file spec * argument has a revision range, then only files selected by that revision range * are returned, and the highest revision in the range is used for each file. * If allRevs is true, all revisions within the specific range, rather than just * the highest revision in the range, are returned.<p> * * See 'p4 help revisions' for help specifying revisions.<p> * * Note that the IFileSpec objects returned will have null client and local * path components. * * @param fileSpecs a non-null list of one or more IFileSpecs to be used * to qualify Perforce depot files * @param allRevs if true, list all revisions of qualifying files. * @return a non-null (but possible empty) list of all qualifying depot files * @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> getDepotFiles(List<IFileSpec> fileSpecs, boolean allRevs) throws ConnectionException, AccessException; /** * Get a list of revision annotations for the specified files. * * @param fileSpecs non-null list of file specs to be annotated * @param wsOpts 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. * @param allResults if true, include both deleted files and lines no longer present * at the head revision * @param useChangeNumbers if true, annotate with change numbers rather than * revision numbers with each line * @param followBranches if true, follow branches. * @return non-null (but possibly-empty) list of IFileAnnotation objects representing * version annotations for the passed-in file specs. * @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<IFileAnnotation> getFileAnnotations(List<IFileSpec> fileSpecs, DiffType wsOpts, boolean allResults, boolean useChangeNumbers, boolean followBranches) throws ConnectionException, RequestException, AccessException; /** * Move a file 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.<p> * * 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.<p> * * Note also that the move command is special in that almost alone among Perforce * file-based commands, it does not allow full filespecs with version specifiers; * these are currently quietly stripped off in the move command implementation here, * which may lead to unexpected behaviour if you pass in specific versions expecting * them to be honoured. * * @param changelistId if not IChangelist.UNKNOWN, the files are opened in the numbered * pending changelist instead of the 'default' changelist. * @param listOnly if true, don't actually perform the move, just return what would * happen if the move was performed * @param noClientMove if true, bypasses the client file rename. This option can be * used to tell the server that the user has already renamed a file on * the client. The use of this option can confuse the server if you * are wrong about the client's contents. Only works for 2009.2 and later * servers; earlier servers will produce a RequestException if you set * this true. * @param fileType if not null, the file is reopened as that filetype. * @param fromFile the original file; must be already open for edit. * @param toFile the target file. * @return list of IFileSpec objects representing the results of this move * @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> moveFile(int changelistId, boolean listOnly, boolean noClientMove, String fileType, IFileSpec fromFile,IFileSpec toFile) throws ConnectionException, RequestException, AccessException; /** * List any directories matching the passed-in file specifications. * * @param fileSpecs non-null list of file specifications * @param clientOnly if true, limit the returns to directories that are mapped in * the current Perforce client workspace * @param deletedOnly if true, includes directories with only deleted files. * @param haveListOnly if true, lists directories of files on the 'have' list. * @return non-null but possibly empty list of qualifying directory file specs; only * the getPath() path will be valid. * @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> getDirectories(List<IFileSpec> fileSpecs, boolean clientOnly, boolean deletedOnly, boolean haveListOnly) throws ConnectionException, AccessException; /** * An omnibus method to get a list of Perforce changelists from a server using zero or more * qualifiers (note that convenience methods also exists, especially on the IClient * interface).<p> * * Note that if both submittedOnly and pendingOnly are true, the results are * implementation-defined. * * @param maxMostRecent if positive, restrict the list to the maxMostRecent * most recent changelists. * Implementations are free to ignore this parameter if necessary * (and return all qualifying results). * @param fileSpecs if non-empty, limits the results to changelists that affect the specified files. If the file specification includes a revision range, limits its results to submitted changelists that affect those particular revisions. * @param clientName if non-null, restrict the results to changelists associated * with the given client. * @param userName if non-null, restrict the results to changelists associated * with the given user name. * @param includeIntegrated if true, also include any changelists integrated into the * specified files (if any). * @param type if non-null, restrict the results to the specified changelist type * @param longDesc if true, produce a non-truncated long version of the description * @return a non-null (but possibly empty) list of qualifying changelists. * @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<IChangelistSummary> getChangelists(int maxMostRecent, List<IFileSpec> fileSpecs, String clientName, String userName, boolean includeIntegrated, IChangelist.Type type, boolean longDesc) throws ConnectionException, RequestException, AccessException; /** * An omnibus method to get a list of Perforce changelists from a server using zero or more * qualifiers (note that convenience methods also exists, especially on the IClient * interface).<p> * * Note that if both submittedOnly and pendingOnly are true, the results are * implementation-defined. * * @param maxMostRecent if positive, restrict the list to the maxMostRecent * most recent changelists. * Implementations are free to ignore this parameter if necessary * (and return all qualifying results). * @param fileSpecs if non-empty, limits the results to changelists that affect the specified files. If the file specification includes a revision range, limits its results to submitted changelists that affect those particular revisions. * @param clientName if non-null, restrict the results to changelists associated * with the given client. * @param userName if non-null, restrict the results to changelists associated * with the given user name. * @param includeIntegrated if true, also include any changelists integrated into the * specified files (if any). * @param longDesc if true, produce a non-truncated long version of the description * @param submittedOnly if true, restrict the results to submitted changelists only. * @param pendingOnly if true, restrict the results to pending changelists only. * @return a non-null (but possibly empty) list of qualifying changelist summary objects. * @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<IChangelistSummary> getChangelists(int maxMostRecent, List<IFileSpec> fileSpecs, String clientName, String userName, boolean includeIntegrated, boolean submittedOnly, boolean pendingOnly, boolean longDesc) throws ConnectionException, RequestException, AccessException; /** * Get a specific Perforce changelist from a Perforce server.<p> * * Corresponds fairly well to the p4 command-line command "change -o", and (like * "change -o") does <i>not</i> include the associated changelist files (if any) * in the returned changelist object -- you must use getChangelistFiles (or similar) * to properly populate the changelist for submission, for example. * * @param id the Perforce changelist ID; if id is IChangelist.DEFAULT, get the default * changelist for the current client (if available) * @return non-null IChangelist describing the changelist; if no such changelist, * a RequestException is thrown. * @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 getChangelist(int id) throws ConnectionException, RequestException, AccessException; /** * Delete a pending Perforce changelist. Throws a RequestException * if the changelist was associated with opened files or was not a * pending changelist.<p> * * Note: any IChangelist object associated with the given changelist * will no longer be valid after this operation, and using that object may * cause undefined results or even global disaster -- you must ensure that * the object is not used again improperly. * * @param id the ID of the Perforce pending changelist to be deleted. * @return possibly-null operation result message string 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 */ String deletePendingChangelist(int id) throws ConnectionException, RequestException, AccessException; /** * Get a list of the Perforce depot files associated with a Perforce changelist.<p> * * The IFileSpec objects returned are not guaranteed to have any fields * except depot path, version, and action valid.<p> * * Changelists that are pending will not have files visible through this method; * you should use the client openedFiles method for retrieving files in that situation. * * @param id numeric changelist identifier * @return non-null (but possibly empty) list of files associated with the 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> getChangelistFiles(int id) throws ConnectionException, RequestException, AccessException; /** * Get an InputStream onto the file diffs associated with a specific submitted * changelist. This method (like the similar "p4 describe" command) will * not return diffs for pending changelists.<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> * * Note that unlike the corresponding command-line command, which * keeps going in the face of errors by moving on to the next file (or * whatever), any errors encountered in this method will cause an exception * from this method at the first error, so plan accordingly.... * * @param id the ID of the target changelist * @param diffType if non-null, describes which type of diff to perform. * @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 getChangelistDiffs(int id, DiffType diffType) throws ConnectionException, RequestException, AccessException; /** * Get an InputStream onto the file diffs associated with a specific submitted * changelist. This method (like the similar "p4 describe" command) will * not return diffs for pending changelists.<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> * * Note that unlike the corresponding command-line command, which * keeps going in the face of errors by moving on to the next file (or * whatever), any errors encountered in this method will cause an exception * from this method at the first error, so plan accordingly.... * * @param id the ID of the target changelist * @param options DescribeOptions behavioural options for method. * @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 getChangelistDiffsStream(int id, DescribeOptions options) throws ConnectionException, RequestException, AccessException; /** * Return an InputStream onto the contents of one or more revisions of one or more * Perforce depot file contents.<p> * * If file is specified as a Perforce client workspace file name, the client view is used to * find the corresponding depot file. If a file argument has a revision, then all files as of that * revision are streamed. If a file argument has a revision range, then only files selected * by that revision range are streamed, and the highest revision in the range is used for each file. * Normally, only the head revision is printed.<p> * * The underlying input stream is not guaranteed to support mark() and skip() operations, and in * some cases can be absolutely ginormously long it is also not guaranteed to be printable, * and will be in the charset encoding stored in the Perforce server.<p> * * You should close the InputStreamReader 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.<p> * * Note that unlike the corresponding command-line command, which * keeps going in the face of errors by moving on to the next file (or * whatever), any errors encountered in this method will cause an exception * from this method at the first error, so plan accordingly.... * * @param fileSpecs non-null list of depot or client file specs defining files to be streamed * @param allrevs if true, streams all revisions within the specific range, rather * than just the highest revision in the range * @param noHeaderLine if true, suppresses the initial line that displays the file name * and revision for each file / revision contents * @return a non-null but possibly-empty InputStream onto the file / revision contents * @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 getFileContents(List<IFileSpec> fileSpecs, boolean allrevs, boolean noHeaderLine) throws ConnectionException, RequestException, AccessException; /** * Get the revision history data for one or more Perforce files.<p> * * 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. * * @param fileSpecs filespecs to be processed; if null or empty, * an empty Map is returned. * @param maxRevs if positive, return at most maxRev revisions for each file. * @param includeInherited if true, causes inherited file history to be returned as well. * @param longOutput if true, return the full descriptions associated with each revision * @param truncatedLongOutput if true, return only the first 250 characters of each description. * @return a non-null map of lists of revision data for qualifying files; the map is keyed * by the IFileSpec of the associated file, meaning that errors are * signaled using the normal IFileSpec getOpStatus() method. * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws AccessException if the Perforce server denies access to the caller */ Map<IFileSpec, List<IFileRevisionData>> getRevisionHistory(List<IFileSpec> fileSpecs, int maxRevs, boolean contentHistory, boolean includeInherited, boolean longOutput, boolean truncatedLongOutput) throws ConnectionException, AccessException; /** * Get a list of all users who have subscribed to review the named files, * the files in the numbered changelist, or all files by default.<p> * * Note that the returned IUserSummary objects will have null access * and update dates associated with them. * * @param changelistId if not IChangelist.UNKNOWN, use this changelist ID. * @param fileSpecs if not null, use this list as the list of named files rather * than all files. * @return non-null but possibly empty list of IUserSummary objects; note that * these objects will have null update and access fields. * @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<IUserSummary> getReviews(int changelistId, List<IFileSpec> fileSpecs) throws ConnectionException, RequestException, AccessException; /** * 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 allClients if true, return results for all known clients rather than the * current client (if any). * @param clientName if non-null, return results for the named client only. * @param maxFiles if positive, return only the first maxFiles qualifying files. * @param changeListId if positive, return only files associated with the given * changelist ID; if IChangelist.DEFAULT, retrieve files open * associated with the default changelist. * @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> getOpenedFiles(List<IFileSpec> fileSpecs, boolean allClients, String clientName, int maxFiles, int changeListId) throws ConnectionException, AccessException; /** * Return a list of everything Perforce knows about a possibly very large set of * Perforce files.<p> * * This method is not intended for general use, and is not documented in detail here; * consult the main Perforce fstat command documentation for detailed help. In particular, * the various options are too complex to be described in a few sentences here, and * the various option arguments reflect this complexity. Note that setting both * sinceChangelist and affectedByChangelist to zero or a positive value will cause * usage errors from the server (these are currently intended to be mutually-exclusive * options).<p> * * This method can be a real server and bandwidth resource hog, and should be used as * sparingly as possible; alternatively, try to use it with as narrow a set of file * specs as possible. * * @param fileSpecs non-null list of Perforce file specification(s) * @param maxFiles if positive, restrict the output to the first maxReturns files. * Implementations are free to ignore this parameter if necessary * (and return all qualifying results). * @param sinceChangelist if larger than or equal to zero, display only files * affected since the given changelist number; zero is equivalent * to IChangelist.DEFAULT. * @param affectedByChangelist if larger than or equal to zero, display only files * affected by the given changelist number; zero is equivalent * to IChangelist.DEFAULT. * @param outputOptions if non-null, specifies the oputput options to be used * @param ancilliaryOptions if non-null, specifies the ancilliary output options to be used * @return a non-null (but possibly empty) list of qualifying files and associated stat info * @throws ConnectionException if the Perforce server is unreachable or is not * connected. * @throws AccessException if the Perforce server denies access to the caller */ List<IExtendedFileSpec> getExtendedFiles(List<IFileSpec> fileSpecs, int maxFiles, int sinceChangelist, int affectedByChangelist, FileStatOutputOptions outputOptions, FileStatAncilliaryOptions ancilliaryOptions) throws ConnectionException, AccessException; /** * Get a list of submitted integrations for the passed-in filespecs. * * @param fileSpecs if null or ommitted, all qualifying depot files are used. * @param branchSpec if non-null, only files integrated from the source * to target files in the branch view are shown. Qualified files * are displayed even if they were integrated without using the * branch view itself. * @param reverseMappings if true,reverses the mappings in the branch view, with * the target files and source files exchanging place. This requires the * branchSpec to be non-null. * @return a non-null but possibly empty list of IFileSpec representing * qualifying integrations. * @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> getSubmittedIntegrations(List<IFileSpec> fileSpecs, String branchSpec, boolean reverseMappings) throws ConnectionException, RequestException, AccessException; /** * Get a list of changes and / or associated files not yet integrated (unsupported). * Corresponds fairly closely to the p4 interchanges command for filespecs.<p> * * Note that if showFiles is true, the returned files are attached to the associated * changelist, and can be retrieved using the getFiles(false) method -- and note that * if you call getFiles(true) you will get a refreshed list of <i>all</i> files associated with * the changelist, which is probably different from the list associated with the * integration.<p> * * Note also that if there are no qualifying changes, this method will return an empty * list rather than throw an exception; this behaviour is different to that seen with * the p4 command line which will throw an exception. * * @param fromFile non-null from-file specification. * @param toFile non-null to-file specification. * @param showFiles if true, show the individual files that would require integration. * @param longDesc if true, return a long description in the changelist. * @param maxChangelistId if greater than zero, only consider integration * history from changelists at or below the given number * @return non-null (but possibly empty) list of qualifying changelists. Note that * the changelists returned here may not have all fields set (only * description, ID, date, user, and client are known to be properly * set by the server for this command). * @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<IChangelist> getInterchanges(IFileSpec fromFile, IFileSpec toFile, boolean showFiles, boolean longDesc, int maxChangelistId) throws ConnectionException, RequestException, AccessException; /** * Get a list of changes and / or associated files not yet integrated, based on * branchspecs (unsupported). Corresponds fairly closely to the p4 interchanges * command for branchspecs.<p> * * Note that if showFiles is true, the returned files are attached to the associated * changelist, and can be retrieved using the getFiles(false) method -- and note that * if you call getFiles(true) you will get a refreshed list of <i>all</i> files associated with * the changelist, which is probably different from the list associated with the * integration.<p> * * Note also that if there are no qualifying changes, this method will return an empty * list rather than throw an exception; this behaviour is different to that seen with * the p4 command line which will throw an exception. * * @param branchSpecName non-null, non-empty branch spec name. * @param fromFileList if non-null and not empty, and biDirectional is true, * use this as the from file list. * @param toFileList if non-null and not empty, use this as the to file list. * @param showFiles if true, show the individual files that would require integration. * @param longDesc if true, return a long description in the changelist. * @param maxChangelistId if greater than zero, only consider integration * @param reverseMapping if true, reverse the mappings in the branch view, with the * target files and source files exchanging place. * @param biDirectional * @return non-null (but possibly empty) list of qualifying changelists. Note that * the changelists returned here may not have all fields set (only * description, ID, date, user, and client are known to be properly * set by the server for this command). * @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<IChangelist> getInterchanges(String branchSpecName, List<IFileSpec> fromFileList, List<IFileSpec> toFileList, boolean showFiles, boolean longDesc, int maxChangelistId, boolean reverseMapping, boolean biDirectional) throws ConnectionException, RequestException, AccessException; /** * Return a list of Perforce jobs. Note that (as discussed in the IJob comments) * Perforce jobs can have a wide variety of fields, formats, semantics, etc., and * this method can return a list that may have to be unpacked at the map level by * the consumer to make any sense of it.<p> * * Note that this method (unlike the main file list methods) throws an exception * and stops at the first encountered error. * * @param fileSpecs if given, return only jobspecs affecting the given file(s) * @param maxJobs if positive, return only up to maxJobs results * @param longDescriptions if true, return full descriptions, otherwise show * only a subset (typically the first 128 characters, but * this is not guaranteed). * @param reverseOrder if true, reverse the normal sort order * @param includeIntegrated if true, include any fixes made by changelists * integrated into the specified files * @param jobView if non-null, a string in format detailed by "p4 help jobview" * used to restrict jobs to those satisfying the job view expression. * @return a non-null (but possibly-empty) list of qualifying 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(List<IFileSpec> fileSpecs, int maxJobs, boolean longDescriptions, boolean reverseOrder, boolean includeIntegrated, String jobView) throws ConnectionException, RequestException, AccessException; /** * Get a specific job. Note that some implementations of the underlying * server do not return null if you ask for a job that doesn't exist; you * must do your own checking to see of what's returned represents a real * job or not. * * @param jobId non-null job Id. * @return IJob for the named job; null if no such job. * @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 */ IJob getJob(String jobId) throws ConnectionException, RequestException, AccessException; /** * Create a new Perforce job in the Perforce server corresponding to the passed-in Perforce * job fields (which in turn should correspond to at least the mandatory fields defined * in the reigning Perforce job spec).<p> * * Perforce job semantics, field count and layout, etc., are to some extent free-form and * specified for each server by the associated job spec (retrievable using the getJobSpec() * method below), so map fields are passed to the Perforce server exactly as passed to the * create method in the job's field map, so you need to know the field names and semantics * given by the associated job spec. This includes setting the relevant job ID field to * "new", but otherwise, no checking is done on fields in this method against the * job spec (this may be added later).<p> * * @param fieldMap non-null field map defining the new job in the Perforce server. * @return returns an IJob representing the newly-created job, if successful. * @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 */ IJob createJob(Map<String, Object> fieldMap) throws ConnectionException, RequestException, AccessException; /** * Update a Perforce job on the Perforce server. Note that <i>only</i> the * associated raw fields map is used for field values; the main description * and ID fields are actually ignored.<p> * * The returned string will contain whatever the Perforce server returned * in response to this command; in general, if the update fails, an exception * will be thrown, meaning that the returned string represents success only. * There are two success states -- either the job was saved or it didn't need * saving (it was the same after updating). Consumers should parse this * accordingly. * * @param job non-null candidate for updating. * @return possibly-null status message as returned from the server; this may include * form trigger output pre-pended and / or appended to the "normal" message. * @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 */ String updateJob(IJob job) throws ConnectionException, RequestException, AccessException; /** * Delete a job from the Perforce server. Note that this method does not change * the status of the associated job locally, just on the Perforce server. * * @param jobId ID of the job to be deleted. * @return possibly-null status message as returned from the server; this may include * form trigger output pre-pended and / or appended to the "normal" message. * @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 */ String deleteJob(String jobId) throws ConnectionException, RequestException, AccessException; /** * Return the Perforce jobspec associated with this Perforce server.<p> * * @return possibly-null IJobSpec representing the unserlying Perforc server's * jobspec. * @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 */ IJobSpec getJobSpec() throws ConnectionException, RequestException, AccessException; /** * Return a list of all Perforce jobs with fix records associated with them, * along with the changelist number of the fix. Detailed semantics for this * method are given in the main Perforce documentation for the p4 command "fixes".<p> * * Note that this method (unlike the main file list methods) throws an exception * and stops at the first encountered error. * * * @param fileSpecs if given, restrict output to fixes associated with these files * @param changeListId if positive, only fixes from the numbered changelist are listed. * @param jobId if non-null, only fixes for the named job are listed * @param includeIntegrations if true, include any fixes made by changelists integrated * into the specified files * @param maxFixes if positive, restrict the list to the first maxFixes fixes * @return non-null but possibly empty list of qualifying IFix fixes. * @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<IFix> getFixList(List<IFileSpec> fileSpecs, int changeListId, String jobId, boolean includeIntegrations, int maxFixes) throws ConnectionException, RequestException, AccessException; /** * Mark each named job as being fixed by the changelist number given with changeListId. * Full details of the use of this method and the associated parameters will not be * given here; consult the main Perforce documentation for the details. * * @param changeListId changelist number * @param status if non-null, use this as the new status rather than "closed" * @param delete if true, delete the specified fixes * @return list of affected fixes * @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<IFix> fixJobs(List<String> jobIdList, int changeListId, String status, boolean delete) throws ConnectionException, RequestException, AccessException; /** * Return a list of Perforce server processes active on the Perforce server. Will throw * a request exception if monitors are not enabled on the target server. * * @return non-null but possibly-empty list of IServerProcess objects * @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<IServerProcess> getServerProcesses() throws ConnectionException, RequestException, AccessException; /** * Run diff on the Perforce server of two files in the depot.<p> * * This method corresponds closely to the standard diff2 command, and that * command's documentation should be consulted for the overall and detailed * semantics. In particular, the various potentially-valid combinations of * branch spec and file specs can be complicated and won't be repeated here.<p> * * As with other streams-based IServer methods, callers should ensure that * the stream returned here is always explicitly closed after use; if not * closed, the stream's associated temporary files managed by P4Java * (if they exist) may not be properly deleted. * * @param file1 optional first file IFileSpec * @param file2 optional second file IFileSpec * @param branchSpecName optional branch spec name * @param quiet if true, suppresses the display of the header lines of files whose * content and types are identical and suppresses the actual diff * for all files. * @param includeNonTextDiffs if true, forces 'p4 diff2' to diff even files with * non-text (binary) types * @param gnuDiffs see "-u" option in the main diff2 documentation. * @return non-null but possibly empty InputStream of diffs and headers * as returned from the 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 */ InputStream getServerFileDiffs(IFileSpec file1, IFileSpec file2, String branchSpecName, DiffType diffType, boolean quiet, boolean includeNonTextDiffs, boolean gnuDiffs) throws ConnectionException, RequestException, AccessException; /** * Run diff on the Perforce server of two files in the depot.<p> * * This method corresponds closely to the standard diff2 command, and that * command's documentation should be consulted for the overall and detailed * semantics. In particular, the various potentially-valid combinations of * branch spec and file specs can be complicated and won't be repeated here.<p> * * @param file1 optional first file IFileSpec * @param file2 optional second file IFileSpec * @param branchSpecName optional branch spec name * @param quiet if true, suppresses the display of the header lines of files whose * content and types are identical and suppresses the actual diff * for all files. * @param includeNonTextDiffs if true, forces 'p4 diff2' to diff even files with * non-text (binary) types * @param gnuDiffs see "-u" option in the main diff2 documentation. * @return non-null but possibly empty array of file diffs * @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<IFileDiff> getFileDiffs(IFileSpec file1, IFileSpec file2, String branchSpecName, DiffType diffType, boolean quiet, boolean includeNonTextDiffs, boolean gnuDiffs) throws ConnectionException, RequestException, AccessException; /** * Issue an arbitrary P4Java command to the Perforce server and return the results as a map.<p> * * This method is intended for low-level commands in the spirit and format of the p4 command * line interpreter, and offers a simple way to issue commands to the associated Perforce server * without the overhead of the more abstract Java interfaces and methods.<p> * * No guidance is given here on the format of the returned map; however, it produces the same * output as the p4 command line interpreter in -G (Python map) mode.<p> * * Note that this method does not allow you to set "usage" options for the command; * these may be added later. Note also that although option arguments passed to this * method must be in a form recognized by the p4 command line interpreter, that does * <i>not</i> mean the method is being implemented by the interpreter -- the actual * implementation depends on the options used to get the server object in the first * place from the server factory. * * @param cmdName the command to be issued; must be non-null, and correspond to a Perforce * command recognized by P4Java and defined in CmdSpec. * @param cmdArgs the array of command arguments (options and file arguments, etc.) to be * sent to the Perforce server. These must be in the form used by the corresponding * p4 command line interpreter. Ignored if null. * @param inMap an optional map to be sent to the server as standard input, using the * Python map format (-G) form. You must remember to issue the relevant * command-specific option to enable this if needed. * @return a non-null Java Map of results; these results are as returned from issuing the command * using the -G option with the p4 command line interpreter. * @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 */ Map<String, Object>[] execMapCmd(String cmdName, String[] cmdArgs, Map<String, Object> inMap) throws ConnectionException, RequestException, AccessException; /** * Issue an arbitrary P4Java command to the Perforce server and return the results as a map.<p> * * This method is intended for low-level commands in the spirit and format of the p4 command * line interpreter, and offers a simple way to issue commands to the associated Perforce server * without the overhead of the more abstract Java interfaces and methods.<p> * * No guidance is given here on the format of the returned map; however, it produces the same * output as the p4 command line interpreter in -G (Python map) mode.<p> * * Note that this method does not allow you to set "usage" options for the command; * these may be added later. Note also that although option arguments passed to this * method must be in a form recognized by the p4 command line interpreter, that does * <i>not</i> mean the method is being implemented by the interpreter -- the actual * implementation depends on the options used to get the server object in the first * place from the server factory. * * @since 2011.1 * @param cmdName the command to be issued; must be non-null, and correspond to a Perforce * command recognized by P4Java and defined in CmdSpec. * @param cmdArgs the array of command arguments (options and file arguments, etc.) to be * sent to the Perforce server. These must be in the form used by the corresponding * p4 command line interpreter. Ignored if null. * @param inString an optional string to be sent to the server as standard input unchanged * (this must be in the format expected by the server, typically as required * when using the "-i" flag to the p4 command line app for the same command). * You must remember to issue the relevant * command-specific option to enable this if needed. * @return a non-null Java Map of results; these results are as returned from issuing the command * using the -G option with the p4 command line interpreter. * @throws P4JavaException if an error occurs processing this method and its parameters */ Map<String, Object>[] execInputStringMapCmd(String cmdName, String[] cmdArgs, String inString) throws P4JavaException; /** * Issue an arbitrary P4Java command to the Perforce server and return the results as a map without * invoking any command callbacks.<p> * * Basically equivalent to execMapCmd with temporary disabling of any ICommandCallback * calls and / or listeners; this turns out to be useful for various reasons we won't go * into here...<p> * * @param cmdName the command to be issued; must be non-null, and correspond to a Perforce * command recognized by P4Java and defined in CmdSpec. * @param cmdArgs the array of command arguments (options and file arguments, etc.) to be * sent to the Perforce server. These must be in the form used by the corresponding * p4 command line interpreter. Ignored if null. * @param inMap an optional map to be sent to the server as standard input, using the * Python map format (-G) form. You must remember to issue the relevant * command-specific option to enable this if needed. * @return a non-null Java Map of results; these results are as returned from issuing the command * using the -G option with the p4 command line interpreter. * @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 */ Map<String, Object>[] execQuietMapCmd(String cmdName, String[] cmdArgs, Map<String, Object> inMap) throws ConnectionException, RequestException, AccessException; /** * Issue an arbitrary P4Java command to the Perforce server and get the results as a stream.<p> * * This method is intended for low-level commands in the spirit and format of the p4 command * line interpreter, and offers a simple way to issue commands to the associated Perforce server * without the overhead of the more abstract Java interfaces and methods.<p> * * Note that this method is intended for things like getting file contents, and may have * unpredictable results on commands not originally expected to return i/o streams.<p> * * Note that this method does not allow you to set "usage" options for the command; * these may be added later. Note also that although option arguments passed to this * method must be in a form recognized by P4Java (as defined by the CmdSpec enum), that does * <i>not</i> mean the method is being implemented by the interpreter -- the actual * implementation depends on the options used to get the server object in the first * place from the server factory. * * @param cmdName the command to be issued; must be non-null, and correspond to a Perforce * command recognized by P4Java and defined in CmdSpec. * @param cmdArgs the array of command arguments (options and file arguments, etc.) to be * sent to the Perforce server. These must be in the form used by the corresponding * p4 command line interpreter. Ignored if null. * @return an InputStream on the command output. This will never be null, but it may be empty. * You <i>must</i> properly close this stream after use or temporary files may * be left lying around the VM's java.io.tmpdir area. * @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 execStreamCmd(String cmdName, String[] cmdArgs) throws ConnectionException, RequestException, AccessException; /** * Issue an arbitrary P4Java command to the Perforce server and get the results as a stream * without invoking any command callbacks.<p> * * Basically equivalent to execStreamCmd with temporary disabling of any ICommandCallback * calls and / or listeners; this turns out to be useful for various reasons we won't go * into here...<p> * * @param cmdName the command to be issued; must be non-null, and correspond to a Perforce * command recognized by P4Java and defined in CmdSpec. * @param cmdArgs the array of command arguments (options and file arguments, etc.) to be * sent to the Perforce server. These must be in the form used by the corresponding * p4 command line interpreter. Ignored if null. * @return an InputStream on the command output. This will never be null, but it may be empty. * You <i>must</i> properly close this stream after use or temporary files may * be left lying around the VM's java.io.tmpdir area. * @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 execQuietStreamCmd(String cmdName, String[] cmdArgs) throws ConnectionException, RequestException, AccessException; /** * Issue a streaming map command to the Perforce server, using an optional * map for any input expected by the server (such as label or job specs, * etc.).<p> * * Streaming commands allow users to get each result from a suitably-issued * command as it comes in from the server, rather than waiting for the entire * command method to complete (and getting the results back as a completed * List or Map or whatever).<p> * * 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 suitably in much the same way as a user * unpacks or processes the results from the other low-level exec methods * like execMapCommand.<p> * * NOTE: 'streaming' here has nothing at all to do with Perforce 'streams', which * are (or will be) implemented elsewhere. * * @since 2011.1 * * @param cmdName the command to be issued; must be non-null, and correspond to a Perforce * command recognized by P4Java and defined in CmdSpec. * @param cmdArgs the array of command arguments (options and file arguments, etc.) to be * sent to the Perforce server. These must be in the form used by the corresponding * p4 command line interpreter. Ignored if null. * @param inMap an optional map to be sent to the server as standard input, using the * Python map format (-G) form. You must remember to issue the relevant * command-specific option to enable this if needed. * @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 an error occurs processing this method and its parameters. */ void execStreamingMapCommand(String cmdName, String[] cmdArgs, Map<String, Object> inMap, IStreamingCallback callback, int key) throws P4JavaException; /** * Issue a streaming map command to the Perforce server, using an optional string * for any input expected by the server (such as label or job specs, etc.).<p> * * Streaming commands allow users to get each result from a suitably-issued * command as it comes in from the server, rather than waiting for the entire * command method to complete (and getting the results back as a completed * List or Map or whatever).<p> * * 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 suitably in much the same way as a user * unpacks or processes the results from the other low-level exec methods * like execMapCommand.<p> * * NOTE: 'streaming' here has nothing at all to do with Perforce 'streams', which * are (or will be) implemented elsewhere. * * @since 2011.1 * * @param cmdName the command to be issued; must be non-null, and correspond to a Perforce * command recognized by P4Java and defined in CmdSpec. * @param cmdArgs the array of command arguments (options and file arguments, etc.) to be * sent to the Perforce server. These must be in the form used by the corresponding * p4 command line interpreter. Ignored if null. * @param inString an optional string to be sent to the server as standard input unchanged * (this must be in the format expected by the server, typically as required * when using the "-i" flag to the p4 command line app for the same command). * You must remember to issue the relevant * command-specific option to enable this if needed. * @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 an error occurs processing this method and its parameters. * * @deprecated As of release 2013.1, replaced by {@link com.perforce.p4java.server.IOptionsServer#execInputStringStreamingMapCmd(java.lang.String, java.lang.String[], java.lang.String, com.perforce.p4java.server.callback.IStreamingCallback, int)} */ @Deprecated void execInputStringStreamingMapComd(String cmdName, String[] cmdArgs, String inString, IStreamingCallback callback, int key) throws P4JavaException; /** * Get the value of a named Perforce counter from the Perforce server. Note that this * method will return a zero string (i.e. "0") if the named counter doesn't exist (rather * than throw an exception); use getCounters to see if a counter actually exists before * you use it.<p> * * Note that despite their name, counters can be any value, not just a number; hence * the string return value here. * * @param counterName non-null counter name. * @return non-null (but possibly empty or useless) counter value associated * with counterName. * @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 */ String getCounter(String counterName) throws ConnectionException, RequestException, AccessException; void setCounter(String counterName, String value, boolean perforceCounter) throws ConnectionException, RequestException, AccessException; void deleteCounter(String counterName, boolean perforceCounter) throws ConnectionException, RequestException, AccessException; /** * Get a map of the Perforce server's counters. Counter usage is not explained here -- see the * main Perforce documentation -- but in general they're sometimes useful to get an indirect * idea of server capabilities and state. * * @return a non-null (but possibly empty) map of counters. key and value semantics and format * are not specified here. * @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 */ Map<String, String> getCounters() throws ConnectionException, RequestException, AccessException; /** * Get the database schema associated with this server (admin / superuser command).<p> * * See the main p4 admin command documentation for full semantics and usage details. * * @param tableSpecs if null, return all known schema; otherwise, restrict the returned * list to the named tables and table versions. * @return a non-null but possibly empty list of IDbSchema for the passed-in * schema identifiers. * @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<IDbSchema> getDbSchema(List<String> tableSpecs) throws ConnectionException, RequestException, AccessException; /** * Get a list of exported journal or checkpoint records (admin / superuser command).<p> * * See the main p4 admin command documentation for full semantics and usage details. * * @param useJournal if true, export journal records; otherwise, export checkpoint records. * @param maxRecs if larger than zero, return only the first maxRec lines * @param sourceNum checkpoint or journal number. * @param offset offset with in checkpoint or journal. * @param format if true, formats record output appropriately for the type of data. * @param journalPrefix if not null, specify a journal name prefix. * @param filter if not null, pass the specified filter to the exporter. * @return non-null but possibly empty list of maps representing exported * journal or checkpoint records. * @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<Map<String, Object>> getExportRecords(boolean useJournal, long maxRecs, int sourceNum, long offset, boolean format, String journalPrefix, String filter) throws ConnectionException, RequestException, AccessException; }
# | 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/server/IServer.java | |||||
#1 | 12541 | Matt Attaway | Initial add of the 14.1 p4java source code |