001/*
002 * This library is part of OpenCms -
003 * the Open Source Content Management System
004 *
005 * Copyright (c) Alkacon Software GmbH & Co. KG (https://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: https://www.alkacon.com
019 *
020 * For further information about OpenCms, please see the
021 * project website: https://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)
159    throws CmsDataAccessException;
160
161    /**
162     * Returns the resources that were subscribed by a user or group set in the filter.<p>
163     *
164     * @param dbc the database context
165     * @param poolName the name of the database pool to use
166     * @param filter the filter that is used to get the subscribed resources
167     *
168     * @return the resources that were subscribed by a user or group set in the filter
169     *
170     * @throws CmsDataAccessException if something goes wrong
171     */
172    List<CmsResource> readSubscribedResources(CmsDbContext dbc, String poolName, CmsSubscriptionFilter filter)
173    throws CmsDataAccessException;
174
175    /**
176     * Marks a subscribed resource as deleted.<p>
177     *
178     * @param dbc the database context
179     * @param poolName the name of the database pool to use
180     * @param resource the subscribed resource to mark as deleted
181     *
182     * @throws CmsDataAccessException if something goes wrong
183     */
184    void setSubscribedResourceAsDeleted(CmsDbContext dbc, String poolName, CmsResource resource)
185    throws CmsDataAccessException;
186
187    /**
188     * Subscribes the user or group to the resource.<p>
189     *
190     * @param dbc the database context
191     * @param poolName the name of the database pool to use
192     * @param principal the principal that subscribes to the resource
193     * @param resource the resource to subscribe to
194     *
195     * @throws CmsDataAccessException if something goes wrong
196     */
197    void subscribeResourceFor(CmsDbContext dbc, String poolName, CmsPrincipal principal, CmsResource resource)
198    throws CmsDataAccessException;
199
200    /**
201     * Unsubscribes all deleted resources that were deleted before the specified time stamp.<p>
202     *
203     * @param dbc the database context
204     * @param poolName the name of the database pool to use
205     * @param deletedTo the time stamp to which the resources have been deleted
206     *
207     * @throws CmsDataAccessException if something goes wrong
208     */
209    void unsubscribeAllDeletedResources(CmsDbContext dbc, String poolName, long deletedTo)
210    throws CmsDataAccessException;
211
212    /**
213     * Unsubscribes the principal from all resources.<p>
214     *
215     * @param dbc the database context
216     * @param poolName the name of the database pool to use
217     * @param principal the principal that unsubscribes from all resources
218     *
219     * @throws CmsDataAccessException if something goes wrong
220     */
221    void unsubscribeAllResourcesFor(CmsDbContext dbc, String poolName, CmsPrincipal principal)
222    throws CmsDataAccessException;
223
224    /**
225     * Unsubscribes the principal from the resource.<p>
226     *
227     * @param dbc the database context
228     * @param poolName the name of the database pool to use
229     * @param principal the principal that unsubscribes from the resource
230     * @param resource the resource to unsubscribe from
231     *
232     * @throws CmsDataAccessException if something goes wrong
233     */
234    void unsubscribeResourceFor(CmsDbContext dbc, String poolName, CmsPrincipal principal, CmsResource resource)
235    throws CmsDataAccessException;
236
237    /**
238     * Unsubscribes all groups and users from the resource.<p>
239     *
240     * @param dbc the database context
241     * @param poolName the name of the database pool to use
242     * @param resource the resource to unsubscribe all groups and users from
243     *
244     * @throws CmsDataAccessException if something goes wrong
245     */
246    void unsubscribeResourceForAll(CmsDbContext dbc, String poolName, CmsResource resource)
247    throws CmsDataAccessException;
248
249}