model/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/source/SourceIdentifier.java

   1 /*
   2  * Copyright (c) 2014 Cisco Systems, Inc. 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.yangtools.yang.model.api.source;
   9
  10 import static java.util.Objects.requireNonNull;
  11
  12 import java.time.format.DateTimeParseException;
  13 import org.eclipse.jdt.annotation.NonNull;
  14 import org.eclipse.jdt.annotation.Nullable;
  15 import org.opendaylight.yangtools.concepts.Identifier;
  16 import org.opendaylight.yangtools.yang.common.Revision;
  17 import org.opendaylight.yangtools.yang.common.UnresolvedQName.Unqualified;
  18 import org.opendaylight.yangtools.yang.common.YangConstants;
  19
  20 /**
  21  * Base class of YANG Schema source identifiers. Source identifiers are designated to be carry only necessary
  22  * information to look up YANG module (or submodule) source and to be used by various SchemaSourceProviders.
  23  *
  24  * <p>
  25  * For further reference see: <a href="https://www.rfc-editor.org/rfc/rfc6020#section-5.2">RFC6020</a>
  26  * and <a href="https://www.rfc-editor.org/rfc/rfc6022#section-3.1">RFC6022</a>.
  27  */
  28 public record SourceIdentifier(@NonNull Unqualified name, @Nullable Revision revision) implements Identifier {
  29     @java.io.Serial
  30     private static final long serialVersionUID = 3L;
  31
  32     /**
  33      * Creates new YANG Schema source identifier for sources with or without a revision.
  34      *
  35      * @param name Name of schema
  36      * @param revision Revision of schema
  37      * @throws NullPointerException if {@code name} is null
  38      */
  39     public SourceIdentifier {
  40         requireNonNull(name);
  41     }
  42
  43     /**
  44      * Creates new YANG Schema source identifier for sources without a revision.
  45      *
  46      * @param name Name of schema
  47      * @throws NullPointerException if {@code name} is null
  48      */
  49     public SourceIdentifier(final @NonNull Unqualified name) {
  50         this(name, null);
  51     }
  52
  53     /**
  54      * Creates new YANG Schema source identifier for sources without a revision.
  55      *
  56      * @param name Name of schema
  57      * @throws NullPointerException if {@code name} is null
  58      * @throws IllegalArgumentException if {@code name} is not a valid YANG identifier
  59      */
  60     public SourceIdentifier(final @NonNull String name) {
  61         this(Unqualified.of(name));
  62     }
  63
  64     /**
  65      * Creates new YANG Schema source identifier for sources with or without a revision.
  66      *
  67      * @param name Name of schema
  68      * @param revision Optional schema revision
  69      * @throws NullPointerException if {@code name} is null
  70      * @throws IllegalArgumentException if {@code name} is not a valid YANG identifier
  71      */
  72     public SourceIdentifier(final @NonNull String name, final @Nullable Revision revision) {
  73         this(Unqualified.of(name), revision);
  74     }
  75
  76     /**
  77      * Creates new YANG Schema source identifier for sources with or without a revision.
  78      *
  79      * @param name Name of schema
  80      * @param revision Optional schema revision
  81      * @throws NullPointerException if {@code name} is null
  82      * @throws IllegalArgumentException if {@code name} is not a valid YANG identifier
  83      * @throws DateTimeParseException if {@code revision} format does not conform specification.
  84      */
  85     public SourceIdentifier(final @NonNull String name, final @Nullable String revision) {
  86         this(name, revision != null ? Revision.of(revision) : null);
  87     }
  88
  89     /**
  90      * Returns filename for this YANG module as specified in RFC 6020.
  91      *
  92      * <p>
  93      * Returns filename in format <code>name ['@' revision] '.yang'</code>, where revision is date in format YYYY-mm-dd.
  94      *
  95      * <p>
  96      * @see <a href="http://www.rfc-editor.org/rfc/rfc6020#section-5.2">RFC6020</a>
  97      *
  98      * @return Filename for this source identifier.
  99      */
 100     public @NonNull String toYangFilename() {
 101         return toYangFileName(name.getLocalName(), revision);
 102     }
 103
 104     @Override
 105     public String toString() {
 106         final var sb = new StringBuilder("SourceIdentifier [").append(name.getLocalName());
 107         if (revision != null) {
 108             sb.append('@').append(revision);
 109         }
 110         return sb.append(']').toString();
 111     }
 112
 113     /**
 114      * Returns filename for this YANG module as specified in RFC 6020.
 115      *
 116      * <p>
 117      * Returns filename in format <code>moduleName ['@' revision] '.yang'</code>,
 118      * where Where revision-date is in format YYYY-mm-dd.
 119      *
 120      * <p>
 121      * See http://www.rfc-editor.org/rfc/rfc6020#section-5.2
 122      *
 123      * @param moduleName module name
 124      * @param revision optional revision
 125      * @return Filename for this source identifier.
 126      */
 127     public static @NonNull String toYangFileName(final @NonNull String moduleName, final @Nullable Revision revision) {
 128         final var sb = new StringBuilder(moduleName);
 129         if (revision != null) {
 130             sb.append('@').append(revision);
 131         }
 132         return sb.append(YangConstants.RFC6020_YANG_FILE_EXTENSION).toString();
 133     }
 134 }