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     private static final long serialVersionUID = 3L;
  30
  31     /**
  32      * Creates new YANG Schema source identifier for sources with or without a revision.
  33      *
  34      * @param name Name of schema
  35      * @param revision Revision of schema
  36      * @throws NullPointerException if {@code name} is null
  37      */
  38     public SourceIdentifier {
  39         requireNonNull(name);
  40     }
  41
  42     /**
  43      * Creates new YANG Schema source identifier for sources without a revision.
  44      *
  45      * @param name Name of schema
  46      * @throws NullPointerException if {@code name} is null
  47      */
  48     public SourceIdentifier(final @NonNull Unqualified name) {
  49         this(name, null);
  50     }
  51
  52     /**
  53      * Creates new YANG Schema source identifier for sources without a revision.
  54      *
  55      * @param name Name of schema
  56      * @throws NullPointerException if {@code name} is null
  57      * @throws IllegalArgumentException if {@code name} is not a valid YANG identifier
  58      */
  59     public SourceIdentifier(final @NonNull String name) {
  60         this(Unqualified.of(name));
  61     }
  62
  63     /**
  64      * Creates new YANG Schema source identifier for sources with or without a revision.
  65      *
  66      * @param name Name of schema
  67      * @param revision Optional schema revision
  68      * @throws NullPointerException if {@code name} is null
  69      * @throws IllegalArgumentException if {@code name} is not a valid YANG identifier
  70      */
  71     public SourceIdentifier(final @NonNull String name, final @Nullable Revision revision) {
  72         this(Unqualified.of(name), revision);
  73     }
  74
  75     /**
  76      * Creates new YANG Schema source identifier for sources with or without a revision.
  77      *
  78      * @param name Name of schema
  79      * @param revision Optional schema revision
  80      * @throws NullPointerException if {@code name} is null
  81      * @throws IllegalArgumentException if {@code name} is not a valid YANG identifier
  82      * @throws DateTimeParseException if {@code revision} format does not conform specification.
  83      */
  84     public SourceIdentifier(final @NonNull String name, final @Nullable String revision) {
  85         this(name, revision != null ? Revision.of(revision) : null);
  86     }
  87
  88     /**
  89      * Returns filename for this YANG module as specified in RFC 6020.
  90      *
  91      * <p>
  92      * Returns filename in format <code>name ['@' revision] '.yang'</code>, where revision is date in format YYYY-mm-dd.
  93      *
  94      * <p>
  95      * @see <a href="http://www.rfc-editor.org/rfc/rfc6020#section-5.2">RFC6020</a>
  96      *
  97      * @return Filename for this source identifier.
  98      */
  99     public @NonNull String toYangFilename() {
 100         return toYangFileName(name.getLocalName(), revision);
 101     }
 102
 103     @Override
 104     public String toString() {
 105         final var sb = new StringBuilder("SourceIdentifier [").append(name.getLocalName());
 106         if (revision != null) {
 107             sb.append('@').append(revision);
 108         }
 109         return sb.append(']').toString();
 110     }
 111
 112     /**
 113      * Returns filename for this YANG module as specified in RFC 6020.
 114      *
 115      * <p>
 116      * Returns filename in format <code>moduleName ['@' revision] '.yang'</code>,
 117      * where Where revision-date is in format YYYY-mm-dd.
 118      *
 119      * <p>
 120      * See http://www.rfc-editor.org/rfc/rfc6020#section-5.2
 121      *
 122      * @param moduleName module name
 123      * @param revision optional revision
 124      * @return Filename for this source identifier.
 125      */
 126     public static @NonNull String toYangFileName(final @NonNull String moduleName, final @Nullable Revision revision) {
 127         final StringBuilder sb = new StringBuilder(moduleName);
 128         if (revision != null) {
 129             sb.append('@').append(revision);
 130         }
 131         return sb.append(YangConstants.RFC6020_YANG_FILE_EXTENSION).toString();
 132     }
 133 }