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.DataInput;
  11 import java.io.DataOutput;
  12 import java.io.IOException;
  13 import java.io.Serializable;
  14 import java.util.NoSuchElementException;
  15 import java.util.Optional;
  16 import org.eclipse.jdt.annotation.NonNullByDefault;
  17 import org.eclipse.jdt.annotation.Nullable;
  18 import org.opendaylight.yangtools.concepts.Immutable;
  19 import org.opendaylight.yangtools.concepts.WritableObject;
  20
  21 /**
  22  * A capture of an optional {@code revision-date}. This is a replacement for {@code Optional<Revision>}, with the added
  23  * benefit of having a non-null string representation in {@link #unionString()}, which is also conveniently returned
  24  * from {@link #toString()}.
  25  *
  26  * <p>
  27  * This contract is exactly the same as this fragment from {@code ietf-yang-library}:
  28  * <pre>{@code
  29  *   type union {
  30  *     type revision-identifier;
  31  *     type string {
  32  *       length "0";
  33  *     }
  34  *   }
  35  * }</pre>
  36  */
  37 @NonNullByDefault
  38 public sealed interface RevisionUnion extends Comparable<RevisionUnion>, Immutable, Serializable, WritableObject
  39         permits Revision, NotRevision {
  40     /**
  41      * Return empty {@link RevisionUnion}.
  42      *
  43      * @return empty {@link RevisionUnion}
  44      */
  45     static NotRevision none() {
  46         return NotRevision.of();
  47     }
  48
  49     static RevisionUnion of(final String unionString) {
  50         return unionString.isEmpty() ? none() : Revision.of(unionString);
  51     }
  52
  53     static RevisionUnion of(final @Nullable Revision revision) {
  54         return revision != null ? revision : none();
  55     }
  56
  57     /**
  58      * A {@code revision-date}-compliant date, or an empty string ({@code ""}).
  59      *
  60      * @return A revision-date or empty string
  61      */
  62     String unionString();
  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     @SuppressWarnings("checkstyle:parameterName")
  85     default int compareTo(final RevisionUnion o) {
  86         // Since all strings conform to the format, we can use their comparable property to do the correct thing
  87         // with respect to temporal ordering.
  88         return unionString().compareTo(o.unionString());
  89     }
  90
  91     @Override
  92     default void writeTo(final DataOutput out) throws IOException {
  93         out.writeUTF(unionString());
  94     }
  95
  96     static RevisionUnion readFrom(final DataInput in) throws IOException {
  97         final var unionString = in.readUTF();
  98         return unionString.isEmpty() ? none() : Revision.ofRead(unionString);
  99     }
 100
 101     @Override
 102     int hashCode();
 103
 104     @Override
 105     boolean equals(@Nullable Object obj);
 106
 107     /**
 108      * Returns {@link #unionString()}.
 109      *
 110      * @return {@link #unionString()}
 111      */
 112     @Override
 113     String toString();
 114 }