IServer (Perforce Java API 2015.1.1210280 API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.perforce.p4java.server
Interface IServer

All Known Subinterfaces:: IOptionsServer, IStreamingServer

All Known Implementing Classes:: NtsServerImpl, OneShotServerImpl, RpcServer, Server

public interface IServer

Provides an interface onto a Perforce SCM server.

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.

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 Also:: ServerFactory

Method Summary
`void`	`connect()` Connect to the Perforce server associated with this server object.
`String`	`createBranchSpec(IBranchSpec branchSpec)` Create a new Perforce branch spec on the Perforce server.
`String`	`createClient(IClient newClient)` Attempt to create a new Perforce client (a.k.a.
`IJob`	`createJob(Map<String,Object> fieldMap)` 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).
`String`	`createLabel(ILabel label)` Create a new Perforce label in the Perforce server.
`String`	`createUser(IUser user, boolean force)` Create a new Perforce user on the Perforce server.
`String`	`createUserGroup(IUserGroup group)` Create a new Perforce user group on the Perforce server.
`String`	`deleteBranchSpec(String branchSpecName, boolean force)` Delete a named Perforce branch spec from the Perforce server.
`String`	`deleteClient(String clientName, boolean force)` Delete a Perforce client from a Perforce server.
`void`	`deleteCounter(String counterName, boolean perforceCounter)`
`String`	`deleteJob(String jobId)` Delete a job from the Perforce server.
`String`	`deleteLabel(String labelName, boolean force)` Delete a named Perforce label from the Perforce server.
`String`	`deletePendingChangelist(int id)` Delete a pending Perforce changelist.
`String`	`deleteUser(String userName, boolean force)` Delete a named Perforce user from the Perforce server.
`String`	`deleteUserGroup(IUserGroup group)` Delete a Perforce user group from the Perforce server.
`void`	`disconnect()` Disconnect from this Perforce server.
`Map<String,Object>[]`	`execInputStringMapCmd(String cmdName, String[] cmdArgs, String inString)` Issue an arbitrary P4Java command to the Perforce server and return the results as a map.
`void`	`execInputStringStreamingMapComd(String cmdName, String[] cmdArgs, String inString, IStreamingCallback callback, int key)` Deprecated. As of release 2013.1, replaced by `IOptionsServer.execInputStringStreamingMapCmd(java.lang.String, java.lang.String[], java.lang.String, com.perforce.p4java.server.callback.IStreamingCallback, int)`
`Map<String,Object>[]`	`execMapCmd(String cmdName, String[] cmdArgs, Map<String,Object> inMap)` Issue an arbitrary P4Java command to the Perforce server and return the results as a map.
`Map<String,Object>[]`	`execQuietMapCmd(String cmdName, String[] cmdArgs, Map<String,Object> inMap)` Issue an arbitrary P4Java command to the Perforce server and return the results as a map without invoking any command callbacks.
`InputStream`	`execQuietStreamCmd(String cmdName, String[] cmdArgs)` Issue an arbitrary P4Java command to the Perforce server and get the results as a stream without invoking any command callbacks.
`InputStream`	`execStreamCmd(String cmdName, String[] cmdArgs)` Issue an arbitrary P4Java command to the Perforce server and get the results as a stream.
`void`	`execStreamingMapCommand(String cmdName, String[] cmdArgs, Map<String,Object> inMap, IStreamingCallback callback, int key)` 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.).
`List<IFix>`	`fixJobs(List<String> jobIdList, int changeListId, String status, boolean delete)` Mark each named job as being fixed by the changelist number given with changeListId.
`String`	`getAuthTicket()` Return the current Perforce authentication ticket being used by this server, if any.
`IBranchSpec`	`getBranchSpec(String name)` Get a specific named Perforce branch spec from the Perforce server.
`List<IBranchSpecSummary>`	`getBranchSpecs(String userName, String nameFilter, int maxReturns)` Get a list of all summary Perforce branch specs known to the Perforce server.
`IChangelist`	`getChangelist(int id)` Get a specific Perforce changelist from a Perforce server.
`InputStream`	`getChangelistDiffs(int id, DiffType diffType)` Get an InputStream onto the file diffs associated with a specific submitted changelist.
`InputStream`	`getChangelistDiffsStream(int id, DescribeOptions options)` Get an InputStream onto the file diffs associated with a specific submitted changelist.
`List<IFileSpec>`	`getChangelistFiles(int id)` Get a list of the Perforce depot files associated with a Perforce changelist.
`List<IChangelistSummary>`	`getChangelists(int maxMostRecent, List<IFileSpec> fileSpecs, String clientName, String userName, boolean includeIntegrated, boolean submittedOnly, boolean pendingOnly, boolean longDesc)` 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).
`List<IChangelistSummary>`	`getChangelists(int maxMostRecent, List<IFileSpec> fileSpecs, String clientName, String userName, boolean includeIntegrated, IChangelist.Type type, boolean longDesc)` 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).
`String`	`getCharsetName()` Get the current charset name for the server connection.
`IClient`	`getClient(IClientSummary clientSummary)` Convenience method for getClient(clientSummary.getName()).
`IClient`	`getClient(String clientName)` Get an IClient object for a specific named Perforce client.
`List<IClientSummary>`	`getClients(String userName, String queryString, int maxResults)` Get a list of IClientSummary objects for all Perforce clients known to this Perforce server.
`IClient`	`getClientTemplate(String clientName)` Get a template of a non-existent named Perforce client.
`IClient`	`getClientTemplate(String clientName, boolean allowExistent)` Get a template of a non-existent named Perforce client.
`String`	`getCounter(String counterName)` Get the value of a named Perforce counter from the Perforce server.
`Map<String,String>`	`getCounters()` Get a map of the Perforce server's counters.
`IClient`	`getCurrentClient()` Return the Perforce client currently associated with this Perforce server, if any.
`List<IDbSchema>`	`getDbSchema(List<String> tableSpecs)` Get the database schema associated with this server (admin / superuser command).
`List<IFileSpec>`	`getDepotFiles(List<IFileSpec> fileSpecs, boolean allRevs)` List all Perforce depot files known to the Perforce server that conform to the passed-in wild-card file specification(s).
`List<IDepot>`	`getDepots()` Get a list of all Perforce depots known to this Perforce server.
`List<IFileSpec>`	`getDirectories(List<IFileSpec> fileSpecs, boolean clientOnly, boolean deletedOnly, boolean haveListOnly)` List any directories matching the passed-in file specifications.
`List<Map<String,Object>>`	`getExportRecords(boolean useJournal, long maxRecs, int sourceNum, long offset, boolean format, String journalPrefix, String filter)` Get a list of exported journal or checkpoint records (admin / superuser command).
`List<IExtendedFileSpec>`	`getExtendedFiles(List<IFileSpec> fileSpecs, int maxFiles, int sinceChangelist, int affectedByChangelist, FileStatOutputOptions outputOptions, FileStatAncilliaryOptions ancilliaryOptions)` Return a list of everything Perforce knows about a possibly very large set of Perforce files.
`List<IFileAnnotation>`	`getFileAnnotations(List<IFileSpec> fileSpecs, DiffType wsOpts, boolean allResults, boolean useChangeNumbers, boolean followBranches)` Get a list of revision annotations for the specified files.
`InputStream`	`getFileContents(List<IFileSpec> fileSpecs, boolean allrevs, boolean noHeaderLine)` Return an InputStream onto the contents of one or more revisions of one or more Perforce depot file contents.
`List<IFileDiff>`	`getFileDiffs(IFileSpec file1, IFileSpec file2, String branchSpecName, DiffType diffType, boolean quiet, boolean includeNonTextDiffs, boolean gnuDiffs)` Run diff on the Perforce server of two files in the depot.
`List<IFix>`	`getFixList(List<IFileSpec> fileSpecs, int changeListId, String jobId, boolean includeIntegrations, int maxFixes)` Return a list of all Perforce jobs with fix records associated with them, along with the changelist number of the fix.
`List<IChangelist>`	`getInterchanges(IFileSpec fromFile, IFileSpec toFile, boolean showFiles, boolean longDesc, int maxChangelistId)` Get a list of changes and / or associated files not yet integrated (unsupported).
`List<IChangelist>`	`getInterchanges(String branchSpecName, List<IFileSpec> fromFileList, List<IFileSpec> toFileList, boolean showFiles, boolean longDesc, int maxChangelistId, boolean reverseMapping, boolean biDirectional)` Get a list of changes and / or associated files not yet integrated, based on branchspecs (unsupported).
`IJob`	`getJob(String jobId)` Get a specific job.
`List<IJob>`	`getJobs(List<IFileSpec> fileSpecs, int maxJobs, boolean longDescriptions, boolean reverseOrder, boolean includeIntegrated, String jobView)` Return a list of Perforce jobs.
`IJobSpec`	`getJobSpec()` Return the Perforce jobspec associated with this Perforce server.
`String[]`	`getKnownCharsets()` Return an array of strings representing "known" charsets (e.g.
`ILabel`	`getLabel(String labelName)` Get a specific named Perforce label.
`List<ILabelSummary>`	`getLabels(String user, int maxLabels, String nameFilter, List<IFileSpec> fileList)` Get a list of Perforce labels, optionally tied to a specific set of files.
`String`	`getLoginStatus()` Return a string indicating the current login status; corresponds to the p4 login -s command.
`List<IFileSpec>`	`getOpenedFiles(List<IFileSpec> fileSpecs, boolean allClients, String clientName, int maxFiles, int changeListId)` 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.
`Properties`	`getProperties()` Return the Java properties associated with this server.
`List<IProtectionEntry>`	`getProtectionEntries(boolean allUsers, String hostName, String userName, String groupName, List<IFileSpec> fileList)` Get a list of Perforce protection entries for the passed-in arguments.
`List<IUserSummary>`	`getReviews(int changelistId, List<IFileSpec> fileSpecs)` 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.
`Map<IFileSpec,List<IFileRevisionData>>`	`getRevisionHistory(List<IFileSpec> fileSpecs, int maxRevs, boolean contentHistory, boolean includeInherited, boolean longOutput, boolean truncatedLongOutput)` Get the revision history data for one or more Perforce files.
`InputStream`	`getServerFileDiffs(IFileSpec file1, IFileSpec file2, String branchSpecName, DiffType diffType, boolean quiet, boolean includeNonTextDiffs, boolean gnuDiffs)` Run diff on the Perforce server of two files in the depot.
`IServerInfo`	`getServerInfo()` Return a snapshot set of data on the Perforce server associated with this server interface.
`List<IServerProcess>`	`getServerProcesses()` Return a list of Perforce server processes active on the Perforce server.
`int`	`getServerVersionNumber()` Get the Perforce version number of the Perforce server associated with this IServer object, if any.
`ServerStatus`	`getStatus()` Return the current status of this server object.
`List<IFileSpec>`	`getSubmittedIntegrations(List<IFileSpec> fileSpecs, String branchSpec, boolean reverseMappings)` Get a list of submitted integrations for the passed-in filespecs.
`IUser`	`getUser(String userName)` Get the user details of a specific Perforce user from the Perforce server.
`IUserGroup`	`getUserGroup(String name)` Get the named Perforce user group.
`List<IUserGroup>`	`getUserGroups(String userOrGroupName, boolean indirect, boolean displayValues, int maxGroups)` Get a list of Perforce user groups from the server.
`String`	`getUserName()` Return the user name currently associated with this server, if any.
`List<IUserSummary>`	`getUsers(List<String> userList, int maxUsers)` Get a list of Perforce users known to this Perforce server.
`String`	`getWorkingDirectory()` Get the underlying server's notion of the current working directory.
`boolean`	`isCaseSensitive()` Returns whether the Perforce server associated with this IServer object is case sensitive.
`boolean`	`isConnected()` Return true iff and the server object is connected to the associated Perforce server.
`void`	`login(String password)` Convenience method for login(password, false).
`void`	`login(String password, boolean allHosts)` Log the current user (if any) in to a Perforce server, optionally arranging to be logged in for all hosts.
`void`	`logout()` Log the current Perforce user out of a Perforce server session.
`List<IFileSpec>`	`moveFile(int changelistId, boolean listOnly, boolean noClientMove, String fileType, IFileSpec fromFile, IFileSpec toFile)` Move a file already opened for edit or add (the fromFile) to the destination file (the toFile).
`ICommandCallback`	`registerCallback(ICommandCallback callback)` Register a P4Java command callback with this Perforce server.
`IProgressCallback`	`registerProgressCallback(IProgressCallback callback)` Register a P4Java command progress callback with this Perforce server.
`ISSOCallback`	`registerSSOCallback(ISSOCallback callback, String ssoKey)` Register a Perforce Single Sign On (SSO) callback and key for this server.
`void`	`setAuthTicket(String authTicket)` Set the server's Perforce authentication ticket to the passed-in string.
`boolean`	`setCharsetName(String charsetName)` Set the Perforce server's charset to the passed-in charset name.
`void`	`setCounter(String counterName, String value, boolean perforceCounter)`
`void`	`setCurrentClient(IClient client)` Set the Perforce client associated with this server.
`void`	`setUserName(String userName)` Set the Perforce user name to be used with this server.
`void`	`setWorkingDirectory(String dirPath)` Set the Perforce server's idea of each command's working directory.
`boolean`	`supportsSmartMove()` Return true IFF the underlying Perforce server supports the new 2009.1 and later "smart move" command.
`boolean`	`supportsUnicode()` Return true if the underlying Perforce server supports Unicode (and is connected).
`List<IFileSpec>`	`tagFiles(List<IFileSpec> fileSpecs, String labelName, boolean listOnly, boolean delete)` Tag files with a Perforce label.
`String`	`updateBranchSpec(IBranchSpec branchSpec)` Update a Perforce branch spec on the Perforce server.
`String`	`updateClient(IClient client)` Update an existing Perforce client on the current Perforce server.
`String`	`updateJob(IJob job)` Update a Perforce job on the Perforce server.
`String`	`updateLabel(ILabel label)` Update an existing Perforce label in the Perforce server.
`String`	`updateUser(IUser user, boolean force)` Update a Perforce user on the Perforce server.
`String`	`updateUserGroup(IUserGroup group, boolean updateIfOwner)` Update a Perforce user group on the Perforce server.

Method Detail

getProperties

Properties getProperties()

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.

Returns:: Properties object; may be empty but will not be null.

registerCallback

ICommandCallback registerCallback(ICommandCallback callback)

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.

Parameters:: callback - ICommandCallback object to be registered; if null, command callbacks are disabled.
Returns:: the previous command callback, if it existed; null otherwise

registerProgressCallback

IProgressCallback registerProgressCallback(IProgressCallback callback)

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.

Parameters:: callback - IProgressCallback object to be registered; if null, progress callbacks are disabled.
Returns:: the previous progress callback, if it existed; null otherwise

registerSSOCallback

ISSOCallback registerSSOCallback(ISSOCallback callback,
                                 String ssoKey)

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.

Note that SSO callbacks work only with the (default) pure Java (RPC) protocol implementation.

Parameters:: callback - ISSOCallback object to be registered; if null, SSO callbacks are disabled.; ssoKey - opaque string to be passed untouched to the callback; can be null, in which case null is passed in to the callback
Returns:: the previous SSO callback, if it existed; null otherwise

getStatus

ServerStatus getStatus()

Return the current status of this server object.

Returns:: non-null ServerStatus representing the server status.

setCharsetName

boolean setCharsetName(String charsetName)
                       throws UnsupportedCharsetException

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.

Parameters:: charsetName - charset name; if null, resets the charset to "no charset".
Returns:: 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.

getCharsetName

String getCharsetName()

Get the current charset name for the server connection. May be null, in which case there is no associated character set.

Returns:: charset name associated with this server; may be null.

getServerVersionNumber

int getServerVersionNumber()

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.

Returns:: positive integer version number or -1 if not known or unavailable.

isCaseSensitive

boolean isCaseSensitive()

Returns whether the Perforce server associated with this IServer object is case sensitive.

Returns:: - true if case sensitive, false if case insensitive.

supportsUnicode

boolean supportsUnicode()
                        throws ConnectionException,
                               RequestException,
                               AccessException

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.

Returns:: true iff the underlying server supports Unicode.
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

supportsSmartMove

boolean supportsSmartMove()
                          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.

Returns:: true iff the server supports the smart move command.
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getKnownCharsets

String[] getKnownCharsets()

Return an array of strings representing "known" charsets (e.g. "utf8" or "utf32le".

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.

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.

Returns:: a non-null array of strings representing lower-case charset names known to the server.

setUserName

void setUserName(String userName)

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.

Note that the auth ticket (if available) for this user will also be set to this server instance.

Parameters:: userName - Perforce user name; can be null, which is interpreted as "don't associate a user name with this server".

setAuthTicket

void setAuthTicket(String authTicket)

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.

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.

Parameters:: authTicket - possibly-null Perforce authentication ticket

getAuthTicket

String getAuthTicket()

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.

Returns:: possibly-null Perforce authentication ticket

setWorkingDirectory

void setWorkingDirectory(String dirPath)

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).

Note: no checking is done at call time for correctness (or otherwise) of the passed-in path.

Parameters:: dirPath - absolute path of directory to be used, or null

getWorkingDirectory

String getWorkingDirectory()

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.

Returns:: current working directory path, or null if not set

getUserName

String getUserName()

Return the user name currently associated with this server, if any. User names are set using the setUserName method.

Returns:: the user name currently associated with this server, if any; null otherwise.

connect

void connect()
             throws ConnectionException,
                    AccessException,
                    RequestException,
                    ConfigException

Connect to the Perforce server associated with this server object.

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.

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.; AccessException - if the Perforce server denies access to the caller; RequestException - if the Perforce server encounters an error during its processing of the request; ConfigException - if local I/O exception occurs

isConnected

boolean isConnected()

Return true iff and the server object is connected to the associated Perforce server.

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.

Returns:: - true iff connected, false otherwise

disconnect

void disconnect()
                throws ConnectionException,
                       AccessException

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.

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.

Throws:: ConnectionException; AccessException

login

void login(String password,
           boolean allHosts)
           throws ConnectionException,
                  RequestException,
                  AccessException,
                  ConfigException

Log the current user (if any) in to a Perforce server, optionally arranging to be logged in for all hosts.

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.

Behaviour is undefined if the server's user name attribute is null (but will probably cause a NullPointerError with most implementations).

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...).

