com.perforce.p4java.server
Interface IOptionsServer

All Superinterfaces:

IServer

All Known Subinterfaces:

IStreamingServer

All Known Implementing Classes:

NtsServerImpl, OneShotServerImpl, RpcServer, Server

public interface IOptionsServer
extends IServer

An extension of the basic IServer interface to provide Options object-based method access to Perforce server functionality and objects.

Note that unless otherwise noted, individual method options objects can be null; if they're null, the individual method Javadoc will spell out what default options apply (if any) in that case.

Note that in individual method Javadoc comments below, all method "throws" clauses are assumed to throw the normal complement of RequestException, ConnectionException, and AccessException with their usual semantics unless otherwise noted. The three standard P4JavaException classes and the broad causes for their being thrown are:

 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.
 

Method Summary

String	createDepot(IDepot newDepot) Create a new depot in the repository.
String	createUser(IUser user, UpdateUserOptions opts) Create a new Perforce user on the Perforce server.
String	createUserGroup(IUserGroup group, UpdateUserGroupOptions opts) Create a new Perforce user group on the Perforce server.
String	deleteBranchSpec(String branchSpecName, DeleteBranchSpecOptions opts) Delete a named Perforce branch spec from the Perforce server.
String	deleteClient(String clientName, DeleteClientOptions opts) Delete a Perforce client from a Perforce server.
String	deleteDepot(String name) Delete a named depot from the repository.
String	deleteLabel(String labelName, DeleteLabelOptions opts) Delete a named Perforce label from the Perforce server.
String	deleteUser(String userName, UpdateUserOptions opts) Delete a named Perforce user from the Perforce server
String	deleteUserGroup(IUserGroup group, UpdateUserGroupOptions opts) Delete a Perforce user group from the Perforce server.
List<IFix>	fixJobs(List<String> jobIds, int changelistId, FixJobsOptions opts) Mark each named job as being fixed by the changelist number given with changeListId.
List<IBranchSpecSummary>	getBranchSpecs(GetBranchSpecsOptions opts) Get a list of all summary Perforce branch specs known to the Perforce server.
InputStream	getChangelistDiffs(int id, GetChangelistDiffsOptions opts) Get an InputStream onto the file diffs associated with a specific submitted changelist.
List<IChangelistSummary>	getChangelists(List<IFileSpec> fileSpecs, GetChangelistsOptions opts) Get a list of Perforce changelist summary objects from the Perforce server.
List<IClientSummary>	getClients(GetClientsOptions opts) Get a list of IClientSummary objects for all Perforce clients known to this Perforce server.
IClient	getClientTemplate(String clientName, GetClientTemplateOptions opts) Get a template of a non-existent named Perforce client.
IDepot	getDepot(String name) Get an individual depot by name.
List<IFileSpec>	getDepotFiles(List<IFileSpec> fileSpecs, GetDepotFilesOptions opts) List all Perforce depot files known to the Perforce server that conform to the passed-in wild-card file specification(s).
List<IFileSpec>	getDirectories(List<IFileSpec> fileSpecs, GetDirectoriesOptions opts) List any directories matching the passed-in file specifications.
List<Map<String,Object>>	getExportRecords(ExportRecordsOptions opts) Get a list of exported journal or checkpoint records (admin / superuser command).
List<IExtendedFileSpec>	getExtendedFiles(List<IFileSpec> fileSpecs, GetExtendedFilesOptions opts) Return a list of everything Perforce knows about a set of Perforce files.
List<IFileAnnotation>	getFileAnnotations(List<IFileSpec> fileSpecs, GetFileAnnotationsOptions opts) Get a list of revision annotations for the specified files.
InputStream	getFileContents(List<IFileSpec> fileSpecs, GetFileContentsOptions opts) 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, GetFileDiffsOptions opts) Run diff on the Perforce server of two files in the depot.
InputStream	getFileDiffsStream(IFileSpec file1, IFileSpec file2, String branchSpecName, GetFileDiffsOptions opts) Run diff on the Perforce server of two files in the depot.
List<IFix>	getFixes(List<IFileSpec> fileSpecs, GetFixesOptions opts) 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, GetInterchangesOptions opts)
List<IChangelist>	getInterchanges(String branchSpecName, List<IFileSpec> fromFileList, List<IFileSpec> toFileList, GetInterchangesOptions opts)
List<IJob>	getJobs(List<IFileSpec> fileSpecs, GetJobsOptions opts) Return a list of Perforce jobs.
List<ILabelSummary>	getLabels(List<IFileSpec> fileList, GetLabelsOptions opts) Get a list of Perforce labels, optionally tied to a specific set of files.
List<IFileLineMatch>	getMatchingLines(List<IFileSpec> fileSpecs, String pattern, List<String> infoLines, MatchingLinesOptions options) Get list of matching lines in the specified file specs.
List<IFileLineMatch>	getMatchingLines(List<IFileSpec> fileSpecs, String pattern, MatchingLinesOptions options) Get list of matching lines in the specified file specs.
List<IFileSpec>	getOpenedFiles(List<IFileSpec> fileSpecs, OpenedFilesOptions opts) 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.
List<IProtectionEntry>	getProtectionEntries(List<IFileSpec> fileList, GetProtectionEntriesOptions opts) Get a list of Perforce protection entries for the passed-in arguments.
List<IUserSummary>	getReviews(List<IFileSpec> fileSpecs, GetReviewsOptions opts) Get a list of all users who have subscribed to review the named files.
Map<IFileSpec,List<IFileRevisionData>>	getRevisionHistory(List<IFileSpec> fileSpecs, GetRevisionHistoryOptions opts) Get the revision history data for one or more Perforce files.
List<IFileSpec>	getSubmittedIntegrations(List<IFileSpec> fileSpecs, GetSubmittedIntegrationsOptions opts) Get a list of submitted integrations for the passed-in filespecs
UsageOptions	getUsageOptions() Get the UsageOptions object associated with this server.
List<IUserGroup>	getUserGroups(String userOrGroupName, GetUserGroupsOptions opts) Get a list of Perforce user groups from the server.
List<IUserSummary>	getUsers(List<String> userList, GetUsersOptions opts) Get a list of Perforce users known to this Perforce server.
void	login(String password, LoginOptions opts) Log the current user (if any) in to a Perforce server, optionally arranging to be logged in for all hosts.
void	logout(LoginOptions opts) Log the current Perforce user out of a Perforce server session.
List<IFileSpec>	moveFile(IFileSpec fromFile, IFileSpec toFile, MoveFileOptions opts) Move a file already opened for edit or add (the fromFile) to the destination file (the toFile).
String	setCounter(String counterName, String value, CounterOptions opts) Create, set or delete a counter on a Perforce server.
List<IFileSpec>	setFileAttributes(List<IFileSpec> files, Map<String,String> attributes, SetFileAttributesOptions opts) Set file attributes on one or more files (unsupported).
List<IFileSpec>	setFileAttributes(List<IFileSpec> files, String attributeName, InputStream inStream, SetFileAttributesOptions opts) Set a file attribute on one or more files using the passed-in input stream as the source for the attribute's value (unsupported).
String	setServerConfigurationValue(String name, String value) Set or unset a specific names server configuration variable.
IOptionsServer	setUsageOptions(UsageOptions opts) Set the UsageOptions object associated with this server.
List<ServerConfigurationValue>	showServerConfiguration(String serverName, String variableName) Show server configuration values.
List<IFileSpec>	tagFiles(List<IFileSpec> fileSpecs, String labelName, TagFilesOptions opts)
String	updateUser(IUser user, UpdateUserOptions opts) Update a Perforce user on the Perforce server.
String	updateUserGroup(IUserGroup group, UpdateUserGroupOptions opts) Update a Perforce user group on the Perforce server.

