org.osgi.service.remoteserviceadmin
Interface EndpointEventListener
@ConsumerType
public interface EndpointEventListener
A white board service that represents a listener for endpoints.
An Endpoint Event Listener represents a participant in the distributed model
that is interested in Endpoint Descriptions.
This white board service can be used in many different scenarios. However,
the primary use case is to allow a remote manager to be informed of Endpoint
Descriptions available in the network and inform the network about available
Endpoint Descriptions.
Both the network bundle and the manager bundle register an Endpoint Event
Listener service. The manager informs the network bundle about Endpoints that
it creates. The network bundles then uses a protocol like SLP to announce
these local end-points to the network.
If the network bundle discovers a new Endpoint through its discovery
protocol, then it sends an Endpoint Description to all the Endpoint Listener
services that are registered (except its own) that have specified an interest
in that endpoint.
Endpoint Event Listener services can express their scope with the
service property ENDPOINT_LISTENER_SCOPE
. This service property is a
list of filters. An Endpoint Description should only be given to a Endpoint
Event Listener when there is at least one filter that matches the Endpoint
Description properties.
This filter model is quite flexible. For example, a discovery bundle is only
interested in locally originating Endpoint Descriptions. The following filter
ensures that it only sees local endpoints.
(org.osgi.framework.uuid=72dc5fd9-5f8f-4f8f-9821-9ebb433a5b72)
In the same vein, a manager that is only interested in remote Endpoint
Descriptions can use a filter like:
(!(org.osgi.framework.uuid=72dc5fd9-5f8f-4f8f-9821-9ebb433a5b72))
Where in both cases, the given UUID is the UUID of the local framework that
can be found in the Framework properties.
The Endpoint Event Listener's scope maps very well to the service hooks. A
manager can just register all filters found from the Listener Hook as its
scope. This will automatically provide it with all known endpoints that match
the given scope, without having to inspect the filter string.
In general, when an Endpoint Description is discovered, it should be
dispatched to all registered Endpoint Event Listener services. If a new
Endpoint Event Listener is registered, it should be informed about all
currently known Endpoints that match its scope. If a getter of the Endpoint
Listener service is unregistered, then all its registered Endpoint
Description objects must be removed.
The Endpoint Event Listener models a best effort approach.
Participating bundles should do their utmost to keep the listeners up to
date, but implementers should realize that many endpoints come through
unreliable discovery processes.
The Endpoint Event Listener supersedes the EndpointListener
interface
as it also supports notifications around modifications of endpoints.
- Since:
- 1.1
- ThreadSafe:
Field Summary |
static java.lang.String |
ENDPOINT_LISTENER_SCOPE
Specifies the interest of this listener with filters. |
ENDPOINT_LISTENER_SCOPE
static final java.lang.String ENDPOINT_LISTENER_SCOPE
- Specifies the interest of this listener with filters. This listener is
only interested in Endpoint Descriptions where its properties match the
given filter. The type of this property must be
String+
.
- See Also:
- Constant Field Values
endpointChanged
void endpointChanged(EndpointEvent event,
java.lang.String filter)
- Notification that an endpoint has changed.
Details of the change is captured in the Endpoint Event provided. This
could be that an endpoint was added, removed or modified.
- Parameters:
event
- The event containing the details about the change.filter
- The filter from the ENDPOINT_LISTENER_SCOPE
that
matches (or for EndpointEvent.MODIFIED_ENDMATCH
and
EndpointEvent.REMOVED
used to match) the endpoint, must
not be null
.