Package org.opendaylight.yangtools.yang.common

Class Revision

java.lang.Object
org.opendaylight.yangtools.yang.common.Revision
All Implemented Interfaces:
Serializable, Comparable<RevisionUnion>, Immutable, WritableObject, RevisionUnion
public final class Revision extends Object implements RevisionUnion
Dedicated object identifying a YANG module revision.

API design note

This class defines the contents of a revision statement, but modules do not require to have a revision (e.g. they have not started to keep track of revisions).

APIs which involve this class should always transfer instances via Optional<Revision>, which is the primary bridge data type. Implementations can use nullable fields with explicit conversions to/from Optional. Both patterns can take advantage of compare(Optional, Optional) and compare(Revision, Revision) respectively.

See Also:

  • Field Details

    • STRING_FORMAT_PATTERN

      public static final Pattern STRING_FORMAT_PATTERN
      String format pattern, which can be used to match parts of a string into components.

    • MAX_VALUE

      public static final Revision MAX_VALUE
      Revision which compares as greater than any other valid revision.

  • Method Details

    • of

      public static @NonNull Revision of(@NonNull String str)
      Parse a revision string.
      Parameters:
      str - String to be parsed
      Returns:
      A Revision instance.
      Throws:
      DateTimeParseException - if the string format does not conform specification.
      NullPointerException - if the string is null

    • ofNullable

      public static @NonNull Optional<Revision> ofNullable(@Nullable String str)
      Parse a (potentially null) revision string. Null strings result result in Optional.empty().
      Parameters:
      str - String to be parsed
      Returns:
      An optional Revision instance.
      Throws:
      DateTimeParseException - if the string format does not conform specification.

    • revision

      public Revision revision()
      Description copied from interface: RevisionUnion
      Return the Revision, if present.
      Specified by:
      revision in interface RevisionUnion
      Returns:
      the revision, or null if not present

    • unionString

      public String unionString()
      Description copied from interface: RevisionUnion
      A revision-date-compliant date, or an empty string ("").
      Specified by:
      unionString in interface RevisionUnion
      Returns:
      A revision-date or empty string

    • readFrom

      public static @NonNull Revision readFrom(DataInput in) throws IOException
      Throws:
      IOException

    • compare

      public static int compare(@NonNull Optional<Revision> first, @NonNull Optional<Revision> second)
      Compare two Optionals wrapping Revisions. Arguments and return value are consistent with Comparator.compare(Object, Object) interface contract. Missing revisions compare as lower than any other revision.
      Parameters:
      first - First optional revision
      second - Second optional revision
      Returns:
      Positive, zero, or negative integer.

    • compare

      public static int compare(@Nullable Revision first, @Nullable Revision second)
      Compare two explicitly nullable Revisions. Unlike RevisionUnion.compareTo(Revision), this handles both arguments being null such that total ordering is defined.
      Parameters:
      first - First revision
      second - Second revision
      Returns:
      Positive, zero, or negative integer.

    • hashCode

      public int hashCode()
      Specified by:
      hashCode in interface RevisionUnion
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Specified by:
      equals in interface RevisionUnion
      Overrides:
      equals in class Object

    • toString

      public String toString()
      Return the revision string according to RFC7950, section 7.1.9. The string is guaranteed to be composed on 10 ASCII characters in YYYY-MM-DD format. The items are guaranteed to be decimal numbers. There are no further guarantees as to convertibility to an actual calendar date, as this method can validly return "2019-02-29" (even if 2019 is not a leap year) or "2022-12-32" (even if no month has 32 days).
      Specified by:
      toString in interface RevisionUnion
      Overrides:
      toString in class Object
      Returns:
      A string in YYYY-MM-DD format