Methods inherited from interface com.perforce.p4java.server.IServer

connect, createBranchSpec, createClient, createJob, createLabel, createUser, createUserGroup, deleteBranchSpec, deleteClient, deleteCounter, deleteJob, deleteLabel, deletePendingChangelist, deleteUser, deleteUserGroup, disconnect, execInputStringMapCmd, execInputStringStreamingMapComd, execMapCmd, execQuietMapCmd, execQuietStreamCmd, execStreamCmd, execStreamingMapCommand, fixJobs, getAuthTicket, getBranchSpec, getBranchSpecs, getChangelist, getChangelistDiffs, getChangelistDiffsStream, getChangelistFiles, getChangelists, getChangelists, getCharsetName, getClient, getClient, getClients, getClientTemplate, getClientTemplate, getCounter, getCounters, getCurrentClient, getDbSchema, getDepotFiles, getDepots, getDirectories, getExportRecords, getExtendedFiles, getFileAnnotations, getFileContents, getFileDiffs, getFixList, getInterchanges, getInterchanges, getJob, getJobs, getJobSpec, getKnownCharsets, getLabel, getLabels, getLoginStatus, getOpenedFiles, getProperties, getProtectionEntries, getReviews, getRevisionHistory, getServerFileDiffs, getServerInfo, getServerProcesses, getServerVersionNumber, getStatus, getSubmittedIntegrations, getUser, getUserGroup, getUserGroups, getUserName, getUsers, getWorkingDirectory, isCaseSensitive, isConnected, login, login, logout, moveFile, registerCallback, registerProgressCallback, registerSSOCallback, setAuthTicket, setCharsetName, setCounter, setCurrentClient, setUserName, setWorkingDirectory, supportsSmartMove, supportsUnicode, tagFiles, updateBranchSpec, updateClient, updateJob, updateLabel, updateUser, updateUserGroup

