public interface IStreamingCallback
Users must implement this interface if they're using the streaming command interface, but little or no restrictions are placed on implementations beyond noting that the callbacks occur during critical sections of the underlying RPC protocol handlers and that callback implementers should ensure that the callback methods return as quickly as possible and that they do not themselves call back into the server layer.
Note that the ability to have the command stopped as a result of a callback returning false is mentioned but not promised -- the RPC layer may continue calling the callbacks (or not), or it may stop calling the callbacks (or not); and in any case, it may still continue to field results from the Perforce server even though it is no longer calling the relevant callback. The reasons for this are mostly due to the protocol itself, and users should write their callbacks accordingly and robustly. In pathological cases it is even possible that a callback's endResults method is never called, so implementers need to also plan for that.
If any of the callback methods throw a P4JavaException the system will rethrow the same exception from the main streaming command method after attempting to clean up; similarly with P4JavaErrors. In either case, while the main method has returned and no more results are available, the state of the underlying protocol layers is not defined, and you should proceed carefully from that point on (in the case of 'ordinary' P4JavaExceptions, the underlying state is actually typically stable and OK for continuing on, with a possible delay due to non-terminated results still being sent to the API; however, all bets are off with the P4JavaError case).
NOTE: 'streaming' here has nothing at all to do with Perforce 'streams', which are (or will be) implemented elsewhere.
| Modifier and Type | Method and Description |
|---|---|
boolean |
endResults(int key)
When called, this signals to the consumer that a command has been
completed at the Perforce server, and that no more results will be available
from the associated command.
|
boolean |
handleResult(java.util.Map<java.lang.String,java.lang.Object> resultMap,
int key)
When called, this method signals to the consumer that an individual result
or error / warning / info message is available in map form from the Perforce
server.
|
boolean |
startResults(int key)
When called, this signals to the consumer that a command has been
issued to the Perforce server.
|
boolean startResults(int key)
throws P4JavaException
key - opaque integer key as passed to the associated streaming method.P4JavaException - if any problem that should stop normal command processing.boolean endResults(int key)
throws P4JavaException
key - opaque integer key as passed to the associated streaming method.P4JavaException - if any problem that should stop normal command processing.boolean handleResult(java.util.Map<java.lang.String,java.lang.Object> resultMap,
int key)
throws P4JavaException
Consumers are assumed to be able to make sense of (i.e. deserialize) the map payload quickly and on their own -- no help is (currently...) given to consumers with this, although there are many suitable map-based constructors available for the common object types within the P4Java impl packages.
NOTE: this method is called in a critical section of the underlying P4Java client / server protocol handler, and must not cause any undue delays or calls back into the server. Serious protocol-level errors and / or major performance problems can result from even minor implementation errors with this method (and these problems can be extremely difficult to debug), so you are on your own if you use this streaming feature.
resultMap - non-null map of results from the server. The map may represent
a single result from the server, or a single status (error / info, etc.)
message either from the server or from the lower levels of the P4Java
implementation. This means there may be more than one class to handleResult
for each 'result' -- consumers must be able to cope with this.key - opaque integer key as passed to the associated streaming method.P4JavaException - if any problem that should stop normal command processing.