Parameters:: password - Perforce password; can be null if no password is needed (as in the case of SSO logins); allHosts - if true, perform the equivalent of a "login -a"
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller; ConfigException - if the p4tickets file could not be updated successfully

login

void login(String password)
           throws ConnectionException,
                  RequestException,
                  AccessException,
                  ConfigException

Convenience method for login(password, false).

Parameters:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller; ConfigException - if the p4tickets file could not be updated successfully

getLoginStatus

String getLoginStatus()
                      throws P4JavaException

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.

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

logout

void logout()
            throws ConnectionException,
                   RequestException,
                   AccessException,
                   ConfigException

Log the current Perforce user out of a Perforce server session.

Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller; ConfigException - if the p4tickets file could not be updated successfully

getServerInfo

IServerInfo getServerInfo()
                          throws ConnectionException,
                                 RequestException,
                                 AccessException

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.

Returns:: non-null IServerInfo interface.
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getDepots

List<IDepot> getDepots()
                       throws ConnectionException,
                              RequestException,
                              AccessException

Get a list of all Perforce depots known to this Perforce server.

Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getUser

IUser getUser(String userName)
              throws ConnectionException,
                     RequestException,
                     AccessException

Get the user details of a specific Perforce user from the Perforce server.

Parameters:: userName - if null, get the current user details, otherwise use the passed-in user name.
Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