Method Detail

getUsageOptions

UsageOptions getUsageOptions()

Get the UsageOptions object associated with this server.

Returns:

possibly-null UsageOptions object.

setUsageOptions

IOptionsServer setUsageOptions(UsageOptions opts)

Set the UsageOptions object associated with this server. Note that changing this object (or its contents) while a server is busy can cause issues.

Parameters:

opts - non-null UsageOptions object to associate with this server.

Returns:

the current server.

login

void login(String password,
           LoginOptions opts)
           throws P4JavaException

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)

opts - if LoginOptions.allHosts is true, perform the equivalent of a "login -a". A null LoginOptions parameter is equivalent to no options being set.

Throws:

P4JavaException - if any error occurs in the processing of this method. A specific ConfigException is thrown if the p4tickets file could not be updated successfully.

logout

void logout(LoginOptions opts)
            throws P4JavaException

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

Parameters:

opts - currently ignored; can be null.

Throws:

P4JavaException - if any error occurs in the processing of this method.

getDepot

IDepot getDepot(String name)
                throws P4JavaException

Get an individual depot by name. Note that this method will return a fake depot if you ask it for a non-existent depot, so it's not the most useful of operations.

Parameters:

name - non-null name of the depot to be retrieved.

Returns:

IDepot non-null object corresponding to the named depot if it exists and is retrievable; otherwise an IDepot object that looks real but does not, in fact, correspond to any known depot in the repository.

Throws:

P4JavaException - if any error occurs in the processing of this method.

Since:

2011.1

createDepot

String createDepot(IDepot newDepot)
                   throws P4JavaException

Create a new depot in the repository. You must be an admin for this operation to succeed.

Parameters:

newDepot - non-null IDepot object representing the depot to be created.

Returns:

possibly-null operation result message string from the Perforce server.

Throws:

P4JavaException - if any error occurs in the processing of this method.

Since:

2011.1

deleteDepot

String deleteDepot(String name)
                   throws P4JavaException

Delete a named depot from the repository. You must be an admin for this operation to succeed.

Parameters:

name - non-null IDepot object representing the depot to be deleted

Returns:

possibly-null operation result message string from the Perforce server.

Throws:

P4JavaException - if any error occurs in the processing of this method.

Since:

2011.1

getDepotFiles

List<IFileSpec> getDepotFiles(List<IFileSpec> fileSpecs,
                              GetDepotFilesOptions opts)
                              throws P4JavaException

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

opts - GetDepotFilesOptions describing the associated options; if null, no options are set.

Returns:

a non-null (but possible empty) list of all qualifying depot files

Throws:

P4JavaException - if any error occurs in the processing of this method.

getFixes

List<IFix> getFixes(List<IFileSpec> fileSpecs,
                    GetFixesOptions opts)
                    throws P4JavaException

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

opts - FixListOptions object describing optional parameters; if null, no options are set

Returns:

non-null but possibly empty list of qualifying IFix fixes.

Throws:

P4JavaException - if any error occurs in the processing of this method.

getMatchingLines

List<IFileLineMatch> getMatchingLines(List<IFileSpec> fileSpecs,
                                      String pattern,
                                      MatchingLinesOptions options)
                                      throws P4JavaException

Get list of matching lines in the specified file specs. This method implements the p4 grep command; for full semantics, see the separate p4 documentation and / or the GrepOptions Javadoc.

Parameters:

fileSpecs - file specs to search for matching lines

pattern - non-null string pattern to be passed to the grep command

options - - Options to grep command

Returns:

- non-null but possibly empty list of file line matches

Throws:

P4JavaException - if any error occurs in the processing of this method.

getMatchingLines

List<IFileLineMatch> getMatchingLines(List<IFileSpec> fileSpecs,
                                      String pattern,
                                      List<String> infoLines,
                                      MatchingLinesOptions options)
                                      throws P4JavaException

Get list of matching lines in the specified file specs. This method implements the p4 grep command; for full semantics, see the separate p4 documentation and / or the GrepOptions Javadoc.

