public interface IProgressCallback
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.
Modifier and Type | Method and Description |
---|---|
void |
start(int key)
A new tick sequence has begun.
|
void |
stop(int key)
The current tick sequence has finished.
|
boolean |
tick(int key,
java.lang.String tickMarker)
Signal the completion of a significant event, and poll the callback for
whether to continue the command.
|
void start(int key)
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.
key
- -- opaque integer key for correlation with subsidiary calls.boolean tick(int key, java.lang.String tickMarker)
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.
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.void stop(int key)
key
- -- opaque integer key as given by the associated start call.