The one shared file that waits for the user's receiver pick. More...

Collaboration diagram for de.yaacc.share.PendingShare:

Classes
class	Data
	What a pending share holds.

enum	Kind
	What the pending share is, set by whoever offered it (never guessed from the text). More...

Public Member Functions
	PendingShare (LongSupplier nowMillis, Consumer< byte[]> randomBytes, long timeoutMillis)

String	offer (String uri, String displayName, String mimeType)
	Makes a share pending, if none is.

synchronized String	offer (Kind kind, String uri, String displayName, String mimeType)
	Same as `offer(String, String, String)` with an explicit kind.

synchronized Data	take (String token)
	Hands the pending share out, once.

synchronized Data	peek (String token)
	Reads the pending share without consuming it (e.g.

synchronized boolean	cancel (String token)
	Releases the pending share.

synchronized boolean	isPending ()

Static Public Member Functions
static PendingShare	createDefault ()
	A holder on the monotonic system clock and a `SecureRandom` with the default timeout.

Static Public Attributes
static final long	DEFAULT_TIMEOUT_MILLIS = ShareLimits.PENDING_SHARE_TIMEOUT_MILLIS
	How long a share waits for the user's pick: two minutes.

Detailed Description

The one shared file that waits for the user's receiver pick.

Plain Java, thread-safe, no android.*.

Intake is untrusted (the launcher is exported), so a share that nobody confirmed holds nothing but text: the validated URI string, the cleaned display name and the declared MIME type. No descriptor, no copy and no registry slot exist until the user has picked receivers.

At most ONE share is pending. offer while one is pending and not expired is dropped (returns null, changes nothing, does not extend the timeout); it never replaces the pending one, so the user cannot confirm a different file than the one named in the picker.
The pending share expires timeout after it was offered: at exactly that moment it is gone (elapsed >= timeout; a clock that runs backwards counts as expired). After that a new share may be offered.
The pending action is bound to a random 128-bit token (32 hex chars) that offer returns. take, peek and cancel need it, so a stale, forged or second result for another sheet changes nothing.
take hands the data out exactly once and clears it.

The clock must be monotonic (the default uses System.nanoTime()); the random source is injectable for tests. toString() of Data does not show its content.

Constructor & Destructor Documentation

◆ PendingShare()

de.yaacc.share.PendingShare.PendingShare	(	LongSupplier	nowMillis,
		Consumer< byte[]>	randomBytes,
		long	timeoutMillis )

Parameters

nowMillis	a monotonic clock in milliseconds
randomBytes	fills the given array with random bytes (e.g. `secureRandom::nextBytes`)
timeoutMillis	how long a share waits for the pick, greater than zero

Exceptions

IllegalArgumentException if a source is null or the timeout is not positive

Referenced by de.yaacc.share.PendingShare.createDefault().

Here is the caller graph for this function:

Member Function Documentation

◆ cancel()

synchronized boolean de.yaacc.share.PendingShare.cancel ( String token )

Releases the pending share.

Returns: true if the token matched and the pending share was released; false (and nothing changes) for a wrong, null, consumed or already released token

Referenced by de.yaacc.browser.ShareIntentHandler.cancel().

Here is the caller graph for this function:

◆ isPending()

synchronized boolean de.yaacc.share.PendingShare.isPending ( )

Returns: true if a share is pending and has not expired

◆ offer() [1/2]

synchronized String de.yaacc.share.PendingShare.offer	(	Kind	kind,
		String	uri,
		String	displayName,
		String	mimeType )

Same as offer(String, String, String) with an explicit kind.

Parameters

kind	what the share is; null is refused (returns null, nothing changes)

Here is the call graph for this function:

◆ offer() [2/2]

String de.yaacc.share.PendingShare.offer	(	String	uri,
		String	displayName,
		String	mimeType )

Makes a share pending, if none is.

Parameters

uri	the validated URI text (the caller ran `SharedContentPolicy`); null or empty is refused
displayName	the display name; it is cleaned again here (idempotent), null becomes empty
mimeType	the declared MIME type, null becomes empty

Returns: the token that binds the pending action, or null (and nothing changes) if a share is already pending and not expired, or if the URI is null or empty

Referenced by de.yaacc.share.PendingShare.offer().

Here is the call graph for this function: