Class DittoPresence

java.lang.Object

com.ditto.java.DittoPresence

public final class DittoPresence
extends Object

The entrypoint for all actions that relate to presence of other peers known by the current peer, either directly or through other peers. You don't create one directly but can access it via the Ditto.getPresence() getter.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	DittoPresence.ConnectionRequestHandler	Handler interface for controlling incoming connection requests.
static interface	DittoPresence.PresenceGraphChangedListener	Listener interface for receiving presence graph updates.

Method Summary

Modifier and Type	Method	Description
@Nullable DittoPresence.ConnectionRequestHandler	getConnectionRequestHandler()	Returns the handler that controls which peers in a Ditto mesh can connect to the current peer.
@NonNull DittoPresenceGraph	getGraph()	Returns the latest snapshot of information about peers in the Ditto mesh network.
@NonNull DittoJsonSerializable.ObjectValue	getPeerMetadata()	Returns metadata associated with the current peer.
@NonNull String	getPeerMetadataJsonString()	Returns metadata associated with the current peer as a JSON string.
@NonNull Flow.Publisher<@NonNull DittoPresenceGraph>	observe()	Returns a Flow Publisher that emits presence graph updates.
DittoAsyncCancellable	observe(@NonNull DittoPresence.PresenceGraphChangedListener listener)	Requests information about Ditto peers in the local peer-to-peer network.
void	setConnectionRequestHandler(@Nullable DittoPresence.ConnectionRequestHandler connectionRequestHandler)	Sets a handler to control which peers in a Ditto mesh can connect to the current peer.
void	setPeerMetadata(@NonNull DittoJsonSerializable.ObjectValue peerMetadata)	Sets metadata to be associated with the current peer.
void	setPeerMetadataJsonString(@NonNull String peerMetadataJsonString)	Sets metadata to be associated with the current peer from a JSON string.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

getGraph

public @NonNull DittoPresenceGraph getGraph()

Returns the latest snapshot of information about peers in the Ditto mesh network.

Returns:

a DittoPresenceGraph representing the current state of the mesh network.

getPeerMetadata

public @NonNull DittoJsonSerializable.ObjectValue getPeerMetadata()

Returns metadata associated with the current peer. Other peers in the same mesh can access this user-provided map of metadata via the presence graph at getGraph() and when evaluating connection requests using getConnectionRequestHandler(). Use setPeerMetadata(DittoJsonSerializable.ObjectValue) or setPeerMetadataJsonString(String) to set this value. This is a convenience property that wraps getPeerMetadataJsonString().

Returns:

a DittoJsonSerializable.ObjectValue containing the peer metadata.

See Also:

• setPeerMetadata(DittoJsonSerializable.ObjectValue)

setPeerMetadata

public void setPeerMetadata(@NonNull DittoJsonSerializable.ObjectValue peerMetadata)

Sets metadata to be associated with the current peer.

Parameters:

peerMetadata - a DittoJsonSerializable.ObjectValue containing the metadata to set.

See Also:

• getPeerMetadata()

getPeerMetadataJsonString

public @NonNull String getPeerMetadataJsonString()

Returns metadata associated with the current peer as a JSON string. Other peers in the same mesh can access this user-provided map of metadata via the presence graph at getGraph() and when evaluating connection requests using getConnectionRequestHandler(). Use setPeerMetadataJsonString(String) or setPeerMetadata(DittoJsonSerializable.ObjectValue) to set this value.

Returns:

a JSON string containing the peer metadata.

See Also:

• setPeerMetadataJsonString(String)

setPeerMetadataJsonString

public void setPeerMetadataJsonString(@NonNull String peerMetadataJsonString)

Sets metadata to be associated with the current peer from a JSON string.

Parameters:

peerMetadataJsonString - a JSON string containing the metadata to set.

See Also:

• getPeerMetadataJsonString()

getConnectionRequestHandler

public @Nullable DittoPresence.ConnectionRequestHandler getConnectionRequestHandler()

Returns the handler that controls which peers in a Ditto mesh can connect to the current peer. Each peer in a Ditto mesh will attempt to connect to other peers that it can reach. By default, the mesh will try and establish connections that optimize for the best overall connectivity between peers. However, you can set this handler to assert some control over which peers you connect to. If set, this handler is called for every incoming connection request from a remote peer and is passed the other peer's DittoPeer.getPeerKey(), getPeerMetadata(), and DittoConnectionRequest.getIdentityServiceMetadata(). The handler can then accept or reject the request by returning a DittoConnectionRequestAuthorization value. When the connection request is rejected, the remote peer may retry the connection request after a short delay. Connection request handlers must reliably respond to requests within a short time. If a handler takes too long to respond or throws an exception, the connection request will be denied. The response timeout is currently 10 seconds but may be subject to change in future releases.

Returns:

the current DittoPresence.ConnectionRequestHandler, or null if not set.

See Also:

• setConnectionRequestHandler(ConnectionRequestHandler)
• getPeerMetadata()

Implementation Note:

The handler is called from a different thread.

setConnectionRequestHandler

public void setConnectionRequestHandler(@Nullable DittoPresence.ConnectionRequestHandler connectionRequestHandler)

Sets a handler to control which peers in a Ditto mesh can connect to the current peer.

Parameters:

connectionRequestHandler - the DittoPresence.ConnectionRequestHandler to use, or null to remove the handler.

See Also:

• getConnectionRequestHandler()

observe

public @NonNull Flow.Publisher<@NonNull DittoPresenceGraph> observe()

Returns a Flow Publisher that emits presence graph updates.

Returns:

a Flow.Publisher that emits DittoPresenceGraph instances when the mesh changes.

See Also:

• observe(PresenceGraphChangedListener)

observe

public DittoAsyncCancellable observe(@NonNull DittoPresence.PresenceGraphChangedListener listener)

Requests information about Ditto peers in the local peer-to-peer network. This method returns an observer which will invoke the DittoPresence.PresenceGraphChangedListener.onGraphChanged(com.ditto.java.DittoPresenceGraph) method on the provided callback object for each update. A newly registered observer will have an update delivered to it immediately. Then it will be invoked repeatedly when new information is learned about Ditto peers or their connections in the local peer-to-peer network. When the observer is no longer required the caller must call close() on the returned DittoAsyncCancellable.

Parameters:

listener - an object that implements the DittoPresence.PresenceGraphChangedListener interface, whose DittoPresence.PresenceGraphChangedListener.onGraphChanged(com.ditto.java.DittoPresenceGraph) method will be called when there is an update.

Returns:

a DittoAsyncCancellable that can be used to stop observing.