com.aquafold.openapi.vcs
Interface AQPerforce

All Superinterfaces:

Closeable

public interface AQPerforce
extends Closeable

An interface to Perforce revision control system.

Method Summary

void	add(Object files) Open one or more Perforce client workspace files for adding to the Perforce server.
void	close() Disconnects the object from Perforce server.
void	connect(String url, String client, String folder, Object username, Object password) Establishes connection to the perforce server.
void	connect(String url, String client, String folder, Object username, Object password, String charset) Establishes connection to the perforce server.
List<IFileSpec>	deleteFiles(Object files, int changeListId, boolean noUpdate) Open a Perforce client workspace file(s) for deletion from a Perforce depot.
void	edit(Object files) Open one or more Perforce client workspace files for editing.
IClient	getClient(String name) 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.
List<IFileSpec>	getDepotFiles(Object files, 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>	getDiffFiles(Object files, boolean diffNonTextFiles, boolean openedDifferentMissing, boolean openedForIntegrate, boolean unopenedMissing, boolean unopenedDifferent, boolean unopenedWithStatus, boolean openedSame) Return a list of files that differ in some (arbitrarily complex) way from depot.
String[]	getDirectories(Object files, boolean clientOnly, boolean deletedOnly, boolean haveListOnly) List any directories matching the passed-in file specifications.
AQRevision[]	getHistory(String filename) Returns the file's complete revision history.
AQRevision[]	getHistory(String filename, int count) Returns the file's revision history.
AQRevision	getRevision(String filename) Returns the file revision.
byte[]	getRevisionContents(String filename, String revision) Returns the binary contents of the specified revision.
IServerInfo	getServerInfo() Returns a snapshot set of data on the Perforce server associated with this server interface.
IUser	getUser(String name) 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) Get a list of Perforce user groups from the server.
List<IUserSummary>	getUsers() Get a list of Perforce users known to this Perforce server.
List<IFileSpec>	haveList(Object files) Return a list of all Perforce-managed files and versions that the Perforce server believes this Perforce client workspace has as of the latest sync.
List<IFileSpec>	lockFiles(Object files, int changeListId) Lock an opened file against changelist submission.
List<IFileSpec>	moveFile(int changelistId, boolean listOnly, boolean noClientMove, String fileType, String fromFile, String toFile) Move a file already opened for edit or add (the fromFile) to the destination file (the toFile).
void	revert(Object files) Revert an open Perforce client workspace file back to the revision previously synced from the Perforce depot, discarding any pending changelists or integrations that have been made so far.
void	setVerbose(boolean verbose) Sets the amount of diagnostic messages sent to the debugger console.
void	submit(Object files, String comment) This method submits changes in the specified file(s) or folder(s) to the Perforce revision control system.
void	sync(Object files) This method syncs the local filesystem with the latest Perforce revision.
List<IFileSpec>	unlockFiles(Object files, int changeListId, boolean force) Release locked files but leave them open.

Method Detail

setVerbose

void setVerbose(boolean verbose)

Sets the amount of diagnostic messages sent to the debugger console.

Parameters:

verbose - (Default value - true).

connect

void connect(String url,
             String client,
             String folder,
             Object username,
             Object password)
             throws Exception

Establishes connection to the perforce server. This method must be called prior to any file operation.

Parameters:

url - Server URL string.

client - Perforce workspace client name.

folder - Filesystem folder under Perforce revision control.

username - A String or a AQOpaqueObject containing the user name.

password - A String password or a AQOpaqueObject containing the password.

Throws:

Exception

connect

void connect(String url,
             String client,
             String folder,
             Object username,
             Object password,
             String charset)
             throws Exception

Establishes connection to the perforce server. This method must be called prior to any file operation.

Parameters:

url - Server URL string.

client - Perforce workspace client name.

folder - Filesystem folder under Perforce revision control.

username - A String or a AQOpaqueObject containing the user name.

password - A String password or a AQOpaqueObject containing the password.

charset - A String or a AQOpaqueObject containing the charset.

Throws:

