plugins/netconf-dom-api/src/main/java/org/opendaylight/netconf/dom/api/NetconfDataTreeService.java

   1 /*
   2  * Copyright (c) 2020 PANTHEON.tech, s.r.o. and others.  All rights reserved.
   3  *
   4  * This program and the accompanying materials are made available under the
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html
   7  */
   8 package org.opendaylight.netconf.dom.api;
   9
  10 import com.google.common.util.concurrent.ListenableFuture;
  11 import edu.umd.cs.findbugs.annotations.CheckReturnValue;
  12 import java.util.List;
  13 import java.util.Optional;
  14 import org.eclipse.jdt.annotation.NonNull;
  15 import org.opendaylight.mdsal.common.api.LogicalDatastoreType;
  16 import org.opendaylight.mdsal.dom.api.DOMRpcResult;
  17 import org.opendaylight.mdsal.dom.api.DOMService;
  18 import org.opendaylight.netconf.api.EffectiveOperation;
  19 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
  20 import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
  21
  22 /**
  23  * Interface for base and additional operations for NETCONF (e.g. {@code get}, {@code get-config}, {@code edit-config},
  24  * {@code lock}, {@code unlock}, {@code commit}, etc).
  25  * The {@code <edit-config>} operation is extended according its attributes (merge, replace, create, delete, remove), as
  26  * per RFC6241.
  27  */
  28 public interface NetconfDataTreeService extends DOMService<NetconfDataTreeService, NetconfDataTreeService.Extension> {
  29     /**
  30      * Type capture of a {@link DOMService.Extension} applicable to {@link NetconfDataTreeService} implementations.
  31      */
  32     interface Extension extends DOMService.Extension<NetconfDataTreeService, Extension> {
  33         // Marker interface
  34     }
  35
  36     /**
  37      * Return device identifier.
  38      *
  39      * @return Device's identifier, must not be {@code null}.
  40      */
  41     @NonNull Object getDeviceId();
  42
  43     /**
  44      * The {@code <lock>} operation. Allows the client to lock the entire configuration datastore system of a device.
  45      *
  46      * @return result of {@code <lock>} operation
  47      */
  48     @CheckReturnValue
  49     ListenableFuture<? extends DOMRpcResult> lock();
  50
  51     /**
  52      * The {@code <lock>} operation. Used to release a configuration lock, previously obtained with the {@code <lock>}
  53      * operation.
  54      *
  55      * @return result of {@code <unlock>} operation
  56      */
  57     @CheckReturnValue
  58     ListenableFuture<? extends DOMRpcResult> unlock();
  59
  60     /**
  61      * The {@code <discard-changes>} operation. If device supports {@code :candidate} capability, discards any
  62      * uncommitted changes by resetting the candidate configuration with the content of the running configuration.
  63      *
  64      * @return result of {@code <discard-changes>} operation
  65      */
  66     ListenableFuture<? extends DOMRpcResult> discardChanges();
  67
  68     /**
  69      * The {@code <get>} operation. Retrieve running configuration and device state information.
  70      *
  71      * @return result of {@code <get>} operation
  72      */
  73     ListenableFuture<Optional<NormalizedNode>> get(YangInstanceIdentifier path);
  74
  75     /**
  76      * The {@code <get>} operation with specific fields that are read from device.
  77      *
  78      * @param path   path to data
  79      * @param fields list of fields (paths relative to parent path)
  80      * @return result of {@code <get>} operation
  81      */
  82     ListenableFuture<Optional<NormalizedNode>> get(YangInstanceIdentifier path, List<YangInstanceIdentifier> fields);
  83
  84     /**
  85      * The {@code <get-config>} operation. Retrieve all or part of a specified configuration datastore.
  86      *
  87      * @return result of {@code <get-config>} operation
  88      */
  89     ListenableFuture<Optional<NormalizedNode>> getConfig(YangInstanceIdentifier path);
  90
  91     /**
  92      * The {@code <get-config>} operation with specified fields that are read from device.
  93      *
  94      * @return result of {@code <get-config>} operation
  95      */
  96     ListenableFuture<Optional<NormalizedNode>> getConfig(YangInstanceIdentifier path,
  97         List<YangInstanceIdentifier> fields);
  98
  99     /**
 100      * The {@code <edit-config>} operation with {@code merge} attribute. The configuration data identified by the
 101      * element containing this attribute is merged with the configuration at the corresponding level in the
 102      * configuration datastore.
 103      *
 104      * @return result of {@code <edit-config>} operation
 105      */
 106     ListenableFuture<? extends DOMRpcResult> merge(LogicalDatastoreType store, YangInstanceIdentifier path,
 107         NormalizedNode data, Optional<EffectiveOperation> defaultOperation);
 108
 109     /**
 110      * The {@code <edit-config>} operation with {@code replace} attribute. The configuration data identified by the
 111      * element containing this attribute replaces any related configuration in the configuration datastore.
 112      *
 113      * @return result of {@code <edit-config>} operation
 114      */
 115     ListenableFuture<? extends DOMRpcResult> replace(LogicalDatastoreType store, YangInstanceIdentifier path,
 116         NormalizedNode data, Optional<EffectiveOperation> defaultOperation);
 117
 118     /**
 119      * The {@code <edit-config>} operation with {@code create} attribute. The configuration data identified by the
 120      * element containing this attribute is added to the configuration if and only if the configuration data does not
 121      * already exist in the configuration datastore.
 122      *
 123      * @return result of{@code <edit-config>} operation
 124      */
 125     ListenableFuture<? extends DOMRpcResult> create(LogicalDatastoreType store, YangInstanceIdentifier path,
 126         NormalizedNode data, Optional<EffectiveOperation> defaultOperation);
 127
 128     /**
 129      * The {@code <edit-config>} operation with {@code create} attribute. The configuration data identified by the
 130      * element containing this attribute is deleted from the configuration if and only if the configuration data
 131      * currently exists in the configuration datastore.
 132      *
 133      * @return result of {@code <edit-config>} operation
 134      */
 135     ListenableFuture<? extends DOMRpcResult> delete(LogicalDatastoreType store, YangInstanceIdentifier path);
 136
 137     /**
 138      * The {@code <edit-config>} operation with {@code create} attribute. The configuration data identified by the
 139      * element containing this attribute is deleted from the configuration if the configuration data currently exists
 140      * in the configuration datastore.
 141      *
 142      * @return result of {@code <edit-config>} operation
 143      */
 144     ListenableFuture<? extends DOMRpcResult> remove(LogicalDatastoreType store, YangInstanceIdentifier path);
 145
 146     /**
 147      * The {@code <commit>} operation. If device supports {@code :candidate} capability, commit the candidate
 148      * configuration as the device's new current configuration.
 149      *
 150      * @return result of {@code <commit>} operation
 151      */
 152     ListenableFuture<? extends DOMRpcResult> commit();
 153 }