This method allows the user to retrieve useful info and warning message lines the Perforce server may generate in response to things like encountering a too-long line, etc., by passing in a non-null infoLines parameter.

Parameters:

fileSpecs - file specs to search for matching lines

pattern - non-null string pattern to be passed to the grep command

infoLines - if not null, any "info" lines returned from the server (i.e. warnings about exceeded line lengths, etc.) will be put into the passed-in list in the order they are received.

options - - Options to grep command

Returns:

- non-null but possibly empty list of file line matches

Throws:

P4JavaException - if any error occurs in the processing of this method.

Since:

2011.1

createUser

String createUser(IUser user,
                  UpdateUserOptions opts)
                  throws P4JavaException

Create a new Perforce user on the Perforce server.

Parameters:

user - non-null IUser defining the new user to be created.

opts - UpdateUserOptions object describing optional parameters; if null, no options are set

Returns:

possibly-null status message string as returned from the server

Throws:

P4JavaException - if any error occurs in the processing of this method.

updateUser

String updateUser(IUser user,
                  UpdateUserOptions opts)
                  throws P4JavaException

Update a Perforce user on the Perforce server.

Parameters:

user - non-null IUser defining the new user to be updated.

opts - UpdateUserOptions object describing optional parameters; if null, no options are set

Returns:

possibly-null status message string as returned from the server

Throws:

P4JavaException - if any error occurs in the processing of this method.

deleteUser

String deleteUser(String userName,
                  UpdateUserOptions opts)
                  throws P4JavaException

Delete a named Perforce user from the Perforce server

Parameters:

userName - non-null name of the user to be deleted.

opts - UpdateUserOptions object describing optional parameters; if null, no options are set

Returns:

possibly-null status message string as returned from the server

Throws:

P4JavaException - if any error occurs in the processing of this method.

getUsers

List<IUserSummary> getUsers(List<String> userList,
                            GetUsersOptions opts)
                            throws P4JavaException

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.

opts - GetUsersOptions object describing optional parameters; if null, no options are set

Returns:

non-null (but possibly empty) list of non-null IUserSummary objects representing the underlying Perforce users (if any).

Throws:

P4JavaException - if any error occurs in the processing of this method.

getUserGroups

List<IUserGroup> getUserGroups(String userOrGroupName,
                               GetUserGroupsOptions opts)
                               throws P4JavaException

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.

opts - GetUserGroupsOptions object describing optional parameters; if null, no options are set

Returns:

a non-null but possibly-empty list of qualifying groups.

Throws:

P4JavaException - if any error occurs in the processing of this method.

createUserGroup

String createUserGroup(IUserGroup group,
                       UpdateUserGroupOptions opts)
                       throws P4JavaException

Create a new Perforce user group on the Perforce server.

Parameters:

group - group non-null IUserGroup to be created.

opts - UpdateUserGroupOptions object describing optional parameters; if null, no options are set

Returns:

possibly-null status message string as returned from the server.

Throws:

P4JavaException - if any error occurs in the processing of this method.

updateUserGroup

String updateUserGroup(IUserGroup group,
                       UpdateUserGroupOptions opts)
                       throws P4JavaException

Update a Perforce user group on the Perforce server.

Parameters:

group - group non-null IUserGroup to be updated.

opts - UpdateUserGroupOptions object describing optional parameters; if null, no options are set

Returns:

possibly-null status message string as returned from the server.

Throws:

P4JavaException - if any error occurs in the processing of this method.

deleteUserGroup

String deleteUserGroup(IUserGroup group,
                       UpdateUserGroupOptions opts)
                       throws P4JavaException

Delete a Perforce user group from the Perforce server.

Parameters:

group - non-null group to be deleted.

opts - UpdateUserGroupOptions object describing optional parameters; if null, no options are set

Returns:

possibly-null status message string as returned from the server.

Throws:

P4JavaException - if any error occurs in the processing of this method.

getProtectionEntries

List<IProtectionEntry> getProtectionEntries(List<IFileSpec> fileList,
                                            GetProtectionEntriesOptions opts)
                                            throws P4JavaException

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 any annotations in the file paths will be ignored. The reason is the Perforce server 'protects' command requires a file list devoid of annotated revision specificity.

Parameters:

fileList - if non-null, only those protection entries that apply to the specified files are displayed.

opts - GetProtectionEntriesOptions object describing optional parameters; if null, no options are set.

Returns:

non-null but possibly empty list of protection entries.

Throws:

P4JavaException - if any error occurs in the processing of this method.