Exception

close

void close()
           throws IOException

Disconnects the object from Perforce server. Does nothing if the object is not connected or is already disconnected.

Specified by:

close in interface Closeable

Throws:

IOException

submit

void submit(Object files,
            String comment)
            throws Exception

This method submits changes in the specified file(s) or folder(s) to the Perforce revision control system.

Parameters:

files - A file name, or a javascript array of file names.

comment -

Throws:

Exception

sync

void sync(Object files)
          throws Exception

This method syncs the local filesystem with the latest Perforce revision.

Parameters:

files - A file name, or a javascript array of file names.

Throws:

Exception

edit

void edit(Object files)
          throws Exception

Open one or more Perforce client workspace files for editing.

Parameters:

files - A file name, or a javascript array of file names.

Throws:

Exception

add

void add(Object files)
         throws Exception

Open one or more Perforce client workspace files for adding to the Perforce server.

Parameters:

files - A file name, or a javascript array of file names.

Throws:

Exception

revert

void revert(Object files)
            throws Exception

Revert an open Perforce client workspace file back to the revision previously synced from the Perforce depot, discarding any pending changelists or integrations that have been made so far.

Parameters:

files - A file name, or a javascript array of file names.

Throws:

Exception

getRevision

AQRevision getRevision(String filename)
                       throws Exception

Returns the file revision.

Parameters:

filename - Workspace file name.

Throws:

Exception

getHistory

AQRevision[] getHistory(String filename)
                        throws Exception

Returns the file's complete revision history.

Parameters:

filename - Workspace file name.

Throws:

Exception

getHistory

AQRevision[] getHistory(String filename,
                        int count)
                        throws Exception

Returns the file's revision history.

Parameters:

filename - Workspace file name.

count - Maximum number of revisions to return.

Throws:

Exception

getRevisionContents

byte[] getRevisionContents(String filename,
                           String revision)
                           throws Exception

Returns the binary contents of the specified revision.

Parameters:

filename - Workspace file name.

revision - Revision number or "head" for head revision or "have" for have revision.

Throws:

Exception

deleteFiles

List<IFileSpec> deleteFiles(Object files,
                            int changeListId,
                            boolean noUpdate)
                            throws Exception

Open a Perforce client workspace file(s) for deletion from a Perforce depot.

Parameters:

files - A file name, or a javascript array of file names.

changeListId - If positive, the opened files are put into the pending changelist identified by changeListId; this changelist must have been previously created. If zero or negative, the file is opened in the 'default' (unnumbered) changelist.

noUpdate - If true, don't actually do the open, just return the files that would have been opened for deletion.

Returns:

A non-null but possibly-empty list of IFileSpec objects representing the opened files. Not all fields in these specs will be valid or set.

Throws:

Exception

moveFile

List<IFileSpec> moveFile(int changelistId,
                         boolean listOnly,
                         boolean noClientMove,
                         String fileType,
                         String fromFile,
                         String toFile)
                         throws Exception

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.

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:

Exception

lockFiles

List<IFileSpec> lockFiles(Object files,
                          int changeListId)
                          throws Exception

Lock an opened file against changelist submission.

The open files named are locked in the Perforce depot, preventing any user other than the current user on the current client from submitting changes to the files. If a file is already locked then the lock request is rejected. If no file specs are given then lock all files currently open in the changelist number given if it is IChangelist.DEFAULT or > 0.

Parameters:

files - A file name, or a javascript array of file names.

changeListId - If IChangelist.DEFAULT or larger than zero, lock all files associated this changelist ID.

Returns:

A non-null (but possibly empty) list of locked file specs or errors.

Throws:

Exception

unlockFiles

List<IFileSpec> unlockFiles(Object files,
                            int changeListId,
                            boolean force)
                            throws Exception

Release locked files but leave them open.

If the files are open in a specific pending changelist other than 'default', then the changeListId parameter is required to specify the pending changelist. If no file name is given then all files in the designated changelist are unlocked.

Parameters:

files - A file name, or a javascript array of file names.

