Clarify the semantics of put{Configuration,Operational}Data() 07/5107/1
authorRobert Varga <rovarga@cisco.com>
Mon, 3 Feb 2014 18:40:03 +0000 (19:40 +0100)
committerRobert Varga <rovarga@cisco.com>
Mon, 3 Feb 2014 18:40:03 +0000 (19:40 +0100)
This just adds documentation to how the put operations interact with
pre-existing data.

Change-Id: I01979df6a22f1a6d16c04c2cb0b97d7472d62040
Signed-off-by: Robert Varga <rovarga@cisco.com>
opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/DataModification.java

index d74b26d..29ba192 100644 (file)
@@ -37,8 +37,46 @@ public interface DataModification<P/* extends Path<P> */, D> extends DataChange<
     @Deprecated
     void putRuntimeData(P path, D data);
 
+    /**
+     * Store a piece of data at specified path. This acts as a merge operation,
+     * which is to say that any pre-existing data which is not explicitly
+     * overwritten will be preserved. This means that if you store a container,
+     * its child lists will be merged. Performing the following put operations:
+     *
+     * 1) container { list [ a ] }
+     * 2) container { list [ b ] }
+     *
+     * will result in the following data being present:
+     *
+     * container { list [ a, b ] }
+     *
+     * This also means that storing the container will preserve any augmentations
+     * which have been attached to it.
+     *
+     * If you require an explicit replace operation, perform
+     * {@link removeOperationalData} first.
+     */
     void putOperationalData(P path, D data);
 
+    /**
+     * Store a piece of data at specified path. This acts as a merge operation,
+     * which is to say that any pre-existing data which is not explicitly
+     * overwritten will be preserved. This means that if you store a container,
+     * its child lists will be merged. Performing the following put operations:
+     *
+     * 1) container { list [ a ] }
+     * 2) container { list [ b ] }
+     *
+     * will result in the following data being present:
+     *
+     * container { list [ a, b ] }
+     *
+     * This also means that storing the container will preserve any augmentations
+     * which have been attached to it.
+     *
+     * If you require an explicit replace operation, perform
+     * {@link removeConfigurationData} first.
+     */
     void putConfigurationData(P path, D data);
 
     /**

©2013 OpenDaylight, A Linux Foundation Collaborative Project. All Rights Reserved.
OpenDaylight is a registered trademark of The OpenDaylight Project, Inc.
Linux Foundation and OpenDaylight are registered trademarks of the Linux Foundation.
Linux is a registered trademark of Linus Torvalds.