createUser

String createUser(IUser user,
                  boolean force)
                  throws ConnectionException,
                         RequestException,
                         AccessException

Create a new Perforce user on the Perforce server.

Parameters:: user - non-null IUser defining the new user to be created.; force - if true, force the creation of any named user; requires admin privileges,
Returns:: possibly-null status message string as returned from the server
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

updateUser

String updateUser(IUser user,
                  boolean force)
                  throws ConnectionException,
                         RequestException,
                         AccessException

Update a Perforce user on the Perforce server.

Parameters:: user - non-null IUser defining the user to be updated; force - if true, force update for users other than the caller. Requires super user / admin privileges (enforced by the server).
Returns:: possibly-null status message string as returned from the server
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

deleteUser

String deleteUser(String userName,
                  boolean force)
                  throws ConnectionException,
                         RequestException,
                         AccessException

Delete a named Perforce user from the Perforce server.

Parameters:: userName - non-null name of the user to be deleted.; force - if true, force deletion for users other than the caller. Requires super user / admin privileges (enforced by the server).
Returns:: possibly-null status message string as returned from the server
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getUsers

List<IUserSummary> getUsers(List<String> userList,
                            int maxUsers)
                            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.

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.

Parameters:: userList - if non-null, restrict output to users matching the passed-in list of users.; maxUsers - if positive, only return the first maxUsers users.
Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getUserGroups

