org.eclipse.gemini.blueprint.service.importer.support

Class OsgiServiceCollectionProxyFactoryBean

java.lang.Object

org.eclipse.gemini.blueprint.service.importer.support.AbstractOsgiServiceImportFactoryBean

org.eclipse.gemini.blueprint.service.importer.support.AbstractServiceImporterProxyFactoryBean

org.eclipse.gemini.blueprint.service.importer.support.OsgiServiceCollectionProxyFactoryBean

All Implemented Interfaces:

BundleContextAware, org.springframework.beans.factory.Aware, org.springframework.beans.factory.BeanClassLoaderAware, org.springframework.beans.factory.BeanNameAware, org.springframework.beans.factory.DisposableBean, org.springframework.beans.factory.FactoryBean<java.lang.Object>, org.springframework.beans.factory.InitializingBean, org.springframework.beans.factory.SmartFactoryBean<java.lang.Object>

public final class OsgiServiceCollectionProxyFactoryBean
extends AbstractServiceImporterProxyFactoryBean

OSGi service (collection) importer. This implementation creates a managed (read-only) collection of OSGi services. The returned collection automatically handles the OSGi services dynamics. If a new service that matches the configuration criteria appears, it will be automatically added to the collection. If a service that matches the criteria disappears (is unregistered), it will be automatically removed from the collection.

Due to the dynamic nature of OSGi services, the collection content can change at runtime, even during iteration. This implementation will correctly update all the collection Iterators so they reflect the collection content. This approach (as opposed to the 'snapshot' strategy) prevents dealing with dead services which can appear when imported services go down while iterating. This means that iterating while the collection is being changed is safe.

Note that the Iterator still has to be fulfilled meaning the next() method always obey the result of the previous hasNext() invocation:

hasNext() returned value	next() behaviour
true	Always return a non-null value, even when the collection has shrunk as services when away. This means returning a proxy that will throw an exception on an invocation that requires the backing service to be present.
false	per Iterator contract, NoSuchElementException is thrown. This applies even if other services are added to the collection.

Due to the dynamic nature of OSGi, hasNext() invocation made on the same Iterator can return different values based on the services availability. However, as explained above, next() will always obey the result of the last hasNext() method.

Note: Even though the collection and its iterators communicate in a thread-safe manner, iterators themselves are not thread-safe. Concurrent access on the iterators should be properly synchronized. Due to the light nature of the iterators, consider creating a new one rather then reusing or sharing.

See Also:

Iterator, Collection, List, Set, SortedSet

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private class	OsgiServiceCollectionProxyFactoryBean.Executor Wrapper around internal commands.

Field Summary

Fields

Modifier and Type	Field and Description
private CollectionType	collectionType
private java.util.Comparator	comparator
private ImporterInternalActions	controller
private CollectionProxy	exposedProxy proxy casted to a specific interface to allow specific method calls
private boolean	greedyProxying greedy-proxying
private java.lang.Runnable	initializationCallback
private static org.apache.commons.logging.Log	log
private MemberType	memberType
private ServiceProxyCreator	proxyCreator proxy creator
private java.lang.Runnable	proxyDestructionCallback proxy infrastructure hook exposed to allow clean up
private java.util.List<ImporterStateListener>	stateListeners internal listeners

Fields inherited from class org.eclipse.gemini.blueprint.service.importer.support.AbstractServiceImporterProxyFactoryBean

proxy

Constructor Summary

Constructors

Constructor and Description
OsgiServiceCollectionProxyFactoryBean()

Method Summary

Modifier and Type	Method and Description
void	afterPropertiesSet()
(package private) java.lang.Object	createProxy(boolean lazyProxy) Create the managed-collection given the existing settings.
(package private) Cardinality	getInternalCardinality()
MemberType	getMemberType() Sets the member type of this service collection.
(package private) java.lang.Runnable	getProxyDestructionCallback() Returns the destruction callback associated with the proxy created by this object.
(package private) java.lang.Runnable	getProxyInitializer() Returns a callback to the proxy which gets called when the proxy is called for the first time, if a lazy creation was used.
void	setCollectionType(CollectionType collectionType) Sets the collection type this FactoryBean will produce.
void	setComparator(java.util.Comparator comparator) Sets the (optional) comparator for ordering the resulting collection.
void	setGreedyProxying(boolean greedyProxying) Dictates whether greedy proxies are created or not (default).
void	setMemberType(MemberType type) Sets the member type of this service collection.

Methods inherited from class org.eclipse.gemini.blueprint.service.importer.support.AbstractServiceImporterProxyFactoryBean

destroy, getAopClassLoader, getObject, getObjectType, isBlueprintCompliant, isEagerInit, isPrototype, isSingleton, isUseBlueprintExceptions, setBeanClassLoader, setBlueprintCompliant, setUseBlueprintExceptions

Methods inherited from class org.eclipse.gemini.blueprint.service.importer.support.AbstractOsgiServiceImportFactoryBean

getAvailability, getBeanClassLoader, getBeanName, getBundleContext, getCardinality, getContextClassLoader, getFilter, getImportContextClassLoader, getInterfaces, getListeners, getUnifiedFilter, setAvailability, setBeanName, setBundleContext, setCardinality, setContextClassLoader, setFilter, setImportContextClassLoader, setInterfaces, setListeners, setServiceBeanName

Methods inherited from class java.lang.Object

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

Field Detail

log

private static final org.apache.commons.logging.Log log

exposedProxy

private CollectionProxy exposedProxy

proxy casted to a specific interface to allow specific method calls

proxyDestructionCallback

private java.lang.Runnable proxyDestructionCallback

proxy infrastructure hook exposed to allow clean up

initializationCallback

private java.lang.Runnable initializationCallback

proxyCreator

private ServiceProxyCreator proxyCreator

proxy creator

comparator

private java.util.Comparator comparator

collectionType

private CollectionType collectionType

greedyProxying

private boolean greedyProxying

greedy-proxying

memberType

private MemberType memberType

stateListeners

private final java.util.List<ImporterStateListener> stateListeners

internal listeners

controller

private final ImporterInternalActions controller

Constructor Detail

OsgiServiceCollectionProxyFactoryBean

public OsgiServiceCollectionProxyFactoryBean()

Method Detail

afterPropertiesSet

public void afterPropertiesSet()

Specified by:

afterPropertiesSet in interface org.springframework.beans.factory.InitializingBean

Overrides:

afterPropertiesSet in class AbstractServiceImporterProxyFactoryBean

createProxy

java.lang.Object createProxy(boolean lazyProxy)

Create the managed-collection given the existing settings. This method creates the osgi managed collection and wraps it with an unmodifiable map to prevent exposing infrastructure methods and write access.

Specified by:

createProxy in class AbstractServiceImporterProxyFactoryBean

Parameters:

lazyProxy - indicates whether the proxy is lazy (no code is executed in the proxy) or not

Returns:

importer proxy

See Also:

AbstractServiceImporterProxyFactoryBean.getProxyDestructionCallback()

getProxyInitializer

java.lang.Runnable getProxyInitializer()

Description copied from class: AbstractServiceImporterProxyFactoryBean

Returns a callback to the proxy which gets called when the proxy is called for the first time, if a lazy creation was used. For eager initialization, a null object should be returned.

Specified by:

getProxyInitializer in class AbstractServiceImporterProxyFactoryBean

Returns:

proxy initialization callback

getProxyDestructionCallback

java.lang.Runnable getProxyDestructionCallback()

Description copied from class: AbstractServiceImporterProxyFactoryBean

Returns the destruction callback associated with the proxy created by this object. The callback is called once, during the destruction process of the FactoryBean.

Specified by:

getProxyDestructionCallback in class AbstractServiceImporterProxyFactoryBean

Returns:

destruction callback for the service proxy.

See Also:

#createProxy()

setComparator

public void setComparator(java.util.Comparator comparator)

Sets the (optional) comparator for ordering the resulting collection. The presence of a comparator will force the FactoryBean to use a sorted collection even though, the specified collection type does not imply ordering.

Thus, instead of list a sorted list will be created and instead of a set, a sorted set.

Parameters:

comparator - Comparator (can be null) used for ordering the resulting collection.

See Also:

setCollectionType(CollectionType)

setCollectionType

public void setCollectionType(CollectionType collectionType)

Sets the collection type this FactoryBean will produce. Note that if a comparator is set, a sorted collection will be created even if the specified type is does not imply ordering. If no comparator is set but the collection type implies ordering, the natural order of the elements will be used.

Parameters:

collectionType - the collection type as string using one of the values above.

See Also:

setComparator(Comparator), Comparable, Comparator, CollectionType

setGreedyProxying

public void setGreedyProxying(boolean greedyProxying)

Dictates whether greedy proxies are created or not (default).

Greedy proxies will proxy all the (visible) classes published by the imported OSGi services. This means that the individual service proxy, might implement/extend additional classes.

By default, greedy proxies are disabled (false) meaning that only the specified classes are used for generating the the imported OSGi service proxies.

Note:Greedy proxying will use the proxy mechanism dictated by this factory configuration. This means that if JDK proxies are used, greedy proxing will consider only additional interfaces exposed by the OSGi service and none of the extra classes. When CGLIB is used, all extra published classes (whether interfaces or non-final concrete classes) will be considered.

Parameters:

greedyProxying - true if greedy proxying should be enabled, false otherwise.

getMemberType

public MemberType getMemberType()

Sets the member type of this service collection.

Returns:

the collection member type

setMemberType

public void setMemberType(MemberType type)

Sets the member type of this service collection. The collection can hold either service proxies (the default) indicated by MemberType.SERVICE_OBJECT or service references MemberType.SERVICE_REFERENCE.

Parameters:

type - the collection member type

getInternalCardinality

Cardinality getInternalCardinality()

Specified by:

getInternalCardinality in class AbstractOsgiServiceImportFactoryBean