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