List<IUserGroup> getUserGroups(String userOrGroupName,
                               boolean indirect,
                               boolean displayValues,
                               int maxGroups)
                               throws ConnectionException,
                                      RequestException,
                                      AccessException

Get a list of Perforce user groups from the server.

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.

Parameters:: userOrGroupName - if non-null, restrict the list to the specified group or username.; indirect - if true, also displays groups that the specified user or group belongs to indirectly via subgroups.; displayValues - if true, display the MaxResults, MaxScanRows, MaxLockTime, and Timeout values for the named group.; maxGroups - if > 0, display only the first m results.
Returns:: a non-zero but possibly-empty list of qualifying groups.
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request.; AccessException - if the Perforce server denies access to the caller.

getUserGroup

IUserGroup getUserGroup(String name)
                        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.

Parameters:: name - non-null group name.
Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request.; AccessException - if the Perforce server denies access to the caller.

createUserGroup

String createUserGroup(IUserGroup group)
                       throws ConnectionException,
                              RequestException,
                              AccessException

Create a new Perforce user group on the Perforce server.

Parameters:: group - non-null IUserGroup to be created.
Returns:: possibly-null status message string as returned from the server
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request.; AccessException - if the Perforce server denies access to the caller.

updateUserGroup

String updateUserGroup(IUserGroup group,
                       boolean updateIfOwner)
                       throws ConnectionException,
                              RequestException,
                              AccessException

Update a Perforce user group on the Perforce server.

Parameters:: group - non-null user group to be updated.; updateIfOwner - if true, allows a user without 'super' access to modify the group only if that user is an 'owner' of that group.
Returns:: possibly-null status message string as returned from the server
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request.; AccessException - if the Perforce server denies access to the caller.

deleteUserGroup

String deleteUserGroup(IUserGroup group)
                       throws ConnectionException,
                              RequestException,
                              AccessException

Delete a Perforce user group from the Perforce server.

Parameters:: group - non-null group to be deleted.
Returns:: possibly-null status message string as returned from the server
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request.; AccessException - if the Perforce server denies access to the caller.

getProtectionEntries

List<IProtectionEntry> getProtectionEntries(boolean allUsers,
                                            String hostName,
                                            String userName,
                                            String groupName,
                                            List<IFileSpec> fileList)
                                            throws ConnectionException,
                                                   RequestException,
                                                   AccessException

Get a list of Perforce protection entries for the passed-in arguments.

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.

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.

Parameters:: allUsers - if true, protection lines for all users are displayed.; hostName - only protection entries that apply to the given host (IP address) are displayed.; userName - protection lines Perforce user "userName" are displayed.; groupName - protection lines for Perforce group "groupName" are displayed.; fileList - if non-null, only those protection entries that apply to the specified files are displayed.
Returns:: non-null but possibly empty list of protection entries.
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request.; AccessException - if the Perforce server denies access to the caller.

getClients

List<IClientSummary> getClients(String userName,
                                String queryString,
                                int maxResults)
                                throws ConnectionException,
                                       RequestException,
                                       AccessException

Get a list of IClientSummary objects for all Perforce clients known to this Perforce server.

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.

Parameters:: userName - if not null, restrict listings to clients owned by the user 'userName'; 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.; maxResults - if > 0, restrict output to the first maxResults results.
Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getLabels

List<ILabelSummary> getLabels(String user,
                              int maxLabels,
                              String nameFilter,
                              List<IFileSpec> fileList)
                              throws ConnectionException,
                                     RequestException,
                                     AccessException

Get a list of Perforce labels, optionally tied to a specific set of files.

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.

Parameters:: user - if non-null, limit labels to those owned by the named user; maxLabels - if larger than zero, return only the first maxLabels (or fewer) qualifying labels; nameFilter - if not null, limits output to labels whose name matches the nameFilter pattern, e.g. -e 'svr-dev-rel*'; fileList - if not null, limits its report to labels that contain those files
Returns:: non-null (but possibly-empty) list of qualifying Perforce labels
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getLabel

ILabel getLabel(String labelName)
                throws ConnectionException,
                       RequestException,
                       AccessException

Get a specific named Perforce label.

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.

Parameters:: labelName - non-null label name
Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

createLabel

String createLabel(ILabel label)
                   throws ConnectionException,
                          RequestException,
                          AccessException

Create a new Perforce label in the Perforce server.

Parameters:: label - non-null ILabel to be saved
Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

updateLabel

String updateLabel(ILabel label)
                   throws ConnectionException,
                          RequestException,
                          AccessException

Update an existing Perforce label in the Perforce server.

Parameters:: label - non-null ILabel to be updated
Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

deleteLabel

