* A LDAPFilter can be used numerous times to determine if the match
* argument matches the filter string that was used to create the LDAPFilter.
*
* Some examples of LDAP filters are:
*
* - "(cn=Babs Jensen)"
* - "(!(cn=Tim Howes))"
* - "(&(" + ServiceConstants::OBJECTCLASS() + "=Person)(|(sn=Jensen)(cn=Babs J*)))"
* - "(o=univ*of*mich*)"
*
* \remarks This class is thread safe.
*/
class MITK_CORE_EXPORT LDAPFilter {
public:
/**
* Creates in invalid LDAPFilter object.
* Test the validity by using the boolean conversion operator.
*
*
* Calling methods on an invalid LDAPFilter
* will result in undefined behavior.
*/
LDAPFilter();
/**
* Creates a LDAPFilter object. This LDAPFilter
* object may be used to match a ServiceReference object or a
* ServiceProperties object.
*
*
* If the filter cannot be parsed, an std::invalid_argument will be
* thrown with a human readable message where the filter became unparsable.
*
* @param filter The filter string.
* @return A LDAPFilter object encapsulating the filter string.
* @throws std::invalid_argument If filter contains an invalid
* filter string that cannot be parsed.
* @see "Framework specification for a description of the filter string syntax." TODO!
*/
LDAPFilter(const std::string& filter);
LDAPFilter(const LDAPFilter& other);
~LDAPFilter();
operator bool() const;
/**
* Filter using a service's properties.
*
* This LDAPFilter is executed using the keys and values of the
* referenced service's properties. The keys are looked up in a case
* insensitive manner.
*
* @param reference The reference to the service whose properties are used
* in the match.
* @return true if the service's properties match this
* LDAPFilter false otherwise.
*/
bool Match(const ServiceReference& reference) const;
/**
* Filter using a ServiceProperties object with case insensitive key lookup. This
* LDAPFilter is executed using the specified ServiceProperties's keys
* and values. The keys are looked up in a case insensitive manner.
*
* @param dictionary The ServiceProperties whose key/value pairs are used
* in the match.
* @return true if the ServiceProperties's values match this
* filter; false otherwise.
*/
bool Match(const ServiceProperties& dictionary) const;
/**
* Filter using a ServiceProperties. This LDAPFilter is executed using
* the specified ServiceProperties's keys and values. The keys are looked
* up in a normal manner respecting case.
*
* @param dictionary The ServiceProperties whose key/value pairs are used
* in the match.
* @return true if the ServiceProperties's values match this
* filter; false otherwise.
*/
bool MatchCase(const ServiceProperties& dictionary) const;
/**
* Returns this LDAPFilter's filter string.
*
* The filter string is normalized by removing whitespace which does not
* affect the meaning of the filter.
*
* @return This LDAPFilter's filter string.
*/
std::string ToString() const;
/**
* Compares this LDAPFilter to another LDAPFilter.
*
*
* This implementation returns the result of calling
*
* A
* A module has unique identity, a
* A module can be in one of two states:
*
* You can determine the current state by using IsLoaded().
*
*
* A module can only execute code when its state is
* The framework is the only entity that is allowed to create
*
* A module can be in only one state at any time.
*
* @return
* If this module is not in the
* A module's unique identifier has the following attributes:
*
* This method continues to return this module's unique identifier while
* this module is in the
* The location is the full path to the module's shared library.
* This method continues to return this module's location
* while this module is in the
* This method continues to return this module's name while
* this module is in the
* This method continues to return this module's version while
* this module is in the
*
* A
* The
* The
* The framework is the only entity that can create
* This method returns a list of all modules loaded in the module
* environment at the time of the call to this method. This list will
* also contain modules which might already have been unloaded.
*
* @param modules A std::vector of
* A module can register a service object that implements the
* {@link ServiceFactory} interface to have more flexibility in providing
* service objects to other modules.
*
*
* The following steps are taken when registering a service:
*
* This method is otherwise identical to
* RegisterService(const std:vector
* This method is provided as a convenience when
* The list is valid at the time of the call to this method. However since
* the Micro Services framework is a very dynamic environment, services can be modified or
* unregistered at any time.
*
*
* The specified
* The result is a list of
* This method is identical to GetServiceReferences(const std::tring&, const std::string&) except that
* the class name for the service object is automatically deduced from the template argument.
*
* @tparam S The type under which the requested service objects must have been registered.
* @param filter The filter expression or empty for all
* services.
* @return A list of
* The returned
* This method is the same as calling
* {@link ModuleContext::GetServiceReferences(const std::string&, const std::string&)} with an
* empty filter expression. It is provided as a convenience for
* when the caller is interested in any service that implements the
* specified class.
*
* If multiple such services exist, the service with the highest ranking (as
* specified in its {@link ServiceConstants::SERVICE_RANKING} property) is returned.
*
* If there is a tie in ranking, the service with the lowest service ID (as
* specified in its {@link ServiceConstants::SERVICE_ID} property); that is, the
* service that was registered first is returned.
*
* @param clazz The class name with which the service was registered.
* @return A
* This method is identical to GetServiceReference(const std::string&) except that
* the class name for the service object is automatically deduced from the template argument.
*
* @tparam S The type under which the requested service must have been registered.
* @return A
* A module's use of a service is tracked by the module's use count of that
* service. Each time a service's service object is returned by
* {@link #GetService(const ServiceReference&)} the context module's use count for
* that service is incremented by one. Each time the service is released by
* {@link #UngetService(const ServiceReference&)} the context module's use count
* for that service is decremented by one.
*
* When a module's use count for a service drops to zero, the module should
* no longer use that service.
*
*
* This method will always return
* The following steps are taken to get the service object:
*
* This is a convenience method which is identical to itk::LightObject* GetService(const ServiceReference&)
* except that it casts the service object to the supplied template argument type
*
* @tparam S The type the service object will be cast to.
* @return A service object for the service associated with
*
* The service's service object should no longer be used and all references
* to it should be destroyed when a module's use count for the service drops
* to zero.
*
*
* The following steps are taken to unget the service object:
*
* You must take care to remove registered listeners befor the
* If the context module's list of listeners already contains a pair
* The callback is called if the filter criteria is met. To filter based
* upon the class of the service, the filter should reference the
* {@link ServiceConstants#OBJECTCLASS} property. If
* When using a
* If the
* If the context module's list of listeners already contains a pair
* If the
* Note that the case of the keys will be preserved.
*/
#ifdef MITK_HAS_UNORDERED_MAP_H
typedef std::unordered_map
* This property is set by the framework when a service is registered.
*/
MITK_CORE_EXPORT const std::string& OBJECTCLASS(); // = "objectclass"
/**
* Service property identifying a service's registration number. The value
* of this property must be of type
* The value of this property is assigned by the framework when a service is
* registered. The framework assigns a unique value that is larger than all
* previously assigned values since the framework was started. These values
* are NOT persistent across restarts of the framework.
*/
MITK_CORE_EXPORT const std::string& SERVICE_ID(); // = "service.id"
/**
* Service property identifying a service's ranking number.
*
*
* This property may be supplied in the
*
* The service ranking is used by the framework to determine the natural
* order of services, see ServiceReference::operator<(const ServiceReference&),
* and the default service to be returned from a call to the
* {@link ModuleContext::GetServiceReference} method.
*
*
* The default ranking is zero (0). A service with a ranking of
*
* If the supplied property value is not of type
* The framework returns
* A
* Every service registered in the framework has a unique
*
* If the same service object is registered multiple times,
*
* Property keys are case-insensitive.
*
*
* This method continues to return property values after the service has
* been unregistered. This is so references to unregistered services can
* still be interrogated.
*
* @param key The property key.
* @return The property value to which the key is mapped; an invalid Any
* if there is no property named after the key.
*/
Any GetProperty(const std::string& key) const;
/**
* Returns a list of the keys in the
* This method will continue to return the keys after the service has been
* unregistered. This is so references to unregistered services can
* still be interrogated.
*
* @param keys A vector being filled with the property keys.
*/
void GetPropertyKeys(std::vector
* This method must return
* If this
* The framework returns a
* The
* The
* The {@link ServiceProperties#OBJECTCLASS} and {@link ServiceProperties#SERVICE_ID} keys
* cannot be modified by this method. These values are set by the framework
* when the service is registered in the environment.
*
*
* The following steps are taken to modify service properties:
*
* The following steps are taken to unregister a service:
*
* A
* The
* The
* The service referenced by the specified
* Services registered under the specified class name will be tracked by
* this
* Services which match the specified
* Services registered under the interface name of the class template
* argument S will be tracked by this
* Services which match the search criteria specified when this
*
* This method should be called when this
* This implementation calls GetServiceReferences() to get the list
* of tracked services to remove.
*/
virtual void Close();
/**
* Wait for at least one service to be tracked by this
*
* It is strongly recommended that
* This implementation calls GetService() to determine if a service
* is being tracked.
*
* @return Returns the result of GetService().
*/
virtual T WaitForService();
/**
* Return a list of
* If multiple services are being tracked, the service with the highest
* ranking (as specified in its
* This implementation calls GetServiceReferences() to get the list
* of references for the tracked services.
*
* @return A
* This implementation calls GetServiceReferences() to get the list
* of references for the tracked services and then calls
* GetService(const ServiceReference&) for each reference to get the
* tracked service object.
*
* @param services A list of service objects or an empty list if no services
* are being tracked.
*/
virtual void GetServices(std::list
* If any services are being tracked, this implementation returns the result
* of calling
* The tracking count can be used to determine if this
*
* This method is only called when this
* This implementation returns the result of calling
* This method can be overridden in a subclass to customize the service
* object to be tracked for the service being added. In that case, take care
* not to rely on the default implementation of
* \link RemovedService(const ServiceReference&, T service) removedService\endlink
* to unget the service.
*
* @param reference The reference to the service being added to this
*
* This method is only called when this
* This implementation does nothing.
*
* @param reference The reference to modified service.
* @param service The service object for the modified service.
* @see ServiceTrackerCustomizer::ModifiedService(const ServiceReference&, itk::LighObject*)
*/
void ModifiedService(const ServiceReference& reference, T service);
/**
* Default implementation of the
*
* This method is only called when this
* This implementation calls
* This method can be overridden in a subclass. If the default
* implementation of \link AddingService(const ServiceReference&) AddingService\endlink
* method was used, this method must unget the service.
*
* @param reference The reference to removed service.
* @param service The service object for the removed service.
* @see ServiceTrackerCustomizer::RemovedService(const ServiceReference&, itk::LighObject*)
*/
void RemovedService(const ServiceReference& reference, T service);
private:
typedef ServiceTrackerthis->ToString() == other.ToString().
*
* @param other The object to compare against this LDAPFilter.
* @return Returns the result of calling
* this->ToString() == other.ToString().
*/
bool operator==(const LDAPFilter& other) const;
LDAPFilter& operator=(const LDAPFilter& filter);
protected:
SharedDataPointer%Module object is the access point to a MITK module.
* Each MITK module has an associated %Module object.
*
* long, chosen by the
* framework. This identity does not change during the lifecycle of a module.
*
*
*
* LOADED.
* An UNLOADED module is a
* zombie and can only be reached because it was loaded before. However,
* unloaded modules can be loaded again.
*
* %Module objects.
*
* @remarks This class is thread safe.
*/
class MITK_CORE_EXPORT Module
{
public:
static const std::string& PROP_ID();
static const std::string& PROP_NAME();
static const std::string& PROP_LOCATION();
static const std::string& PROP_MODULE_DEPENDS();
static const std::string& PROP_PACKAGE_DEPENDS();
static const std::string& PROP_LIB_DEPENDS();
static const std::string& PROP_VERSION();
static const std::string& PROP_QT();
~Module();
/**
* Returns this module's current state.
*
* true if the module is LOADED
* false if it is UNLOADED
*/
bool IsLoaded() const;
/**
* Returns this module's {@link ModuleContext}. The returned
* ModuleContext can be used by the caller to act on behalf
* of this module.
*
* LOADED state, then this
* module has no valid ModuleContext. This method will
* return 0 if this module has no valid
* ModuleContext.
*
* @return A ModuleContext for this module or
* 0 if this module has no valid
* ModuleContext.
*/
ModuleContext* GetModuleContext() const;
/**
* Returns this module's unique identifier. This module is assigned a unique
* identifier by the framework when it was loaded.
*
*
*
*
* long.
* UNLOADED state.
*
* @return The unique identifier of this module.
*/
long GetModuleId() const;
/**
* Returns this module's location.
*
* UNLOADED state.
*
* @return The string representation of this module's location.
*/
std::string GetLocation() const;
/**
* Returns the name of this module as specified by the
* MITK_CREATE_MODULE CMake macro. The module
* name together with a version must identify a unique module.
*
* UNLOADED state.
*
* @return The name of this module.
*/
std::string GetName() const;
/**
* Returns the version of this module as specified by the
* MITK_CREATE_MODULE CMake macro. If this module does not have a
* specified version then {@link ModuleVersion#EmptyVersion} is returned.
*
* UNLOADED state.
*
* @return The version of this module.
*/
ModuleVersion GetVersion() const;
/**
* Returns the value of the specified property for this module. The
* method returns an empty string if the property is not found.
*
* @param key The name of the requested property.
* @return The value of the requested property, or an empty string
* if the property is undefined.
*/
std::string GetProperty(const std::string& key) const;
private:
friend class ModuleRegistry;
friend class ServiceReferencePrivate;
ModulePrivate* d;
Module();
Module(const Module&);
void Init(CoreModuleContext* coreCtx, ModuleInfo* info);
void Start();
void Stop();
};
}
#ifdef MITK_HAS_UNORDERED_MAP_H
namespace std {
#elif defined(__GNUC__)
namespace __gnu_cxx {
#else
namespace itk {
#endif
templateModuleContext methods allow a module to:
*
*
*
* ServiceReferences from the framework service
* registry.
* ModuleContext object will be created and provided to the
* module associated with this context when it is loaded using the
* {@link ModuleActivator::Load} method. The same ModuleContext
* object will be passed to the module associated with this context when it is
* unloaded using the {@link ModuleActivator::Unload} method. A
* ModuleContext object is generally for the private use of its
* associated module and is not meant to be shared with other modules in the
* module environment.
*
* Module object associated with a ModuleContext
* object is called the context module.
*
* ModuleContext object is only valid during the execution of
* its context module; that is, during the period when the context module
* is loaded. If the ModuleContext
* object is used subsequently, a std::logic_error is
* thrown. The ModuleContext object is never reused after
* its context module is unloaded.
*
* ModuleContext
* objects.
*
* @remarks This class is thread safe.
*/
class MITK_CORE_EXPORT ModuleContext
{
public:
~ModuleContext();
/**
* Returns the Module object associated with this
* ModuleContext. This module is called the context module.
*
* @return The Module object associated with this
* ModuleContext.
* @throws std::logic_error If this ModuleContext is no
* longer valid.
*/
Module* GetModule() const;
/**
* Returns the module with the specified identifier.
*
* @param id The identifier of the module to retrieve.
* @return A Module object or 0 if the
* identifier does not match any previously loaded module.
*/
Module* GetModule(long id) const;
/**
* Returns a list of all known modules.
* Module objects which
* will hold one object per known module.
*/
void GetModules(std::vectorServiceRegistration object is returned. The
* ServiceRegistration object is for the private use of the
* module registering the service and should not be shared with other
* modules. The registering module is defined to be the context module.
* Other modules can locate the service by using either the
* {@link #GetServiceReferences} or {@link #GetServiceReference} method.
*
*
*
*
* @param clazzes The class names under which the service can be located.
* The class names will be stored in the service's
* properties under the key {@link ServiceConstants#OBJECTCLASS}.
* @param service The service object or a ServiceProperties (which may be
* omitted):
* A property named {@link ServiceConstants#SERVICE_ID} identifying the
* registration number of the service
* A property named {@link ServiceConstants#OBJECTCLASS} containing all the
* specified classes.
* Properties with these names in the specified ServiceProperties will
* be ignored.
* ServiceRegistration object for this registration is
* returned.
* ServiceFactory
* object.
* @param properties The properties for this service. The keys in the
* properties object must all be std::string objects. See
* {@link ServiceConstants} for a list of standard service property keys.
* Changes should not be made to this object after calling this
* method. To update the service's properties the
* {@link ServiceRegistration::SetProperties} method must be called.
* The set of properties may be omitted if the service has
* no properties.
* @return A ServiceRegistration object for use by the module
* registering the service to update the service's properties or to
* unregister the service.
* @throws std::invalid_argument If one of the following is true:
*
*
* @throws std::logic_error If this ModuleContext is no longer valid.
* @see ServiceRegistration
* @see ServiceFactory
*/
ServiceRegistration RegisterService(const std::listservice is 0.
* properties contains case variants of the same key name.
* service will only be registered under a single
* class name. Note that even in this case the value of the service's
* ServiceConstants::OBJECTCLASS property will be a std::listservice will only be registered under
* a single class name whose type is available to the caller. It is otherwise identical to
* RegisterService(const char*, itk::LightObject*, const ServiceProperties&) but should be preferred
* since it avoids errors in the string literal identifying the class name or interface identifier.
*
* @tparam S The type under which the service can be located.
* @param service The service object or a ServiceFactory object.
* @param properties The properties for this service.
* @return A ServiceRegistration object for use by the module
* registering the service to update the service's properties or to
* unregister the service.
* @throws std::logic_error If this ModuleContext is no longer valid.
* @see RegisterService(const char*, itk::LighObject*, const ServiceProperties&)
*/
templateServiceReference objects. The returned
* list contains services that
* were registered under the specified class and match the specified filter
* expression.
*
* filter expression is used to select the
* registered services whose service properties contain keys and values
* which satisfy the filter expression. See {@link LDAPFilter} for a description
* of the filter syntax. If the specified filter is
* empty, all registered services are considered to match the
* filter. If the specified filter expression cannot be parsed,
* an std::invalid_argument will be thrown with a human readable
* message where the filter became unparsable.
*
* ServiceReference objects for all
* services that meet all of the following conditions:
*
*
*
* @param clazz The class name with which the service was registered or
* an empty string for all services.
* @param filter The filter expression or empty for all
* services.
* @return A list of clazz, is not
* empty, the service must have been registered with the
* specified class name. The complete list of class names with which a
* service was registered is available from the service's
* {@link ServiceConstants::OBJECTCLASS objectClass} property.
* filter is not empty, the
* filter expression must match the service.
* ServiceReference objects or
* an empty list if no services are registered which satisfy the
* search.
* @throws std::invalid_argument If the specified filter
* contains an invalid filter expression that cannot be parsed.
* @throws std::logic_error If this ModuleContext is no longer valid.
*/
std::listServiceReference objects. The returned
* list contains services that
* were registered under the interface id of the template argument S
* and match the specified filter expression.
*
* ServiceReference objects or
* an empty list if no services are registered which satisfy the
* search.
* @throws std::invalid_argument If the specified filter
* contains an invalid filter expression that cannot be parsed.
* @throws std::logic_error If this ModuleContext is no longer valid.
* @see GetServiceReferences(const std::string&, const std::string&)
*/
templateServiceReference object for a service that
* implements and was registered under the specified class.
*
* ServiceReference object is valid at the time of
* the call to this method. However as the Micro Services framework is a very dynamic
* environment, services can be modified or unregistered at any time.
*
* ServiceReference object, or an invalid ServiceReference if
* no services are registered which implement the named class.
* @throws std::logic_error If this ModuleContext is no longer valid.
* @throws ServiceException If no service was registered under the given class name.
* @see #GetServiceReferences(const std::string&, const std::string&)
*/
ServiceReference GetServiceReference(const std::string& clazz);
/**
* Returns a ServiceReference object for a service that
* implements and was registered under the specified template class argument.
*
* ServiceReference object, or an invalid ServiceReference if
* no services are registered which implement the type S.
* @throws std::logic_error If this ModuleContext is no longer valid.
* @throws ServiceException It no service was registered under the given class name.
* @see #GetServiceReference(const std::string&)
* @see #GetServiceReferences(const std::string&)
*/
templateServiceReference object.
* 0 when the service
* associated with this reference has been unregistered.
*
*
*
*
* @param reference A reference to the service.
* @return A service object for the service associated with
* 0 is returned.
* ServiceFactory interface, the
* {@link ServiceFactory::GetService} method is
* called to create a service object for the context module. This service
* object is cached by the framework. While the context module's use count
* for the service is greater than zero, subsequent calls to get the
* services's service object for the context module will return the cached
* service object.
* If the ServiceFactory object throws an
* exception, 0 is returned and a warning is logged.
* reference or 0 if the service is not
* registered or the ServiceFactory threw
* an exception.
* @throws std::logic_error If this ModuleContext is no
* longer valid.
* @throws std::invalid_argument If the specified
* ServiceReference is invalid (default constructed).
* @see #UngetService(const ServiceReference&)
* @see ServiceFactory
*/
itk::LightObject* GetService(const ServiceReference& reference);
/**
* Returns the service object referenced by the specified
* ServiceReference object.
* reference or 0 if the service is not
* registered, the ServiceFactory threw
* an exception or the service could not be casted to the desired type.
* @throws std::logic_error If this ModuleContext is no
* longer valid.
* @throws std::invalid_argument If the specified
* ServiceReference is invalid (default constructed).
* @see #GetService(const ServiceReference&)
* @see #UngetService(const ServiceReference&)
* @see ServiceFactory
*/
templateServiceReference object. If the context module's use count
* for the service is zero, this method returns false.
* Otherwise, the context modules's use count for the service is decremented
* by one.
*
*
*
*
* @param reference A reference to the service to be released.
* @return false is returned.
* ServiceFactory object,
* the ServiceFactory#UngetService
* method is called to release the service object for the context module.
* true is returned.
* false if the context module's use count for the
* service is zero or if the service has been unregistered;
* true otherwise.
* @throws std::logic_error If this ModuleContext is no
* longer valid.
* @see #GetService
* @see ServiceFactory
*/
bool UngetService(const ServiceReference& reference);
/**
* Adds the specified callback with the
* specified filter to the context modules's list of listeners.
* See LDAPFilter for a description of the filter syntax. Listeners
* are notified when a service has a lifecycle state change.
*
* receiver
* object is destroyed. However, the Micro Services framework takes care
* of removing all listeners registered by this context module's classes
* after the module is unloaded.
*
* (r,c)
* of receiver and callback such that
* (r == receiver && c == callback), then this
* method replaces that callback's filter (which may be empty)
* with the specified one (which may be empty).
*
* filter is
* empty, all services are considered to match the filter.
*
* filter, it is possible that the
* ServiceEvents for the complete lifecycle of a service
* will not be delivered to the callback. For example, if the
* filter only matches when the property x has
* the value 1, the callback will not be called if the
* service is registered with the property x not set to the
* value 1. Subsequently, when the service is modified
* setting property x to the value 1, the
* filter will match and the callback will be called with a
* ServiceEvent of type MODIFIED. Thus, the
* callback will not be called with a ServiceEvent of type
* REGISTERED.
*
* @tparam The type of the receiver (containing the member function to be called)
* @param receiver The object to connect to.
* @param callback The member function pointer to call.
* @param filter The filter criteria.
* @throws std::invalid_argument If filter contains an
* invalid filter string that cannot be parsed.
* @throws std::logic_error If this ModuleContext is no
* longer valid.
* @see ServiceEvent
* @see RemoveServiceListener()
*/
templatecallback from the context module's
* list of listeners.
*
* (receiver,callback) pair is not contained in this
* context module's list of listeners, this method does nothing.
*
* @tparam The type of the receiver (containing the member function to be removed)
* @param receiver The object from which to disconnect.
* @param callback The member function pointer to remove.
* @throws std::logic_error If this ModuleContext is no
* longer valid.
* @see AddServiceListener()
*/
templatecallback to the context modules's list
* of listeners. Listeners are notified when a module has a lifecycle
* state change.
*
* (r,c)
* of receiver and callback such that
* (r == receiver && c == callback), then this method does nothing.
*
* @tparam The type of the receiver (containing the member function to be called)
* @param receiver The object to connect to.
* @param callback The member function pointer to call.
* @throws std::logic_error If this ModuleContext is no
* longer valid.
* @see ModuleEvent
*/
templatecallback from the context module's
* list of listeners.
*
* (receiver,callback) pair is not contained in this
* context module's list of listeners, this method does nothing.
*
* @tparam The type of the receiver (containing the member function to be removed)
* @param receiver The object from which to disconnect.
* @param callback The member function pointer to remove.
* @throws std::logic_error If this ModuleContext is no
* longer valid.
* @see AddModuleListener()
*/
templatestd::list<std::string>.
*
* long int.
*
* ServiceProperties object passed to the
* ModuleContext::RegisterService method. The value of this
* property must be of type int.
*
* std::numeric_limits is very likely to be returned as the
* default service, whereas a service with a ranking of
* std::numeric_limits is very unlikely to be returned.
*
* int, it is
* deemed to have a ranking value of zero.
*/
MITK_CORE_EXPORT const std::string& SERVICE_RANKING(); // = "service.ranking"
}
}
#endif // MITK_SERVICE_PROPERTIES_H
diff --git a/Core/Code/Service/mitkServiceReference.h b/Core/Code/Service/mitkServiceReference.h
index 2bb504c8db..2229bb33d3 100644
--- a/Core/Code/Service/mitkServiceReference.h
+++ b/Core/Code/Service/mitkServiceReference.h
@@ -1,239 +1,239 @@
/*=========================================================================
Program: Medical Imaging & Interaction Toolkit
Language: C++
Date: $Date$
Version: $Revision$
Copyright (c) German Cancer Research Center, Division of Medical and
Biological Informatics. All rights reserved.
See MITKCopyright.txt or http://www.mitk.org/copyright.html for details.
This software is distributed WITHOUT ANY WARRANTY; without even
the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. See the above copyright notices for more information.
=========================================================================*/
#ifndef MITKSERVICEREFERENCE_H
#define MITKSERVICEREFERENCE_H
-#include ServiceReference objects from the
* ModuleContext::GetServiceReference and
* ModuleContext::GetServiceReferences methods.
* ServiceReference object may be shared between modules and
* can be used to examine the properties of the service and to get the service
* object.
* ServiceRegistration object and may have multiple, distinct
* ServiceReference objects referring to it.
* ServiceReference objects associated with a
* ServiceRegistration are considered equal
* (more specifically, their operator==()
* method will return true when compared).
* ServiceReference objects associated with different
* ServiceRegistration objects are not equal.
*
* @see ModuleContext::GetServiceReference
* @see ModuleContext::GetServiceReferences
* @see ModuleContext::GetService
* @remarks This class is thread safe.
*/
class MITK_CORE_EXPORT ServiceReference {
public:
/**
* Creates an invalid ServiceReference object. You can use
* this object in boolean expressions and it will evaluate to
* false.
*/
ServiceReference();
ServiceReference(const ServiceReference& ref);
/**
* Converts this ServiceReference instance into a boolean
* expression. If this instance was default constructed or
* the service it references has been unregistered, the conversion
* returns false, otherwise it returns true.
*/
operator bool() const;
/**
* Releases any resources held or locked by this
* ServiceReference and renders it invalid.
*/
ServiceReference& operator=(int null);
~ServiceReference();
/**
* Returns the property value to which the specified property key is mapped
* in the properties ServiceProperties object of the service
* referenced by this ServiceReference object.
*
* ServiceProperties
* object of the service referenced by this ServiceReference
* object.
*
* ServiceReference object.
*
* 0 when the service has been
* unregistered. This can be used to determine if the service has been
* unregistered.
*
* @return The module that registered the service referenced by this
* ServiceReference object; 0 if that
* service has already been unregistered.
* @see ModuleContext::RegisterService(const std::vectorServiceReference object. Specifically, this method returns
* the modules whose usage count for that service is greater than zero.
*
* @param modules A list of modules whose usage count for the service referenced
* by this ServiceReference object is greater than
* zero.
*/
void GetUsingModules(std::vectorServiceReference with the specified
* ServiceReference for order.
*
* ServiceReference and the specified
* ServiceReference have the same {@link ServiceProperties::SERVICE_ID
* service id} they are equal. This ServiceReference is less
* than the specified ServiceReference if it has a lower
* {@link ServiceProperties::SERVICE_RANKING service ranking} and greater if it has a
* higher service ranking. Otherwise, if this ServiceReference
* and the specified ServiceReference have the same
* {@link ServiceProperties::SERVICE_RANKING service ranking}, this
* ServiceReference is less than the specified
* ServiceReference if it has a higher
* {@link ServiceProperties::SERVICE_ID service id} and greater if it has a lower
* service id.
*
* @param reference The ServiceReference to be compared.
* @return Returns a false or true if this
* ServiceReference is less than or greater
* than the specified ServiceReference.
*/
bool operator<(const ServiceReference& reference) const;
bool operator==(const ServiceReference& reference) const;
ServiceReference& operator=(const ServiceReference& reference);
protected:
friend class ModulePrivate;
friend class ModuleContext;
friend class ServiceFilter;
friend class ServiceRegistrationPrivate;
friend class ServiceListeners;
friend class LDAPFilter;
templateServiceRegistration object when a
* ModuleContext#RegisterService() method invocation is successful.
* The ServiceRegistration object is for the private use of the
* registering module and should not be shared with other modules.
* ServiceRegistration object may be used to update the
* properties of the service or to unregister the service.
*
* @see ModuleContext#RegisterService()
* @remarks This class is thread safe.
*/
class MITK_CORE_EXPORT ServiceRegistration {
public:
/**
* Creates an invalid ServiceRegistration object. You can use
* this object in boolean expressions and it will evaluate to
* false.
*/
ServiceRegistration();
ServiceRegistration(const ServiceRegistration& reg);
operator bool() const;
/**
* Releases any resources held or locked by this
* ServiceRegistration and renders it invalid.
*/
ServiceRegistration& operator=(int null);
~ServiceRegistration();
/**
* Returns a ServiceReference object for a service being
* registered.
* ServiceReference object may be shared with other
* modules.
*
* @throws std::logic_error If this
* ServiceRegistration object has already been
* unregistered or if it is invalid.
* @return ServiceReference object.
*/
ServiceReference GetReference() const;
/**
* Updates the properties associated with a service.
*
*
*
*
* @param properties The properties for this service. See {@link ServiceProperties}
* for a list of standard service property keys. Changes should not
* be made to this object after calling this method. To update the
* service's properties this method should be called again.
*
* @throws std::logic_error If this ServiceRegistration
* object has already been unregistered or if it is invalid.
* @throws std::invalid_argument If properties contains
* case variants of the same key name.
*/
void SetProperties(const ServiceProperties& properties);
/**
* Unregisters a service. Remove a ServiceRegistration object
* from the framework service registry. All ServiceRegistration
* objects associated with this ServiceRegistration object
* can no longer be used to interact with the service once unregistration is
* complete.
*
*
*
*
* @throws std::logic_error If this
* ServiceRegistration objects for the service may no longer be
* used to get a service object for the service.
*
* The module's use count for this service is set to zero.
* If the service was registered with a {@link ServiceFactory} object, the
* ServiceFactory#UngetService method is called to release
* the service object for the module.
* ServiceRegistration object has already been
* unregistered or if it is invalid.
* @see ModuleContext#UngetService
* @see ServiceFactory#UngetService
*/
virtual void Unregister();
bool operator<(const ServiceRegistration& o) const;
bool operator==(const ServiceRegistration& registration) const;
ServiceRegistration& operator=(const ServiceRegistration& registration);
protected:
friend class ServiceRegistry;
friend class ServiceReferencePrivate;
friend struct HashServiceRegistration;
ServiceRegistration(ServiceRegistrationPrivate* registrationPrivate);
ServiceRegistration(ModulePrivate* module, itk::LightObject* service,
const ServiceProperties& props);
ServiceRegistrationPrivate* d;
};
}
inline std::ostream& operator<<(std::ostream& os, const mitk::ServiceRegistration& /*reg*/)
{
return os << "mitk::ServiceRegistration object";
}
#endif // MITKSERVICEREGISTRATION_H
diff --git a/Core/Code/Service/mitkServiceRegistry.cpp b/Core/Code/Service/mitkServiceRegistry.cpp
index 3f6644f91f..b295497328 100644
--- a/Core/Code/Service/mitkServiceRegistry.cpp
+++ b/Core/Code/Service/mitkServiceRegistry.cpp
@@ -1,329 +1,331 @@
/*=========================================================================
Program: Medical Imaging & Interaction Toolkit
Language: C++
Date: $Date$
Version: $Revision$
Copyright (c) German Cancer Research Center, Division of Medical and
Biological Informatics. All rights reserved.
See MITKCopyright.txt or http://www.mitk.org/copyright.html for details.
This software is distributed WITHOUT ANY WARRANTY; without even
the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. See the above copyright notices for more information.
=========================================================================*/
#include ServiceTracker class simplifies using services from the
* framework's service registry.
* ServiceTracker object is constructed with search criteria and
* a ServiceTrackerCustomizer object. A ServiceTracker
* can use a ServiceTrackerCustomizer to customize the service
* objects to be tracked. The ServiceTracker can then be opened to
* begin tracking all services in the framework's service registry that match
* the specified search criteria. The ServiceTracker correctly
* handles all of the details of listening to ServiceEvents and
* getting and ungetting services.
* GetServiceReferences method can be called to get references
* to the services being tracked. The GetService and
* GetServices methods can be called to get the service objects for
* the tracked service.
* ServiceTracker class is thread-safe. It does not call a
* ServiceTrackerCustomizer while holding any locks.
* ServiceTrackerCustomizer implementations must also be
* thread-safe.
*
* \tparam S The type of the service being tracked. The type must be an
* assignable datatype. Further, if the
* ServiceTracker(ModuleContext*, ServiceTrackerCustomizer
* constructor is used, the type must have an associated interface id via
* MITK_DECLARE_SERVICE_INTERFACE.
* \tparam T The type of the tracked object. The type must be an assignable
* datatype, provide a boolean conversion function, and provide
* a constructor and an assignment operator which can handle 0 as an argument.
* \remarks This class is thread safe.
*/
templateServiceTracker on the specified
* ServiceReference.
*
* ServiceReference
* will be tracked by this ServiceTracker.
*
* @param context The ModuleContext against which the tracking
* is done.
* @param reference The ServiceReference for the service to be
* tracked.
* @param customizer The customizer object to call when services are added,
* modified, or removed in this ServiceTracker. If
* customizer is null, then this
* ServiceTracker will be used as the
* ServiceTrackerCustomizer and this
* ServiceTracker will call the
* ServiceTrackerCustomizer methods on itself.
*/
ServiceTracker(ModuleContext* context,
const ServiceReference& reference,
ServiceTrackerCustomizerServiceTracker on the specified class name.
*
* ServiceTracker.
*
* @param context The ModuleContext against which the tracking
* is done.
* @param clazz The class name of the services to be tracked.
* @param customizer The customizer object to call when services are added,
* modified, or removed in this ServiceTracker. If
* customizer is null, then this
* ServiceTracker will be used as the
* ServiceTrackerCustomizer and this
* ServiceTracker will call the
* ServiceTrackerCustomizer methods on itself.
*/
ServiceTracker(ModuleContext* context, const std::string& clazz,
ServiceTrackerCustomizerServiceTracker on the specified
* LDAPFilter object.
*
* LDAPFilter object will be
* tracked by this ServiceTracker.
*
* @param context The ModuleContext against which the tracking
* is done.
* @param filter The LDAPFilter to select the services to be
* tracked.
* @param customizer The customizer object to call when services are added,
* modified, or removed in this ServiceTracker. If
* customizer is null, then this ServiceTracker will be
* used as the ServiceTrackerCustomizer and this
* ServiceTracker will call the
* ServiceTrackerCustomizer methods on itself.
*/
ServiceTracker(ModuleContext* context, const LDAPFilter& filter,
ServiceTrackerCustomizerServiceTracker on the class template
* argument S.
*
* ServiceTracker.
*
* @param context The ModuleContext against which the tracking
* is done.
* @param customizer The customizer object to call when services are added,
* modified, or removed in this ServiceTracker. If
* customizer is null, then this ServiceTracker will be
* used as the ServiceTrackerCustomizer and this
* ServiceTracker will call the
* ServiceTrackerCustomizer methods on itself.
*/
ServiceTracker(ModuleContext* context, ServiceTrackerCustomizerServiceTracker and begin tracking services.
*
* ServiceTracker was created are now tracked by this
* ServiceTracker.
*
* @throws std::logic_error If the ModuleContext
* with which this ServiceTracker was created is no
* longer valid.
*/
virtual void Open();
/**
* Close this ServiceTracker.
*
* ServiceTracker should
* end the tracking of services.
*
* ServiceTracker. This method will also return when this
* ServiceTracker is closed.
*
* WaitForService is not used
* during the calling of the ModuleActivator methods.
* ModuleActivator methods are expected to complete in a short
* period of time.
*
* ServiceReferences for all services being
* tracked by this ServiceTracker.
*
* @param refs List of ServiceReferences.
*/
virtual void GetServiceReferences(std::listServiceReference for one of the services being
* tracked by this ServiceTracker.
*
* service.ranking property) is
* returned. If there is a tie in ranking, the service with the lowest
* service ID (as specified in its service.id property); that
* is, the service that was registered first is returned. This is the same
* algorithm used by ModuleContext::GetServiceReference().
*
* ServiceReference for a tracked service.
* @throws ServiceException if no services are being tracked.
*/
virtual ServiceReference GetServiceReference() const;
/**
* Returns the service object for the specified
* ServiceReference if the specified referenced service is
* being tracked by this ServiceTracker.
*
* @param reference The reference to the desired service.
* @return A service object or null if the service referenced
* by the specified ServiceReference is not being
* tracked.
*/
virtual T GetService(const ServiceReference& reference) const;
/**
* Return a list of service objects for all services being tracked by this
* ServiceTracker.
*
* ServiceTracker.
*
* %GetService(%GetServiceReference()).
*
* @return A service object or null if no services are being
* tracked.
*/
virtual T GetService() const;
/**
* Remove a service from this ServiceTracker.
*
* The specified service will be removed from this
* ServiceTracker. If the specified service was being tracked
* then the ServiceTrackerCustomizer::RemovedService method will
* be called for that service.
*
* @param reference The reference to the service to be removed.
*/
virtual void Remove(const ServiceReference& reference);
/**
* Return the number of services being tracked by this
* ServiceTracker.
*
* @return The number of services being tracked.
*/
virtual int Size() const;
/**
* Returns the tracking count for this ServiceTracker.
*
* The tracking count is initialized to 0 when this
* ServiceTracker is opened. Every time a service is added,
* modified or removed from this ServiceTracker, the tracking
* count is incremented.
*
* ServiceTracker has added, modified or removed a service by
* comparing a tracking count value previously collected with the current
* tracking count value. If the value has not changed, then no service has
* been added, modified or removed from this ServiceTracker
* since the previous tracking count was collected.
*
* @return The tracking count for this ServiceTracker or -1 if
* this ServiceTracker is not open.
*/
virtual int GetTrackingCount() const;
/**
* Return a sorted map of the ServiceReferences and
* service objects for all services being tracked by this
* ServiceTracker. The map is sorted in natural order
* of ServiceReference. That is, the last entry is the service
* with the highest ranking and the lowest service id.
*
* @param tracked A TrackingMap with the ServiceReferences
* and service objects for all services being tracked by this
* ServiceTracker. If no services are being tracked,
* then the returned map is empty.
*/
virtual void GetTracked(TrackingMap& tracked) const;
/**
* Return if this ServiceTracker is empty.
*
* @return true if this ServiceTracker is not tracking any
* services.
*/
virtual bool IsEmpty() const;
protected:
/**
* Default implementation of the
* ServiceTrackerCustomizer::AddingService method.
*
* ServiceTracker has been
* constructed with a null ServiceTrackerCustomizer argument.
*
* GetService
* on the ModuleContext with which this
* ServiceTracker was created passing the specified
* ServiceReference.
* ServiceTracker.
* @return The service object to be tracked for the service added to this
* ServiceTracker.
* @see ServiceTrackerCustomizer::AddingService(const ServiceReference&)
*/
T AddingService(const ServiceReference& reference);
/**
* Default implementation of the
* ServiceTrackerCustomizer::ModifiedService method.
*
* ServiceTracker has been
* constructed with a null ServiceTrackerCustomizer argument.
*
* ServiceTrackerCustomizer::RemovedService method.
*
* ServiceTracker has been
* constructed with a null ServiceTrackerCustomizer argument.
*
* UngetService, on the
* ModuleContext with which this ServiceTracker
* was created, passing the specified ServiceReference.
*