2 * Copyright (c) 2013 Cisco Systems, Inc. and others. All rights reserved.
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
8 package org.opendaylight.yangtools.yang.common;
10 import static com.google.common.base.Preconditions.checkArgument;
11 import static java.util.Objects.requireNonNull;
13 import com.google.common.base.Strings;
14 import com.google.common.collect.Interner;
15 import com.google.common.collect.Interners;
16 import java.io.Serializable;
18 import java.net.URISyntaxException;
19 import java.util.Objects;
20 import java.util.Optional;
21 import java.util.regex.Matcher;
22 import java.util.regex.Pattern;
23 import javax.annotation.Nonnull;
24 import javax.annotation.Nullable;
25 import javax.annotation.RegEx;
26 import org.opendaylight.yangtools.concepts.Identifier;
27 import org.opendaylight.yangtools.concepts.Immutable;
30 * The QName from XML consists of local name of element and XML namespace, but
31 * for our use, we added module revision to it.
34 * In YANG context QName is full name of defined node, type, procedure or
35 * notification. QName consists of XML namespace, YANG model revision and local
36 * name of defined type. It is used to prevent name clashes between nodes with
37 * same local name, but from different schemas.
40 * <li><b>XMLNamespace</b> - {@link #getNamespace()} - the namespace assigned to the YANG module which
41 * defined element, type, procedure or notification.</li>
42 * <li><b>Revision</b> - {@link #getRevision()} - the revision of the YANG module which describes the
44 * <li><b>LocalName</b> - {@link #getLocalName()} - the YANG schema identifier which were defined for this
45 * node in the YANG module</li>
49 * QName may also have <code>prefix</code> assigned, but prefix does not
50 * affect equality and identity of two QNames and carry only information
51 * which may be useful for serializers / deserializers.
53 public final class QName implements Immutable, Serializable, Comparable<QName>, Identifier {
54 private static final Interner<QName> INTERNER = Interners.newWeakInterner();
55 private static final long serialVersionUID = 5398411242927766414L;
57 static final String QNAME_REVISION_DELIMITER = "?revision=";
58 static final String QNAME_LEFT_PARENTHESIS = "(";
59 static final String QNAME_RIGHT_PARENTHESIS = ")";
62 private static final String QNAME_STRING_FULL = "^\\((.+)\\?revision=(.+)\\)(.+)$";
63 private static final Pattern QNAME_PATTERN_FULL = Pattern.compile(QNAME_STRING_FULL);
66 private static final String QNAME_STRING_NO_REVISION = "^\\((.+)\\)(.+)$";
67 private static final Pattern QNAME_PATTERN_NO_REVISION = Pattern.compile(QNAME_STRING_NO_REVISION);
69 private static final char[] ILLEGAL_CHARACTERS = new char[] { '?', '(', ')', '&', ':' };
72 private final QNameModule module;
74 private final String localName;
75 private transient int hash;
77 private QName(final QNameModule module, final String localName) {
78 this.localName = checkLocalName(localName);
86 * the namespace assigned to the YANG module
88 * YANG schema identifier
90 private QName(final URI namespace, final String localName) {
91 this(QNameModule.create(namespace), localName);
94 private static String checkLocalName(final String localName) {
95 checkArgument(localName != null, "Parameter 'localName' may not be null.");
96 checkArgument(!Strings.isNullOrEmpty(localName), "Parameter 'localName' must be a non-empty string.");
98 for (final char c : ILLEGAL_CHARACTERS) {
99 if (localName.indexOf(c) != -1) {
100 throw new IllegalArgumentException(String.format(
101 "Parameter 'localName':'%s' contains illegal character '%s'", localName, c));
107 public static QName create(final String input) {
108 Matcher matcher = QNAME_PATTERN_FULL.matcher(input);
109 if (matcher.matches()) {
110 final String namespace = matcher.group(1);
111 final String revision = matcher.group(2);
112 final String localName = matcher.group(3);
113 return create(namespace, revision, localName);
115 matcher = QNAME_PATTERN_NO_REVISION.matcher(input);
116 if (matcher.matches()) {
117 final URI namespace = URI.create(matcher.group(1));
118 final String localName = matcher.group(2);
119 return new QName(namespace, localName);
121 throw new IllegalArgumentException("Invalid input: " + input);
124 public static QName create(final QName base, final String localName) {
125 return create(base.getModule(), localName);
132 * Namespace and revision enclosed as a QNameModule
134 * Local name part of QName. MUST NOT BE null.
135 * @return Instance of QName
137 public static QName create(final QNameModule qnameModule, final String localName) {
138 return new QName(requireNonNull(qnameModule, "module may not be null"), localName);
145 * Namespace of QName or null if namespace is undefined.
147 * Revision of namespace or null if revision is unspecified.
149 * Local name part of QName. MUST NOT BE null.
150 * @return Instance of QName
152 public static QName create(final URI namespace, @Nullable final Revision revision, final String localName) {
153 return create(QNameModule.create(namespace, revision), localName);
160 * Namespace of QName or null if namespace is undefined.
162 * Revision of namespace.
164 * Local name part of QName. MUST NOT BE null.
165 * @return Instance of QName
167 public static QName create(final URI namespace, final Optional<Revision> revision, final String localName) {
168 return create(QNameModule.create(namespace, revision), localName);
175 * Namespace of QName or null if namespace is undefined.
177 * Revision of namespace or null if revision is unspecified.
179 * Local name part of QName. MUST NOT BE null.
180 * @return Instance of QName
182 public static QName create(final String namespace, final String localName, final Revision revision) {
183 final URI namespaceUri = parseNamespace(namespace);
184 return create(QNameModule.create(namespaceUri, revision), localName);
191 * Namespace of QName, MUST NOT BE Null.
193 * Revision of namespace / YANG module. MUST NOT BE null, MUST BE
194 * in format <code>YYYY-mm-dd</code>.
196 * Local name part of QName. MUST NOT BE null.
197 * @return A new QName
198 * @throws NullPointerException
199 * If any of parameters is null.
200 * @throws IllegalArgumentException
201 * If <code>namespace</code> is not valid URI or
202 * <code>revision</code> is not according to format
203 * <code>YYYY-mm-dd</code>.
205 public static QName create(final String namespace, final String revision, final String localName) {
206 final URI namespaceUri = parseNamespace(namespace);
207 final Revision revisionDate = Revision.of(revision);
208 return create(namespaceUri, revisionDate, localName);
215 * Namespace of QName, MUST NOT BE Null.
217 * Local name part of QName. MUST NOT BE null.
218 * @return A new QName
219 * @throws NullPointerException
220 * If any of parameters is null.
221 * @throws IllegalArgumentException
222 * If <code>namespace</code> is not valid URI.
224 public static QName create(final String namespace, final String localName) {
225 return create(parseNamespace(namespace), localName);
232 * Namespace of QName, MUST NOT BE null.
234 * Local name part of QName. MUST NOT BE null.
235 * @return A new QName
236 * @throws NullPointerException
237 * If any of parameters is null.
238 * @throws IllegalArgumentException
239 * If <code>namespace</code> is not valid URI.
241 public static QName create(final URI namespace, final String localName) {
242 return new QName(namespace, localName);
246 * Get the module component of the QName.
248 * @return Module component
250 public QNameModule getModule() {
255 * Returns XMLNamespace assigned to the YANG module.
257 * @return XMLNamespace assigned to the YANG module.
259 public URI getNamespace() {
260 return module.getNamespace();
264 * Returns YANG schema identifier which were defined for this node in the
267 * @return YANG schema identifier which were defined for this node in the
270 public String getLocalName() {
275 * Returns revision of the YANG module if the module has defined revision.
277 * @return revision of the YANG module if the module has defined revision.
279 public Optional<Revision> getRevision() {
280 return module.getRevision();
284 * Return an interned reference to a equivalent QName.
286 * @return Interned reference, or this object if it was interned.
288 public QName intern() {
289 // We also want to make sure we keep the QNameModule cached
290 final QNameModule cacheMod = module.intern();
292 // Identity comparison is here on purpose, as we are deciding whether to potentially store 'qname' into the
293 // interner. It is important that it does not hold user-supplied reference (such a String instance from
294 // parsing of an XML document).
295 final QName template = cacheMod == module ? this : QName.create(cacheMod, localName.intern());
297 return INTERNER.intern(template);
301 public int hashCode() {
303 hash = Objects.hash(module, localName);
309 * Compares the specified object with this list for equality. Returns
310 * <tt>true</tt> if and only if the specified object is also instance of
311 * {@link QName} and its {@link #getLocalName()}, {@link #getNamespace()} and
312 * {@link #getRevision()} are equals to same properties of this instance.
314 * @param obj the object to be compared for equality with this QName
315 * @return <tt>true</tt> if the specified object is equal to this QName
319 public boolean equals(final Object obj) {
323 if (!(obj instanceof QName)) {
326 final QName other = (QName) obj;
327 return Objects.equals(localName, other.localName) && module.equals(other.module);
330 private static URI parseNamespace(final String namespace) {
332 return new URI(namespace);
333 } catch (final URISyntaxException ue) {
334 throw new IllegalArgumentException(String.format("Namespace '%s' is not a valid URI", namespace), ue);
339 public String toString() {
340 final StringBuilder sb = new StringBuilder();
341 if (getNamespace() != null) {
342 sb.append(QNAME_LEFT_PARENTHESIS).append(getNamespace());
344 final Optional<Revision> rev = getRevision();
345 if (rev.isPresent()) {
346 sb.append(QNAME_REVISION_DELIMITER).append(rev.get());
348 sb.append(QNAME_RIGHT_PARENTHESIS);
350 sb.append(localName);
351 return sb.toString();
355 * Creates copy of this with revision and prefix unset.
357 * @return copy of this QName with revision and prefix unset.
359 public QName withoutRevision() {
360 return create(getNamespace(), localName);
364 * Formats {@link Revision} representing revision to format <code>YYYY-mm-dd</code>
367 * YANG Specification defines format for <code>revision</code> as
368 * YYYY-mm-dd. This format for revision is reused accross multiple places
369 * such as capabilities URI, YANG modules, etc.
372 * Date object to format
373 * @return String representation or null if the input was null.
375 public static String formattedRevision(final Optional<Revision> revision) {
376 return revision.map(Revision::toString).orElse(null);
380 * Compares this QName to other, without comparing revision.
383 * Compares instance of this to other instance of QName and returns true if
384 * both instances have equal <code>localName</code> ({@link #getLocalName()}
385 * ) and <code>namespace</code> ({@link #getNamespace()}).
388 * Other QName. Must not be null.
389 * @return true if this instance and other have equals localName and
391 * @throws NullPointerException
392 * if <code>other</code> is null.
394 public boolean isEqualWithoutRevision(final QName other) {
395 return localName.equals(other.getLocalName()) && Objects.equals(getNamespace(), other.getNamespace());
398 // FIXME: this comparison function looks odd. We are sorting first by local name and then by module? What is
399 // the impact on iteration order of SortedMap<QName, ?>?
401 @SuppressWarnings("checkstyle:parameterName")
402 public int compareTo(@Nonnull final QName o) {
404 // compare mandatory localName parameter
405 int result = localName.compareTo(o.localName);
409 return module.compareTo(o.module);