001/*
002 * This library is part of OpenCms -
003 * the Open Source Content Management System
004 *
005 * Copyright (c) Alkacon Software GmbH & Co. KG (http://www.alkacon.com)
006 *
007 * This library is free software; you can redistribute it and/or
008 * modify it under the terms of the GNU Lesser General Public
009 * License as published by the Free Software Foundation; either
010 * version 2.1 of the License, or (at your option) any later version.
011 *
012 * This library is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015 * Lesser General Public License for more details.
016 *
017 * For further information about Alkacon Software GmbH & Co. KG, please see the
018 * company website: http://www.alkacon.com
019 *
020 * For further information about OpenCms, please see the
021 * project website: http://www.opencms.org
022 *
023 * You should have received a copy of the GNU Lesser General Public
024 * License along with this library; if not, write to the Free Software
025 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
026 */
027
028package org.opencms.file.collectors;
029
030import org.opencms.file.CmsDataAccessException;
031import org.opencms.file.CmsObject;
032import org.opencms.file.CmsResource;
033import org.opencms.main.CmsException;
034
035import java.util.List;
036
037/**
038 * A collector that generates list of {@link org.opencms.file.CmsResource} objects from the VFS.<p>
039 *
040 * @since 6.0.0
041 */
042public interface I_CmsResourceCollector extends Comparable<I_CmsResourceCollector>, I_CmsCollectorPublishListProvider {
043
044    /** The default limit for collector results. */
045    int DEFAULT_LIMIT = 200;
046
047    /**
048     * Returns a list of all collector names (Strings) this collector implementation supports.<p>
049     *
050     * @return a list of all collector names this collector implementation supports
051     */
052    List<String> getCollectorNames();
053
054    /**
055     * Returns the link that must be executed when a user clicks on the direct edit
056     * "new" button on a list created by the default collector.<p>
057     *
058     * If this method returns <code>null</code>,
059     * it indicated that the selected collector implementation does not support a "create link",
060     * and so no "new" button will should shown on lists generated with this collector.<p>
061     *
062     * @param cms the current CmsObject
063     *
064     * @return the link to execute after a "new" button was clicked
065     *
066     * @throws CmsException if something goes wrong
067     * @throws CmsDataAccessException if the parameter attribute of the corresponding collector tag is invalid
068     * @see #getCreateParam(CmsObject, String, String)
069     *
070     */
071    String getCreateLink(CmsObject cms) throws CmsException, CmsDataAccessException;
072
073    /**
074     * Returns the link that must be executed when a user clicks on the direct edit
075     * "new" button on a list created by the named collector.<p>
076     *
077     * If this method returns <code>null</code>,
078     * it indicated that the selected collector implementation does not support a "create link",
079     * and so no "new" button will should shown on lists generated with this collector.<p>
080     *
081     * @param cms the current CmsObject
082     * @param collectorName the name of the collector to use
083     * @param param an optional collector parameter
084     *
085     * @return the link to execute after a "new" button was clicked
086     *
087     * @throws CmsException if something goes wrong
088     * @throws CmsDataAccessException if the parameter attribute of the corresponding collector tag is invalid
089     * @see #getCreateParam(CmsObject, String, String)
090     *
091     */
092    String getCreateLink(CmsObject cms, String collectorName, String param) throws CmsException, CmsDataAccessException;
093
094    /**
095     * Returns the default parameter that must be passed to the
096     * {@link #getCreateLink(CmsObject, String, String)} method.<p>
097     *
098     * If this method returns <code>null</code>,
099     * it indicates that the selected collector implementation does not support a "create link",
100     * and so no "new" button will should shown on lists generated with this collector.<p>
101     *
102     * @param cms the current CmsObject
103     *
104     * @return the parameter that will be passed to the {@link #getCreateLink(CmsObject, String, String)} method, or null
105     *
106     * @throws CmsDataAccessException if the param attrib of the corresponding collector tag is invalid
107     *
108     * @see #getCreateLink(CmsObject, String, String)
109     */
110    String getCreateParam(CmsObject cms) throws CmsDataAccessException;
111
112    /**
113     * Returns the parameter that must be passed to the
114     * {@link #getCreateLink(CmsObject, String, String)} method.<p>
115     *
116     * If this method returns <code>null</code>,
117     * it indicates that the selected collector implementation does not support a "create link",
118     * and so no "new" button will should shown on lists generated with this collector.<p>
119     *
120     * @param cms the current CmsObject
121     * @param collectorName the name of the collector to use
122     * @param param an optional collector parameter from the current page context
123     *
124     * @return the parameter that will be passed to the {@link #getCreateLink(CmsObject, String, String)} method, or null
125     *
126     * @throws CmsDataAccessException if the parameter attribute of the corresponding collector tag is invalid
127     *
128     * @see #getCreateLink(CmsObject, String, String)
129     */
130    String getCreateParam(CmsObject cms, String collectorName, String param) throws CmsDataAccessException;
131
132    /**
133     * Returns the id of the resource type for new collector items.<p>
134     * Returns -1 if creation of new items is not supported.<p>
135     *
136     * @param cms the current CmsObject
137     * @param collectorName the name of the collector to use
138     * @param param an optional collector parameter
139     *
140     * @return the resource type id
141     *
142     * @throws CmsException if something goes wrong
143     */
144    int getCreateTypeId(CmsObject cms, String collectorName, String param) throws CmsException;
145
146    /**
147     * Returns the default collector name to use for collecting resources.<p>
148     *
149     * @return the default collector name
150     */
151    String getDefaultCollectorName();
152
153    /**
154     * Returns the default collector parameter to use for collecting resources.<p>
155     *
156     * @return the default collector parameter
157     */
158    String getDefaultCollectorParam();
159
160    /**
161     * Returns the "order weight" of this collector.<p>
162     *
163     * The "order weight" is important because two collector classes may provide a collector with
164     * the same name. If this is the case, the collector implementation with the higher
165     * order number "overrules" the lower order number class.<p>
166     *
167     * @return the "order weight" of this collector
168     */
169    int getOrder();
170
171    /**
172     * Returns a list of {@link org.opencms.file.CmsResource} Objects that are
173     * gathered in the VFS using the default collector name and parameter.<p>
174     *
175     * @param cms the current CmsObject
176     *
177     * @return a list of CmsXmlContent objects
178     *
179     * @throws CmsException if something goes wrong
180     * @throws CmsDataAccessException if the parameter attribute of the corresponding collector tag is invalid
181     */
182    List<CmsResource> getResults(CmsObject cms) throws CmsDataAccessException, CmsException;
183
184    /**
185     * Returns a list of {@link org.opencms.file.CmsResource} Objects that are
186     * gathered in the VFS using the named collector.<p>
187     *
188     * @param cms the current CmsObject
189     * @param collectorName the name of the collector to use
190     * @param param an optional collector parameter
191     *
192     * @return a list of CmsXmlContent objects
193     *
194     * @throws CmsException if something goes wrong
195     * @throws CmsDataAccessException if the parameter attribute of the corresponding collector tag is invalid
196     */
197    List<CmsResource> getResults(CmsObject cms, String collectorName, String param)
198    throws CmsDataAccessException, CmsException;
199
200    /**
201     * Returns a list of {@link org.opencms.file.CmsResource} Objects that are
202     * gathered in the VFS using the named collector.<p>
203     *
204     * This method takes as a parameter the desired number of results. If this number is -1,
205     * the number of results will only depend on the collector parameters. If it is positive, any given result
206     * number in the collector parameter string will not be used.
207     *
208     * @param cms the current CmsObject
209     * @param collectorName the name of the collector to use
210     * @param params an optional collector parameter
211     * @param numResults the desired number of results (overrides result number possibl
212     *
213     * @return a list of CmsXmlContent objects
214     *
215     * @throws CmsException if something goes wrong
216     * @throws CmsDataAccessException if the parameter attribute of the corresponding collector tag is invalid
217     */
218    List<CmsResource> getResults(CmsObject cms, String collectorName, String params, int numResults)
219    throws CmsException;
220
221    /**
222     * Sets the default collector name to use for collecting resources.<p>
223     *
224     * @param collectorName the default collector name
225     */
226    void setDefaultCollectorName(String collectorName);
227
228    /**
229     * Sets the default collector parameter to use for collecting resources.<p>
230     *
231     * @param param the default collector parameter
232     */
233    void setDefaultCollectorParam(String param);
234
235    /**
236     * Sets the "order weight" of this collector.<p>
237     *
238     * @param order the order weight to set
239     *
240     * @see #getOrder()
241     */
242    void setOrder(int order);
243}