public class IntegerIdPool
extends java.lang.Object
Pool of integer IDs. The pool is both thread safe and lock free. IDs are acquired as objects and the life-cycle of the numeric ID is bound to the life-cycle of this object. Numeric IDs are automatically returned to the pool when their associated ID object is finalized. However, as the time of finalization is not predictable, ID objects should be released explicitly if possible in order to avoid exhaustion of the ID pool.
The pool generates integer IDs from a configurable range, ensuring that each numeric ID is only handed out once. In order to accommodate for applications that need a large number of IDs over their life-cycle, the pool supports the reuse of numeric IDs that have been released.
Optionally, the pool can be configured to block released IDs from immediate reuse for a certain time. This is useful in environments where IDs leave the scope of the application and thus external entities might have dangling references to those IDs. In this case, configuring a time for which the ID is blocked from reuse after having been released can help in avoiding a situation in which an external entity uses an ID that has now been reused for a different purpose.
Internally, this implementation uses a BasicIntegerIdPool
for
managing numeric IDs. Therefore the performance considerations in the
documentation of that class also apply to this class.
Modifier and Type | Class and Description |
---|---|
static class |
IntegerIdPool.Id
Integer identifier.
|
Constructor and Description |
---|
IntegerIdPool(int minimumId,
int maximumId,
long blockFromReuseTime,
boolean earlyReuseOnExhaustion)
Creates a new pool for integer IDs.
|
Modifier and Type | Method and Description |
---|---|
IntegerIdPool.Id |
acquireId()
Acquires an ID that is currently not in use.
|
public IntegerIdPool(int minimumId, int maximumId, long blockFromReuseTime, boolean earlyReuseOnExhaustion)
Creates a new pool for integer IDs. All IDs returned by the pools
acquireId()
method are guaranteed to be in the range from
minimumId
to maximumId
(both inclusive).
If minimumId
is greater than maximumId
, the
pool will start at minimumId
counting upwards until
Integer.MAX_VALUE
is reached. Then, the counter will wrap around
continuing with negative numbers until maximumId
is reached.
minimumId
and maximumId
must be chosen so that
there is at least one integer number that is not covered by the range.
This number is needed because it will be internally used as a marker when
the counter has been exhausted.
The blockFromReuseTime
parameter specifies the amount of
time in milliseconds that must pass between an ID being returned by
calling its release()
method and
acquireId()
returning the same ID. This is useful for
applications where an external entity might keep an ID for some time and
it is important to distinguish the now invalid ID from newly acquired
IDs.
If earlyReuseOnExhaustion
is true
,
acquireId()
will not fail immediately if no ID can be reused yet
and no new ID can be assigned because all possible IDs are already in
use. Instead of that, it will try to find an ID that has been released,
but for which the blockFromReuseTime
has not passed yet.
This can be used as a last resort, when it is more important to make sure
that IDs can be acquired than it is important to ensure that released IDs
are not reused for a certain time.
Effectively, all parameters of this constructor are simply passed on to
the constructor
BasicIntegerIdPool.BasicIntegerIdPool(int, int, long, boolean)
.
minimumId
- minimum number used as an ID (inclusive). If
minimumId
is greater than maximumId
,
IDs that are less than minimumId
are used if they
are also less than or equal to maximumId
.maximumId
- maximum number used as an ID (inclusive). If
maximumId
is less than minimumId
,
IDs that are greater than maximumId
are used if
they are also greater than or equal to minimumId
.blockFromReuseTime
- number of milliseconds to wait before reusing an ID after it
has been released. A value of 0
means that IDs
can be reused immediately.earlyReuseOnExhaustion
- if true
IDs which have been released less than
blockFromReuseTime
milliseconds ago are still
used if otherwise the pool would be exhausted.java.lang.IllegalArgumentException
- if minimumId
and maximumId
have not
been chosen so that there is at least one unusable ID or if
blockFromReuseTime is negative.public IntegerIdPool.Id acquireId()
release()
method.release()
method when it is not needed any
longer.java.lang.IllegalStateException
- if this pool is exhausted and no unused ID can be assigned at
the moment.Copyright © 2014–2017 aquenos GmbH. All rights reserved.