Class Scopelet<S extends Scopelet<S>>

java.lang.Object

org.microbean.scopelet.Scopelet<S>

Type Parameters:

S - the Scopelet subtype extending this class

All Implemented Interfaces:

AutoCloseable, Constable, Aggregate, Factory<S>, ScopeMember

Direct Known Subclasses:

MapBackedScopelet, NoneScopelet

public abstract class Scopelet<S extends Scopelet<S>>
extends Object
implements AutoCloseable, Factory<S>, ScopeMember

A manager of object lifespans identified by a scope.

Author:

Laird Nelson

See Also:

• Scope
• ScopeMember

Field Summary

Fields inherited from interface org.microbean.bean.Aggregate

EMPTY_ASSIGNMENTS, EMPTY_DEPENDENCIES

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Scopelet(NamedAttributeMap<?> scopeId)	Creates a new Scopelet.

Method Summary

Modifier and Type	Method	Description
boolean	active()	Returns true if and only if this Scopelet is active at the moment of the call.
final Bean<S>	bean()	Returns a Bean for this Scopelet.
void	close()	Irrevocably closes this Scopelet, and, by doing so, notionally makes it irrevocably inactive.
protected final boolean	closed()	Returns true if and only if at the moment of invocation this Scopelet is (irrevocably) closed (and therefore also not active).
boolean	containsId(Object id)	Checks to see if this Scopelet is active and then returns true if and only if, at the moment of an invocation, this Scopelet is active and already contains an object identified by the supplied Object.
final S	create(Request<S> r)	Creates this Scopelet by simply returning it.
final boolean	destroys()	Returns true when invoked to indicate that Scopelet implementations destroy what they create.
boolean	equals(Object other)	Returns true if and only if the supplied Object is not null, has the same class as this Scopelet, has an Id equal to that of this Scopelet, and a scope identifier equal to that of this Scopelet.
final <I> I	get(Object id)	Checks to see if this Scopelet is active, and then returns the preexisting contextual instance identified by the supplied Object, or null if no such instance exists.
final boolean	governedBy(NamedAttributeMap<?> scopeId)	Returns true if this Scopelet is governed by the scope represented by the supplied NamedAttributeMap.
final NamedAttributeMap<?>	governingScopeId()	Returns the NamedAttributeMap representing the identifier of the scope to which this Scopelet belongs.
int	hashCode()	Returns a hashcode for this Scopelet.
abstract Id	id()	Returns an Id representing this Scopelet.
abstract <I> I	instance(Object id, Factory<I> factory, Request<I> request)	Checks to see if this Scopelet is active and then returns a pre-existing or created-on-demand contextual instance suitable for the combination of identifier, Factory and Request.
final <I> I	instance(Request<I> request)	Checks to see if this Scopelet is active and then eturns a contextual instance identified by the identifying information present within the supplied Request, creating the instance and associating it with the identifying information present within the supplied Request if necessary.
boolean	remove(Object id)	Checks to see if this Scopelet is active and then removes any contextual instance stored under the supplied id, returning true if and only if removal actually took place.
final NamedAttributeMap<?>	scopeId()	Returns the NamedAttributeMap that identifies this Scopelet's affiliated scope.
final S	singleton()	Returns this Scopelet if it has been created via the create(Request) method, or null if that method has not yet been invoked.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.microbean.bean.Aggregate

assign, dependencies

Methods inherited from interface org.microbean.bean.Factory

describeConstable, destroy

Constructor Details

Scopelet

protected Scopelet(NamedAttributeMap<?> scopeId)

Creates a new Scopelet.

Parameters:

scopeId - a NamedAttributeMap identifying the scope being implemented; must not be null

Throws:

NullPointerException - if scopeId is null

Method Details

id

public abstract Id id()

Returns an Id representing this Scopelet.

Implementations of this method must return determinate values.

Returns:

an Id representing this Scopelet; never null

See Also:

• governingScopeId()
• bean()

bean

public final Bean<S> bean()

Returns a Bean for this Scopelet.

This Scopelet will be used as the Bean's associated Factory. This Scopelet's Id will be used as the Bean's identifier.

Returns:

a Bean for this Scopelet; never null

See Also:

• id()

create

public final S create(Request<S> r)

Creates this Scopelet by simply returning it.

Specified by:

create in interface Factory<S extends Scopelet<S>>

Returns:

this Scopelet

singleton

public final S singleton()

Returns this Scopelet if it has been created via the create(Request) method, or null if that method has not yet been invoked.

Specified by:

singleton in interface Factory<S extends Scopelet<S>>

Returns:

this Scopelet if it has been "created"; null otherwise

See Also:

• create(Request)

destroys

public final boolean destroys()

Returns true when invoked to indicate that Scopelet implementations destroy what they create.

Specified by:

destroys in interface Factory<S extends Scopelet<S>>

Returns:

true when invoked

See Also:

• Factory.destroy(Object, Request)
• create(Request)

hashCode

public int hashCode()

Returns a hashcode for this Scopelet.

Overrides:

hashCode in class Object

Returns:

a hashcode for this Scopelet

equals

public boolean equals(Object other)

Returns true if and only if the supplied Object is not null, has the same class as this Scopelet, has an Id equal to that of this Scopelet, and a scope identifier equal to that of this Scopelet.

