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()
.
ServiceReference
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.