Imported Service Filters

Bundles that wish to filter imported services based on their registered properties should override the method start() as follows:

   protected void start() {
     String filter = "(&(cn=simona)(o=OTI)(c=US))";
     addImportedServiceFilter(CounterService.SERVICE_NAME, filter);
   }

In the start() method a filter is added for the imported CounterService by calling the configuration method addImportedServiceFilter(String, String).
The service filter must be a valid LDAP filter.
Once a service filter has been set, SAT only acquires a service if it matches the specified service filter.
If multiple services exist that match the specified service filter, the service with the highest service.ranking attribute is chosen. If two or more services are tied with the same service.ranking attribute, the service with the lowest service.id attribute is chosen.
If a bundle fails to acquire an imported service, because a service matching its specified filter could not be found, a warning is issued to help understand why the bundle has not been activated:

> SAT Warning: Failed to acquire service matching the filter <Filter>.
> Service: <Service-Name>
> Source: <Bundle-SymbolicName>

SAT warns against LDAP filters that contains whitespace after an equals-operator and before a close parenthesis.

> SAT Warning: LDAP filter contains questionable whitespace  - <Filter>.
> Service: <Service-Name>
> Source: <Bundle-SymbolicName>

The configuration method addImportedServiceFilter(String, String) can also be used to change a bundles imported service filter, even after the imported service has been acquired.
The configuration method removeImportedServiceFilter(String) can be used to remove an imported service filter, even after the imported service has been acquired.
It is important to understand that when a bundle modifies an imported service filter using addImportedServiceFilter(String, String), SAT will compare the acquired service with the filter, and possibly release it if its service attributes do not match the new filter.
If SAT releases a service because its service attributes do not match the new filter, SAT will attempt to acquire another service with matching attributes. If another service with matching attributes cannot be acquired, SAT will issue a warning.