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.web;
021
022import com.google.common.collect.ArrayListMultimap;
023import com.google.common.collect.ListMultimap;
024import com.google.common.collect.Maps;
025
026import java.util.Collection;
027import java.util.List;
028import java.util.Map;
029
030/**
031 * Definition of a dashboard.
032 * <p/>
033 * Its name and description can be retrieved using the i18n mechanism, using the keys "dashboard.&lt;id&gt;.name" and
034 * "dashboard.&lt;id&gt;.description".
035 *
036 * @since 2.13
037 */
038public final class Dashboard {
039
040  private String description;
041  private DashboardLayout layout = DashboardLayout.TWO_COLUMNS;
042  private ListMultimap<Integer, Widget> widgetsByColumn = ArrayListMultimap.create();
043  private boolean global = false;
044  private boolean activated = true;
045
046  private Dashboard() {
047  }
048
049  /**
050   * Creates a new {@link Dashboard}.
051   */
052  public static Dashboard create() {
053    return new Dashboard();
054  }
055
056  /**
057   * Add a widget with the given parameters, and return the newly created {@link Widget} object if one wants to add parameters to it.
058   *
059   * <p>The widget ids are listed by the web service /api/widgets</p>
060   *
061   * @param widgetId id of an existing widget
062   * @param columnId column starts with 1. The widget is ignored if the column id does not match the layout.
063   */
064  public Widget addWidget(String widgetId, int columnId) {
065    if (columnId < 1) {
066      throw new IllegalArgumentException("Widget column starts with 1");
067    }
068
069    Widget widget = new Widget(widgetId);
070    widgetsByColumn.put(columnId, widget);
071    return widget;
072  }
073
074  public Collection<Widget> getWidgets() {
075    return widgetsByColumn.values();
076  }
077
078  public List<Widget> getWidgetsOfColumn(int columnId) {
079    return widgetsByColumn.get(columnId);
080  }
081
082  /**
083   * Returns the description of the dashboard.
084   *
085   * @return the description
086   */
087  public String getDescription() {
088    return description;
089  }
090
091  /**
092   * Sets the description of the dashboard.
093   * <p/>
094   * Note: you should use the i18n mechanism for the description.
095   *
096   * @param description the description to set
097   */
098  public Dashboard setDescription(String description) {
099    this.description = description;
100    return this;
101  }
102
103  /**
104   * Returns the layout. Default value is the 2 columns mode with width 50%/50%.
105   *
106   * @return the layout
107   */
108  public DashboardLayout getLayout() {
109    return layout;
110  }
111
112  public Dashboard setLayout(DashboardLayout dl) {
113    if (dl == null) {
114      throw new IllegalArgumentException("The layout can not be null");
115    }
116    this.layout = dl;
117    return this;
118  }
119
120  /**
121   * A dashboard is global when it doesn't display information from a projet but rather more general information.
122   * <p>Before version 3.1 no dashboard was global.</p>
123   *
124   * @since 3.1
125   */
126  public boolean isGlobal() {
127    return global;
128  }
129
130  /**
131   * A dashboard is global when it doesn't display information from a projet but rather more general information.
132   * <p>Before version 3.1 no dashboard was global.</p>
133   *
134   * @since 3.1
135   */
136  public Dashboard setGlobal(boolean global) {
137    this.global = global;
138    return this;
139  }
140
141  /**
142   * A dashboard can be activated for all anonymous users or users who haven't configured their own dashboards.
143   * <p>Before version 3.1 every dashboard created through this extension point was automatically activated.
144   * This is still the default behavior.</p>
145   *
146   * @since 3.1
147   */
148  public boolean isActivated() {
149    return activated;
150  }
151
152  /**
153   * Set whether the dashboard is activated for all anonymous users or users who haven't configured their own dashboards.
154   *
155   * @since 3.1
156   */
157  public Dashboard setActivated(boolean activated) {
158    this.activated = activated;
159    return this;
160  }
161
162  /**
163   * Note that this class is an inner class to avoid confusion with the extension point org.sonar.api.web.Widget.
164   */
165  public static final class Widget {
166    private String id;
167    private Map<String, String> properties;
168
169    Widget(String id) {
170      this.id = id;
171      this.properties = Maps.newHashMap();
172    }
173
174    public Widget setProperty(String key, String value) {
175      properties.put(key, value);
176      return this;
177    }
178
179    /**
180     * Returns the properties of this widget.
181     *
182     * @return the properties
183     */
184    public Map<String, String> getProperties() {
185      return properties;
186    }
187
188    public String getProperty(String key) {
189      return properties.get(key);
190    }
191
192    /**
193     * Returns the identifier of this widget.
194     *
195     * @return the id
196     */
197    public String getId() {
198      return id;
199    }
200  }
201}