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.extensions.api.changes;
      16             : 
      17             : import com.google.gerrit.extensions.client.ChangeEditDetailOption;
      18             : import com.google.gerrit.extensions.common.EditInfo;
      19             : import com.google.gerrit.extensions.restapi.BinaryResult;
      20             : import com.google.gerrit.extensions.restapi.NotImplementedException;
      21             : import com.google.gerrit.extensions.restapi.RawInput;
      22             : import com.google.gerrit.extensions.restapi.RestApiException;
      23             : import java.util.EnumSet;
      24             : import java.util.Optional;
      25             : import java.util.Set;
      26             : 
      27             : /**
      28             :  * An API for the change edit of a change. A change edit is similar to a patch set and will become
      29             :  * one if it is published (by {@link #publish(PublishChangeEditInput)}). Whenever the descriptions
      30             :  * below refer to files of a change edit, they actually refer to the files of the Git tree which is
      31             :  * represented by the change edit. A change can have at most one change edit at each point in time.
      32             :  */
      33             : public interface ChangeEditApi {
      34             : 
      35           1 :   abstract class ChangeEditDetailRequest {
      36             :     private String base;
      37           1 :     private EnumSet<ChangeEditDetailOption> options = EnumSet.noneOf(ChangeEditDetailOption.class);
      38             : 
      39             :     public abstract Optional<EditInfo> get() throws RestApiException;
      40             : 
      41             :     public ChangeEditDetailRequest withBase(String base) {
      42           1 :       this.base = base;
      43           1 :       return this;
      44             :     }
      45             : 
      46             :     public ChangeEditDetailRequest withOption(ChangeEditDetailOption option) {
      47           1 :       this.options.add(option);
      48           1 :       return this;
      49             :     }
      50             : 
      51             :     public String getBase() {
      52           1 :       return base;
      53             :     }
      54             : 
      55             :     public Set<ChangeEditDetailOption> options() {
      56           1 :       return options;
      57             :     }
      58             :   }
      59             : 
      60             :   ChangeEditDetailRequest detail() throws RestApiException;
      61             : 
      62             :   /**
      63             :    * Retrieves details regarding the change edit.
      64             :    *
      65             :    * @return an {@code Optional} containing details about the change edit if it exists, or {@code
      66             :    *     Optional.empty()}
      67             :    * @throws RestApiException if the change edit couldn't be retrieved
      68             :    */
      69             :   Optional<EditInfo> get() throws RestApiException;
      70             : 
      71             :   /**
      72             :    * Creates a new change edit. It has exactly the same Git tree as the current patch set of the
      73             :    * change.
      74             :    *
      75             :    * @throws RestApiException if the change edit couldn't be created or a change edit already exists
      76             :    */
      77             :   void create() throws RestApiException;
      78             : 
      79             :   /**
      80             :    * Deletes the change edit.
      81             :    *
      82             :    * @throws RestApiException if the change edit couldn't be deleted or a change edit wasn't present
      83             :    */
      84             :   void delete() throws RestApiException;
      85             : 
      86             :   /**
      87             :    * Rebases the change edit on top of the latest patch set of this change.
      88             :    *
      89             :    * @throws RestApiException if the change edit couldn't be rebased or a change edit wasn't present
      90             :    */
      91             :   void rebase() throws RestApiException;
      92             : 
      93             :   /**
      94             :    * Publishes the change edit using default settings. See {@link #publish(PublishChangeEditInput)}
      95             :    * for more details.
      96             :    *
      97             :    * @throws RestApiException if the change edit couldn't be published or a change edit wasn't
      98             :    *     present
      99             :    */
     100             :   void publish() throws RestApiException;
     101             : 
     102             :   /**
     103             :    * Publishes the change edit. Publishing means that the change edit is turned into a regular patch
     104             :    * set of the change.
     105             :    *
     106             :    * @param publishChangeEditInput a {@code PublishChangeEditInput} specifying the options which
     107             :    *     should be applied
     108             :    * @throws RestApiException if the change edit couldn't be published or a change edit wasn't
     109             :    *     present
     110             :    */
     111             :   void publish(PublishChangeEditInput publishChangeEditInput) throws RestApiException;
     112             : 
     113             :   /**
     114             :    * Retrieves the contents of the specified file from the change edit.
     115             :    *
     116             :    * @param filePath the path of the file
     117             :    * @return an {@code Optional} containing the contents of the file as a {@code BinaryResult} if
     118             :    *     the file exists within the change edit, or {@code Optional.empty()}
     119             :    * @throws RestApiException if the contents of the file couldn't be retrieved or a change edit
     120             :    *     wasn't present
     121             :    */
     122             :   Optional<BinaryResult> getFile(String filePath) throws RestApiException;
     123             : 
     124             :   /**
     125             :    * Renames a file of the change edit or moves the file to another directory. If the change edit
     126             :    * doesn't exist, it will be created based on the current patch set of the change.
     127             :    *
     128             :    * @param oldFilePath the current file path
     129             :    * @param newFilePath the desired file path
     130             :    * @throws RestApiException if the file couldn't be renamed
     131             :    */
     132             :   void renameFile(String oldFilePath, String newFilePath) throws RestApiException;
     133             : 
     134             :   /**
     135             :    * Restores a file of the change edit to the state in which it was before the patch set on which
     136             :    * the change edit is based. This includes the file content as well as the existence or
     137             :    * non-existence of the file. If the change edit doesn't exist, it will be created based on the
     138             :    * current patch set of the change.
     139             :    *
     140             :    * @param filePath the path of the file
     141             :    * @throws RestApiException if the file couldn't be restored to its previous state
     142             :    */
     143             :   void restoreFile(String filePath) throws RestApiException;
     144             : 
     145             :   /**
     146             :    * Modify the contents of the specified file of the change edit. If no content is provided, the
     147             :    * content of the file is erased but the file isn't deleted. If the change edit doesn't exist, it
     148             :    * will be created based on the current patch set of the change.
     149             :    *
     150             :    * @param filePath the path of the file which should be modified
     151             :    * @param newContent the desired content of the file
     152             :    * @throws RestApiException if the content of the file couldn't be modified
     153             :    */
     154             :   default void modifyFile(String filePath, RawInput newContent) throws RestApiException {
     155          18 :     FileContentInput input = new FileContentInput();
     156          18 :     input.content = newContent;
     157          17 :     modifyFile(filePath, input);
     158          17 :   }
     159             : 
     160             :   /**
     161             :    * Modify the contents of the specified file of the change edit. If no content is provided, the
     162             :    * content of the file is erased but the file isn't deleted. If the change edit doesn't exist, it
     163             :    * will be created based on the current patch set of the change.
     164             :    *
     165             :    * @param filePath the path of the file which should be modified
     166             :    * @param input the desired content of the file
     167             :    * @throws RestApiException if the content of the file couldn't be modified
     168             :    */
     169             :   void modifyFile(String filePath, FileContentInput input) throws RestApiException;
     170             : 
     171             :   /**
     172             :    * Deletes the specified file from the change edit. If the change edit doesn't exist, it will be
     173             :    * created based on the current patch set of the change.
     174             :    *
     175             :    * @param filePath the path fo the file which should be deleted
     176             :    * @throws RestApiException if the file couldn't be deleted
     177             :    */
     178             :   void deleteFile(String filePath) throws RestApiException;
     179             : 
     180             :   /**
     181             :    * Retrieves the commit message of the change edit.
     182             :    *
     183             :    * @return the commit message of the change edit
     184             :    * @throws RestApiException if the commit message couldn't be retrieved or a change edit wasn't
     185             :    *     present
     186             :    */
     187             :   String getCommitMessage() throws RestApiException;
     188             : 
     189             :   /**
     190             :    * Modifies the commit message of the change edit. If the change edit doesn't exist, it will be
     191             :    * created based on the current patch set of the change.
     192             :    *
     193             :    * @param newCommitMessage the desired commit message
     194             :    * @throws RestApiException if the commit message couldn't be modified
     195             :    */
     196             :   void modifyCommitMessage(String newCommitMessage) throws RestApiException;
     197             : 
     198             :   /**
     199             :    * A default implementation which allows source compatibility when adding new methods to the
     200             :    * interface.
     201             :    */
     202           0 :   class NotImplemented implements ChangeEditApi {
     203             :     @Override
     204             :     public ChangeEditDetailRequest detail() throws RestApiException {
     205           0 :       throw new NotImplementedException();
     206             :     }
     207             : 
     208             :     @Override
     209             :     public Optional<EditInfo> get() throws RestApiException {
     210           0 :       throw new NotImplementedException();
     211             :     }
     212             : 
     213             :     @Override
     214             :     public void create() throws RestApiException {
     215           0 :       throw new NotImplementedException();
     216             :     }
     217             : 
     218             :     @Override
     219             :     public void delete() throws RestApiException {
     220           0 :       throw new NotImplementedException();
     221             :     }
     222             : 
     223             :     @Override
     224             :     public void rebase() throws RestApiException {
     225           0 :       throw new NotImplementedException();
     226             :     }
     227             : 
     228             :     @Override
     229             :     public void publish() throws RestApiException {
     230           0 :       throw new NotImplementedException();
     231             :     }
     232             : 
     233             :     @Override
     234             :     public void publish(PublishChangeEditInput publishChangeEditInput) throws RestApiException {
     235           0 :       throw new NotImplementedException();
     236             :     }
     237             : 
     238             :     @Override
     239             :     public Optional<BinaryResult> getFile(String filePath) throws RestApiException {
     240           0 :       throw new NotImplementedException();
     241             :     }
     242             : 
     243             :     @Override
     244             :     public void renameFile(String oldFilePath, String newFilePath) throws RestApiException {
     245           0 :       throw new NotImplementedException();
     246             :     }
     247             : 
     248             :     @Override
     249             :     public void restoreFile(String filePath) throws RestApiException {
     250           0 :       throw new NotImplementedException();
     251             :     }
     252             : 
     253             :     @Override
     254             :     public void modifyFile(String filePath, FileContentInput input) throws RestApiException {
     255           0 :       throw new NotImplementedException();
     256             :     }
     257             : 
     258             :     @Override
     259             :     public void deleteFile(String filePath) throws RestApiException {
     260           0 :       throw new NotImplementedException();
     261             :     }
     262             : 
     263             :     @Override
     264             :     public String getCommitMessage() throws RestApiException {
     265           0 :       throw new NotImplementedException();
     266             :     }
     267             : 
     268             :     @Override
     269             :     public void modifyCommitMessage(String newCommitMessage) throws RestApiException {
     270           0 :       throw new NotImplementedException();
     271             :     }
     272             :   }
     273             : }