001/*
002 * SonarQube, open source software quality management tool.
003 * Copyright (C) 2008-2013 SonarSource
004 * mailto:contact AT sonarsource DOT com
005 *
006 * SonarQube is free software; you can redistribute it and/or
007 * modify it under the terms of the GNU Lesser General Public
008 * License as published by the Free Software Foundation; either
009 * version 3 of the License, or (at your option) any later version.
010 *
011 * SonarQube is distributed in the hope that it will be useful,
012 * but WITHOUT ANY WARRANTY; without even the implied warranty of
013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014 * Lesser General Public License for more details.
015 *
016 * You should have received a copy of the GNU Lesser General Public License
017 * along with this program; if not, write to the Free Software Foundation,
018 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
019 */
020package org.sonar.api.issue;
021
022import org.sonar.api.ServerComponent;
023
024import java.util.Map;
025
026/**
027 * Facade for JRuby on Rails extensions to request issues.
028 * <p>
029 * Reference from Ruby code : <code>Api.issues</code>
030 * </p>
031 *
032 * @since 3.6
033 */
034public interface RubyIssueService extends ServerComponent {
035
036  /**
037   * Search for an issue by its key.
038   * <p/>
039   * Ruby example: <code>result = Api.issues.find('ABCDE-12345')</code>
040   */
041  IssueQueryResult find(String issueKey);
042
043  /**
044   * Search for issues.
045   * <p/>
046   * Ruby example: <code>Api.issues.find({'statuses' => ['OPEN', 'RESOLVED'], 'assignees' => 'john,carla')}</code>
047   * <p/>
048   * <b>Keys of parameters must be Ruby strings but not symbols</b>. Multi-value parameters can be arrays (<code>['OPEN', 'RESOLVED']</code>) or
049   * comma-separated list of strings (<code>'OPEN,RESOLVED'</code>).
050   * <p/>
051   * Optional parameters are:
052   * <ul>
053   *   <li>'issues': list of issue keys</li>
054   *   <li>'severities': list of severity to match. See constants in {@link org.sonar.api.rule.Severity}</li>
055   *   <li>'statuses': list of status to match. See constants in {@link Issue}</li>
056   *   <li>'resolutions': list of resolutions to match. See constants in {@link Issue}</li>
057   *   <li>'resolved': true to match only resolved issues, false to match only unresolved issues. By default no filtering is done.</li>
058   *   <li>'components': list of component keys to match, for example 'org.apache.struts:struts:org.apache.struts.Action'</li>
059   *   <li>'componentRoots': list of keys of root components. All the issues related to descendants of these roots are returned.</li>
060   *   <li>'rules': list of keys of rules to match. Format is &lt;repository&gt;:&lt;rule&gt;, for example 'squid:AvoidCycles'</li>
061   *   <li>'actionPlans': list of keys of the action plans to match. Note that plan names are not accepted.</li>
062   *   <li>'planned': true to get only issues associated to an action plan, false to get only non associated issues. By default no filtering is done.</li>
063   *   <li>'reporters': list of reporter logins. Note that reporters are defined only on "manual" issues.</li>
064   *   <li>'assignees': list of assignee logins.</li>
065   *   <li>'assigned': true to get only assigned issues, false to get only unassigned issues. By default no filtering is done.</li>
066   *   <li>'createdAfter': match all the issues created after the given date (strictly).
067   *   Both date and datetime ISO formats are supported: 2013-05-18 or 2010-05-18T15:50:45+0100</li>
068   *   <li>'createdAt': match all the issues created at the given date (require second precision).
069   *   Both date and datetime ISO formats are supported: 2013-05-18 or 2010-05-18T15:50:45+0100</li>
070   *   <li>'createdBefore': match all the issues created before the given date (exclusive).
071   *   Both date and datetime ISO formats are supported: 2013-05-18 or 2010-05-18T15:50:45+0100</li>
072   *   <li>'pageSize': maximum number of results per page. Default is {@link org.sonar.api.issue.IssueQuery#DEFAULT_PAGE_SIZE},
073   *   except when the parameter 'components' is set. In this case there's no limit by default (all results in the same page).</li>
074   *   <li>'pageIndex': index of the selected page. Default is 1.</li>
075   *   <li>'sort': field to sort on. See supported values in {@link IssueQuery}</li>
076   *   <li>'asc': ascending or descending sort? Value can be a boolean or strings 'true'/'false'</li>
077   * </ul>
078   */
079  IssueQueryResult find(Map<String, Object> parameters);
080
081}