/hudson-core/src/main/java/hudson/views/ListViewColumn.java

  1/*
  2 * The MIT License
  3 * 
  4 * Copyright (c) 2004-2009, Sun Microsystems, Inc., Kohsuke Kawaguchi, Martin Eigenbrodt
  5 * 
  6 * Permission is hereby granted, free of charge, to any person obtaining a copy
  7 * of this software and associated documentation files (the "Software"), to deal
  8 * in the Software without restriction, including without limitation the rights
  9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 10 * copies of the Software, and to permit persons to whom the Software is
 11 * furnished to do so, subject to the following conditions:
 12 * 
 13 * The above copyright notice and this permission notice shall be included in
 14 * all copies or substantial portions of the Software.
 15 * 
 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 22 * THE SOFTWARE.
 23 */
 24package hudson.views;
 25
 26import hudson.DescriptorExtensionList;
 27import hudson.Extension;
 28import hudson.ExtensionPoint;
 29import hudson.model.Describable;
 30import hudson.model.Descriptor;
 31import hudson.model.Descriptor.FormException;
 32import hudson.model.Hudson;
 33import hudson.model.Item;
 34import hudson.model.ItemGroup;
 35import hudson.model.ListView;
 36import hudson.model.View;
 37import hudson.util.DescriptorList;
 38import org.kohsuke.stapler.export.Exported;
 39
 40import java.util.ArrayList;
 41import java.util.Arrays;
 42import java.util.List;
 43import java.util.logging.Level;
 44import java.util.logging.Logger;
 45
 46/**
 47 * Extension point for adding a column to a table rendering of {@link Item}s, such as {@link ListView}.
 48 *
 49 * <p>
 50 * This object must have the <tt>column.jelly</tt>. This view
 51 * is called for each cell of this column. The {@link Item} object
 52 * is passed in the "job" variable. The view should render
 53 * the &lt;td> tag.
 54 *
 55 * <p>
 56 * This object may have an additional <tt>columHeader.jelly</tt>. The default ColmnHeader
 57 * will render {@link #getColumnCaption()}.
 58 *
 59 * <p>
 60 * If you opt to {@linkplain ListViewColumnDescriptor#shownByDefault() be shown by default},
 61 * there also must be a default constructor, which is invoked to create a list view column in
 62 * the default configuration.
 63 *
 64 * <p>
 65 * Originally, this extension point was designed for {@link ListView}, but since then
 66 * it has grown to be applicable to other {@link View}s and {@link ItemGroup}s that render
 67 * a collection of {@link Item}s in a tabular format.
 68 *
 69 * @author Kohsuke Kawaguchi
 70 * @since 1.279
 71 * @see ListViewColumnDescriptor
 72 */
 73public abstract class ListViewColumn implements ExtensionPoint, Describable<ListViewColumn> {
 74    /**
 75     * Returns the name of the column that explains what this column means
 76     *
 77     * @return
 78     *      The convention is to use capitalization like "Foo Bar Zot".
 79     */
 80    @Exported
 81    public String getColumnCaption() {
 82        return getDescriptor().getDisplayName();
 83    }
 84
 85    /**
 86     * Returns all the registered {@link ListViewColumn} descriptors.
 87     */
 88    public static DescriptorExtensionList<ListViewColumn, Descriptor<ListViewColumn>> all() {
 89        return Hudson.getInstance().<ListViewColumn, Descriptor<ListViewColumn>>getDescriptorList(ListViewColumn.class);
 90    }
 91
 92    /**
 93     * All registered {@link ListViewColumn}s.
 94     * @deprecated as of 1.281
 95     *      Use {@link #all()} for read access and {@link Extension} for registration.
 96     */
 97    public static final DescriptorList<ListViewColumn> LIST = new DescriptorList<ListViewColumn>(ListViewColumn.class);
 98
 99    /**
100     * Whether this column will be shown by default.
101     * The default implementation is true.
102     *
103     * @since 1.301
104     * @deprecated as of 1.342.
105     *      Use {@link ListViewColumnDescriptor#shownByDefault()}
106     */
107    public boolean shownByDefault() {
108        return true;
109    }
110
111    /**
112     * For compatibility reason, this method may not return a {@link ListViewColumnDescriptor}
113     * and instead return a plain {@link Descriptor} instance.
114     */
115    public Descriptor<ListViewColumn> getDescriptor() {
116        return Hudson.getInstance().getDescriptorOrDie(getClass());
117    }
118
119    /**
120     * Creates the list of {@link ListViewColumn}s to be used for newly created {@link ListView}s and their likes.
121     * @since 1.391
122     */
123    public static List<ListViewColumn> createDefaultInitialColumnList() {
124        // OK, set up default list of columns:
125        // create all instances
126        ArrayList<ListViewColumn> r = new ArrayList<ListViewColumn>();
127        DescriptorExtensionList<ListViewColumn, Descriptor<ListViewColumn>> all = ListViewColumn.all();
128        ArrayList<Descriptor<ListViewColumn>> left = new ArrayList<Descriptor<ListViewColumn>>(all);
129
130        for (Class<? extends ListViewColumn> d: DEFAULT_COLUMNS) {
131            Descriptor<ListViewColumn> des = all.find(d);
132            if (des  != null) {
133                try {
134                    r.add(des.newInstance(null, null));
135                    left.remove(des);
136                } catch (FormException e) {
137                    LOGGER.log(Level.WARNING, "Failed to instantiate "+des.clazz,e);
138                }
139            }
140        }
141        for (Descriptor<ListViewColumn> d : left)
142            try {
143                if (d instanceof ListViewColumnDescriptor) {
144                    ListViewColumnDescriptor ld = (ListViewColumnDescriptor) d;
145                    if (!ld.shownByDefault())       continue;   // skip this
146                }
147                ListViewColumn lvc = d.newInstance(null, null);
148                if (!lvc.shownByDefault())      continue; // skip this
149
150                r.add(lvc);
151            } catch (FormException e) {
152                LOGGER.log(Level.WARNING, "Failed to instantiate "+d.clazz,e);
153            }
154
155        return r;
156    }
157
158    /**
159     * Traditional column layout before the {@link ListViewColumn} becomes extensible.
160     */
161    private static final List<Class<? extends ListViewColumn>> DEFAULT_COLUMNS =  Arrays.asList(
162        StatusColumn.class,
163        WeatherColumn.class,
164        JobColumn.class,
165        LastSuccessColumn.class,
166        LastFailureColumn.class,
167        LastDurationColumn.class,
168        ConsoleColumn.class,
169        BuildButtonColumn.class
170    );
171
172    private static final Logger LOGGER = Logger.getLogger(ListViewColumn.class.getName());
173}