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 GmbH & Co. KG, 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.CmsProperty;
032import org.opencms.file.CmsPropertyDefinition;
033import org.opencms.file.CmsResource;
034import org.opencms.file.history.CmsHistoryPrincipal;
035import org.opencms.file.history.CmsHistoryProject;
036import org.opencms.file.history.I_CmsHistoryResource;
037import org.opencms.security.I_CmsPrincipal;
038import org.opencms.util.CmsUUID;
039
040import java.util.List;
041
042/**
043 * Definitions of all required history driver methods.<p>
044 *
045 * A history driver is a driver to write projects, resources and properties of
046 * resources optionally to a second set of history database tables while resources
047 * get published. A unique publish tag ID is used to identify a set of resource that
048 * were saved during one publish process.<p>
049 *
050 * @since 6.9.1
051 */
052public interface I_CmsHistoryDriver {
053
054    /** The type ID to identify history driver implementations. */
055    int DRIVER_TYPE_ID = 0;
056
057    /**
058     * Creates a new property defintion in the database.<p>
059     *
060     * @param dbc the current database context
061     * @param name the name of the property definition
062     * @param type the type of the property definition
063     *
064     * @return the new property definition object
065     *
066     * @throws CmsDataAccessException if something goes wrong
067     */
068    CmsPropertyDefinition createPropertyDefinition(
069        CmsDbContext dbc,
070        String name,
071        CmsPropertyDefinition.CmsPropertyType type)
072    throws CmsDataAccessException;
073
074    /**
075     * Deletes all historical versions of a resource
076     * keeping maximal <code>versionsToKeep</code> versions.<p>
077     *
078     * @param dbc the current database context
079     * @param histResource the historical resource to delete versions for
080     * @param versionsToKeep the number of versions to keep
081     * @param time deleted resources older than this will also be deleted, is ignored if negative
082     *
083     * @return the number of versions that were deleted
084     *
085     * @throws CmsDataAccessException if something goes wrong
086     */
087    int deleteEntries(CmsDbContext dbc, I_CmsHistoryResource histResource, int versionsToKeep, long time)
088    throws CmsDataAccessException;
089
090    /**
091     * Deletes a property definition.<p>
092     *
093     * @param dbc the current database context
094     * @param propertyDef the property definition to be deleted
095     *
096     * @throws CmsDataAccessException if something goes wrong
097     */
098    void deletePropertyDefinition(CmsDbContext dbc, CmsPropertyDefinition propertyDef) throws CmsDataAccessException;
099
100    /**
101     * Destroys this driver.<p>
102     *
103     * @throws Throwable if something goes wrong
104     */
105    void destroy() throws Throwable;
106
107    /**
108     * Returns all historical resources (of deleted resources).<p>
109     *
110     * @param dbc the current database context
111     *
112     * @return a list of {@link I_CmsHistoryResource} objects
113     *
114     * @throws CmsDataAccessException if something goes wrong
115     */
116    List<I_CmsHistoryResource> getAllDeletedEntries(CmsDbContext dbc) throws CmsDataAccessException;
117
118    /**
119     * Returns all historical resources (of not deleted resources).<p>
120     *
121     * @param dbc the current database context
122     *
123     * @return a list of {@link I_CmsHistoryResource} objects
124     *
125     * @throws CmsDataAccessException if something goes wrong
126     */
127    List<I_CmsHistoryResource> getAllNotDeletedEntries(CmsDbContext dbc) throws CmsDataAccessException;
128
129    /**
130     * Returns the SqlManager of this driver.<p>
131     *
132     * @return the SqlManager of this driver
133     */
134    CmsSqlManager getSqlManager();
135
136    /**
137     * Initializes the SQL manager for this driver.<p>
138     *
139     * @param classname the classname of the SQL manager
140     *
141     * @return the SQL manager for this driver
142     */
143    CmsSqlManager initSqlManager(String classname);
144
145    /**
146     * Reads all file headers of the resource with the given structure id.<p>
147     *
148     * This method returns a list with the history of the resource, i.e.
149     * the historical resources, independent of the project they were attached to.<br>
150     *
151     * The reading excludes the file content.<p>
152     *
153     * @param dbc the current database context
154     * @param structureId the structure id
155     *
156     * @return a list of historical resources, as <code>{@link I_CmsHistoryResource}</code> objects
157     *
158     * @throws CmsDataAccessException if something goes wrong
159     */
160    List<I_CmsHistoryResource> readAllAvailableVersions(CmsDbContext dbc, CmsUUID structureId)
161    throws CmsDataAccessException;
162
163    /**
164     * Reads the content of the historical version of the resource
165     * identified by its structure id.<p>
166     *
167     * @param dbc the current database context
168     * @param resourceId the resource id of the resource to read the content for
169     * @param publishTag the publish tag of the version
170     *
171     * @return the content if found
172     *
173     * @throws CmsDataAccessException if something goes wrong
174     */
175    byte[] readContent(CmsDbContext dbc, CmsUUID resourceId, int publishTag) throws CmsDataAccessException;
176
177    /**
178     * Reads all deleted (historical) resources below the given path, that the given user deleted by itself.<p>
179     *
180     * @param dbc the current db context
181     * @param structureId the structure id of the parent resource to read the deleted resources from
182     * @param userId the id of the user that deleted the resources, or <code>null</code> to retrieve them all
183     *
184     * @return a list of <code>{@link I_CmsHistoryResource}</code> objects
185     *
186     * @throws CmsDataAccessException if something goes wrong
187     */
188    List<I_CmsHistoryResource> readDeletedResources(CmsDbContext dbc, CmsUUID structureId, CmsUUID userId)
189    throws CmsDataAccessException;
190
191    /**
192     * Returns the last historical version of a resource.<p>
193     *
194     * @param dbc the current database context
195     * @param structureId the structure ID of the resource
196     *
197     * @return the last historical version of a resource
198     *
199     * @throws CmsDataAccessException if something goes wrong
200     */
201    int readLastVersion(CmsDbContext dbc, CmsUUID structureId) throws CmsDataAccessException;
202
203    /**
204     * Reads the maximal publish tag for a specified resource id.<p>
205     *
206     * @param dbc the current database context
207     * @param resourceId the id of the resource the get the publish tag for
208     *
209     * @return the maximal publish tag for the given resource
210     *
211     * @throws CmsDataAccessException if something goes wrong
212     */
213    int readMaxPublishTag(CmsDbContext dbc, CmsUUID resourceId) throws CmsDataAccessException;
214
215    /**
216     * Returns the next available history publish tag.<p>
217     *
218     * @param dbc the current database context
219     *
220     * @return the next available history publish tag
221     */
222    int readNextPublishTag(CmsDbContext dbc);
223
224    /**
225     * Reads an historical principal entry.<p>
226     *
227     * @param dbc the current database context
228     * @param principalId the id of the principal to retrieve
229     *
230     * @return the historical principal entry
231     *
232     * @throws CmsDataAccessException if something goes wrong
233     */
234    CmsHistoryPrincipal readPrincipal(CmsDbContext dbc, CmsUUID principalId) throws CmsDataAccessException;
235
236    /**
237     * Reads the latest historical project version with the given id.<p>
238     *
239     * @param dbc the current database context
240     * @param projectId the project id
241     *
242     * @return the requested historical project
243     *
244     * @throws CmsDataAccessException is something goes wrong
245     */
246    CmsHistoryProject readProject(CmsDbContext dbc, CmsUUID projectId) throws CmsDataAccessException;
247
248    /**
249     * Reads an historical project version.<p>
250     *
251     * @param dbc the current database context
252     * @param publishTag the publish tag
253     *
254     * @return the requested historical project
255     *
256     * @throws CmsDataAccessException is something goes wrong
257     */
258    CmsHistoryProject readProject(CmsDbContext dbc, int publishTag) throws CmsDataAccessException;
259
260    /**
261     * Reads all resources that belong to the historical project identified by the given publish tag.<p>
262     *
263     * @param dbc the current database context
264     * @param publishTag the publish tag
265     *
266     * @return all resources that belong to the historical project identified by the given publish tag
267     *
268     * @throws CmsDataAccessException if something goes wrong
269     */
270    List<String> readProjectResources(CmsDbContext dbc, int publishTag) throws CmsDataAccessException;
271
272    /**
273     * Returns all projects from the history.<p>
274     *
275     * @param dbc the current database context
276     *
277     * @return list of <code>{@link CmsHistoryProject}</code> objects
278     *           with all projects from history.
279     *
280     * @throws CmsDataAccessException if an error occurs
281     */
282    List<CmsHistoryProject> readProjects(CmsDbContext dbc) throws CmsDataAccessException;
283
284    /**
285     * Returns a list of all properties of a historical file or folder.<p>
286     *
287     * @param dbc the current database context
288     * @param historicalResource the resource to read the properties from
289     *
290     * @return a list of {@link org.opencms.file.CmsProperty} objects
291     *
292     * @throws CmsDataAccessException if something goes wrong
293     */
294    List<CmsProperty> readProperties(CmsDbContext dbc, I_CmsHistoryResource historicalResource)
295    throws CmsDataAccessException;
296
297    /**
298     * Reads a property definition with the given name.<p>
299     *
300     * @param dbc the current database context
301     * @param name the name of the property definition to read
302     *
303     * @return the property definition that corresponds to the given arguments - or <code>null</code> if not found
304     *
305     * @throws CmsDataAccessException if something goes wrong
306     */
307    CmsPropertyDefinition readPropertyDefinition(CmsDbContext dbc, String name) throws CmsDataAccessException;
308
309    /**
310     * Gets the publish tag of the first historical project after a given date.<p>
311     *
312     * This method is used during the deletion process of older historical data.<p>
313     *
314     * @param dbc the current database context
315     * @param maxdate the date to compare the historical projects with
316     *
317     * @return publish tag of the first historical project after maxdate
318     *
319     * @throws CmsDataAccessException if something goes wrong
320     */
321    int readPublishTag(CmsDbContext dbc, long maxdate) throws CmsDataAccessException;
322
323    /**
324     * Reads a historical resource version without including the file content.<p>
325     *
326     * @param dbc the current database context
327     * @param structureId the structure id of the resource to read
328     * @param version the desired version number
329     *
330     * @return the historical resource version
331     *
332     * @throws CmsDataAccessException if something goes wrong
333     */
334    I_CmsHistoryResource readResource(CmsDbContext dbc, CmsUUID structureId, int version) throws CmsDataAccessException;
335
336    /**
337     * Sets the driver manager for this driver if possible.<p>
338     *
339     * @param driverManager the new driver manager
340     */
341    void setDriverManager(CmsDriverManager driverManager);
342
343    /**
344     * Sets the SQL manager for this driver if possible.<p>
345     *
346     * @param sqlManager the new SQL manager
347     */
348    void setSqlManager(CmsSqlManager sqlManager);
349
350    /**
351     * Writes an historical entry for the given principal.<p>
352     *
353     * @param dbc the current database context
354     * @param principal the principal to write
355     *
356     * @throws CmsDataAccessException if something goes wrong
357     */
358    void writePrincipal(CmsDbContext dbc, I_CmsPrincipal principal) throws CmsDataAccessException;
359
360    /**
361     * Creates an historical entry for the current project.<p>
362     *
363     * @param dbc the current database context
364     * @param publishTag the publish tag
365     * @param publishDate long timestamp when the current project was published
366     *
367     * @throws CmsDataAccessException if something goes wrong
368     */
369    void writeProject(CmsDbContext dbc, int publishTag, long publishDate) throws CmsDataAccessException;
370
371    /**
372     * Writes the properties of a resource to the history.<p>
373     *
374     * @param dbc the current database context
375     * @param resource the resource of the properties
376     * @param properties the properties to write
377     * @param publishTag the publish tag
378     *
379     * @throws CmsDataAccessException if something goes wrong
380     */
381    void writeProperties(CmsDbContext dbc, CmsResource resource, List<CmsProperty> properties, int publishTag)
382    throws CmsDataAccessException;
383
384    /**
385     * Writes a resource to the history.<p>
386     *
387     * @param dbc the current database context
388     * @param resource the resource that is written to the history
389     * @param properties the properties of the resource
390     * @param publishTag the publish tag
391     *
392     * @throws CmsDataAccessException if something goes wrong
393     */
394    void writeResource(CmsDbContext dbc, CmsResource resource, List<CmsProperty> properties, int publishTag)
395    throws CmsDataAccessException;
396}