Line data    Source code

       1             : // Copyright (C) 2015 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.groups;
      16             : 
      17             : import com.google.gerrit.extensions.client.ListGroupsOption;
      18             : import com.google.gerrit.extensions.common.GroupInfo;
      19             : import com.google.gerrit.extensions.restapi.NotImplementedException;
      20             : import com.google.gerrit.extensions.restapi.RestApiException;
      21             : import java.util.ArrayList;
      22             : import java.util.Arrays;
      23             : import java.util.Collections;
      24             : import java.util.EnumSet;
      25             : import java.util.List;
      26             : import java.util.Map;
      27             : import java.util.Set;
      28             : 
      29             : public interface Groups {
      30             :   /**
      31             :    * Look up a group by ID.
      32             :    *
      33             :    * <p><strong>Note:</strong> This method eagerly reads the group. Methods that mutate the group do
      34             :    * not necessarily re-read the group. Therefore, calling a getter method on an instance after
      35             :    * calling a mutation method on that same instance is not guaranteed to reflect the mutation. It
      36             :    * is not recommended to store references to {@code groupApi} instances.
      37             :    *
      38             :    * @param id any identifier supported by the REST API, including group name or UUID.
      39             :    * @return API for accessing the group.
      40             :    * @throws RestApiException if an error occurred.
      41             :    */
      42             :   GroupApi id(String id) throws RestApiException;
      43             : 
      44             :   /** Create a new group with the given name and default options. */
      45             :   GroupApi create(String name) throws RestApiException;
      46             : 
      47             :   /** Create a new group. */
      48             :   GroupApi create(GroupInput input) throws RestApiException;
      49             : 
      50             :   /** Returns new request for listing groups. */
      51             :   ListRequest list();
      52             : 
      53             :   /**
      54             :    * Query groups.
      55             :    *
      56             :    * <p>Example code: {@code query().withQuery("inname:test").withLimit(10).get()}
      57             :    *
      58             :    * @return API for setting parameters and getting result.
      59             :    */
      60             :   QueryRequest query();
      61             : 
      62             :   /**
      63             :    * Query groups.
      64             :    *
      65             :    * <p>Shortcut API for {@code query().withQuery(String)}.
      66             :    *
      67             :    * @see #query()
      68             :    */
      69             :   QueryRequest query(String query);
      70             : 
      71           1 :   abstract class ListRequest {
      72           1 :     private final EnumSet<ListGroupsOption> options = EnumSet.noneOf(ListGroupsOption.class);
      73           1 :     private final List<String> projects = new ArrayList<>();
      74           1 :     private final List<String> groups = new ArrayList<>();
      75             : 
      76             :     private boolean visibleToAll;
      77             :     private String user;
      78             :     private boolean owned;
      79             :     private int limit;
      80             :     private int start;
      81             :     private String substring;
      82             :     private String suggest;
      83             :     private String regex;
      84             :     private String ownedBy;
      85             : 
      86             :     public List<GroupInfo> get() throws RestApiException {
      87           1 :       Map<String, GroupInfo> map = getAsMap();
      88           1 :       List<GroupInfo> result = new ArrayList<>(map.size());
      89           1 :       for (Map.Entry<String, GroupInfo> e : map.entrySet()) {
      90             :         // ListGroups "helpfully" nulls out names when converting to a map.
      91           1 :         e.getValue().name = e.getKey();
      92           1 :         result.add(e.getValue());
      93           1 :       }
      94           1 :       return Collections.unmodifiableList(result);
      95             :     }
      96             : 
      97             :     public abstract Map<String, GroupInfo> getAsMap() throws RestApiException;
      98             : 
      99             :     public ListRequest addOption(ListGroupsOption option) {
     100           0 :       options.add(option);
     101           0 :       return this;
     102             :     }
     103             : 
     104             :     public ListRequest addOptions(ListGroupsOption... options) {
     105           0 :       return addOptions(Arrays.asList(options));
     106             :     }
     107             : 
     108             :     public ListRequest addOptions(Iterable<ListGroupsOption> options) {
     109           0 :       for (ListGroupsOption option : options) {
     110           0 :         this.options.add(option);
     111           0 :       }
     112           0 :       return this;
     113             :     }
     114             : 
     115             :     public ListRequest withProject(String project) {
     116           0 :       projects.add(project);
     117           0 :       return this;
     118             :     }
     119             : 
     120             :     public ListRequest addGroup(String uuid) {
     121           1 :       groups.add(uuid);
     122           1 :       return this;
     123             :     }
     124             : 
     125             :     public ListRequest withVisibleToAll(boolean visible) {
     126           1 :       visibleToAll = visible;
     127           1 :       return this;
     128             :     }
     129             : 
     130             :     public ListRequest withUser(String user) {
     131           1 :       this.user = user;
     132           1 :       return this;
     133             :     }
     134             : 
     135             :     public ListRequest withOwned(boolean owned) {
     136           1 :       this.owned = owned;
     137           1 :       return this;
     138             :     }
     139             : 
     140             :     public ListRequest withLimit(int limit) {
     141           0 :       this.limit = limit;
     142           0 :       return this;
     143             :     }
     144             : 
     145             :     public ListRequest withStart(int start) {
     146           1 :       this.start = start;
     147           1 :       return this;
     148             :     }
     149             : 
     150             :     public ListRequest withSubstring(String substring) {
     151           1 :       this.substring = substring;
     152           1 :       return this;
     153             :     }
     154             : 
     155             :     public ListRequest withRegex(String regex) {
     156           1 :       this.regex = regex;
     157           1 :       return this;
     158             :     }
     159             : 
     160             :     public ListRequest withSuggest(String suggest) {
     161           1 :       this.suggest = suggest;
     162           1 :       return this;
     163             :     }
     164             : 
     165             :     public ListRequest withOwnedBy(String ownedBy) {
     166           1 :       this.ownedBy = ownedBy;
     167           1 :       return this;
     168             :     }
     169             : 
     170             :     public Set<ListGroupsOption> getOptions() {
     171           1 :       return options;
     172             :     }
     173             : 
     174             :     public List<String> getProjects() {
     175           1 :       return Collections.unmodifiableList(projects);
     176             :     }
     177             : 
     178             :     public List<String> getGroups() {
     179           1 :       return Collections.unmodifiableList(groups);
     180             :     }
     181             : 
     182             :     public boolean getVisibleToAll() {
     183           1 :       return visibleToAll;
     184             :     }
     185             : 
     186             :     public String getUser() {
     187           1 :       return user;
     188             :     }
     189             : 
     190             :     public boolean getOwned() {
     191           1 :       return owned;
     192             :     }
     193             : 
     194             :     public int getLimit() {
     195           1 :       return limit;
     196             :     }
     197             : 
     198             :     public int getStart() {
     199           1 :       return start;
     200             :     }
     201             : 
     202             :     public String getSubstring() {
     203           1 :       return substring;
     204             :     }
     205             : 
     206             :     public String getRegex() {
     207           1 :       return regex;
     208             :     }
     209             : 
     210             :     public String getSuggest() {
     211           1 :       return suggest;
     212             :     }
     213             : 
     214             :     public String getOwnedBy() {
     215           1 :       return ownedBy;
     216             :     }
     217             :   }
     218             : 
     219             :   /**
     220             :    * API for setting parameters and getting result. Used for {@code query()}.
     221             :    *
     222             :    * @see #query()
     223             :    */
     224          12 :   abstract class QueryRequest {
     225             :     private String query;
     226             :     private int limit;
     227             :     private int start;
     228          12 :     private Set<ListGroupsOption> options = EnumSet.noneOf(ListGroupsOption.class);
     229             : 
     230             :     /** Execute query and returns the matched groups as list. */
     231             :     public abstract List<GroupInfo> get() throws RestApiException;
     232             : 
     233             :     /**
     234             :      * Set query.
     235             :      *
     236             :      * @param query needs to be in human-readable form.
     237             :      */
     238             :     public QueryRequest withQuery(String query) {
     239          12 :       this.query = query;
     240          12 :       return this;
     241             :     }
     242             : 
     243             :     /**
     244             :      * Set limit for returned list of groups. Optional; server-default is used when not provided.
     245             :      */
     246             :     public QueryRequest withLimit(int limit) {
     247           2 :       this.limit = limit;
     248           2 :       return this;
     249             :     }
     250             : 
     251             :     /** Set number of groups to skip. Optional; no groups are skipped when not provided. */
     252             :     public QueryRequest withStart(int start) {
     253           2 :       this.start = start;
     254           2 :       return this;
     255             :     }
     256             : 
     257             :     /** Set an option on the request, appending to existing options. */
     258             :     public QueryRequest withOption(ListGroupsOption options) {
     259           1 :       this.options.add(options);
     260           1 :       return this;
     261             :     }
     262             : 
     263             :     /** Set options on the request, appending to existing options. */
     264             :     public QueryRequest withOptions(ListGroupsOption... options) {
     265           0 :       this.options.addAll(Arrays.asList(options));
     266           0 :       return this;
     267             :     }
     268             : 
     269             :     /** Set options on the request, replacing existing options. */
     270             :     public QueryRequest withOptions(Set<ListGroupsOption> options) {
     271           0 :       this.options = options;
     272           0 :       return this;
     273             :     }
     274             : 
     275             :     public String getQuery() {
     276          12 :       return query;
     277             :     }
     278             : 
     279             :     public int getLimit() {
     280          12 :       return limit;
     281             :     }
     282             : 
     283             :     public int getStart() {
     284          12 :       return start;
     285             :     }
     286             : 
     287             :     public Set<ListGroupsOption> getOptions() {
     288          12 :       return options;
     289             :     }
     290             :   }
     291             : 
     292             :   /**
     293             :    * A default implementation which allows source compatibility when adding new methods to the
     294             :    * interface.
     295             :    */
     296           0 :   class NotImplemented implements Groups {
     297             :     @Override
     298             :     public GroupApi id(String id) throws RestApiException {
     299           0 :       throw new NotImplementedException();
     300             :     }
     301             : 
     302             :     @Override
     303             :     public GroupApi create(String name) throws RestApiException {
     304           0 :       throw new NotImplementedException();
     305             :     }
     306             : 
     307             :     @Override
     308             :     public GroupApi create(GroupInput input) throws RestApiException {
     309           0 :       throw new NotImplementedException();
     310             :     }
     311             : 
     312             :     @Override
     313             :     public ListRequest list() {
     314           0 :       throw new NotImplementedException();
     315             :     }
     316             : 
     317             :     @Override
     318             :     public QueryRequest query() {
     319           0 :       throw new NotImplementedException();
     320             :     }
     321             : 
     322             :     @Override
     323             :     public QueryRequest query(String query) {
     324           0 :       throw new NotImplementedException();
     325             :     }
     326             :   }
     327             : }