Line data    Source code

       1             : // Copyright (C) 2014 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.accounts;
      16             : 
      17             : import com.google.gerrit.extensions.client.ListAccountsOption;
      18             : import com.google.gerrit.extensions.common.AccountInfo;
      19             : import com.google.gerrit.extensions.restapi.NotImplementedException;
      20             : import com.google.gerrit.extensions.restapi.RestApiException;
      21             : import java.util.Arrays;
      22             : import java.util.EnumSet;
      23             : import java.util.List;
      24             : import java.util.Set;
      25             : 
      26             : public interface Accounts {
      27             :   /**
      28             :    * Look up an account by ID.
      29             :    *
      30             :    * <p><strong>Note:</strong> This method eagerly reads the account. Methods that mutate the
      31             :    * account do not necessarily re-read the account. Therefore, calling a getter method on an
      32             :    * instance after calling a mutation method on that same instance is not guaranteed to reflect the
      33             :    * mutation. It is not recommended to store references to {@code AccountApi} instances.
      34             :    *
      35             :    * @param id any identifier supported by the REST API, including numeric ID, email, or username.
      36             :    * @return API for accessing the account.
      37             :    * @throws RestApiException if an error occurred.
      38             :    */
      39             :   AccountApi id(String id) throws RestApiException;
      40             : 
      41             :   /**
      42             :    * Look up an account by ID. #id(String)
      43             :    *
      44             :    * <p>See #id(String)
      45             :    */
      46             :   AccountApi id(int id) throws RestApiException;
      47             : 
      48             :   /**
      49             :    * Look up the account of the current in-scope user.
      50             :    *
      51             :    * @see #id(String)
      52             :    */
      53             :   AccountApi self() throws RestApiException;
      54             : 
      55             :   /** Create a new account with the given username and default options. */
      56             :   AccountApi create(String username) throws RestApiException;
      57             : 
      58             :   /** Create a new account. */
      59             :   AccountApi create(AccountInput input) throws RestApiException;
      60             : 
      61             :   /**
      62             :    * Suggest users for a given query.
      63             :    *
      64             :    * <p>Example code: {@code suggestAccounts().withQuery("Reviewer").withLimit(5).get()}
      65             :    *
      66             :    * @return API for setting parameters and getting result.
      67             :    */
      68             :   SuggestAccountsRequest suggestAccounts() throws RestApiException;
      69             : 
      70             :   /**
      71             :    * Suggest users for a given query.
      72             :    *
      73             :    * <p>Shortcut API for {@code suggestAccounts().withQuery(String)}.
      74             :    *
      75             :    * @see #suggestAccounts()
      76             :    */
      77             :   SuggestAccountsRequest suggestAccounts(String query) throws RestApiException;
      78             : 
      79             :   /**
      80             :    * Query users.
      81             :    *
      82             :    * <p>Example code: {@code query().withQuery("name:John email:example.com").withLimit(5).get()}
      83             :    *
      84             :    * @return API for setting parameters and getting result.
      85             :    */
      86             :   QueryRequest query() throws RestApiException;
      87             : 
      88             :   /**
      89             :    * Query users.
      90             :    *
      91             :    * <p>Shortcut API for {@code query().withQuery(String)}.
      92             :    *
      93             :    * @see #query()
      94             :    */
      95             :   QueryRequest query(String query) throws RestApiException;
      96             : 
      97             :   /**
      98             :    * API for setting parameters and getting result. Used for {@code suggestAccounts()}.
      99             :    *
     100             :    * @see #suggestAccounts()
     101             :    */
     102           1 :   abstract class SuggestAccountsRequest {
     103             :     private String query;
     104             :     private int limit;
     105             : 
     106             :     /** Execute query and return a list of accounts. */
     107             :     public abstract List<AccountInfo> get() throws RestApiException;
     108             : 
     109             :     /**
     110             :      * Set query.
     111             :      *
     112             :      * @param query needs to be in human-readable form.
     113             :      */
     114             :     public SuggestAccountsRequest withQuery(String query) {
     115           1 :       this.query = query;
     116           1 :       return this;
     117             :     }
     118             : 
     119             :     /**
     120             :      * Set limit for returned list of accounts. Optional; server-default is used when not provided.
     121             :      */
     122             :     public SuggestAccountsRequest withLimit(int limit) {
     123           0 :       this.limit = limit;
     124           0 :       return this;
     125             :     }
     126             : 
     127             :     public String getQuery() {
     128           1 :       return query;
     129             :     }
     130             : 
     131             :     public int getLimit() {
     132           1 :       return limit;
     133             :     }
     134             :   }
     135             : 
     136             :   /**
     137             :    * API for setting parameters and getting result. Used for {@code query()}.
     138             :    *
     139             :    * @see #query()
     140             :    */
     141           5 :   abstract class QueryRequest {
     142             :     private String query;
     143             :     private int limit;
     144             :     private int start;
     145             :     private boolean suggest;
     146           5 :     private Set<ListAccountsOption> options = EnumSet.noneOf(ListAccountsOption.class);
     147             : 
     148             :     /** Execute query and return a list of accounts. */
     149             :     public abstract List<AccountInfo> get() throws RestApiException;
     150             : 
     151             :     /**
     152             :      * Set query.
     153             :      *
     154             :      * @param query needs to be in human-readable form.
     155             :      */
     156             :     public QueryRequest withQuery(String query) {
     157           5 :       this.query = query;
     158           5 :       return this;
     159             :     }
     160             : 
     161             :     /**
     162             :      * Set limit for returned list of accounts. Optional; server-default is used when not provided.
     163             :      */
     164             :     public QueryRequest withLimit(int limit) {
     165           2 :       this.limit = limit;
     166           2 :       return this;
     167             :     }
     168             : 
     169             :     /** Set number of accounts to skip. Optional; no accounts are skipped when not provided. */
     170             :     public QueryRequest withStart(int start) {
     171           2 :       this.start = start;
     172           2 :       return this;
     173             :     }
     174             : 
     175             :     public QueryRequest withSuggest(boolean suggest) {
     176           2 :       this.suggest = suggest;
     177           2 :       return this;
     178             :     }
     179             : 
     180             :     /** Set an option on the request, appending to existing options. */
     181             :     public QueryRequest withOption(ListAccountsOption options) {
     182           2 :       this.options.add(options);
     183           2 :       return this;
     184             :     }
     185             : 
     186             :     /** Set options on the request, appending to existing options. */
     187             :     public QueryRequest withOptions(ListAccountsOption... options) {
     188           2 :       this.options.addAll(Arrays.asList(options));
     189           2 :       return this;
     190             :     }
     191             : 
     192             :     /** Set options on the request, replacing existing options. */
     193             :     public QueryRequest withOptions(Set<ListAccountsOption> options) {
     194           0 :       this.options = options;
     195           0 :       return this;
     196             :     }
     197             : 
     198             :     public String getQuery() {
     199           5 :       return query;
     200             :     }
     201             : 
     202             :     public int getLimit() {
     203           5 :       return limit;
     204             :     }
     205             : 
     206             :     public int getStart() {
     207           5 :       return start;
     208             :     }
     209             : 
     210             :     public boolean getSuggest() {
     211           5 :       return suggest;
     212             :     }
     213             : 
     214             :     public Set<ListAccountsOption> getOptions() {
     215           5 :       return options;
     216             :     }
     217             :   }
     218             : 
     219             :   /**
     220             :    * A default implementation which allows source compatibility when adding new methods to the
     221             :    * interface.
     222             :    */
     223           0 :   class NotImplemented implements Accounts {
     224             :     @Override
     225             :     public AccountApi id(String id) throws RestApiException {
     226           0 :       throw new NotImplementedException();
     227             :     }
     228             : 
     229             :     @Override
     230             :     public AccountApi id(int id) throws RestApiException {
     231           0 :       throw new NotImplementedException();
     232             :     }
     233             : 
     234             :     @Override
     235             :     public AccountApi self() throws RestApiException {
     236           0 :       throw new NotImplementedException();
     237             :     }
     238             : 
     239             :     @Override
     240             :     public AccountApi create(String username) throws RestApiException {
     241           0 :       throw new NotImplementedException();
     242             :     }
     243             : 
     244             :     @Override
     245             :     public AccountApi create(AccountInput input) throws RestApiException {
     246           0 :       throw new NotImplementedException();
     247             :     }
     248             : 
     249             :     @Override
     250             :     public SuggestAccountsRequest suggestAccounts() throws RestApiException {
     251           0 :       throw new NotImplementedException();
     252             :     }
     253             : 
     254             :     @Override
     255             :     public SuggestAccountsRequest suggestAccounts(String query) throws RestApiException {
     256           0 :       throw new NotImplementedException();
     257             :     }
     258             : 
     259             :     @Override
     260             :     public QueryRequest query() throws RestApiException {
     261           0 :       throw new NotImplementedException();
     262             :     }
     263             : 
     264             :     @Override
     265             :     public QueryRequest query(String query) throws RestApiException {
     266           0 :       throw new NotImplementedException();
     267             :     }
     268             :   }
     269             : }