YMS broker and Notification handler
Change-Id: Ic3659b2c2ad26ea2db1f03725b4883f19db2cc41
diff --git a/apps/yms/api/src/main/java/org/onosproject/yms/ynh/YangNotification.java b/apps/yms/api/src/main/java/org/onosproject/yms/ynh/YangNotification.java
new file mode 100644
index 0000000..48e9807
--- /dev/null
+++ b/apps/yms/api/src/main/java/org/onosproject/yms/ynh/YangNotification.java
@@ -0,0 +1,74 @@
+/*
+ * Copyright 2015-present Open Networking Laboratory
+ *
+ * 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.onosproject.yms.ynh;
+
+import org.onosproject.yms.ydt.YdtContext;
+
+/**
+ * Represents YANG notification which is a subject of YANG based event.
+ *
+ * YMS add themselves as a listener to applications. Application sends
+ * their notification in YANG utils generated notification. YMS obtains
+ * the module/sub-module schema tree in which this notification is contained
+ * and then convert this data to an abstract tree notation (YDT) with root
+ * node as the logical node with name "yangnotification" it contains
+ * module/sub-module node in which notification is contained.
+ * It sends the same to all the protocol who has added them as a listener
+ * as a YANG notification.
+ *
+ * This class represents YANG notification which contains the
+ * notification context in abstract tree notation.
+ */
+public class YangNotification {
+
+ /**
+ * YANG notification in form of abstract tree notation (YDT)
+ * Root node of notification root context will be logical node with
+ * name as "yangnotification", it contains module/sub-module node
+ * in which notification is contained.
+ */
+ YdtContext notificationRootContext;
+
+ /**
+ * Creates an instance of YANG notification subject.
+ *
+ * @param notificationContext logical root node with name as
+ * "yangnotification"
+ */
+ public YangNotification(YdtContext notificationContext) {
+ this.notificationRootContext = notificationContext;
+ }
+
+ /**
+ * Assign the YANG modeled notification data.
+ *
+ * @param notificationRootContext YANG data tree containing the data for
+ * the notification
+ */
+ public void setNotificationRootContext(YdtContext notificationRootContext) {
+ this.notificationRootContext = notificationRootContext;
+ }
+
+ /**
+ * Returns YANG notification data.
+ *
+ * @return YANG data tree containing the data for the notification
+ */
+ public YdtContext getNotificationRootContext() {
+ return notificationRootContext;
+ }
+}
diff --git a/apps/yms/api/src/main/java/org/onosproject/yms/ynh/YangNotificationEvent.java b/apps/yms/api/src/main/java/org/onosproject/yms/ynh/YangNotificationEvent.java
new file mode 100644
index 0000000..ca3292d
--- /dev/null
+++ b/apps/yms/api/src/main/java/org/onosproject/yms/ynh/YangNotificationEvent.java
@@ -0,0 +1,52 @@
+/*
+ * Copyright 2016-present Open Networking Laboratory
+ *
+ * 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.onosproject.yms.ynh;
+
+import org.onosproject.event.AbstractEvent;
+
+/**
+ * Represents YANG notification event.
+ *
+ * YANG notification handler listens for the notification from the application.
+ * It convert the received notification in YANG notification events.
+ *
+ * YangNotificationEvent represents event generated by YANG management system
+ * in response to the YANG defined application notification. The applications
+ * notification information is in abstract YANG data tree.
+ */
+public class YangNotificationEvent
+ extends AbstractEvent<YangNotificationEvent.Type, YangNotification> {
+
+ /**
+ * Event type is the notification as defined in the YANG file.
+ */
+ public enum Type {
+ /**
+ * Indicates a YANG notification.
+ */
+ YANG_NOTIFICATION
+ }
+
+ /**
+ * YANG notification information shared to NBI protocol in YANG data tree
+ * using the registered callback.
+ *
+ * @param subject notification information in YANG data tree.
+ */
+ public YangNotificationEvent(YangNotification subject) {
+ super(Type.YANG_NOTIFICATION, subject);
+ }
+}
diff --git a/apps/yms/api/src/main/java/org/onosproject/yms/ynh/YangNotificationListener.java b/apps/yms/api/src/main/java/org/onosproject/yms/ynh/YangNotificationListener.java
new file mode 100644
index 0000000..eeca157
--- /dev/null
+++ b/apps/yms/api/src/main/java/org/onosproject/yms/ynh/YangNotificationListener.java
@@ -0,0 +1,28 @@
+/*
+ * Copyright 2016-present Open Networking Laboratory
+ *
+ * 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.onosproject.yms.ynh;
+
+import org.onosproject.event.EventListener;
+
+/**
+ * Abstraction of listener for YANG notification handler events.
+ * NBI protocols/interfaces supporting YANG notification needs to implement
+ * YANG notification listener and add themselves as a listener to YANG
+ * notification event.
+ */
+public interface YangNotificationListener
+ extends EventListener<YangNotificationEvent> {
+}
diff --git a/apps/yms/api/src/main/java/org/onosproject/yms/ynh/YangNotificationService.java b/apps/yms/api/src/main/java/org/onosproject/yms/ynh/YangNotificationService.java
index 1beb498..a32f45f 100644
--- a/apps/yms/api/src/main/java/org/onosproject/yms/ynh/YangNotificationService.java
+++ b/apps/yms/api/src/main/java/org/onosproject/yms/ynh/YangNotificationService.java
@@ -16,17 +16,86 @@
package org.onosproject.yms.ynh;
+import org.onosproject.event.ListenerService;
+
/**
* Abstraction of an entity which provides interfaces to YANG notification
- * service. YNH handles notification from the application/core and provide
- * it to the protocols.
- * <p>
+ * service. YANG notification handler receives the event notifications from
+ * application/core and provide it to the protocols.
+ *
* NBI Protocols which can support notification delivery for application(s)
* needs to add themselves as a listeners with YANG notification service.
- * Protocols can use YANG notification service to check if a received
+ * Also based on registered schema YMS add themselves as a listener to
+ * applications. Application sends their notification in YANG utils generated
+ * notification. YMS obtains the module/sub-module schema tree in which this
+ * notification is contained and then convert this data to an abstract tree
+ * notation (YDT) with root node as the module/sub-module node in which
+ * notification is contained. It sends the same to all the protocol who has
+ * added them as a listener as a YANG notification.
+ *
+ * Also Protocols can use YANG notification service to check if a received
* notification should be filtered against any of their protocol specific
* filtering mechanism.
*/
-public interface YangNotificationService {
- //TODO
+public interface YangNotificationService
+ extends ListenerService<YangNotificationEvent,
+ YangNotificationListener> {
+
+ /*
+ * Example of a use case of notification filtering.
+ * The following example illustrates how to select fault events which
+ * have severities of critical, major, or minor. The filtering criteria
+ * evaluation is as follows:
+ *
+ * ((fault & severity=critical) | (fault & severity=major) | (fault &
+ * severity=minor))
+ *
+ * <netconf:rpc netconf:message-id="101"
+ * xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
+ * <create-subscription
+ * xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
+ * <filter netconf:type="subtree">
+ * <event xmlns="http://example.com/event/1.0">
+ * <eventClass>fault</eventClass>
+ * <severity>critical</severity>
+ * </event>
+ * <event xmlns="http://example.com/event/1.0">
+ * <eventClass>fault</eventClass>
+ * <severity>major</severity>
+ * </event>
+ * <event xmlns="http://example.com/event/1.0">
+ * <eventClass>fault</eventClass>
+ * <severity>minor</severity>
+ * </event>
+ * </filter>
+ * </create-subscription>
+ * </netconf:rpc>
+ */
+
+ /**
+ * Protocols have their own mechanism to support notification filtering
+ * or notification subscription. Depending on the protocol specification,
+ * the filtering is implemented in the protocol.
+ * The Protocol implementations are abstracted of the Schema, there are
+ * scenarios in which they need to check if the received notification
+ * is of interest as per the schema filtering / subscription.
+ * In such scenario, protocols can create a filtering / subscription YANG
+ * data tree and use the notification service to filter the notification
+ * subject against their filter.
+ *
+ * Filters the notification subject YANG data tree, with the specified
+ * filter of the NBI protocol. If the filter does not match for the
+ * passed notification subject, null will be returned.
+ * Otherwise, the part of the subject matching the filter will be returned.
+ *
+ * @param notificationSubject YANG notification subject reported by YANG
+ * notification service.
+ * @param notificationFilter Protocols data model specific notification
+ * filter represented in YANG data tree.
+ * @return filtered notification which passes the data model specific
+ * notification filter.
+ */
+ YangNotification getFilteredSubject(YangNotification notificationSubject,
+ YangNotification notificationFilter);
+
}
diff --git a/apps/yms/api/src/main/java/org/onosproject/yms/ynh/package-info.java b/apps/yms/api/src/main/java/org/onosproject/yms/ynh/package-info.java
index 4c62822..0d3f6c5 100644
--- a/apps/yms/api/src/main/java/org/onosproject/yms/ynh/package-info.java
+++ b/apps/yms/api/src/main/java/org/onosproject/yms/ynh/package-info.java
@@ -17,14 +17,11 @@
/**
* Provides interfaces to YANG notification handler. YNH handles notification
* from the application and provide it to the protocols.
- */
-
-/**
- * Provides interfaces to YANG notification service.
*
* NBI Protocols which can support notification delivery for application(s)
- * needs to add themselves as a listeners with YANG notification service.
- * Protocols can use YANG notification service to check if a received
+ * need to add themselves as a listeners with YANG notification service.
+ *
+ * Also protocols can use YANG notification service to check if a received
* notification should be filtered against any of their protocol specific
* filtering mechanism.
*/