String deleteLabel(String labelName,
                   boolean force)
                   throws ConnectionException,
                          RequestException,
                          AccessException

Delete a named Perforce label from the Perforce server.

Parameters:: labelName - non-null label name; force - if true, forces the deletion of any label; normally labels can only be deleted by their owner
Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

tagFiles

List<IFileSpec> tagFiles(List<IFileSpec> fileSpecs,
                         String labelName,
                         boolean listOnly,
                         boolean delete)
                         throws ConnectionException,
                                RequestException,
                                AccessException

Tag files with a Perforce label.

Parameters:: fileSpecs - non-null list of files to be tagged.; labelName - non-null label name to use for the tagging.; listOnly - if true, don't do the actual tag, just return the list of files that would have been tagged.; delete - if true, delete the label tag from the files.
Returns:: a non-null (but possibly empty) list of affected file specs
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getBranchSpecs

List<IBranchSpecSummary> getBranchSpecs(String userName,
                                        String nameFilter,
                                        int maxReturns)
                                        throws ConnectionException,
                                               RequestException,
                                               AccessException

Get a list of all summary Perforce branch specs known to the Perforce server.

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.

Parameters:: userName - if non-null, limit qualifying branches to those owned by the named user.; nameFilter - if non-null, limits output to branches whose name matches the nameFilter pattern.; maxReturns - if greater than zero, limit output to the first maxReturns number of branches.
Returns:: non-null (but possibly-empty) list of IBranchSpecSummary objects.
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getBranchSpec

IBranchSpec getBranchSpec(String name)
                          throws ConnectionException,
                                 RequestException,
                                 AccessException

Get a specific named Perforce branch spec from the Perforce server.

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.

Parameters:: name - non-null branch name
Returns:: potentially-null IBranchSpec for the named Perforce branch spec.
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

createBranchSpec

String createBranchSpec(IBranchSpec branchSpec)
                        throws ConnectionException,
                               RequestException,
                               AccessException

Create a new Perforce branch spec on the Perforce server.

Parameters:: branchSpec - non-null branch spec to be created.
Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

updateBranchSpec

String updateBranchSpec(IBranchSpec branchSpec)
                        throws ConnectionException,
                               RequestException,
                               AccessException

Update a Perforce branch spec on the Perforce server.

Parameters:: branchSpec - non-null branch spec to be updated.
Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

deleteBranchSpec

String deleteBranchSpec(String branchSpecName,
                        boolean force)
                        throws ConnectionException,
                               RequestException,
                               AccessException

Delete a named Perforce branch spec from the Perforce server.

Parameters:: branchSpecName - non-null branch spec name; force - if true, forces the deletion of any branch; normally branches can only be deleted by their owner
Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getCurrentClient

IClient getCurrentClient()

Return the Perforce client currently associated with this Perforce server, if any.

Returns:: IClient representing the current client, or null if no client associated with this server.

setCurrentClient

void setCurrentClient(IClient client)
                      throws ConnectionException,
                             RequestException,
                             AccessException

Set the Perforce client associated with this server.

Parameters:: client -
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getClient

IClient getClient(String clientName)
                  throws ConnectionException,
                         RequestException,
                         AccessException

Get an IClient object for a specific named Perforce client.

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.

Parameters:: clientName - non-null Perforce client name.
Returns:: IClient representing the specified Perforce client, or null if no such client.
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getClient

IClient getClient(IClientSummary clientSummary)
                  throws ConnectionException,
                         RequestException,
                         AccessException

Convenience method for getClient(clientSummary.getName()).

Parameters:: clientSummary - non-null Perforce client summary object.
Returns:: IClient representing the specified Perforce client, or null if no such client.
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getClientTemplate

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. This method is designed to be able to get the server returned default values it uses when a non-existent client is requested.

Parameters:: clientName - non-null Perforce client name.
Returns:: IClient representing the specified Perforce client, or null if no such client.
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getClientTemplate

IClient getClientTemplate(String clientName,
                          boolean allowExistent)
                          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.

Parameters:: clientName - non-null Perforce client name.; allowExistent - - true to return a client even if it exists
Returns:: IClient representing the specified Perforce client, or null if no such client.
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

createClient

String createClient(IClient newClient)
                    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 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.

Parameters:: newClient - non-null IClient defining the new Perforce client to be created.
Returns:: non-null result message string from the Perforce server
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

updateClient

String updateClient(IClient client)
                    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).

Parameters:: client - non-null IClient defining the Perforce client to be updated
Returns:: possibly-null operation result message string from the Perforce server
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

deleteClient

String deleteClient(String clientName,
                    boolean force)
                    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.

Parameters:: clientName - non-null name of the client to be deleted from the server.; force - if true, tell the server to attempt to force the delete regardless of the consequences. You're on your own with this one...
Returns:: possibly-null operation result message string from the Perforce server
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getDepotFiles

List<IFileSpec> getDepotFiles(List<IFileSpec> fileSpecs,
                              boolean allRevs)
                              throws ConnectionException,
                                     AccessException

List all Perforce depot files known to the Perforce server that conform to the passed-in wild-card file specification(s).

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).

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.

See 'p4 help revisions' for help specifying revisions.

Note that the IFileSpec objects returned will have null client and local path components.

Parameters:: fileSpecs - a non-null list of one or more IFileSpecs to be used to qualify Perforce depot files; allRevs - if true, list all revisions of qualifying files.
Returns:: a non-null (but possible empty) list of all qualifying depot files
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; AccessException - if the Perforce server denies access to the caller

getFileAnnotations

List<IFileAnnotation> getFileAnnotations(List<IFileSpec> fileSpecs,
                                         DiffType wsOpts,
                                         boolean allResults,
                                         boolean useChangeNumbers,
                                         boolean followBranches)
                                         throws ConnectionException,
                                                RequestException,
                                                AccessException

Get a list of revision annotations for the specified files.

Parameters:: fileSpecs - non-null list of file specs to be annotated; 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.; allResults - if true, include both deleted files and lines no longer present at the head revision; useChangeNumbers - if true, annotate with change numbers rather than revision numbers with each line; followBranches - if true, follow branches.
Returns:: non-null (but possibly-empty) list of IFileAnnotation objects representing version annotations for the passed-in file specs.
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

moveFile

List<IFileSpec> moveFile(int changelistId,
                         boolean listOnly,
                         boolean noClientMove,
                         String fileType,
                         IFileSpec fromFile,
                         IFileSpec toFile)
                         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.

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.

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.