Overrides:

equals in class Object

Parameters:

other - the Object to test; may be null

Returns:

true if and only if the supplied Object is not null, has the same class as this Scopelet, has an Id equal to that of this Scopelet, and a scope identifier equal to that of this Scopelet

governingScopeId

public final NamedAttributeMap<?> governingScopeId()

Returns the NamedAttributeMap representing the identifier of the scope to which this Scopelet belongs.

Specified by:

governingScopeId in interface ScopeMember

Returns:

the NamedAttributeMap representing the identifier of the scope to which this Scopelet belongs; never null

See Also:

• ScopeMember

governedBy

public final boolean governedBy(NamedAttributeMap<?> scopeId)

Returns true if this Scopelet is governed by the scope represented by the supplied NamedAttributeMap.

Specified by:

governedBy in interface ScopeMember

Parameters:

scopeId - a NamedAttributeMap identifying a scope; must not be null

Returns:

true if this Scopelet is governed by the scope represented by the supplied NamedAttributeMap

Throws:

NullPointerException - if scopeId is null

scopeId

public final NamedAttributeMap<?> scopeId()

Returns the NamedAttributeMap that identifies this Scopelet's affiliated scope.

Returns:

the NamedAttributeMap that identifies this Scopelet's affiliated scope; never null

active

public boolean active()

Returns true if and only if this Scopelet is active at the moment of the call.

Overrides of this method must ensure that if closed() returns true, this method must return false.

Returns:

true if and only if this Scopelet is active at the moment of the call

See Also:

• closed()

containsId

public boolean containsId(Object id)

Checks to see if this Scopelet is active and then returns true if and only if, at the moment of an invocation, this Scopelet is active and already contains an object identified by the supplied Object.

The default implementation of this method checks to see if this Scopelet is active, and then true if and only if the result of invoking the instance(Object, Factory, Request) method with the supplied id, null, and null is not null.

Subclasses are encouraged to override this method to be more efficient or to use a different algorithm.

Parameters:

id - the Object serving as an identifier; may be null in certain pathological cases

Returns:

true if and only if, at the moment of an invocation, this Scopelet is active and contains a preexisting object identified by the supplied Object

Throws:

InactiveScopeletException - if this Scopelet is not active

See Also:

• active()
• instance(Object, Factory, Request)

get

public final <I> I get(Object id)

Checks to see if this Scopelet is active, and then returns the preexisting contextual instance identified by the supplied Object, or null if no such instance exists.

This convenience method checks to see if this Scopelet is active, and then, if the supplied Object is not a Request, calls the instance(Object, Factory, Request) method with the supplied id, null, and null, and returns its result.

If the supplied Object is a Request, this method calls the instance(Request) method with the supplied (cast) id and returns its result.

Type Parameters:

I - the type of contextual instance

Parameters:

id - an Object serving as an identifier; may be null in certain pathological cases

Returns:

the contextual instance identified by the supplied Object, or null if no such instance exists

Throws:

InactiveScopeletException - if this Scopelet is not active

See Also:

• instance(Object, Factory, Request)
• instance(Request)

instance

public final <I> I instance(Request<I> request)

Checks to see if this Scopelet is active and then eturns a contextual instance identified by the identifying information present within the supplied Request, creating the instance and associating it with the identifying information present within the supplied Request if necessary.

Type Parameters:

I - the type of contextual instance

Parameters:

request - a Request; may be null in which case the return value of an invocation of instance(Object, Factory, Request) with null supplied for all three arguments will be returned instead

Returns:

an appropriate contextual instance, or null

Throws:

InactiveScopeletException - if this Scopelet is not active

See Also:

• Request.beanReduction()
• instance(Object, Factory, Request)

instance

public abstract <I> I instance(Object id,
 Factory<I> factory,
 Request<I> request)

Checks to see if this Scopelet is active and then returns a pre-existing or created-on-demand contextual instance suitable for the combination of identifier, Factory and Request.

Type Parameters:

I - the type of contextual instance

Parameters:

id - an identifier that can identify a contextual instance; may be null

factory - a Factory; may be null

request - a Request, typically the one in effect that is causing this method to be invoked in the first place; may be null

Returns:

a contextual instance, possibly pre-existing, or possibly created just in time, or null

Throws:

InactiveScopeletException - if this Scopelet is not active

remove

public boolean remove(Object id)

Checks to see if this Scopelet is active and then removes any contextual instance stored under the supplied id, returning true if and only if removal actually took place.

The default implementation of this method always returns false. Subclasses are encouraged to override it as appropriate.

Parameters:

id - an identifier; may be null

Returns:

true if and only if removal actually occurred

Throws:

InactiveScopeletException - if this Scopelet is not active

close

public void close()

Irrevocably closes this Scopelet, and, by doing so, notionally makes it irrevocably inactive.

Specified by:

close in interface AutoCloseable

See Also:

• closed()
• active()

closed

protected final boolean closed()

Returns true if and only if at the moment of invocation this Scopelet is (irrevocably) closed (and therefore also not active).

Returns:

true if and only if at the moment of invocation this Scopelet is (irrevocably) closed (and therefore also not active)