001    /*
002     * Sonar, open source software quality management tool.
003     * Copyright (C) 2008-2012 SonarSource
004     * mailto:contact AT sonarsource DOT com
005     *
006     * Sonar 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     * Sonar 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
017     * License along with Sonar; if not, write to the Free Software
018     * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02
019     */
020    package org.sonar.api.web;
021    
022    import com.google.common.collect.ArrayListMultimap;
023    import com.google.common.collect.ListMultimap;
024    import com.google.common.collect.Maps;
025    
026    import java.util.Collection;
027    import java.util.List;
028    import 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     */
038    public final class Dashboard {
039    
040      private String description;
041      private DashboardLayout layout = DashboardLayout.TWO_COLUMNS;
042      private ListMultimap<Integer, Widget> widgetsByColumn = ArrayListMultimap.create();
043    
044      private Dashboard() {
045      }
046    
047      /**
048       * Creates a new {@link Dashboard}.
049       */
050      public static Dashboard create() {
051        return new Dashboard();
052      }
053    
054      /**
055       * Add a widget with the given parameters, and return the newly created {@link Widget} object if one wants to add parameters to it.
056       *
057       * <p>The widget ids are listed by the web service /api/widgets</p>
058       *
059       * @param widgetId id of an existing widget
060       * @param columnId column starts with 1. The widget is ignored if the column id does not match the layout.
061       */
062      public Widget addWidget(String widgetId, int columnId) {
063        if (columnId < 1) {
064          throw new IllegalArgumentException("Widget column starts with 1");
065        }
066    
067        Widget widget = new Widget(widgetId);
068        widgetsByColumn.put(columnId, widget);
069        return widget;
070      }
071    
072      public Collection<Widget> getWidgets() {
073        return widgetsByColumn.values();
074      }
075    
076      public List<Widget> getWidgetsOfColumn(int columnId) {
077        return widgetsByColumn.get(columnId);
078      }
079    
080      /**
081       * Returns the description of the dashboard.
082       *
083       * @return the description
084       */
085      public String getDescription() {
086        return description;
087      }
088    
089      /**
090       * Sets the description of the dashboard.
091       * <p/>
092       * Note: you should use the i18n mechanism for the description.
093       *
094       * @param description the description to set
095       */
096      public Dashboard setDescription(String description) {
097        this.description = description;
098        return this;
099      }
100    
101      /**
102       * Returns the layout. Default value is the 2 columns mode with width 50%/50%.
103       *
104       * @return the layout
105       */
106      public DashboardLayout getLayout() {
107        return layout;
108      }
109    
110      public Dashboard setLayout(DashboardLayout dl) {
111        if (dl == null) {
112          throw new IllegalArgumentException("The layout can not be null");
113        }
114        this.layout = dl;
115        return this;
116      }
117    
118    
119      /**
120       * Note that this class is an inner class to avoid confusion with the extension point org.sonar.api.web.Widget.
121       */
122      public static final class Widget {
123        private String id;
124        private Map<String, String> properties;
125    
126        Widget(String id) {
127          this.id = id;
128          this.properties = Maps.newHashMap();
129        }
130    
131        public Widget setProperty(String key, String value) {
132          properties.put(key, value);
133          return this;
134        }
135    
136        /**
137         * Returns the properties of this widget.
138         *
139         * @return the properties
140         */
141        public Map<String, String> getProperties() {
142          return properties;
143        }
144    
145        public String getProperty(String key) {
146          return properties.get(key);
147        }
148    
149        /**
150         * Returns the identifier of this widget.
151         *
152         * @return the id
153         */
154        public String getId() {
155          return id;
156        }
157      }
158    
159    }