/* * Copyright (c) 2013 Cisco Systems, Inc. and others. All rights reserved. * * This program and the accompanying materials are made available under the * terms of the Eclipse Public License v1.0 which accompanies this distribution, * and is available at http://www.eclipse.org/legal/epl-v10.html */ package org.opendaylight.controller.sal.binding.api; import org.opendaylight.yangtools.concepts.ListenerRegistration; import org.opendaylight.yangtools.yang.binding.Notification; /** * Notification broker which allows clients to subscribe for and publish YANG-modeled notifications. * *
* Two styles of listeners are supported: *
{ModelName}Listener
interface,
* which has dispatch methods for each defined notification. Methods are invoked based on notification type (class).
*
* A generic listener implements the {@link NotificationListener} interface which has one callback method
* onNotification
that is invoked for any notification type the listener is subscribed to.
*
* A generic listener is subscribed using the {@link #registerNotificationListener(Class, NotificationListener)} * method by which you specify the type of notification to receive. A generic listener may be registered for * multiple notification types via multiple subscriptions. *
* Generic listeners allow for a more flexible approach, allowing you to subscribe for just * one type of notification from a YANG model. You could also have a general subscription * for all notification in the system via *
* service.registerNotificationListener(Notification.class, listener); ** *
* A dispatch listener implements a YANG-generated module interface {ModuleName}Listener
* which handles all the notifications defined in the YANG model. Each notification type translates to
* a specific method of the form on{NotificationType}
on the generated interface.
* The generated interface also extends the
* {@link org.opendaylight.yangtools.yang.binding.NotificationListener} interface and implementations
* are registered using {@link #registerNotificationListener(org.opendaylight.yangtools.yang.binding.NotificationListener)}
* method.
*
*
* Lets assume we have following YANG model: * *
* module example { * ... * * notification start { * ... * } * * notification stop { * ... * } * } ** * The generated interface will be: *
* public interface ExampleListener extends NotificationListener { * void onStart(Start notification); * void onStop(Stop notification); * } ** The following defines an implementation of the generated interface: *
* public class MyExampleListener implements ExampleListener { * public void onStart(Start notification) { * // do something * } * * public void onStop(Stop notification) { * // do something * } * } ** The implementation is registered as follows: *
* MyExampleListener listener = new MyExampleListener(); * ListenerRegistration* Thereg = service.registerNotificationListener( listener ); *
onStart
method will be invoked when someone publishes a Start
notification and
* the onStop
method will be invoked when someone publishes a Stop
notification.
*/
public interface NotificationService extends BindingAwareService {
/**
* Registers a generic listener implementation for a specified notification type.
*
* @param notificationType the YANG-generated interface of the notification type.
* @param listener the listener implementation that will receive notifications.
* @return a {@link ListenerRegistration} instance that should be used to unregister the listener
* by invoking the {@link ListenerRegistration#close()} method when no longer needed.
*/