Parameters:: changelistId - if not IChangelist.UNKNOWN, the files are opened in the numbered pending changelist instead of the 'default' changelist.; listOnly - if true, don't actually perform the move, just return what would happen if the move was performed; noClientMove - if true, bypasses the client file rename. 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.; fileType - if not null, the file is reopened as that filetype.; fromFile - the original file; must be already open for edit.; toFile - the target file.
Returns:: list of IFileSpec objects representing the results of this move
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getDirectories

List<IFileSpec> getDirectories(List<IFileSpec> fileSpecs,
                               boolean clientOnly,
                               boolean deletedOnly,
                               boolean haveListOnly)
                               throws ConnectionException,
                                      AccessException

List any directories matching the passed-in file specifications.

Parameters:: fileSpecs - non-null list of file specifications; clientOnly - if true, limit the returns to directories that are mapped in the current Perforce client workspace; deletedOnly - if true, includes directories with only deleted files.; haveListOnly - if true, lists directories of files on the 'have' list.
Returns:: 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.; AccessException - if the Perforce server denies access to the caller

getChangelists

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).

Note that if both submittedOnly and pendingOnly are true, the results are implementation-defined.

Parameters:: 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).; 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.; clientName - if non-null, restrict the results to changelists associated with the given client.; userName - if non-null, restrict the results to changelists associated with the given user name.; includeIntegrated - if true, also include any changelists integrated into the specified files (if any).; type - if non-null, restrict the results to the specified changelist type; longDesc - if true, produce a non-truncated long version of the description
Returns:: a non-null (but possibly empty) list of qualifying changelists.
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getChangelists

List<IChangelistSummary> getChangelists(int maxMostRecent,
                                        List<IFileSpec> fileSpecs,
                                        String clientName,
                                        String userName,
                                        boolean includeIntegrated,
                                        boolean submittedOnly,
                                        boolean pendingOnly,
                                        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).

Note that if both submittedOnly and pendingOnly are true, the results are implementation-defined.

Parameters:: 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).; 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.; clientName - if non-null, restrict the results to changelists associated with the given client.; userName - if non-null, restrict the results to changelists associated with the given user name.; includeIntegrated - if true, also include any changelists integrated into the specified files (if any).; longDesc - if true, produce a non-truncated long version of the description; submittedOnly - if true, restrict the results to submitted changelists only.; pendingOnly - if true, restrict the results to pending changelists only.
Returns:: a non-null (but possibly empty) list of qualifying changelist summary objects.
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getChangelist

IChangelist getChangelist(int id)
                          throws ConnectionException,
                                 RequestException,
                                 AccessException

Get a specific Perforce changelist from a Perforce server.

Corresponds fairly well to the p4 command-line command "change -o", and (like "change -o") does not 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.

Parameters:: id - the Perforce changelist ID; if id is IChangelist.DEFAULT, get the default changelist for the current client (if available)
Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

deletePendingChangelist

String deletePendingChangelist(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.

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.

Parameters:: id - the ID of the Perforce pending changelist to be deleted.
Returns:: possibly-null operation result message string from the Perforce server
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getChangelistFiles

List<IFileSpec> getChangelistFiles(int id)
                                   throws ConnectionException,
                                          RequestException,
                                          AccessException

Get a list of the Perforce depot files associated with a Perforce changelist.

The IFileSpec objects returned are not guaranteed to have any fields except depot path, version, and action valid.

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.

Parameters:: id - numeric changelist identifier
Returns:: non-null (but possibly empty) list of files associated with the changelist.
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getChangelistDiffs

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.

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.

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

Parameters:: id - the ID of the target changelist; diffType - if non-null, describes which type of diff to perform.
Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getChangelistDiffsStream

InputStream getChangelistDiffsStream(int id,
                                     DescribeOptions options)
                                     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.

Parameters:: id - the ID of the target changelist; options - DescribeOptions behavioural options for method.
Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getFileContents

InputStream getFileContents(List<IFileSpec> fileSpecs,
                            boolean allrevs,
                            boolean noHeaderLine)
                            throws ConnectionException,
                                   RequestException,
                                   AccessException

Return an InputStream onto the contents of one or more revisions of one or more Perforce depot file contents.

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.

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.

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.

Parameters:: fileSpecs - non-null list of depot or client file specs defining files to be streamed; allrevs - if true, streams all revisions within the specific range, rather than just the highest revision in the range; noHeaderLine - if true, suppresses the initial line that displays the file name and revision for each file / revision contents
Returns:: a non-null but possibly-empty InputStream onto the file / revision contents
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getRevisionHistory

Map<IFileSpec,List<IFileRevisionData>> getRevisionHistory(List<IFileSpec> fileSpecs,
                                                          int maxRevs,
                                                          boolean contentHistory,
                                                          boolean includeInherited,
                                                          boolean longOutput,
                                                          boolean truncatedLongOutput)
                                                          throws ConnectionException,
                                                                 AccessException

Get the revision history data for one or more Perforce files.

Behavior is undefined if both longOutput and truncatedLongOutput are true. If both are false, a short form of the description (prepared by the server) is returned.

Parameters:: fileSpecs - filespecs to be processed; if null or empty, an empty Map is returned.; maxRevs - if positive, return at most maxRev revisions for each file.; includeInherited - if true, causes inherited file history to be returned as well.; longOutput - if true, return the full descriptions associated with each revision; truncatedLongOutput - if true, return only the first 250 characters of each description.
Returns:: a non-null map of lists of 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.; AccessException - if the Perforce server denies access to the caller

getReviews

List<IUserSummary> getReviews(int changelistId,
                              List<IFileSpec> fileSpecs)
                              throws ConnectionException,
                                     RequestException,
                                     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.

Note that the returned IUserSummary objects will have null access and update dates associated with them.

Parameters:: changelistId - if not IChangelist.UNKNOWN, use this changelist ID.; fileSpecs - if not null, use this list as the list of named files rather than all files.
Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getOpenedFiles

List<IFileSpec> getOpenedFiles(List<IFileSpec> fileSpecs,
                               boolean allClients,
                               String clientName,
                               int maxFiles,
                               int changeListId)
                               throws ConnectionException,
                                      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.

The returned list can be modified with the other arguments as described below.

Parameters:: fileSpecs - if non-empty, determine the status of the specified files; otherwise return all qualifying files known to be open; allClients - if true, return results for all known clients rather than the current client (if any).; clientName - if non-null, return results for the named client only.; maxFiles - if positive, return only the first maxFiles qualifying files.; changeListId - if positive, return only files associated with the given changelist ID; if IChangelist.DEFAULT, retrieve files open associated with the default changelist.
Returns:: 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.; AccessException - if the Perforce server denies access to the caller

getExtendedFiles

List<IExtendedFileSpec> getExtendedFiles(List<IFileSpec> fileSpecs,
                                         int maxFiles,
                                         int sinceChangelist,
                                         int affectedByChangelist,
                                         FileStatOutputOptions outputOptions,
                                         FileStatAncilliaryOptions ancilliaryOptions)
                                         throws ConnectionException,
                                                AccessException

Return a list of everything Perforce knows about a possibly very large set of Perforce files.

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).

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.