changeListId - If IChangelist.DEFAULT or larger than zero, lock all files associated this changelist ID.

force - Force the lock on non-owned filespecs. Requires appropriate permissions.

Returns:

A non-null (but possibly empty) list of unlocked file specs or errors.

Throws:

Exception

getClients

List<IClientSummary> getClients(String userName,
                                String queryString,
                                int maxResults)
                                throws Exception

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

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:

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

Throws:

Exception

getClient

IClient getClient(String name)
                  throws Exception

Get an IClient object for a specific named Perforce client.

Parameters:

name - A non-null Perforce client name.

Returns:

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

Throws:

Exception

getUsers

List<IUserSummary> getUsers()
                            throws Exception

Get a list of Perforce users known to this Perforce server.

Returns:

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

Throws:

Exception

getUser

IUser getUser(String name)
              throws Exception

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

Parameters:

name - 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:

Exception

getDepots

List<IDepot> getDepots()
                       throws Exception

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

Returns:

A non-null (but possibly empty) list of non-null IDepot objects representing the underlying Perforce depots.

Throws:

Exception

getDiffFiles

List<IFileSpec> getDiffFiles(Object files,
                             boolean diffNonTextFiles,
                             boolean openedDifferentMissing,
                             boolean openedForIntegrate,
                             boolean unopenedMissing,
                             boolean unopenedDifferent,
                             boolean unopenedWithStatus,
                             boolean openedSame)
                             throws Exception

Return a list of files that differ in some (arbitrarily complex) way from depot. See the help documentation for the p4 diff command using the "-sx" (-sa, -sl, etc.) options for a full discussion of the options used below.

Parameters:

files - A file name, or a javascript array of file names.

diffNonTextFiles - Include non-text files in the diff lists.

openedDifferentMissing - Corresponds to the "-sa" option for the p4 command line.

openedForIntegrate - Corresponds to the "-sb" option for the p4 command line.

unopenedMissing - Corresponds to the "-sd" option for the p4 command line.

unopenedDifferent - Corresponds to the "-se" option for the p4 command line.

unopenedWithStatus - Corresponds to the "-sl" option for the p4 command line.

openedSame - Corresponds to the "-sr" option for the p4 command line.

Returns:

A non-null (but possibly empty) list of qualifying filepecs.

Throws:

Exception

getDirectories

String[] getDirectories(Object files,
                        boolean clientOnly,
                        boolean deletedOnly,
                        boolean haveListOnly)
                        throws Exception

List any directories matching the passed-in file specifications.

Parameters:

files - A file name, or a javascript array of file names.

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:

A non-null (but possibly empty) array of directory names.

Throws:

Exception

getDepotFiles

List<IFileSpec> getDepotFiles(Object files,
                              boolean allRevs)
                              throws Exception

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.

Parameters:

files - A file name, or a javascript array of file names.

allRevs - If true, list all revisions of qualifying files.

Returns:

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

Throws:

Exception

getUserGroup

IUserGroup getUserGroup(String name)
                        throws Exception

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 which make no sense, frankly).

Throws:

Exception

getUserGroups

List<IUserGroup> getUserGroups(String userOrGroupName,
                               boolean indirect,
                               boolean displayValues)
                               throws Exception

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.

Returns:

A non-zero but possibly-empty list of qualifying groups.

Throws:

Exception

haveList

List<IFileSpec> haveList(Object files)
                         throws Exception

Return a list of all Perforce-managed files and versions that the Perforce server believes this Perforce client workspace has as of the latest sync. If fileSpecs is given, this method returns, only information on those files is returned.

Parameters:

files - A file name, or a javascript array of file names.

Returns:

A non-null (but possibly empty) list of IFileSpec objects for the passed-in arguments. Only the depotFile, revision, clientPath, and localPath fields of the returned file specs are guaranteed to be valid.

Throws:

Exception

getServerInfo

IServerInfo getServerInfo()
                          throws Exception

Returns a snapshot set of data on the Perforce server associated with this server interface.

Throws:

Exception