/*
 * 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.md.sal.common.api.data;

import java.util.Map;
import java.util.Set;
import java.util.concurrent.Future;

import org.opendaylight.controller.md.sal.common.api.TransactionStatus;
// FIXME: After 0.6 Release of YANGTools refactor to use Path marker interface for arguments.
// import org.opendaylight.yangtools.concepts.Path;
import org.opendaylight.yangtools.yang.common.RpcResult;

public interface DataModification<P/* extends Path<P> */, D> extends DataChange<P, D>, DataReader<P, D> {

    /**
     * Returns transaction identifier
     * 
     * @return Transaction identifier
     */
    Object getIdentifier();

    TransactionStatus getStatus();

    /**
     * 
     * @deprecated Use {@link #putOperationalData(Object, Object)} instead.
     * 
     * @param path
     * @param data
     */
    @Deprecated
    void putRuntimeData(P path, D data);

    void putOperationalData(P path, D data);

    void putConfigurationData(P path, D data);

    /**
     * @deprecated Use {@link #removeOperationalData(Object)}
     * 
     * @param path
     */
    @Deprecated
    void removeRuntimeData(P path);

    void removeOperationalData(P path);

    void removeConfigurationData(P path);

    /**
     * Initiates a two-phase commit of modification.
     * 
     * <p>
     * The successful commit changes the state of the system and may affect
     * several components.
     * 
     * <p>
     * The effects of successful commit of data are described in the
     * specifications and YANG models describing the Provider components of
     * controller. It is assumed that Consumer has an understanding of this
     * changes.
     * 
     * 
     * @see DataCommitHandler for further information how two-phase commit is
     *      processed.
     * @param store
     *            Identifier of the store, where commit should occur.
     * @return Result of the Commit, containing success information or list of
     *         encountered errors, if commit was not successful. The Future
     *         blocks until {@link TransactionStatus#COMMITED} or
     *         {@link TransactionStatus#FAILED} is reached.
     */
    Future<RpcResult<TransactionStatus>> commit();

}

@@ -1203,49 +1203,1555 @@
     
-void putOperationalData(P path, D data);%0A
+/**%0A     * Store a piece of data at specified path. This acts as a merge operation,%0A     * which is to say that any pre-existing data which is not explicitly%0A     * overwritten will be preserved. This means that if you store a container,%0A     * its child lists will be merged. Performing the following put operations:%0A     *%0A     * 1) container %7B list %5B a %5D %7D%0A     * 2) container %7B list %5B b %5D %7D%0A     *%0A     * will result in the following data being present:%0A     *%0A     * container %7B list %5B a, b %5D %7D%0A     *%0A     * This also means that storing the container will preserve any augmentations%0A     * which have been attached to it.%0A     *%0A     * If you require an explicit replace operation, perform%0A     * %7B@link removeOperationalData%7D first.%0A     */%0A    void putOperationalData(P path, D data);%0A%0A    /**%0A     * Store a piece of data at specified path. This acts as a merge operation,%0A     * which is to say that any pre-existing data which is not explicitly%0A     * overwritten will be preserved. This means that if you store a container,%0A     * its child lists will be merged. Performing the following put operations:%0A     *%0A     * 1) container %7B list %5B a %5D %7D%0A     * 2) container %7B list %5B b %5D %7D%0A     *%0A     * will result in the following data being present:%0A     *%0A     * container %7B list %5B a, b %5D %7D%0A     *%0A     * This also means that storing the container will preserve any augmentations%0A     * which have been attached to it.%0A     *%0A     * If you require an explicit replace operation, perform%0A     * %7B@link removeConfigurationData%7D first.%0A     */
 %0A   

Clarify the semantics of put{Configuration,Operational}Data()