protocol/netconf-api/src/main/java/org/opendaylight/netconf/api/capability/SimpleCapability.java

   1 /*
   2  * Copyright (c) 2023 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.api.capability;
   9
  10 import static java.util.Objects.requireNonNull;
  11
  12 import java.net.URI;
  13 import org.eclipse.jdt.annotation.NonNull;
  14 import org.opendaylight.netconf.api.CapabilityURN;
  15
  16 /**
  17  * Enumeration of all simple
  18  * <a href="https://www.iana.org/assignments/netconf-capability-urns/netconf-capability-urns.xhtml#netconf-capability-urns-1">
  19  *     NETCONF capabilities,</a>
  20  * i.e. those which do not have any additional parameters.
  21  */
  22 public enum SimpleCapability implements Capability {
  23     /**
  24      * The base NETCONF capability, as defined in
  25      * <a href="https://www.rfc-editor.org/rfc/rfc4741.html#section-8.1">RFC4741, section 8.1</a>.
  26      * @deprecated This capability identifies legacy NETCONF devices and has been superseded by {@link #BASE_1_1}, just
  27      *             as RFC6241 obsoletes RFC4741.
  28      */
  29     @Deprecated
  30     BASE(":base:1.0", CapabilityURN.BASE),
  31     /**
  32      * The base NETCONF capability, as defined in
  33      * <a href="https://www.rfc-editor.org/rfc/rfc6241.html#section-8.1">RFC6241, section 8.1</a>.
  34      */
  35     BASE_1_1(":base:1.1", CapabilityURN.BASE_1_1),
  36     /**
  37      * The Candidate Configuration Capability, as defined in
  38      * <a href="https://www.rfc-editor.org/rfc/rfc6241.html#section-8.3">RFC6241, section 8.3</a>.
  39      */
  40     CANDIDATE(":candidate", CapabilityURN.CANDIDATE),
  41     /**
  42      * The Candidate Configuration Capability, as defined in
  43      * <a href="https://www.rfc-editor.org/rfc/rfc4741.html#section-8.3">RFC4741, section 8.3</a>.
  44      * @deprecated This capability is superseded by {@link #CONFIRMED_COMMIT_1_1}.
  45      */
  46     @Deprecated
  47     CONFIRMED_COMMIT(":confirmed-commit", CapabilityURN.CONFIRMED_COMMIT),
  48     /**
  49      * The Rollback-on-Error Capability, as defined in
  50      * <a href="https://www.rfc-editor.org/rfc/rfc6241.html#section-8.4">RFC6241, section 8.4</a>.
  51      */
  52     CONFIRMED_COMMIT_1_1(":confirmed-commit:1.1", CapabilityURN.CONFIRMED_COMMIT_1_1),
  53     /**
  54      * The Interleave Capability, as defined in
  55      * <a href="https://www.rfc-editor.org/rfc/rfc5277.html#section-6">RFC5277, section 6</a>.
  56      */
  57     INTERLEAVE(":interleave", CapabilityURN.INTERLEAVE),
  58     /**
  59      * The Validate Capability, as defined in
  60      * <a href="https://www.rfc-editor.org/rfc/rfc5277.html#section-3.1">RFC5277, section 3.1</a>.
  61      */
  62     NOTIFICATION(":notification", CapabilityURN.NOTIFICATION),
  63     /**
  64      * The Partial Locking Capability, as defined in
  65      * <a href="https://www.rfc-editor.org/rfc/rfc5717.html#section-2">RFC5715, section 2</a>.
  66      */
  67     PARTIAL_LOCK(":partial-lock", CapabilityURN.PARTIAL_LOCK),
  68     /**
  69      * The Rollback-on-Error Capability, as defined in
  70      * <a href="https://www.rfc-editor.org/rfc/rfc6241.html#section-8.5">RFC6241, section 8.5</a>.
  71      */
  72     ROLLBACK_ON_ERROR(":rollback-on-error", CapabilityURN.ROLLBACK_ON_ERROR),
  73     /**
  74      * The Distinct Startup Capability, as defined in
  75      * <a href="https://www.rfc-editor.org/rfc/rfc6241.html#section-8.7">RFC6241, section 8.7</a>.
  76      */
  77     STARTUP(":startup", CapabilityURN.STARTUP),
  78     /**
  79      * The Time Capability, as defined in
  80      * <a href="https://www.rfc-editor.org/rfc/rfc7758.html#section-4">RFC7758, section 4</a>.
  81      */
  82     TIME(":time:1.0", CapabilityURN.TIME),
  83     /**
  84      * The URL Capability, as defined in
  85      * <a href="https://www.rfc-editor.org/rfc/rfc6241.html#section-8.8">RFC6241, section 8.8</a>.
  86      */
  87     URL(":url", CapabilityURN.URL),
  88     /**
  89      * The Validate Capability, as defined in
  90      * <a href="https://www.rfc-editor.org/rfc/rfc4741.html#section-8.6">RFC4741, section 8.6</a>.
  91      * @deprecated This capability is superseded by {@link #VALIDATE_1_1}.
  92      */
  93     @Deprecated
  94     VALIDATE(":validate", CapabilityURN.VALIDATE),
  95     /**
  96      * The Validate Capability, as defined in
  97      * <a href="https://www.rfc-editor.org/rfc/rfc6241.html#section-8.6">RFC6241, section 8.6</a>.
  98      */
  99     VALIDATE_1_1(":validate:1.1", CapabilityURN.VALIDATE_1_1),
 100     /**
 101      * The XPath Capability, as defined in
 102      * <a href="https://www.rfc-editor.org/rfc/rfc6241.html#section-8.9">RFC6241, section 8.9</a>.
 103      */
 104     XPATH(":xpath", CapabilityURN.XPATH),
 105     /**
 106      * The YANG Module Library Capability, as defined in
 107      * <a href="hhttps://www.rfc-editor.org/rfc/rfc7950.html#section-5.6.4">RFC7950, section 5.6.4</a> and further
 108      * specified by <a href="https://www.rfc-editor.org/rfc/rfc7895">RFC7895</a>. Note this applies to NETCONF endpoints
 109      * which DO NOT support Network Management Datastore Architecture as specified by
 110      * <a href="https://www.rfc-editor.org/rfc/rfc8342">RFC8342</a>.
 111      */
 112     YANG_LIBRARY(":yang-library", CapabilityURN.YANG_LIBRARY),
 113     /**
 114      * The YANG Library Capability, as defined in
 115      * <a href="https://www.rfc-editor.org/rfc/rfc8526.html#section-2">RFC8526, section 2</a> and further specified
 116      * by <a href="https://www.rfc-editor.org/rfc/rfc8525">RFC8525</a>. Note this applies to NETCONF endpoints
 117      * which DO support Network Management Datastore Architecture as specified by
 118      * <a href="https://www.rfc-editor.org/rfc/rfc8342">RFC8342</a>.
 119      */
 120     YANG_LIBRARY_1_1(":yang-library:1.1", CapabilityURN.YANG_LIBRARY_1_1),
 121     /**
 122      * The With-defaults Capability, as defined in
 123      * <a href="https://www.rfc-editor.org/rfc/rfc6243.html#section-4">RFC6243, section 4</a>.
 124      */
 125     WITH_DEFAULTS(":with-defaults", CapabilityURN.WITH_DEFAULTS),
 126     /**
 127      * The With-defaults Capability, as augmented by
 128      * <a href="https://www.rfc-editor.org/rfc/rfc8526#section-3.1.1.2">RFC8526, section 3.1.1.2</a>.
 129      */
 130     WITH_OPERATIONAL_DEFAULTS(":with-operational-defaults", CapabilityURN.WITH_OPERATIONAL_DEFAULTS),
 131     /**
 132      * The Writable-Running Capability, as defined in
 133      * <a href="https://www.rfc-editor.org/rfc/rfc6241.html#section-8.2">RFC6241, section 8.2</a>.
 134      */
 135     WRITABLE_RUNNING(":writable-running", CapabilityURN.WRITABLE_RUNNING);
 136
 137     private final @NonNull String capabilityName;
 138     private final @NonNull String urn;
 139     private final @NonNull URI uri;
 140
 141     SimpleCapability(final String capabilityName, final String urn) {
 142         this.capabilityName = requireNonNull(capabilityName);
 143         this.urn = requireNonNull(urn);
 144         uri = URI.create(urn);
 145     }
 146
 147     public @NonNull String capabilityName() {
 148         return capabilityName;
 149     }
 150
 151     @Override
 152     public String urn() {
 153         return urn;
 154     }
 155
 156     @Override
 157     public URI toURI() {
 158         return uri;
 159     }
 160
 161     /**
 162      * Try to match a capability URN to a {@link SimpleCapability}.
 163      *
 164      * @param urn URN to match
 165      * @return A {@link SimpleCapability}
 166      * @throws IllegalArgumentException if {@code urn} is {@code null}
 167      */
 168     public static @NonNull SimpleCapability ofURN(final String urn) {
 169         final var capability = forURN(urn);
 170         if (capability == null) {
 171             throw new IllegalArgumentException(urn + " does not match a known protocol capability");
 172         }
 173         return capability;
 174     }
 175
 176     /**
 177      * Match a capability URN to a {@link SimpleCapability}.
 178      *
 179      * @param urn URN to match
 180      * @return A {@link SimpleCapability}, or {@code null} the URN does not match a known protocol capability
 181      * @throws NullPointerException if {@code urn} is {@code null}
 182      */
 183     public static SimpleCapability forURN(final String urn) {
 184         return switch (urn) {
 185             case CapabilityURN.BASE -> BASE;
 186             case CapabilityURN.BASE_1_1 -> BASE_1_1;
 187             case CapabilityURN.CANDIDATE -> CANDIDATE;
 188             case CapabilityURN.CONFIRMED_COMMIT -> CONFIRMED_COMMIT;
 189             case CapabilityURN.CONFIRMED_COMMIT_1_1 -> CONFIRMED_COMMIT_1_1;
 190             case CapabilityURN.INTERLEAVE -> INTERLEAVE;
 191             case CapabilityURN.NOTIFICATION -> NOTIFICATION;
 192             case CapabilityURN.PARTIAL_LOCK -> PARTIAL_LOCK;
 193             case CapabilityURN.ROLLBACK_ON_ERROR -> ROLLBACK_ON_ERROR;
 194             case CapabilityURN.STARTUP -> STARTUP;
 195             case CapabilityURN.TIME -> TIME;
 196             case CapabilityURN.URL -> URL;
 197             case CapabilityURN.VALIDATE -> VALIDATE;
 198             case CapabilityURN.VALIDATE_1_1 -> VALIDATE_1_1;
 199             case CapabilityURN.WITH_DEFAULTS -> WITH_DEFAULTS;
 200             case CapabilityURN.WITH_OPERATIONAL_DEFAULTS -> WITH_OPERATIONAL_DEFAULTS;
 201             case CapabilityURN.WRITABLE_RUNNING -> WRITABLE_RUNNING;
 202             case CapabilityURN.XPATH -> XPATH;
 203             case CapabilityURN.YANG_LIBRARY -> YANG_LIBRARY;
 204             case CapabilityURN.YANG_LIBRARY_1_1 -> YANG_LIBRARY_1_1;
 205             default -> null;
 206         };
 207     }
 208 }