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, 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.db;
029
030import org.opencms.file.CmsDataAccessException;
031import org.opencms.file.CmsGroup;
032import org.opencms.file.CmsResource;
033import org.opencms.file.CmsUser;
034import org.opencms.file.history.I_CmsHistoryResource;
035import org.opencms.main.CmsException;
036import org.opencms.security.CmsPrincipal;
037
038import java.util.List;
039
040/**
041 * The interface for drivers handling subscriptions and user tracking.<p>
042 *
043 * @since 8.0.0
044 */
045public interface I_CmsSubscriptionDriver {
046
047    /** The type ID to identify subscription driver implementations. */
048    int DRIVER_TYPE_ID = 4;
049
050    /**
051     * Deletes visit entries matching the given filter.<p>
052     *
053     * @param dbc the database context
054     * @param poolName the name of the database pool to use, if <code>null</code>, the default pool is used
055     * @param filter the log entry filter
056     *
057     * @throws CmsDataAccessException if something goes wrong
058     */
059    void deleteVisits(CmsDbContext dbc, String poolName, CmsVisitEntryFilter filter) throws CmsDataAccessException;
060
061    /**
062     * Returns the date when the resource was last visited by the user.<p>
063     *
064     * @param dbc the database context
065     * @param poolName the name of the database pool to use
066     * @param user the user to check the date
067     * @param resource the resource to check the date
068     *
069     * @return the date when the resource was last visited by the user
070     *
071     * @throws CmsException if something goes wrong
072     */
073    long getDateLastVisitedBy(CmsDbContext dbc, String poolName, CmsUser user, CmsResource resource)
074    throws CmsException;
075
076    /**
077     * Returns the SQL manager of this driver, if possible.<p>
078     *
079     * @return an SQL manager
080     */
081    CmsSqlManager getSqlManager();
082
083    /**
084     * Initializes the SQL manager for this driver.<p>
085     *
086     * To obtain JDBC connections from different pools, further
087     * {online|offline|history} pool Urls have to be specified.<p>
088     *
089     * @param classname the classname of the SQL manager
090     *
091     * @return the SQL manager for this driver
092     */
093    CmsSqlManager initSqlManager(String classname);
094
095    /**
096     * Mark the given resource as visited by the user.<p>
097     *
098     * @param dbc the database context
099     * @param poolName the name of the database pool to use
100     * @param resource the resource to mark as visited
101     * @param user the user that visited the resource
102     *
103     * @throws CmsDataAccessException if something goes wrong
104     */
105    void markResourceAsVisitedBy(CmsDbContext dbc, String poolName, CmsResource resource, CmsUser user)
106    throws CmsDataAccessException;
107
108    /**
109     * Returns all resources subscribed by the given user or group.<p>
110     *
111     * @param dbc the database context
112     * @param poolName the name of the database pool to use
113     * @param principal the principal to read the subscribed resources
114     *
115     * @return all resources subscribed by the given user or group
116     *
117     * @throws CmsDataAccessException if something goes wrong
118     */
119    List<CmsResource> readAllSubscribedResources(CmsDbContext dbc, String poolName, CmsPrincipal principal)
120    throws CmsDataAccessException;
121
122    /**
123     * Returns the resources that were visited by a user set in the filter.<p>
124     *
125     * @param dbc the database context
126     * @param poolName the name of the database pool to use
127     * @param filter the filter that is used to get the visited resources
128     *
129     * @return the resources that were visited by a user set in the filter
130     *
131     * @throws CmsDataAccessException if something goes wrong
132     */
133    List<CmsResource> readResourcesVisitedBy(CmsDbContext dbc, String poolName, CmsVisitedByFilter filter)
134    throws CmsDataAccessException;
135
136    /**
137     * Returns the subscribed history resources that were deleted.<p>
138     *
139     * @param dbc the database context
140     * @param poolName the name of the database pool to use
141     * @param user the user that subscribed to the resource
142     * @param groups the groups to check subscribed resources for
143     * @param parent the parent resource (folder) of the deleted resources, if <code>null</code> all deleted resources will be returned
144     * @param includeSubFolders indicates if the sub folders of the specified folder path should be considered, too
145     * @param deletedFrom the time stamp from which the resources should have been deleted
146     *
147     * @return the subscribed history resources that were deleted
148     *
149     * @throws CmsDataAccessException if something goes wrong
150     */
151    List<I_CmsHistoryResource> readSubscribedDeletedResources(
152        CmsDbContext dbc,
153        String poolName,
154        CmsUser user,
155        List<CmsGroup> groups,
156        CmsResource parent,
157        boolean includeSubFolders,
158        long deletedFrom) throws CmsDataAccessException;
159
160    /**
161     * Returns the resources that were subscribed by a user or group set in the filter.<p>
162     *
163     * @param dbc the database context
164     * @param poolName the name of the database pool to use
165     * @param filter the filter that is used to get the subscribed resources
166     *
167     * @return the resources that were subscribed by a user or group set in the filter
168     *
169     * @throws CmsDataAccessException if something goes wrong
170     */
171    List<CmsResource> readSubscribedResources(CmsDbContext dbc, String poolName, CmsSubscriptionFilter filter)
172    throws CmsDataAccessException;
173
174    /**
175     * Marks a subscribed resource as deleted.<p>
176     *
177     * @param dbc the database context
178     * @param poolName the name of the database pool to use
179     * @param resource the subscribed resource to mark as deleted
180     *
181     * @throws CmsDataAccessException if something goes wrong
182     */
183    void setSubscribedResourceAsDeleted(CmsDbContext dbc, String poolName, CmsResource resource)
184    throws CmsDataAccessException;
185
186    /**
187     * Subscribes the user or group to the resource.<p>
188     *
189     * @param dbc the database context
190     * @param poolName the name of the database pool to use
191     * @param principal the principal that subscribes to the resource
192     * @param resource the resource to subscribe to
193     *
194     * @throws CmsDataAccessException if something goes wrong
195     */
196    void subscribeResourceFor(CmsDbContext dbc, String poolName, CmsPrincipal principal, CmsResource resource)
197    throws CmsDataAccessException;
198
199    /**
200     * Unsubscribes all deleted resources that were deleted before the specified time stamp.<p>
201     *
202     * @param dbc the database context
203     * @param poolName the name of the database pool to use
204     * @param deletedTo the time stamp to which the resources have been deleted
205     *
206     * @throws CmsDataAccessException if something goes wrong
207     */
208    void unsubscribeAllDeletedResources(CmsDbContext dbc, String poolName, long deletedTo)
209    throws CmsDataAccessException;
210
211    /**
212     * Unsubscribes the principal from all resources.<p>
213     *
214     * @param dbc the database context
215     * @param poolName the name of the database pool to use
216     * @param principal the principal that unsubscribes from all resources
217     *
218     * @throws CmsDataAccessException if something goes wrong
219     */
220    void unsubscribeAllResourcesFor(CmsDbContext dbc, String poolName, CmsPrincipal principal)
221    throws CmsDataAccessException;
222
223    /**
224     * Unsubscribes the principal from the resource.<p>
225     *
226     * @param dbc the database context
227     * @param poolName the name of the database pool to use
228     * @param principal the principal that unsubscribes from the resource
229     * @param resource the resource to unsubscribe from
230     *
231     * @throws CmsDataAccessException if something goes wrong
232     */
233    void unsubscribeResourceFor(CmsDbContext dbc, String poolName, CmsPrincipal principal, CmsResource resource)
234    throws CmsDataAccessException;
235
236    /**
237     * Unsubscribes all groups and users from the resource.<p>
238     *
239     * @param dbc the database context
240     * @param poolName the name of the database pool to use
241     * @param resource the resource to unsubscribe all groups and users from
242     *
243     * @throws CmsDataAccessException if something goes wrong
244     */
245    void unsubscribeResourceForAll(CmsDbContext dbc, String poolName, CmsResource resource)
246    throws CmsDataAccessException;
247
248}