Qortal/altcoinj
3
0
Fork 0
mirror of https://github.com/Qortal/altcoinj.git synced 2025-01-31 07:12:17 +00:00
Code Issues Projects Releases Wiki Activity

Add some comments for stateless protocols.

Browse Source
This commit is contained in:
Matt Corallo 2013-07-24 20:15:56 +02:00 committed by Mike Hearn
parent 868493f2d1
commit df47993e3d
1 changed files with 11 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
core/src/main/java/com/google/bitcoin/protocols/channels/PaymentChannelClient.java
View File

@ -23,9 +23,13 @@ import static com.google.common.base.Preconditions.checkState;
* <p>Does all required verification of server messages and properly stores state objects in the wallet-attached
* {@link StoredPaymentChannelClientStates} so that they are automatically closed when necessary and refund
* transactions are not lost if the application crashes before it unlocks.</p>
*
* <p>Though this interface is largely designed with stateful protocols (eg simple TCP connections) in mind, it is also
* possible to use it with stateless protocols (eg sending protobufs when required over HTTP headers). In this case, the
* "connection" translates roughly into the server-client relationship. See the javadocs for specific functions for more
* details.</p>
*/
public class PaymentChannelClient {
//TODO: Update JavaDocs with notes for communication over stateless protocols
private static final org.slf4j.Logger log = LoggerFactory.getLogger(PaymentChannelClient.class);
protected final ReentrantLock lock = Threading.lock("channelclient");
@ -51,7 +55,9 @@ public class PaymentChannelClient {
public void sendToServer(Protos.TwoWayChannelMessage msg);
/**
* <p>Requests that the connection to the server be closed</p>
* <p>Requests that the connection to the server be closed. For stateless protocols, note that after this call,
* no more messages should be received from the server and this object is no longer usable. A
* {@link PaymentChannelClient#connectionClosed()} event should be generated immediately after this call.</p>
*
* <p>Called while holding a lock on the {@link PaymentChannelClient} object - be careful about reentrancy</p>
*
@ -294,6 +300,9 @@ public class PaymentChannelClient {
* <p>Called when the connection terminates. Notifies the {@link StoredClientChannel} object that we can attempt to
* resume this channel in the future and stops generating messages for the server.</p>
*
* <p>For stateless protocols, this translates to a client not using the channel for the immediate future, but
* intending to reopen the channel later. There is likely little reason to use this in a stateless protocol.</p>
*
* <p>Note that this <b>MUST</b> still be called even after either
* {@link ClientConnection#destroyConnection(CloseReason)} or
* {@link PaymentChannelClient#close()} is called to actually handle the connection close logic.</p>