Line data    Source code

       1             : // Copyright (C) 2017 The Android Open Source Project
       2             : //
       3             : // Licensed under the Apache License, Version 2.0 (the "License");
       4             : // you may not use this file except in compliance with the License.
       5             : // You may obtain a copy of the License at
       6             : //
       7             : // http://www.apache.org/licenses/LICENSE-2.0
       8             : //
       9             : // Unless required by applicable law or agreed to in writing, software
      10             : // distributed under the License is distributed on an "AS IS" BASIS,
      11             : // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      12             : // See the License for the specific language governing permissions and
      13             : // limitations under the License.
      14             : 
      15             : package com.google.gerrit.server.group.db;
      16             : 
      17             : import com.google.auto.value.AutoValue;
      18             : import com.google.common.collect.ImmutableSet;
      19             : import com.google.gerrit.entities.Account;
      20             : import com.google.gerrit.entities.AccountGroup;
      21             : import java.time.Instant;
      22             : import java.util.Optional;
      23             : import java.util.Set;
      24             : 
      25             : /**
      26             :  * Data holder for updates to be applied to a group.
      27             :  *
      28             :  * <p>A {@link GroupDelta} specifies the modifications to be applied to a group. Only fields set via
      29             :  * {@link GroupDelta.Builder} will be updated.
      30             :  */
      31             : @AutoValue
      32         152 : public abstract class GroupDelta {
      33             : 
      34             :   /** Representation of a member modification as defined by {@link #apply(ImmutableSet)}. */
      35             :   @FunctionalInterface
      36             :   public interface MemberModification {
      37             : 
      38             :     /**
      39             :      * Applies the modification to the given members.
      40             :      *
      41             :      * @param originalMembers current members of the group. If used for a group creation, this set
      42             :      *     is empty.
      43             :      * @return the desired resulting members (not the diff of the members!)
      44             :      */
      45             :     Set<Account.Id> apply(ImmutableSet<Account.Id> originalMembers);
      46             :   }
      47             : 
      48             :   @FunctionalInterface
      49             :   public interface SubgroupModification {
      50             :     /**
      51             :      * Applies the modification to the given subgroups.
      52             :      *
      53             :      * @param originalSubgroups current subgroups of the group. If used for a group creation, this
      54             :      *     set is empty.
      55             :      * @return the desired resulting subgroups (not the diff of the subgroups!)
      56             :      */
      57             :     Set<AccountGroup.UUID> apply(ImmutableSet<AccountGroup.UUID> originalSubgroups);
      58             :   }
      59             : 
      60             :   /** Defines the new name of the group. If not specified, the name remains unchanged. */
      61             :   public abstract Optional<AccountGroup.NameKey> getName();
      62             : 
      63             :   /**
      64             :    * Defines the new description of the group. If not specified, the description remains unchanged.
      65             :    *
      66             :    * <p><strong>Note: </strong>Passing the empty string unsets the description.
      67             :    */
      68             :   public abstract Optional<String> getDescription();
      69             : 
      70             :   /** Defines the new owner of the group. If not specified, the owner remains unchanged. */
      71             :   public abstract Optional<AccountGroup.UUID> getOwnerGroupUUID();
      72             : 
      73             :   /**
      74             :    * Defines the new state of the 'visibleToAll' flag of the group. If not specified, the flag
      75             :    * remains unchanged.
      76             :    */
      77             :   public abstract Optional<Boolean> getVisibleToAll();
      78             : 
      79             :   /**
      80             :    * Defines how the members of the group should be modified. By default (that is if nothing is
      81             :    * specified), the members remain unchanged.
      82             :    *
      83             :    * @return a {@link MemberModification} which gets the current members of the group as input and
      84             :    *     outputs the desired resulting members
      85             :    */
      86             :   public abstract MemberModification getMemberModification();
      87             : 
      88             :   /**
      89             :    * Defines how the subgroups of the group should be modified. By default (that is if nothing is
      90             :    * specified), the subgroups remain unchanged.
      91             :    *
      92             :    * @return a {@link SubgroupModification} which gets the current subgroups of the group as input
      93             :    *     and outputs the desired resulting subgroups
      94             :    */
      95             :   public abstract SubgroupModification getSubgroupModification();
      96             : 
      97             :   /**
      98             :    * Defines the {@code Timestamp} to be used for the NoteDb commits of the update. If not
      99             :    * specified, the current {@code Timestamp} when creating the commit will be used.
     100             :    *
     101             :    * <p>If this {@link GroupDelta} is passed next to an {@link InternalGroupCreation} during a group
     102             :    * creation, this {@code Timestamp} is used for the NoteDb commits of the new group. Hence, the
     103             :    * {@link com.google.gerrit.entities.InternalGroup#getCreatedOn() InternalGroup#getCreatedOn()}
     104             :    * field will match this {@code Timestamp}.
     105             :    *
     106             :    * <p><strong>Note: </strong>{@code Timestamp}s of NoteDb commits for groups are used for events
     107             :    * in the audit log. For this reason, specifying this field will have an effect on the resulting
     108             :    * audit log.
     109             :    */
     110             :   public abstract Optional<Instant> getUpdatedOn();
     111             : 
     112             :   public abstract Builder toBuilder();
     113             : 
     114             :   public static Builder builder() {
     115         152 :     return new AutoValue_GroupDelta.Builder()
     116         152 :         .setMemberModification(in -> in)
     117         152 :         .setSubgroupModification(in -> in);
     118             :   }
     119             : 
     120             :   /** A builder for a {@link GroupDelta}. */
     121             :   @AutoValue.Builder
     122         152 :   public abstract static class Builder {
     123             : 
     124             :     /**
     125             :      * Defines the new name of the group
     126             :      *
     127             :      * <p>See {@link #getName}.
     128             :      */
     129             :     public abstract Builder setName(AccountGroup.NameKey name);
     130             : 
     131             :     /**
     132             :      * Defines the new description of the group
     133             :      *
     134             :      * <p>See {@link #getDescription()}}
     135             :      */
     136             :     public abstract Builder setDescription(String description);
     137             : 
     138             :     /**
     139             :      * Defines the new owner of the group
     140             :      *
     141             :      * <p>See {@link #getOwnerGroupUUID()}
     142             :      */
     143             :     public abstract Builder setOwnerGroupUUID(AccountGroup.UUID ownerGroupUUID);
     144             : 
     145             :     /**
     146             :      * Defines the new state of the 'visibleToAll' flag of the group
     147             :      *
     148             :      * <p>See {@link #getVisibleToAll()}
     149             :      */
     150             :     public abstract Builder setVisibleToAll(boolean visibleToAll);
     151             : 
     152             :     /**
     153             :      * Set {@link MemberModification} for the prospective {@link GroupDelta}
     154             :      *
     155             :      * <p>See {@link #getMemberModification()}
     156             :      */
     157             :     public abstract Builder setMemberModification(MemberModification memberModification);
     158             : 
     159             :     /**
     160             :      * Returns the currently defined {@link MemberModification} for the prospective {@link
     161             :      * GroupDelta}.
     162             :      *
     163             :      * <p>This modification can be tweaked further and passed to {@link
     164             :      * #setMemberModification(GroupDelta.MemberModification)} in order to combine multiple member
     165             :      * additions, deletions, or other modifications into one update.
     166             :      */
     167             :     public abstract MemberModification getMemberModification();
     168             : 
     169             :     /**
     170             :      * Set {@link SubgroupModification} for the prospective {@link GroupDelta}
     171             :      *
     172             :      * <p>See {@link #getSubgroupModification()}
     173             :      */
     174             :     public abstract Builder setSubgroupModification(SubgroupModification subgroupModification);
     175             : 
     176             :     /**
     177             :      * Returns the currently defined {@link SubgroupModification} for the prospective {@link
     178             :      * GroupDelta}.
     179             :      *
     180             :      * <p>This modification can be tweaked further and passed to {@link
     181             :      * #setSubgroupModification(GroupDelta.SubgroupModification)} in order to combine multiple
     182             :      * subgroup additions, deletions, or other modifications into one update.
     183             :      */
     184             :     public abstract SubgroupModification getSubgroupModification();
     185             : 
     186             :     /**
     187             :      * Defines the {@code Instant} to be used for the NoteDb commits of the update. If not
     188             :      * specified, the current {@code Instant} when creating the commit will be used.
     189             :      *
     190             :      * <p>See {@link #getUpdatedOn()}
     191             :      */
     192             :     public abstract Builder setUpdatedOn(Instant timestamp);
     193             : 
     194             :     public abstract GroupDelta build();
     195             :   }
     196             : }