yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/repo/api/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.repo.api;
   9
  10 import com.google.common.annotations.Beta;
  11 import com.google.common.base.Optional;
  12 import com.google.common.base.Preconditions;
  13 import com.google.common.collect.Interner;
  14 import com.google.common.collect.Interners;
  15 import java.util.regex.Pattern;
  16 import javax.annotation.RegEx;
  17 import org.opendaylight.yangtools.concepts.Identifier;
  18 import org.opendaylight.yangtools.concepts.Immutable;
  19 import org.opendaylight.yangtools.concepts.SemVer;
  20 import org.opendaylight.yangtools.yang.common.SimpleDateFormatUtil;
  21 import org.opendaylight.yangtools.yang.common.YangConstants;
  22
  23 /**
  24  * Base class of YANG Schema source identifiers.
  25  *
  26  * Source identifiers are designated to be carry only necessary information to
  27  * look-up YANG model source and to be used by various SchemaSourceProviders.
  28  *
  29  * (For further reference see: http://tools.ietf.org/html/rfc6020#section-5.2
  30  * and http://tools.ietf.org/html/rfc6022#section-3.1 ).
  31  */
  32 @Beta
  33 public abstract class SourceIdentifier implements Identifier, Immutable {
  34     /**
  35      * Default revision for sources without specified revision. This should be used for comparisons
  36      * based on revision when a SourceIdentifier does not have a revision.
  37      */
  38     public static final String NOT_PRESENT_FORMATTED_REVISION = "0000-00-00";
  39
  40     @RegEx
  41     private static final String REVISION_PATTERN_STR = "\\d\\d\\d\\d-\\d\\d-\\d\\d";
  42
  43     /**
  44      * Simplified compiled revision pattern in format YYYY-mm-dd, which checks
  45      * only distribution of number elements.
  46      * <p>
  47      * For checking if supplied string is real date, use
  48      * {@link SimpleDateFormatUtil} instead.
  49      */
  50     public static final Pattern REVISION_PATTERN = Pattern.compile(REVISION_PATTERN_STR);
  51
  52     private static final Interner<SourceIdentifier> INTERNER = Interners.newWeakInterner();
  53
  54     private static final long serialVersionUID = 1L;
  55     private final String revision;
  56     private final String name;
  57
  58     /**
  59      *
  60      * Creates new YANG Schema source identifier for sources without revision.
  61      *
  62      * @param name
  63      *            Name of schema
  64      */
  65     SourceIdentifier(final String name) {
  66         this.name = Preconditions.checkNotNull(name);
  67         this.revision = null;
  68     }
  69
  70     /**
  71      * Creates new YANG Schema source identifier.
  72      *
  73      * @param name
  74      *            Name of schema
  75      * @param formattedRevision
  76      *            Revision of source in format YYYY-mm-dd
  77      */
  78     SourceIdentifier(final String name, final String formattedRevision) {
  79         this.name = Preconditions.checkNotNull(name);
  80         this.revision = Preconditions.checkNotNull(formattedRevision);
  81     }
  82
  83     /**
  84      * Creates new YANG Schema source identifier.
  85      *
  86      * @param name
  87      *            Name of schema
  88      * @param formattedRevision
  89      *            Revision of source in format YYYY-mm-dd. If not present,
  90      *            default value will be used.
  91      */
  92     SourceIdentifier(final String name, final Optional<String> formattedRevision) {
  93         this.name = Preconditions.checkNotNull(name);
  94         this.revision = formattedRevision.orNull();
  95     }
  96
  97     /**
  98      * Return an interned reference to a equivalent OpenconfigVerSourceIdentifier.
  99      *
 100      * @return Interned reference, or this object if it was interned.
 101      */
 102     public SourceIdentifier intern() {
 103         return INTERNER.intern(this);
 104     }
 105
 106     /**
 107      * Returns model name
 108      *
 109      * @return model name
 110      */
 111     public String getName() {
 112         return name;
 113     }
 114
 115     /**
 116      * Returns revision of source or null if revision was not supplied.
 117      *
 118      * @return revision of source or null if revision was not supplied.
 119      */
 120     // FIXME: version 2.0.0: this should return Optional<String>
 121     public String getRevision() {
 122         return revision;
 123     }
 124
 125     /**
 126      * <p>
 127      * Since we've got two ways of model versioning (revision &amp; openconfig version),
 128      * this method shouldn't be called directly anymore. Eventually, callers of this method
 129      * should be notified before method gets deleted.
 130      * @deprecated use either
 131      * <ul>
 132      * <li>{@link OpenconfigVerSourceIdentifier#create(String, SemVer)}</li>
 133      * <li>{@link OpenconfigVerSourceIdentifier#create(String, Optional, SemVer)}</li>
 134      * <li>{@link OpenconfigVerSourceIdentifier#create(String, String, SemVer)}</li>
 135      * </ul>
 136      * or
 137      * <ul>
 138      * <li>{@link RevisionSourceIdentifier#create(String)}</li>
 139      * <li>{@link RevisionSourceIdentifier#create(String, String)}</li>
 140      * <li>{@link RevisionSourceIdentifier#create(String, Optional)}</li>
 141      * </ul>
 142      *
 143      * @param moduleName
 144      *            Name of schema
 145
 146      * @param revision
 147      *            Revision of source in format YYYY-mm-dd. If not present,
 148      *            default value will be used.
 149      *
 150      * @return particular SourceIdentifier instance
 151      *
 152      */
 153     @Deprecated
 154     public static SourceIdentifier create(final String moduleName, final Optional<String> revision) {
 155         return new RevisionSourceIdentifier(moduleName, revision);
 156     }
 157
 158     /**
 159      * Returns filename for this YANG module as specified in RFC 6020.
 160      *
 161      * Returns filename in format <code>name ['@' revision] '.yang'</code>
 162      * <p>
 163      * Where revision is date in format YYYY-mm-dd.
 164      * <p>
 165      *
 166      * @see <a href="http://tools.ietf.org/html/rfc6020#section-5.2">RFC6020</a>
 167      *
 168      * @return Filename for this source identifier.
 169      */
 170     public String toYangFilename() {
 171         final String rev = NOT_PRESENT_FORMATTED_REVISION.equals(revision) ? null : revision;
 172         return toYangFileName(name, Optional.fromNullable(rev));
 173     }
 174
 175     /**
 176      * Returns filename for this YANG module as specified in RFC 6020.
 177      *
 178      * Returns filename in format <code>moduleName ['@' revision] '.yang'</code>
 179      *
 180      * Where Where revision-date is in format YYYY-mm-dd.
 181      *
 182      * <p>
 183      * See http://tools.ietf.org/html/rfc6020#section-5.2
 184      *
 185      * @return Filename for this source identifier.
 186      */
 187     public static String toYangFileName(final String moduleName, final Optional<String> revision) {
 188         StringBuilder filename = new StringBuilder(moduleName);
 189         if (revision.isPresent()) {
 190             filename.append('@');
 191             filename.append(revision.get());
 192         }
 193         filename.append(YangConstants.RFC6020_YANG_FILE_EXTENSION);
 194         return filename.toString();
 195     }
 196 }