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 java.util.Objects;
  14 import java.util.regex.Pattern;
  15 import org.opendaylight.yangtools.concepts.Identifier;
  16 import org.opendaylight.yangtools.concepts.Immutable;
  17 import org.opendaylight.yangtools.objcache.ObjectCache;
  18 import org.opendaylight.yangtools.objcache.ObjectCacheFactory;
  19 import org.opendaylight.yangtools.yang.common.SimpleDateFormatUtil;
  20
  21 /**
  22  * YANG Schema source identifier
  23  *
  24  * Simple transfer object represents identifier of source for YANG schema (module or submodule),
  25  * which consists of
  26  * <ul>
  27  * <li>YANG schema name ({@link #getName()}
  28  * <li>Module revision (optional) ({link {@link #getRevision()})
  29  * </ul>
  30  *
  31  * Source identifier is designated to be carry only necessary information
  32  * to look-up YANG model source and to be used by various SchemaSourceProviders.
  33  *
  34  * <b>Note:</b>On source retrieval layer it is impossible to distinguish
  35  * between YANG module and/or submodule unless source is present.
  36  *
  37  * <p>
  38  * (For further reference see: http://tools.ietf.org/html/rfc6020#section-5.2 and
  39  * http://tools.ietf.org/html/rfc6022#section-3.1 ).
  40  */
  41 @Beta
  42 public final class SourceIdentifier implements Identifier, Immutable {
  43     /**
  44      * Default revision for sources without specified revision.
  45      * Marks the source as oldest.
  46      */
  47     public static final String NOT_PRESENT_FORMATTED_REVISION = "0000-00-00";
  48
  49     /**
  50      *
  51      * Simplified compiled revision pattern in format YYYY-mm-dd, which checks
  52      * only distribution of number elements.
  53      * <p>
  54      * For checking if supplied string is real date, use {@link SimpleDateFormatUtil}
  55      * instead.
  56      *
  57      */
  58     public static final Pattern REVISION_PATTERN = Pattern.compile("\\d\\d\\d\\d-\\d\\d-\\d\\d");
  59
  60     private static final ObjectCache CACHE = ObjectCacheFactory.getObjectCache(SourceIdentifier.class);
  61     private static final long serialVersionUID = 1L;
  62     private final String revision;
  63     private final String name;
  64
  65     /**
  66      *
  67      * Creates new YANG Schema source identifier for sources without revision.
  68      * {@link SourceIdentifier#NOT_PRESENT_FORMATTED_REVISION} as default revision.
  69      *
  70      * @param name Name of schema
  71      */
  72     public SourceIdentifier(final String name) {
  73         this(name, NOT_PRESENT_FORMATTED_REVISION);
  74     }
  75
  76     /**
  77      * Creates new YANG Schema source identifier.
  78      *
  79      * @param name Name of schema
  80      * @param formattedRevision Revision of source in format YYYY-mm-dd
  81      */
  82     public SourceIdentifier(final String name, final String formattedRevision) {
  83         this.name = Preconditions.checkNotNull(name);
  84         this.revision = Preconditions.checkNotNull(formattedRevision);
  85     }
  86
  87     /**
  88      *
  89      * Creates new YANG Schema source identifier.
  90      *
  91      * @param name Name of schema
  92      * @param formattedRevision Revision of source in format YYYY-mm-dd. If not present, default value will be used.
  93      */
  94     public SourceIdentifier(final String name, final Optional<String> formattedRevision) {
  95         this(name, formattedRevision.or(NOT_PRESENT_FORMATTED_REVISION));
  96     }
  97
  98     /**
  99      * Return a cached reference to an object equal to this object.
 100      *
 101      * @return A potentially shared reference, not guaranteed to be unique.
 102      */
 103     public SourceIdentifier cachedReference() {
 104         return CACHE.getReference(this);
 105     }
 106
 107     /**
 108      * Returns model name
 109      *
 110      * @return model name
 111      */
 112     public String getName() {
 113         return name;
 114     }
 115
 116     /**
 117      * Returns revision of source or null if revision was not supplied.
 118      *
 119      * @return revision of source or null if revision was not supplied.
 120      */
 121     public String getRevision() {
 122         return revision;
 123     }
 124
 125     @Override
 126     public int hashCode() {
 127         final int prime = 31;
 128         int result = 1;
 129         result = prime * result + Objects.hashCode(name);
 130         result = prime * result + Objects.hashCode(revision);
 131         return result;
 132     }
 133
 134     @Override
 135     public boolean equals(final Object obj) {
 136         if (this == obj) {
 137             return true;
 138         }
 139         if (obj == null) {
 140             return false;
 141         }
 142         if (getClass() != obj.getClass()) {
 143             return false;
 144         }
 145         SourceIdentifier other = (SourceIdentifier) obj;
 146         return Objects.equals(name, other.name) && Objects.equals(revision, other.revision);
 147     }
 148
 149     public static SourceIdentifier create(final String moduleName, final Optional<String> revision) {
 150         return new SourceIdentifier(moduleName, revision);
 151     }
 152
 153     /**
 154      * Returns filename for this YANG module as specified in RFC 6020.
 155      *
 156      * Returns filename in format
 157      * <code>name ['@' revision] '.yang'</code>
 158      * <p>
 159      * Where revision is  date in format YYYY-mm-dd.
 160      * <p>
 161      *
 162      * @see <a href="http://tools.ietf.org/html/rfc6020#section-5.2">RFC6020</a>
 163      *
 164      * @return Filename for this source identifier.
 165      */
 166     public String toYangFilename() {
 167         return toYangFileName(name, Optional.fromNullable(revision));
 168     }
 169
 170     @Override
 171     public String toString() {
 172         return "SourceIdentifier [name=" + name + "@" + revision + "]";
 173     }
 174
 175     /**
 176      * Returns filename for this YANG module as specified in RFC 6020.
 177      *
 178      * Returns filename in format
 179      * <code>moduleName ['@' revision] '.yang'</code>
 180      *
 181      * Where Where revision-date is in format YYYY-mm-dd.
 182      *
 183      * <p>
 184      * See
 185      * http://tools.ietf.org/html/rfc6020#section-5.2
 186      *
 187      * @return Filename for this source identifier.
 188      */
 189     public static String toYangFileName(final String moduleName, final Optional<String> revision) {
 190         StringBuilder filename = new StringBuilder(moduleName);
 191         if (revision.isPresent()) {
 192             filename.append('@');
 193             filename.append(revision.get());
 194         }
 195         filename.append(".yang");
 196         return filename.toString();
 197     }
 198
 199 }