A lightweight functional DSL to interact with OSGi registry.
This DSL provides a set of operations to fetch service references and configurations from OSGi, as well as to register services back into OSGi registry. It also provides a way to create new custom operations.
This documentation is still work in progress
One of the benefits of using this DSL is that operations are automatically bound to the service or configuration intances that triggered their execution. This allows them to automatically undo (or clean) when those instances are no longer available. This way the user of the DSL does not need to manually account for the tracked instances and ensure the proper cleaning, which is a source of mistakes. For those cases in which manual assistance is needed, such as side effects management, the DSL facilitates specifying the undo operation together with the side effect. This allows for better reutilization.
The DSL runs without the need for any additional runtime.
The foundation of the DSL is one type OSGi<T>. There exist several static
functions defined on the OSGi class that provide us with instances of the
type. Let's start getting a reference to a service:
OSGi<Service> program = OSGi.service(OSGi.serviceReferences(Service.class));if we allow static imports from OSGi class we can type the former as:
OSGi<Service> services = service(serviceReferences(Service.class));
OSGi<Dictionary<String, ?>> configurations = configurations("factory-pid");Once we have instances of OSGi we can combine them. We can use flatMap to
specify that one operation depends on a previous one. For example we could need
to specify a filter for the services that comes in the configuration:
OSGi<Service> services = configurations("factory-pid").flatMap(conf ->
service(serviceReferences(Service.class, conf.get("service.filter").toString()))
);we can also register instances. For this purpose let's create a new class that
will hold instances of both Dictionary<String, ?> and Service.
class Holder {
Dictionary<String, ?> properties;
Service service;
public Holder(Dictionary<String, ?> properties, Service service) {
this.properties = properties;
this.service = service;
}
}and we can register instances of that class with:
OSGi<ServiceRegistration<Holder>> program = configurations("factory-pid").flatMap(conf ->
service(serviceReferences(Service.class, conf.get("service.filter").toString())).flatMap(service ->
register(Holder.class, new Holder(conf, service), new HashMap<>())));in this example we are tracking factory configurations from pid
factory-pid. For each configuration factory that's there, or that's created in
the future, we get the property service.filter and use it's value to track
services of type Service that match the filter in the configuration. Then, for
each service that matches that filter and each configuration factory
combination we register one Holder instance.
If any of the configuration factories goes away, or any of the tracked services
goes away, the corresponding Holder instances will be unregistered
automatically, since the DSL tracks the effects each instance has produced.
In the previous section we have gone through combining different operations to produce new instances. These instances are values that describe how we are going to interact with OSGi and are immutable. You can use them to produce new programs like reusable components.
Once you have a complete specification you can run it passing a BundleContext
to it:
OSGi<T> program;
BundleContext bundleContext;
OSGiResult result = program.run(bundleContext);the OSGiResult instance references the execution of the program. To stop and
clean it we call:
result.close()we can also specify combinations when there exist no dependencies between the
operations. For instance we can declare we want to register a Holder for every
configuration + service combination using OSGi.combine:
OSGi<Holder> holders = combine(Holder::new, configurations("factory.pid"), services(Service.class));the DSL comes with some common operations defined on the OSGi type. All these operations produce values of a type and keep track of the next operations. When a tracked value goes away all the associated operations will be cleaned as well.
There are two operations to deal with Configuration Admin configurations:
OSGi.configuration to deal with singleton configurations and
OSGi.configurations to deal with factory configurations.
OSGi.serviceReferences is a set of overloaded functions that return operations
of type OSGi<CachingServiceReference>:
OSGi<CachingServiceReference<T>> serviceReferences(Class<T> clazz)
OSGi<CachingServiceReference<Object>> serviceReferences(String filterString)
OSGi<CachingServiceReference<T>> serviceReferences(Class<T> clazz, String filterString)
OSGi<CachingServiceReference<T>> serviceReferences(
Class<T> clazz, String filterString,
Refresher<? super CachingServiceReference<T>> onModified)
OSGi<CachingServiceReference<T>> serviceReferences(
Class<T> clazz, Refresher<? super CachingServiceReference<T>> onModified)
OSGi<CachingServiceReference<Object>> serviceReferences(
String filterString,
Refresher<? super CachingServiceReference<Object>> onModified)This class is an explicit wrapper around ServiceReference (it DOES NOT
implement ServiceReference) and provides methods to access underlying
ServiceReference properties and caches them so future access to the
same properties return the same values.
Property values are cached on demand. Values that have never been queried through the method are not cached.
Properties that did not exist when queried will no longer exist even though
they were available at a later time in the underlying ServiceReference.
This class was introduced because ServiceReference is mutable, which made it
very difficult to operate on it within the DSL in a safe manner.
This class is just an alias for Predicate<T>. serviceReferences operations
will invoke the Refresher to know if the modified instance needs to be
retracted and reintroduced in the execution. If no refresher is passed
serviceReferences will check CachingServiceReference.isDirty().
There are two sets of overloaded operations that allow to get services from
CachingServiceReference or ServiceReference: service and prototypes.
service will get services invoking bundleContext.getService and unget them
using bundleContext.ungetServices. prototypes, on the other hand, will
produce a ServiceObjects instance. It will be the responsability of the user
to properly balance getService and ungetService calls to ServiceObjects.
bundleContext operation will produce the BundleContext in use by that piece
of program. It will normally be the one used to invoke OSGi.run unless it is
changed using OSGi.changeContext(BundleContext bundleContext, OSGi<T> program)
for that particular program.
just set of operations allows to wrap any value inside a OSGi type. It is
overloaded to support Supplier and Collection. If a collection is passed it
will produce the elements of the list in the order given by the collection.
nothing, as it name suggests, is a termination operation. Anything depending
on the result of nothing operation should never be executed.
One common operation when using OSGi is service registration. For that purpose
the library offers register set of functions. When the associated instances
are retracted, register set of functions also unregister their instances as a
result.
OSGi<ServiceRegistration<T>> register(
Class<T> clazz, ServiceFactory<T> service,
Map<String, Object> properties)
OSGi<ServiceRegistration<?>> register(
String[] classes, Object service, Map<String, ?> properties)
OSGi<ServiceRegistration<T>> register(
Class<T> clazz, Supplier<T> service,
Supplier<Map<String, ?>> properties)
OSGi<ServiceRegistration<T>> register(
Class<T> clazz, ServiceFactory<T> service,
Supplier<Map<String, ?>> properties)
OSGi<ServiceRegistration<?>> register(
String[] classes, Supplier<Object> service,
Supplier<Map<String, ?>> properties)OSGi<T> all(OSGi<T> ... programs) will execute all given programs and produce
all the elements that the given programs produce.
OSGi<T> coalesce(OSGi<T> ... programs), just as its homonymous SQL function,
coalesce will produce the value of the first producing program that is being
given as argument, from left to right. Since OSGi is a dynamic environment
coalesce will retract and reintroduce instances when needed. For example:
OSGi<Dictionary<String, ?>> props = coalesce(
configuration("some.config.pid"),
just(Hashtable::new)
);this operation will return an empty Hashtable while no configuration is
available. If, at any moment, there is a configuration available the operation
will retract the empty Hashtable and introduce the incoming configuration. If,
at any moment, the configuration is deleted, the operation will retract the
Dictionary associated with that configuration and reintroduce the empty
Hashtable.
This is very useful to model defaults or to model different level for preferred services, from more specific to more general.
OSGi.combine set of functions is the Applicative implementation for OSGi
class. It produces the result of the invocation to the given function with all
the combinations of the values produced by the given operations.
OSGi.once will just let the first instance produced by the given operation to
pass. Further instances won't be published. Actually once does not support any
order so it can't decide that any instance is more suitable than any other.
once will update a counter with the instances that it encounters and that are
retracted. It won't retract the instance it produces until all the instances it
has seen are gone.
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.