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}