osgi/bundles/org.eclipse.osgi.services.remoteserviceadmin/src/org/osgi/service/remoteserviceadmin/EndpointEventListener.java

/*
 * Copyright (c) OSGi Alliance (2013, 2015). All Rights Reserved.
 *
 * Licensed 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.
 */

package org.osgi.service.remoteserviceadmin;

import org.osgi.annotation.versioning.ConsumerType;

/**
 * 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 <i>scope</i> with the
 * service property {@link #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.
 * 
 * <pre>
 *   (org.osgi.framework.uuid=72dc5fd9-5f8f-4f8f-9821-9ebb433a5b72)
 * </pre>
 * 
 * In the same vein, a manager that is only interested in remote Endpoint
 * Descriptions can use a filter like:
 * 
 * <pre>
 *   (!(org.osgi.framework.uuid=72dc5fd9-5f8f-4f8f-9821-9ebb433a5b72))
 * </pre>
 * 
 * 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 <i>best effort</i> 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 {@link EndpointListener} interface
 * as it also supports notifications around modifications of endpoints.
 * 
 * @ThreadSafe
 * @since 1.1
 */
@ConsumerType
public interface EndpointEventListener {
	/**
	 * 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 {@code String+}.
	 */
	String	ENDPOINT_LISTENER_SCOPE	= "endpoint.listener.scope";

	/**
	 * 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.
	 * 
	 * @param event The event containing the details about the change.
	 * @param filter The filter from the {@link #ENDPOINT_LISTENER_SCOPE} that
	 *        matches (or for {@link EndpointEvent#MODIFIED_ENDMATCH} and
	 *        {@link EndpointEvent#REMOVED} used to match) the endpoint, must
	 *        not be {@code null}.
	 */
	void endpointChanged(EndpointEvent event, String filter);
}