net.jxta.impl.util
Interface ResourceAccount

All Known Implementing Classes:

ResourceDispatcher.ClientAccount

public interface ResourceAccount

close

void close()

Tear down this account. Releases all reserved resources.

obtainItem

boolean obtainItem()

Try and grant a new item to this account. If it cannot be done, the account may be eligible for the next available extra item. The account is automatically set to be in need, as if inNeed(true) has been invoked.

Returns:

boolean true if an item was granted, false otherwise.

obtainQuantity

boolean obtainQuantity(long quantity)

Try and grant a certain quantity. It is usefull to manage the allocation of variable sized aggregates when what matters is the cummulated quantity rather than an item count. Quantity could be a number of bytes needed to store something for example. The advantage of using this method rather than obtainItem repeatedly is that it is obvisouly faster if quantity is more than one or two, and also that it is atomic; the entire quantity is either granted or denied. Using this routine is by definition incompatible with the round-robin mode, which could only re-assign quantities of 1. It is legal to use this routine along with round-robin mode if the same dispatcher is used to manage quantities of 1 in this manner, but an account that has failed to obtain its desired quantity is not queued for later re-assignment. And items released with releaseQuantity() are not re-assigned, so overall it is probably best to not mix the two.

Parameters:

quantity - The number of units wanted. The unit is arbitrary It is only meaningfull to the code that uses this dispatcher.

Returns:

boolean whether the requested quantity is authorized.

releaseItem

ResourceAccount releaseItem()

This will release an item and return the most eligible account to re-use this item for. The account that is returned has been granted the item and thus the invoker is expected to do with this account whatever an invoker of obtainItem() would do in case of success. If the items that are managed are threads, the invoker is likely to be one these threads and it should therefore process the returned account as it did the one for which it was calling releaseItem, however be very carefull not to process the new account in the context of the old one; that would rapidly lead to stack overflow. In other words, be carefull of not making a construct equivalent to: process() { doStuff(); myAccount.releaseItem().getUserObject().process(); } That won't work. Instead do: work() { while (myAccount != null) { myAccount.getUserObject().doStuff(); myAccount = myAccount.releaseItem(); } } Or similar; always go back to base stack level. It is mandatory to handle accounts returned by releaseItem(). If handling leads to releaseItem, then it has to be done in a forever loop. That is typical if the items are threads. That is normally not happening if the items are only memory.

Returns:

ResourceAccount the account to which the released item has been re-assigned. null if the released item was not re-assigned.

releaseQuantity

void releaseQuantity(long quantity)

This will release a number of items at once rather than once. To be used in conjunctino with obtainItems(). See that method.

Parameters:

quantity - the number of items to be released.

inNeed

void inNeed(boolean needs)

Call this with true as soon as this account needs a new item. Call this with false as soon as this account has all that it needs. For proper operation, this must be done.

Parameters:

needs - Whether the account needs a new item or not.

getUserObject

Object getUserObject()

Returns:

Object The userObject that was supplied when creating the account.

setUserObject

void setUserObject(Object obj)

Set the userObject associated with that account.

getNbReserved

long getNbReserved()

Returns the number of reserved items that can still be obtained by this account. If that number is negative or zero, it means that all reserved items are currently in use. Still more items might still be obtained from the extra items pool.

Returns:

long The number of reserved items.

isIdle

boolean isIdle()

Tells if this account is idle (that is, none of the resources that it controls are currently in use). This means it can be closed safely.