common/yang-common/src/main/java/org/opendaylight/yangtools/yang/common/RevisionUnion.java

   1 /*
   2  * Copyright (c) 2024 PANTHEON.tech, s.r.o. 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.common;
   9
  10 import java.io.Serializable;
  11 import java.util.NoSuchElementException;
  12 import java.util.Optional;
  13 import org.eclipse.jdt.annotation.NonNullByDefault;
  14 import org.eclipse.jdt.annotation.Nullable;
  15 import org.opendaylight.yangtools.concepts.Immutable;
  16
  17 /**
  18  * A capture of an optional {@code revision-date}. This is a replacement for {@code Optional<Revision>}, with the added
  19  * benefit of having a non-null string representation in {@link #unionString()}, which is also conveniently returned
  20  * from {@link #toString()}.
  21  *
  22  * <p>
  23  * This contract is exactly the same as this fragment from {@code ietf-yang-library}:
  24  * <pre>{@code
  25  *   type union {
  26  *     type revision-identifier;
  27  *     type string {
  28  *       length "0";
  29  *     }
  30  *   }
  31  * }</pre>
  32  */
  33 @NonNullByDefault
  34 public sealed interface RevisionUnion extends Comparable<RevisionUnion>, Immutable, Serializable
  35         permits Revision, NotRevision {
  36     /**
  37      * Return empty {@link RevisionUnion}.
  38      *
  39      * @return empty {@link RevisionUnion}
  40      */
  41     static NotRevision none() {
  42         return NotRevision.of();
  43     }
  44
  45     static RevisionUnion of(final String unionString) {
  46         return unionString.isEmpty() ? none() : Revision.of(unionString);
  47     }
  48
  49     /**
  50      * A {@code revision-date}-compliant date, or an empty string ({@code ""}).
  51      *
  52      * @return A revision-date or empty string
  53      */
  54     String unionString();
  55
  56     @Override
  57     @SuppressWarnings("checkstyle:parameterName")
  58     default int compareTo(final RevisionUnion o) {
  59         // Since all strings conform to the format, we can use their comparable property to do the correct thing
  60         // with respect to temporal ordering.
  61         return unionString().compareTo(o.unionString());
  62     }
  63
  64     /**
  65      * Return the {@link Revision}, if present.
  66      *
  67      * @return the revision, or {@code null} if not present
  68      */
  69     @Nullable Revision revision();
  70
  71     default Optional<Revision> findRevision() {
  72         return Optional.ofNullable(revision());
  73     }
  74
  75     default Revision getRevision() {
  76         final var revision = revision();
  77         if (revision == null) {
  78             throw new NoSuchElementException();
  79         }
  80         return revision;
  81     }
  82
  83     @Override
  84     int hashCode();
  85
  86     @Override
  87     boolean equals(@Nullable Object obj);
  88
  89     /**
  90      * Returns {@link #unionString()}.
  91      *
  92      * @return {@link #unionString()}
  93      */
  94     @Override
  95     String toString();
  96 }