com.perforce.p4java.server.callback
Interface IProgressCallback

public interface IProgressCallback

Provides a simple server command and command progress callback and control interface for P4Java consumers.

The intention here is to provide consumers with a very simple way to measure command progress and to stop a command mid-stream. The underlying P4Java transport mechanism calls the tick() callback every time a "significant" part of a command is finished, and the callback return value determines whether the command should continue normally or be terminated cleanly ASAP.

In context, the significant event is almost always the start of processing for the next file spec to be processed (in a sync, a long-running files or fstat command, a submit, etc), and the tick marker, if it's not null, will almost always be the full client or depot path of the file about to be processed, or the job or changelist about to be processed, etc. Note that only a few commands can get the file path back in the payload, so you cannot rely on it being non-null; however, if it's not null, it's likely to be of interest to the end-user.

This scheme means the consumer should have some basic idea of the likely order of magnitude of the number of ticks that will be generated, and to be able to generate a suitable visual progress bar or popup using this information.

This callback scheme is only properly implemented in the RPC protocol version of P4Java, and only commands likely to be long-running and / or "interesting" currently participate in this scheme; these are typically commands like submit, sync, files, and fstat, but no guarantee is given yet for any particular command.

NOTE: under error conditions it is not guaranteed that the stop() method will be called; consumers should clear the callback's state manually under these conditions.

NOTE: you must ensure that there are no threading or reentrancy issues with your implementation of this interface, and that calling any of the methods here will not cause the caller (P4Java) to block or spend too much time processing the callback. The callback is called in the middle of Perforce client / server communications in the thread context of the protocol handler, and any significant delay here may cause serious performance issues or even botched commands.

start

void start(int key)

A new tick sequence has begun. Always issued at the start of a new user-issued command. The integer key passed into this method should be used as an opaque key for associated tick and stop events; it is guaranteed to have the same value as used with command callbacks (see ICommandCallback) for the same command if command callbacks are enabled (this allows consumers to correlate progress and results by key matching).

In any case, whether command callbacks are enabled or not, this key will be unique across all calls (simultaneous or otherwise) to a given IServer, but is not guaranteed to be unique across an entire P4Java instance.

Parameters:

key - -- opaque integer key for correlation with subsidiary calls.

tick

boolean tick(int key,
             String tickMarker)

Signal the completion of a significant event, and poll the callback for whether to continue the command. If this callback returns false, the underlying protocol will do its best to stop the current command dead in its tracks and clean up.

Note that command cancellation done through this tick method is not guaranteed to have any effect at all, nor are the side-effects of such a cancellation necessarily predictable or safe. In general the default RPC implementation attempts to do a reasonable job of things, but the command-line and RPC-NTS implementations ignore any cancel notices completely.

Note also that command cancellation does not work for connection delays; current implementations force users to wait for connection timeouts. This will probably change in future releases.

Parameters:

key - -- opaque integer key as given by the associated start call.

tickMarker - possibly-interesting possibly non-null tick payload; if not null, will normally be something meaningful to the consumer like a file path (depot or client), or a job ID, or a changelist ID, etc.

Returns:

true if you want the command to continue; false otherwise.

stop

void stop(int key)

The current tick sequence has finished. Usually issued when the user command has completed. Not guaranteed to be delivered when an error has occurred in the command processing.

Parameters:

key - -- opaque integer key as given by the associated start call.