Parameters:: fileSpecs - non-null list of Perforce file specification(s); 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).; sinceChangelist - if larger than or equal to zero, display only files affected since the given changelist number; zero is equivalent to IChangelist.DEFAULT.; affectedByChangelist - if larger than or equal to zero, display only files affected by the given changelist number; zero is equivalent to IChangelist.DEFAULT.; outputOptions - if non-null, specifies the oputput options to be used; ancilliaryOptions - if non-null, specifies the ancilliary output options to be used
Returns:: 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.; AccessException - if the Perforce server denies access to the caller

getSubmittedIntegrations

List<IFileSpec> getSubmittedIntegrations(List<IFileSpec> fileSpecs,
                                         String branchSpec,
                                         boolean reverseMappings)
                                         throws ConnectionException,
                                                RequestException,
                                                AccessException

Get a list of submitted integrations for the passed-in filespecs.

Parameters:: fileSpecs - if null or ommitted, all qualifying depot files are used.; 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.; 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.
Returns:: a non-null but possibly empty list of IFileSpec representing qualifying integrations.
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getInterchanges

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 (unsupported). Corresponds fairly closely to the p4 interchanges command for filespecs.

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 all files associated with the changelist, which is probably different from the list associated with the integration.

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.

Parameters:: fromFile - non-null from-file specification.; toFile - non-null to-file specification.; showFiles - if true, show the individual files that would require integration.; longDesc - if true, return a long description in the changelist.; maxChangelistId - if greater than zero, only consider integration history from changelists at or below the given number
Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getInterchanges

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

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.

Parameters:: branchSpecName - non-null, non-empty branch spec name.; fromFileList - if non-null and not empty, and biDirectional is true, use this as the from file list.; toFileList - if non-null and not empty, use this as the to file list.; showFiles - if true, show the individual files that would require integration.; longDesc - if true, return a long description in the changelist.; maxChangelistId - if greater than zero, only consider integration; reverseMapping - if true, reverse the mappings in the branch view, with the target files and source files exchanging place.; biDirectional -
Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getJobs

List<IJob> getJobs(List<IFileSpec> fileSpecs,
                   int maxJobs,
                   boolean longDescriptions,
                   boolean reverseOrder,
                   boolean includeIntegrated,
                   String jobView)
                   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.

Note that this method (unlike the main file list methods) throws an exception and stops at the first encountered error.

Parameters:: fileSpecs - if given, return only jobspecs affecting the given file(s); maxJobs - if positive, return only up to maxJobs results; longDescriptions - if true, return full descriptions, otherwise show only a subset (typically the first 128 characters, but this is not guaranteed).; reverseOrder - if true, reverse the normal sort order; includeIntegrated - if true, include any fixes made by changelists integrated into the specified files; jobView - if non-null, a string in format detailed by "p4 help jobview" used to restrict jobs to those satisfying the job view expression.
Returns:: a non-null (but possibly-empty) list of qualifying Perforce jobs
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getJob

IJob getJob(String jobId)
            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.

Parameters:: jobId - non-null job Id.
Returns:: IJob for the named job; null if no such job.
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

createJob

IJob createJob(Map<String,Object> fieldMap)
               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).

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).

Parameters:: fieldMap - non-null field map defining the new job in the Perforce server.
Returns:: returns an IJob representing the newly-created job, if successful.
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

updateJob

String updateJob(IJob job)
                 throws ConnectionException,
                        RequestException,
                        AccessException

Update a Perforce job on the Perforce server. Note that only the associated raw fields map is used for field values; the main description and ID fields are actually ignored.

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.

Parameters:: job - non-null candidate for updating.
Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

deleteJob

String deleteJob(String jobId)
                 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.

Parameters:: jobId - ID of the job to be deleted.
Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getJobSpec

IJobSpec getJobSpec()
                    throws ConnectionException,
                           RequestException,
                           AccessException

Return the Perforce jobspec associated with this Perforce server.

Returns:: possibly-null IJobSpec representing the unserlying Perforc server's jobspec.
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getFixList

List<IFix> getFixList(List<IFileSpec> fileSpecs,
                      int changeListId,
                      String jobId,
                      boolean includeIntegrations,
                      int maxFixes)
                      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".

Note that this method (unlike the main file list methods) throws an exception and stops at the first encountered error.

Parameters:: fileSpecs - if given, restrict output to fixes associated with these files; changeListId - if positive, only fixes from the numbered changelist are listed.; jobId - if non-null, only fixes for the named job are listed; includeIntegrations - if true, include any fixes made by changelists integrated into the specified files; maxFixes - if positive, restrict the list to the first maxFixes fixes
Returns:: non-null but possibly empty list of qualifying IFix fixes.
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

fixJobs

List<IFix> fixJobs(List<String> jobIdList,
                   int changeListId,
                   String status,
                   boolean delete)
                   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.

Parameters:: changeListId - changelist number; status - if non-null, use this as the new status rather than "closed"; delete - if true, delete the specified fixes
Returns:: list of affected fixes
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getServerProcesses

List<IServerProcess> getServerProcesses()
                                        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.

Returns:: non-null but possibly-empty list of IServerProcess objects
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getServerFileDiffs

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.

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.

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.

Parameters:: file1 - optional first file IFileSpec; file2 - optional second file IFileSpec; branchSpecName - optional branch spec name; 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.; includeNonTextDiffs - if true, forces 'p4 diff2' to diff even files with non-text (binary) types; gnuDiffs - see "-u" option in the main diff2 documentation.
Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getFileDiffs

