public interface IAdaptable extends IPropertyChangeNotifier
IAdaptable
allows to register (as well as unregister) and retrieve
(registered) adapters under a given AdapterKey
, which combines a
TypeToken
-based type key and a String
-based role.
The combination of a type key with a role (by means of an AdapterKey
)
allows to register multiple adapters with the same type under different
roles. If there is only one adapter for specific type, it can easily be
registered and retrieved without specifying a role, using
setAdapter(TypeToken, Object)
, setAdapter(Class, Object)
,
getAdapter(TypeToken)
, and getAdapter(Class)
. This is
identical to using setAdapter(AdapterKey, Object)
and
getAdapter(AdapterKey)
with an AdapterKey
that uses the
'default' role (AdapterKey.DEFAULT_ROLE
).
Using a TypeToken
-based type key instead of a simple Class
-based type key, an IAdaptable
allows to register and retrieve
adapters also for parameterized types (e.g. by using
new TypeToken<Provider<IGeometry>>(){}
as a type
key). For convenience, non-parameterized types can also be registered and
retrieved via a simple Class
key (a TypeToken
will internally
be computed for it using TypeToken.of(Class)
).
If a to be registered adapter implements the IAdaptable.Bound
interface, it is
expected that the IAdaptable
, on which the adapter is registered,
binds itself to the adapter via IAdaptable.Bound.setAdaptable(IAdaptable)
during
registration, and accordingly unbinds itself from the adapter
(setAdaptable(null)) during un-registration.
Any client implementing this interface may internally use an
AdaptableSupport
as a delegate to easily realize the required
functionality.
Modifier and Type | Interface and Description |
---|---|
static interface |
IAdaptable.Bound<A extends IAdaptable>
To be implemented by an adapter to indicate that it intends to be bounded
to the respective
IAdaptable it is registered at. |
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
ADAPTERS_PROPERTY
A key used as
PropertyChangeEvent.getPropertyName() when
notifying about registering/unregistering of adapters. |
Modifier and Type | Method and Description |
---|---|
<T> T |
getAdapter(AdapterKey<? super T> key)
Returns an adapter for the given
AdapterKey if one can
unambiguously be retrieved, i.e. if there is only a single adapter that
'matches' the given AdapterKey . |
<T> T |
getAdapter(java.lang.Class<? super T> key)
Returns an adapter for the given
Class key if one can
unambiguously be retrieved. |
<T> T |
getAdapter(com.google.common.reflect.TypeToken<? super T> key)
Returns an adapter for the given
TypeToken key if one can
unambiguously be retrieved. |
<T> java.util.Map<AdapterKey<? extends T>,T> |
getAdapters(java.lang.Class<? super T> key)
Returns all adapters 'matching' the given
Class key, i.e. all
adapters whose AdapterKey 's TypeToken key
AdapterKey.getKey() ) refers to the same or a sub-type of the
given Class key (see TypeToken.isAssignableFrom(Type) ). |
<T> java.util.Map<AdapterKey<? extends T>,T> |
getAdapters(com.google.common.reflect.TypeToken<? super T> key)
Returns all adapters 'matching' the given
TypeToken key, i.e. all
adapters whose AdapterKey 's TypeToken key
AdapterKey.getKey() ) refers to the same or a sub-type or of the
given TypeToken key (see
TypeToken.isAssignableFrom(TypeToken) ). |
<T> void |
setAdapter(AdapterKey<? super T> key,
T adapter)
Registers the given adapter under the given
AdapterKey . |
<T> void |
setAdapter(java.lang.Class<? super T> key,
T adapter)
Registers the given adapter under an
AdapterKey , which will use a
TypeToken representing the given Class key, i.e. using
TypeToken.of(Class) , as well as the default role (see
AdapterKey.DEFAULT_ROLE . |
<T> void |
setAdapter(com.google.common.reflect.TypeToken<? super T> key,
T adapter)
Registers the given adapter under an
AdapterKey , which will use
the given TypeToken key as well as the default role (see
AdapterKey.DEFAULT_ROLE . |
<T> T |
unsetAdapter(AdapterKey<? super T> key)
Unregisters the adapter registered under the exact
AdapterKey
given, returning it for convenience. |
addPropertyChangeListener, removePropertyChangeListener
static final java.lang.String ADAPTERS_PROPERTY
PropertyChangeEvent.getPropertyName()
when
notifying about registering/unregistering of adapters.<T> T getAdapter(AdapterKey<? super T> key)
AdapterKey
if one can
unambiguously be retrieved, i.e. if there is only a single adapter that
'matches' the given AdapterKey
.
An adapter 'matching' the AdapterKey
is an adapter, which is
registered with an AdapterKey
, whose TypeToken
key (
AdapterKey.getKey()
) refers to the same type or a sub-type of the
given AdapterKey
's TypeToken
key (@see
TypeToken.isAssignableFrom(TypeToken)
and whose role (
AdapterKey.getRole()
)) equals the role of the given
AdapterKey
's role.
If there is more than one adapter that 'matches' the given
AdapterKey
, or there is no one 'matching' it, null
will be returned.
T
- The adapter type.key
- The AdapterKey
used to retrieve a registered adapter.AdapterKey
or null
if none could be
retrieved.<T> T getAdapter(java.lang.Class<? super T> key)
Class
key if one can
unambiguously be retrieved. That is, if there is only a single adapter
that 'matches' the given Class
key, this adapter is returned,
ignoring the role under which it is registered (see
AdapterKey.getRole()
).
An adapter 'matching' the Class
key is an adapter, which is
registered with an AdapterKey
, whose key (
AdapterKey.getKey()
) refers to the same type or a sub-type of the
given Class
key (see TypeToken.isAssignableFrom(Type)
).
If there is more than one adapter that 'matches' the given Class
key, it will return the single adapter that is registered for the default
role (AdapterKey.DEFAULT_ROLE
), if there is a single adapter for
which this holds. Otherwise it will return null
.
T
- The adapter type.key
- The Class
key used to retrieve a registered adapter.Class
key or null
if none could be retrieved.<T> T getAdapter(com.google.common.reflect.TypeToken<? super T> key)
TypeToken
key if one can
unambiguously be retrieved. That is, if there is only a single adapter
that 'matches' the given TypeToken
key, this adapter is returned,
ignoring the role under which it is registered (see
AdapterKey.getRole()
).
An adapter 'matching' the TypeToken
key is an adapter, which is
registered with an AdapterKey
, whose key (
AdapterKey.getKey()
) refers to the same type or a sub-type of the
given type key (see TypeToken.isAssignableFrom(TypeToken)
.
If there is more than one adapter that 'matches' the given
TypeToken
key, it will return the single adapter that is
registered for the default role (AdapterKey.DEFAULT_ROLE
), if
there is a single adapter for which this holds. Otherwise it will return
null
.
T
- The adapter type.key
- The TypeToken
key used to retrieve a registered
adapter.TypeToken
key or null
if none could be
retrieved.<T> java.util.Map<AdapterKey<? extends T>,T> getAdapters(java.lang.Class<? super T> key)
Class
key, i.e. all
adapters whose AdapterKey
's TypeToken
key
AdapterKey.getKey()
) refers to the same or a sub-type of the
given Class
key (see TypeToken.isAssignableFrom(Type)
).T
- The adapter type.key
- The Class
key to retrieve adapters for.Map
containing all those adapters registered at this
IAdaptable
, whose AdapterKey
's TypeToken
key (AdapterKey.getKey()
) refers to the same or a
sub-type of the given Class
key, qualified by their
respective AdapterKey
s.getAdapter(Class)
<T> java.util.Map<AdapterKey<? extends T>,T> getAdapters(com.google.common.reflect.TypeToken<? super T> key)
TypeToken
key, i.e. all
adapters whose AdapterKey
's TypeToken
key
AdapterKey.getKey()
) refers to the same or a sub-type or of the
given TypeToken
key (see
TypeToken.isAssignableFrom(TypeToken)
).T
- The adapter type.key
- The TypeToken
key to retrieve adapters for.Map
containing all those adapters registered at this
IAdaptable
, whose AdapterKey
's TypeToken
key (AdapterKey.getKey()
) refers to the same or a
sub-type of the given TypeToken
key, qualified by their
respective AdapterKey
s.getAdapter(TypeToken)
<T> void setAdapter(AdapterKey<? super T> key, T adapter)
AdapterKey
. The
adapter has to be compliant to the AdapterKey
, i.e. it has to be
of the same type or a sub-type of the AdapterKey
's type key (
AdapterKey.getKey()
).
If the given adapter implements IAdaptable.Bound
, the adapter
will obtain a back-reference to this IAdaptable
via its
IAdaptable.Bound.setAdaptable(IAdaptable)
method.
T
- The adapter type.key
- The AdapterKey
under which to register the given
adapter.adapter
- The adapter to register under the given AdapterKey
.<T> void setAdapter(java.lang.Class<? super T> key, T adapter)
AdapterKey
, which will use a
TypeToken
representing the given Class
key, i.e. using
TypeToken.of(Class)
, as well as the default role (see
AdapterKey.DEFAULT_ROLE
.
If the given adapter implements IAdaptable.Bound
, the adapter
will obtain a back-reference to this IAdaptable
via its
IAdaptable.Bound.setAdaptable(IAdaptable)
method.
T
- The adapter type.key
- The Class
under which to register the given adapter.adapter
- The adapter to register under the given Class
key.setAdapter(AdapterKey, Object)
<T> void setAdapter(com.google.common.reflect.TypeToken<? super T> key, T adapter)
AdapterKey
, which will use
the given TypeToken
key as well as the default role (see
AdapterKey.DEFAULT_ROLE
.
If the given adapter implements IAdaptable.Bound
, the adapter
will obtain a back-reference to this IAdaptable
via its
IAdaptable.Bound.setAdaptable(IAdaptable)
method.
T
- The adapter type.key
- The TypeToken
under which to register the given
adapter.adapter
- The adapter to register under the given TypeToken
key.setAdapter(AdapterKey, Object)
<T> T unsetAdapter(AdapterKey<? super T> key)
AdapterKey
given, returning it for convenience.
If the given adapter implements IAdaptable.Bound
, the
back-reference to this IAdaptable
will be removed via its
IAdaptable.Bound.setAdaptable(IAdaptable)
method, passing over
null
.
T
- The adapter type.key
- The AdapterKey
for which to remove a registered
adapter.Copyright (c) 2014 itemis AG and others. All rights reserved.