getClients

List<IClientSummary> getClients(GetClientsOptions opts)
                                throws P4JavaException

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:

opts - GetClientsOptions object describing optional parameters; if null, no options are set.

Returns:

non-null (but possibly empty) list of Client objects for Perforce clients known to this Perforce server.

Throws:

P4JavaException - if any error occurs in the processing of this method.

getLabels

List<ILabelSummary> getLabels(List<IFileSpec> fileList,
                              GetLabelsOptions opts)
                              throws P4JavaException

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:

fileList - if not null, limits its report to labels that contain those files

opts - GetLabelsOptions object describing optional parameters; if null, no options are set.

Returns:

non-null (but possibly-empty) list of qualifying Perforce labels

Throws:

P4JavaException - if any error occurs in the processing of this method.

deleteLabel

String deleteLabel(String labelName,
                   DeleteLabelOptions opts)
                   throws P4JavaException

Delete a named Perforce label from the Perforce server.

Parameters:

labelName - non-null label name

opts - DeleteLabelOptions object describing optional parameters; if null, no options are set.

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:

P4JavaException - if any error occurs in the processing of this method.

tagFiles

List<IFileSpec> tagFiles(List<IFileSpec> fileSpecs,
                         String labelName,
                         TagFilesOptions opts)
                         throws P4JavaException

Parameters:

fileSpecs - non-null list of files to be tagged.

labelName - non-null label name to use for the tagging.

opts - TagFilesOptions object describing optional parameters; if null, no options are set.

Returns:

a non-null (but possibly empty) list of affected file specs.

Throws:

P4JavaException - if any error occurs in the processing of this method.

getBranchSpecs

List<IBranchSpecSummary> getBranchSpecs(GetBranchSpecsOptions opts)
                                        throws P4JavaException

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:

GetBranchSpecsOptions - object describing optional parameters; if null, no options are set.

Returns:

non-null (but possibly-empty) list of IBranchSpecSummary objects.

Throws:

P4JavaException - if any error occurs in the processing of this method.

deleteBranchSpec

String deleteBranchSpec(String branchSpecName,
                        DeleteBranchSpecOptions opts)
                        throws P4JavaException

Delete a named Perforce branch spec from the Perforce server.

Parameters:

branchSpecName - non-null name of the branch spec to be deleted.

opts - DeleteBranchSpecOptions object describing optional parameters; if null, no options are set.

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:

P4JavaException - if any error occurs in the processing of this method.

getClientTemplate

IClient getClientTemplate(String clientName,
                          GetClientTemplateOptions opts)
                          throws P4JavaException

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.

opts - GetClientTemplateOptions object describing optional parameters; if null, no options are set.

Returns:

IClient representing the specified Perforce client template, or null if no such client template.

Throws:

P4JavaException - if any error occurs in the processing of this method.

deleteClient

String deleteClient(String clientName,
                    DeleteClientOptions opts)
                    throws P4JavaException

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 server object's current client.

Parameters:

clientName - non-null name of the client to be deleted from the server.

opts - DeleteClientOptions object describing optional parameters; if null, no options are set.

Returns:

possibly-null operation result message string from the Perforce server.

Throws:

P4JavaException - if any error occurs in the processing of this method.

getFileAnnotations

List<IFileAnnotation> getFileAnnotations(List<IFileSpec> fileSpecs,
                                         GetFileAnnotationsOptions opts)
                                         throws P4JavaException

Get a list of revision annotations for the specified files.

Parameters:

fileSpecs - non-null list of file specs to be annotated.

opts - GetFileAnnotationsOptions object describing optional parameters; if null, no options are set.

Returns:

non-null (but possibly-empty) list of IFileAnnotation objects representing version annotations for the passed-in file specs.

Throws:

P4JavaException - if any error occurs in the processing of this method.

moveFile

List<IFileSpec> moveFile(IFileSpec fromFile,
                         IFileSpec toFile,
                         MoveFileOptions opts)
                         throws P4JavaException

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.

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:

fromFile - the original file; must be already open for edit.

toFile - the target file.

opts - MoveFileOptions object describing optional parameters; if null, no options are set.

Returns:

list of IFileSpec objects representing the results of this move.

Throws:

P4JavaException - if any error occurs in the processing of this method.

getDirectories

List<IFileSpec> getDirectories(List<IFileSpec> fileSpecs,
                               GetDirectoriesOptions opts)
                               throws P4JavaException

List any directories matching the passed-in file specifications.

Parameters:

fileSpecs - non-null list of file specifications.

