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