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