opts - GetDirectoriesOptions object describing optional parameters; if null, no options are set.

Returns:

non-null but possibly empty list of qualifying directory file specs; only the getPath() path will be valid.

Throws:

P4JavaException - if any error occurs in the processing of this method.

getChangelists

List<IChangelistSummary> getChangelists(List<IFileSpec> fileSpecs,
                                        GetChangelistsOptions opts)
                                        throws P4JavaException

Get a list of Perforce changelist summary objects from the Perforce server.

Parameters:

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

opts - GetChangelistsOptions object describing optional parameters; if null, no options are set.

Returns:

a non-null (but possibly empty) list of qualifying changelists.

Throws:

P4JavaException - if any error occurs in the processing of this method

getChangelistDiffs

InputStream getChangelistDiffs(int id,
                               GetChangelistDiffsOptions opts)
                               throws P4JavaException

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.

opts - GetChangelistDiffsOptions object describing optional parameters; if null, no options are set.

Returns:

InputStream onto the diff stream. Note that while this stream will not be null, it may be empty.

Throws:

P4JavaException - if any error occurs in the processing of this method.

getFileContents

InputStream getFileContents(List<IFileSpec> fileSpecs,
                            GetFileContentsOptions opts)
                            throws P4JavaException

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.

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:

fileSpecs - non-null list of depot or client file specs defining files to be streamed

opts - GetFileContentsOptions object describing optional parameters; if null, no options are set.

Returns:

a non-null but possibly-empty InputStream onto the file / revision contents.

Throws:

P4JavaException - if any error occurs in the processing of this method.

getRevisionHistory

Map<IFileSpec,List<IFileRevisionData>> getRevisionHistory(List<IFileSpec> fileSpecs,
                                                          GetRevisionHistoryOptions opts)
                                                          throws P4JavaException

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

Parameters:

fileSpecs - filespecs to be processed; if null or empty, an empty Map is returned.

opts - GetRevisionHistoryOptions object describing optional parameters; if null, no options are set.

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:

P4JavaException - if any error occurs in the processing of this method.

getReviews

List<IUserSummary> getReviews(List<IFileSpec> fileSpecs,
                              GetReviewsOptions opts)
                              throws P4JavaException

Get a list of all users who have subscribed to review the named files. Note that the returned IUserSummary objects will have null access and update dates associated with them.

Parameters:

fileSpecs - if not null, use this list as the list of named files rather than all files.

opts - GetReviewsOptions object describing optional parameters; if null, no options are set.

Returns:

non-null but possibly empty list of IUserSummary objects; note that these objects will have null update and access fields.

Throws:

P4JavaException - if any error occurs in the processing of this method.

getOpenedFiles

List<IFileSpec> getOpenedFiles(List<IFileSpec> fileSpecs,
                               OpenedFilesOptions opts)
                               throws P4JavaException

If one or more Perforce file specs is passed-in, return the opened / locked status of each file (if known) within an IFileSpec object; otherwise return a list of all files known to be open for this Perforce client workspace.

Parameters:

fileSpecs - if non-empty, determine the status of the specified files; otherwise return all qualifying files known to be open

opts - possibly-null OpenedFilesOptions object object specifying method options.

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:

P4JavaException - if an error occurs processing this method and its parameters.

getExtendedFiles

List<IExtendedFileSpec> getExtendedFiles(List<IFileSpec> fileSpecs,
                                         GetExtendedFilesOptions opts)
                                         throws P4JavaException

Return a list of everything Perforce knows about a 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. 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).

opts - GetExtendedFilesOptions object describing optional parameters; if null, no options are set.

Returns:

non-null (but possibly empty) list of qualifying files and associated stat info.

Throws:

P4JavaException - if an error occurs processing this method and its parameters.

getSubmittedIntegrations

List<IFileSpec> getSubmittedIntegrations(List<IFileSpec> fileSpecs,
                                         GetSubmittedIntegrationsOptions opts)
                                         throws P4JavaException

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

Parameters:

fileSpecs - if null or omitted, all qualifying depot files are used.

opts - GetSubmittedIntegrations object describing optional parameters; if null, no options are set.

Returns:

a non-null but possibly empty list of IFileSpec representing qualifying integrations.

Throws:

P4JavaException - if an error occurs processing this method and its parameters.

getInterchanges

List<IChangelist> getInterchanges(IFileSpec fromFile,
                                  IFileSpec toFile,
                                  GetInterchangesOptions opts)
                                  throws P4JavaException

Parameters:

fromFile - non-null from-file specification.

toFile - non-null to-file specification.

