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