List<IFileDiff> getFileDiffs(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.

Parameters:: file1 - optional first file IFileSpec; file2 - optional second file IFileSpec; branchSpecName - optional branch spec name; 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.; includeNonTextDiffs - if true, forces 'p4 diff2' to diff even files with non-text (binary) types; gnuDiffs - see "-u" option in the main diff2 documentation.
Returns:: non-null but possibly empty array of file diffs
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

execMapCmd

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.

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.

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.

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 not 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.

Parameters:: cmdName - the command to be issued; must be non-null, and correspond to a Perforce command recognized by P4Java and defined in CmdSpec.; 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.; 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.
Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

execInputStringMapCmd

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.

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.

Parameters:: cmdName - the command to be issued; must be non-null, and correspond to a Perforce command recognized by P4Java and defined in CmdSpec.; 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.; 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.
Returns:: 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
Since:: 2011.1

execQuietMapCmd

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 return the results as a map without invoking any command callbacks.

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

Parameters:: cmdName - the command to be issued; must be non-null, and correspond to a Perforce command recognized by P4Java and defined in CmdSpec.; 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.; 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.
Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

execStreamCmd

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.

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.

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 not 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.

Parameters:: cmdName - the command to be issued; must be non-null, and correspond to a Perforce command recognized by P4Java and defined in CmdSpec.; 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.
Returns:: an InputStream on the command output. This will never be null, but it may be empty. You must 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

execQuietStreamCmd

InputStream execQuietStreamCmd(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.

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

Parameters:: cmdName - the command to be issued; must be non-null, and correspond to a Perforce command recognized by P4Java and defined in CmdSpec.; 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.
Returns:: an InputStream on the command output. This will never be null, but it may be empty. You must 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

execStreamingMapCommand

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 map for any input expected by the server (such as label or job specs, etc.).

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).

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.

NOTE: 'streaming' here has nothing at all to do with Perforce 'streams', which are (or will be) implemented elsewhere.

Parameters:: cmdName - the command to be issued; must be non-null, and correspond to a Perforce command recognized by P4Java and defined in CmdSpec.; 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.; 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.; callback - a non-null IStreamingCallback to be used to process the incoming results.; key - an opaque integer key that is passed to the IStreamingCallback callback methods to identify the action as being associated with this specific call.
Throws:: P4JavaException - if an error occurs processing this method and its parameters.
Since:: 2011.1

execInputStringStreamingMapComd

@Deprecated
void execInputStringStreamingMapComd(String cmdName,
                                                String[] cmdArgs,
                                                String inString,
                                                IStreamingCallback callback,
                                                int key)
                                     throws P4JavaException

Deprecated. As of release 2013.1, replaced by IOptionsServer.execInputStringStreamingMapCmd(java.lang.String, java.lang.String[], java.lang.String, com.perforce.p4java.server.callback.IStreamingCallback, int)

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.).

NOTE: 'streaming' here has nothing at all to do with Perforce 'streams', which are (or will be) implemented elsewhere.

Parameters:: cmdName - the command to be issued; must be non-null, and correspond to a Perforce command recognized by P4Java and defined in CmdSpec.; 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.; 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.; callback - a non-null IStreamingCallback to be used to process the incoming results.; key - an opaque integer key that is passed to the IStreamingCallback callback methods to identify the action as being associated with this specific call.
Throws:: P4JavaException - if an error occurs processing this method and its parameters.
Since:: 2011.1

getCounter

String getCounter(String counterName)
                  throws ConnectionException,
                         RequestException,
                         AccessException

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.

Note that despite their name, counters can be any value, not just a number; hence the string return value here.

Parameters:: counterName - non-null counter name.
Returns:: non-null (but possibly empty or useless) counter value associated with counterName.
Throws:: ConnectionException - if the Perforce server is unreachable or is not connected.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

setCounter

void setCounter(String counterName,
                String value,
                boolean perforceCounter)
                throws ConnectionException,
                       RequestException,
                       AccessException

Throws:: ConnectionException; RequestException; AccessException

deleteCounter

void deleteCounter(String counterName,
                   boolean perforceCounter)
                   throws ConnectionException,
                          RequestException,
                          AccessException

Throws:: ConnectionException; RequestException; AccessException

getCounters

Map<String,String> getCounters()
                               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.

Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getDbSchema

List<IDbSchema> getDbSchema(List<String> tableSpecs)
                            throws ConnectionException,
                                   RequestException,
                                   AccessException

Get the database schema associated with this server (admin / superuser command).

See the main p4 admin command documentation for full semantics and usage details.

Parameters:: tableSpecs - if null, return all known schema; otherwise, restrict the returned list to the named tables and table versions.
Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

getExportRecords

List<Map<String,Object>> getExportRecords(boolean useJournal,
                                          long maxRecs,
                                          int sourceNum,
                                          long offset,
                                          boolean format,
                                          String journalPrefix,
                                          String filter)
                                          throws ConnectionException,
                                                 RequestException,
                                                 AccessException

Get a list of exported journal or checkpoint records (admin / superuser command).

See the main p4 admin command documentation for full semantics and usage details.

Parameters:: useJournal - if true, export journal records; otherwise, export checkpoint records.; maxRecs - if larger than zero, return only the first maxRec lines; sourceNum - checkpoint or journal number.; offset - offset with in checkpoint or journal.; format - if true, formats record output appropriately for the type of data.; journalPrefix - if not null, specify a journal name prefix.; filter - if not null, pass the specified filter to the exporter.
Returns:: 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.; RequestException - if the Perforce server encounters an error during its processing of the request; AccessException - if the Perforce server denies access to the caller

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.perforce.p4java.server Interface IServer

getProperties

registerCallback

registerProgressCallback

registerSSOCallback

getStatus

setCharsetName

getCharsetName

getServerVersionNumber

isCaseSensitive

supportsUnicode

supportsSmartMove

getKnownCharsets

setUserName

setAuthTicket

getAuthTicket

setWorkingDirectory

getWorkingDirectory

getUserName

connect

isConnected

disconnect

login

login

getLoginStatus

logout

getServerInfo

getDepots

getUser

createUser

updateUser

deleteUser

getUsers

getUserGroups

getUserGroup

createUserGroup

updateUserGroup

deleteUserGroup

getProtectionEntries

getClients

getLabels

getLabel

createLabel

updateLabel

deleteLabel

tagFiles

getBranchSpecs

getBranchSpec

createBranchSpec

updateBranchSpec

deleteBranchSpec

getCurrentClient

setCurrentClient

getClient

getClient

getClientTemplate

getClientTemplate

createClient

updateClient

deleteClient

getDepotFiles

getFileAnnotations

moveFile

getDirectories

getChangelists

getChangelists

getChangelist

deletePendingChangelist

getChangelistFiles

getChangelistDiffs

getChangelistDiffsStream

getFileContents

getRevisionHistory

getReviews

getOpenedFiles

getExtendedFiles

getSubmittedIntegrations

getInterchanges

getInterchanges

getJobs

com.perforce.p4java.server
Interface IServer