opts - GetInterchangesOptions object describing optional parameters; if null, no options are set.

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:

P4JavaException - if an error occurs processing this method and its parameters.

getInterchanges

List<IChangelist> getInterchanges(String branchSpecName,
                                  List<IFileSpec> fromFileList,
                                  List<IFileSpec> toFileList,
                                  GetInterchangesOptions opts)
                                  throws P4JavaException

Parameters:

branchSpecName - non-null, non-empty branch spec name.

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

opts - GetInterchangesOptions object describing optional parameters; if null, no options are set.

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:

P4JavaException - if an error occurs processing this method and its parameters.

getJobs

List<IJob> getJobs(List<IFileSpec> fileSpecs,
                   GetJobsOptions opts)
                   throws P4JavaException

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

opts - GetJobsOptions object describing optional parameters; if null, no options are set.

Returns:

a non-null (but possibly-empty) list of qualifying Perforce jobs.

Throws:

P4JavaException - if an error occurs processing this method and its parameters.

fixJobs

List<IFix> fixJobs(List<String> jobIds,
                   int changelistId,
                   FixJobsOptions opts)
                   throws P4JavaException

Mark each named job as being fixed by the changelist number given with changeListId.

Parameters:

jobIdList - non-null non-empty list of affected job IDs.

changelistId - changelist ID for affected changelist.

opts - FixJobsOptions object describing optional parameters; if null, no options are set.

Returns:

list of affected fixes.

Throws:

P4JavaException - if an error occurs processing this method and its parameters.

getFileDiffsStream

InputStream getFileDiffsStream(IFileSpec file1,
                               IFileSpec file2,
                               String branchSpecName,
                               GetFileDiffsOptions opts)
                               throws P4JavaException

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.

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:

optional - first file IFileSpec

file2 - optional second file IFileSpec

branchSpecName - optional branch spec name

opts - GetFileDiffsOptions object describing optional parameters; if null, no options are set.

Returns:

non-null but possibly empty InputStream of diffs and headers as returned from the server.

Throws:

P4JavaException - if an error occurs processing this method and its parameters.

getFileDiffs

List<IFileDiff> getFileDiffs(IFileSpec file1,
                             IFileSpec file2,
                             String branchSpecName,
                             GetFileDiffsOptions opts)
                             throws P4JavaException

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.

Parameters:

optional - first file IFileSpec

file2 - optional second file IFileSpec

branchSpecName - optional branch spec name

opts - GetFileDiffsOptions object describing optional parameters; if null, no options are set.

Returns:

non-null but possibly empty array of file diffs

Throws:

P4JavaException - if an error occurs processing this method and its parameters.

setCounter

String setCounter(String counterName,
                  String value,
                  CounterOptions opts)
                  throws P4JavaException

Create, set or delete a counter on a Perforce server. This method can be used to create, set, increment, or delete a counter according to the specific options set in the associated options object. Note that the increment operation does not work on servers earlier than 10.1, and that the return value is never guaranteed to be non-null -- use with caution.

Parameters:

counterName - non-null counter name.

value - value the counter should be set to; can be null if the set operation is an increment.

opts - CounterOptions object describing optional parameters; if null, no options are set.

Returns:

possibly-null current (post-set, post-increment) value; may be zero if the operation was a delete; may not be reliable for pre 10.1 servers.

Throws:

P4JavaException - if an error occurs processing this method and its parameters.

getExportRecords

List<Map<String,Object>> getExportRecords(ExportRecordsOptions opts)
                                          throws P4JavaException

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:

opts - ExportRecordsOptions object describing optional parameters; if null, no options are set.

Returns:

non-null but possibly empty list of maps representing exported journal or checkpoint records.

Throws:

P4JavaException - if an error occurs processing this method and its parameters.

setFileAttributes

List<IFileSpec> setFileAttributes(List<IFileSpec> files,
                                  Map<String,String> attributes,
                                  SetFileAttributesOptions opts)
                                  throws P4JavaException

Set file attributes on one or more files (unsupported). See the main Perforce documentation for an explanation of file attributes, which are potentially complex and difficult to use efficiently. Attributes can currently only be retrieved using the getExtendedFiles (fstat) operation.

Note that this method only accepts String attribute values; if the attribute is intended to be binary, use the setHexValue setter on the associated SetFileAttributesOptions object and hexify the value, or, alternatively, use the stream version of this method. String input this way will be converted to bytes for the attributes before being sent to the Perforce server using the prevailing character set. If this is a problem, use hex encoding or the stream variant of this method

