common/mdsal-common-api/src/main/java/org/opendaylight/mdsal/common/api/CommitInfo.java

   1 /*
   2  * Copyright (c) 2018 Pantheon Technologies, 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.mdsal.common.api;
   9
  10 import static java.util.Objects.requireNonNull;
  11
  12 import com.google.common.util.concurrent.FluentFuture;
  13 import java.io.Serializable;
  14 import java.time.Instant;
  15 import java.util.UUID;
  16 import org.eclipse.jdt.annotation.NonNullByDefault;
  17 import org.eclipse.jdt.annotation.Nullable;
  18
  19 /**
  20  * Base interface for tagging information about a successful commit. This can include various ways of identifying
  21  * the resulting changeset, timing information or any other piece of data about the commit itself the implementation
  22  * deems interesting to the client.
  23  */
  24 @NonNullByDefault
  25 public interface CommitInfo extends Serializable {
  26     /**
  27      * The {@link UUID} of the commit.
  28      *
  29      * @return the {@link UUID} of this commit
  30      */
  31     @Nullable UUID uuid();
  32
  33     /**
  34      * The {@link Instant} when the commit occurred.
  35      *
  36      * @return the {@link Instant} when the commit occurred
  37      */
  38     @Nullable Instant instant();
  39
  40     /**
  41      * Return an empty {@link CommitInfo}.
  42      *
  43      * @return An empty {@link CommitInfo} instance.
  44      */
  45     static CommitInfo empty() {
  46         return CI.EMPTY;
  47     }
  48
  49     /**
  50      * Return an immediately-completed empty {@link CommitInfo} future.
  51      *
  52      * @return An empty {@link CommitInfo} instance enclosed in a completed future.
  53      */
  54     static FluentFuture<CommitInfo> emptyFluentFuture() {
  55         return CI.EMPTY_FUTURE;
  56     }
  57
  58     /**
  59      * Return a {@link CommitInfo} reporting specified {@link UUID}.
  60      *
  61      * @param uuid UUID to report
  62      * @return a {@link CommitInfo} reporting specified {@link UUID}
  63      * @throws NullPointerException if {@code uuid} is {@code null}
  64      */
  65     static CommitInfo of(final UUID uuid) {
  66         return new CI(requireNonNull(uuid), null);
  67     }
  68
  69     /**
  70      * Return a {@link CommitInfo} reporting specified {@link Instant}.
  71      *
  72      * @param instant Instant to report
  73      * @return a {@link CommitInfo} reporting specified {@link Instant}
  74      * @throws NullPointerException if {@code instant} is {@code null}
  75      */
  76     static CommitInfo of(final Instant instant) {
  77         return new CI(null, requireNonNull(instant));
  78     }
  79
  80     /**
  81      * Return a {@link CommitInfo} reporting specified {@link UUID} and {@link Instant}.
  82      *
  83      * @param uuid UUID to report
  84      * @param instant Instant to report
  85      * @return a {@link CommitInfo} reporting specified {@link UUID} and {@link Instant}
  86      * @throws NullPointerException if any argument is {@code null}
  87      */
  88     static CommitInfo of(final UUID uuid, final Instant instant) {
  89         return new CI(requireNonNull(uuid), requireNonNull(instant));
  90     }
  91
  92     /**
  93      * Return a {@link CommitInfo} reporting optional {@link UUID} and  {@link Instant}.
  94      *
  95      * @param uuid UUID to report
  96      * @param instant Instant to report
  97      * @return a {@link CommitInfo} reporting optional {@link UUID} and  {@link Instant}
  98      */
  99     static CommitInfo ofNullable(final @Nullable UUID uuid, final @Nullable Instant instant) {
 100         return CI.of(uuid, instant);
 101     }
 102 }