Note that attributes can only be removed from a file by setting the appropriate value of the name / value pair passed-in through the attributes map to null.

Note that the filespecs returned by this method, if valid, contain only the depot path and version information; no other field can be assumed to be valid. Note also that, while the p4 command line executable returns a list of results that amounts to the cross product of files and attributes, this method never returns more than one result for each file affected.

Parameters:

opts - SetFileAttributesOptions object describing optional parameters; if null, no options are set.

attributes - a non-null Map of attribute name / value pairs; if any value is null, that attribute is removed.

files - non-null list of files to be affected

Returns:

non-null but possibly empty list of filespec results for the operation.

Throws:

P4JavaException - if an error occurs processing this method and its parameters.

Since:

2011.1

setFileAttributes

List<IFileSpec> setFileAttributes(List<IFileSpec> files,
                                  String attributeName,
                                  InputStream inStream,
                                  SetFileAttributesOptions opts)
                                  throws P4JavaException

Set a file attribute on one or more files using the passed-in input stream as the source for the attribute's value (unsupported). See the main Perforce documentation for an explanation of file attributes, which are potentially complex and difficult to use efficiently. Attributes can currently only be retrieved using the getExtendedFiles (fstat) operation.

This method is intended to allow for unmediated binary definitions of file attribute contents, and is typically used for things like thumbnails that are too big to be conveniently handled using hex conversion with the strings-based version of this method. Absolutely no interpretation is done on the stream -- it's bytes all the way... there is also no hard limit to the size of the stream that contains the attribute value, but the consequences on both the enclosing app and the associated Perforce server of too-large attributes may be severe. Typical 8K thumbnails are no problem at all, but something in the megabyte range or larger might be problematic at both ends.

Note that this method will leave the passed-in stream open, but (in general) the stream's read pointer will be at the end of the stream when this method returns. You are responsible for closing the stream if necessary after the call; you are also responsible for ensuring that the read pointer is where you want it to be in the stream (i.e. where you want the method to start reading the attribute value from) when you pass in the stream. I/O errors while reading the stream will be logged, but otherwise generally ignored -- you must check the actual results of this operation yourself.

Note that the server currently only supports setting file attributes using a stream for one filespec at a time, but for reasons of symmetry you must pass in a list of (one) filespec. Note that this doesn't necessarily mean only one file is affected in the depot, just that only one file spec is used to specify the affected file(s).

Note that attributes can only be removed from a file by setting the appropriate value of the name / value pair passed-in through the attributes map to null.

Note that the filespecs returned by this method, if valid, contain only the depot path and version information; no other field can be assumed to be valid. Note also that, while the p4 command line executable returns a list of results that amounts to the cross product of files and attributes, this method never returns more than one result for each file affected.

Parameters:

opts - SetFileAttributesOptions object describing optional parameters; if null, no options are set.

attributeName - the non-null name of the attribute to be set.

inStream - non-null InputStream ready for reading the attribute value from.

files - non-null list of files to be affected.

Returns:

non-null but possibly empty list of filespec results for the operation.

Throws:

P4JavaException - if an error occurs processing this method and its parameters.

Since:

2011.1

showServerConfiguration

List<ServerConfigurationValue> showServerConfiguration(String serverName,
                                                       String variableName)
                                                       throws P4JavaException

Show server configuration values. See the main Perforce documentation for the details of this admin command, but note that only one of serverName or variableName should be non-null (they can both be null, which means ignore them both). If they're both null, serverName currently takes precedence, but that's not guaranteed.

Note: you must be an admin or super user for this command to work.

Parameters:

serverName - if not null, only show values associated with the named server; if equals ServerConfigurationValue.ALL_SERVERS, show values associated with all participating servers.

variableName - if not null, only show the value of this named config variable.

Returns:

non-null (but possibly-empty) list of qualifying ServerConfigurationValue objects.

Throws:

P4JavaException - if an error occurs processing this method and its parameters.

Since:

2011.1

setServerConfigurationValue

String setServerConfigurationValue(String name,
                                   String value)
                                   throws P4JavaException

Set or unset a specific names server configuration variable. Config variables are unset by passing in a null value parameter.

Expected variable name formats are as specified in the main Perforce documentation: [servername + #] variablename -- but this is not enforced by P4Java itself.

Note: you must be an admin or super user for this command to work.

Parameters:

name - non-null config variable name.

value - if null, unset the named variable; otherwise, set it to the passed-in string value.

Returns:

possibly-null operation status string returned by the server in response to this set / unset attempt.

Throws:

P4JavaException - if an error occurs processing this method and its parameters.

Since:

2011.1