001: /*
002: * File : $Source: /usr/local/cvs/opencms/src/org/opencms/db/I_CmsHistoryDriver.java,v $
003: * Date : $Date: 2008-02-27 12:05:42 $
004: * Version: $Revision: 1.4 $
005: *
006: * This library is part of OpenCms -
007: * the Open Source Content Management System
008: *
009: * Copyright (c) 2002 - 2008 Alkacon Software GmbH (http://www.alkacon.com)
010: *
011: * This library is free software; you can redistribute it and/or
012: * modify it under the terms of the GNU Lesser General Public
013: * License as published by the Free Software Foundation; either
014: * version 2.1 of the License, or (at your option) any later version.
015: *
016: * This library is distributed in the hope that it will be useful,
017: * but WITHOUT ANY WARRANTY; without even the implied warranty of
018: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
019: * Lesser General Public License for more details.
020: *
021: * For further information about Alkacon Software GmbH, please see the
022: * company website: http://www.alkacon.com
023: *
024: * For further information about OpenCms, please see the
025: * project website: http://www.opencms.org
026: *
027: * You should have received a copy of the GNU Lesser General Public
028: * License along with this library; if not, write to the Free Software
029: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
030: */
031:
032: package org.opencms.db;
033:
034: import org.opencms.db.generic.CmsSqlManager;
035: import org.opencms.file.CmsDataAccessException;
036: import org.opencms.file.CmsPropertyDefinition;
037: import org.opencms.file.CmsResource;
038: import org.opencms.file.history.CmsHistoryProject;
039: import org.opencms.file.history.CmsHistoryPrincipal;
040: import org.opencms.file.history.I_CmsHistoryResource;
041: import org.opencms.security.I_CmsPrincipal;
042: import org.opencms.util.CmsUUID;
043:
044: import java.util.List;
045:
046: /**
047: * Definitions of all required history driver methods.<p>
048: *
049: * A history driver is a driver to write projects, resources and properties of
050: * resources optionally to a second set of history database tables while resources
051: * get published. A unique publish tag ID is used to identify a set of resource that
052: * were saved during one publish process.<p>
053: *
054: * @author Michael Emmerich
055: * @author Thomas Weckert
056: * @author Michael Moossen
057: *
058: * @version $Revision: 1.4 $
059: *
060: * @since 6.9.1
061: */
062: public interface I_CmsHistoryDriver {
063:
064: /** The type ID to identify history driver implementations. */
065: int DRIVER_TYPE_ID = 0;
066:
067: /**
068: * Creates a new property defintion in the database.<p>
069: *
070: * @param dbc the current database context
071: * @param name the name of the property definition
072: * @param type the type of the property definition
073: *
074: * @return the new property definition object
075: *
076: * @throws CmsDataAccessException if something goes wrong
077: */
078: CmsPropertyDefinition createPropertyDefinition(CmsDbContext dbc,
079: String name, CmsPropertyDefinition.CmsPropertyType type)
080: throws CmsDataAccessException;
081:
082: /**
083: * Deletes all historical versions of a resource
084: * keeping maximal <code>versionsToKeep</code> versions.<p>
085: *
086: * @param dbc the current database context
087: * @param histResource the historical resource to delete versions for
088: * @param versionsToKeep the number of versions to keep
089: * @param time deleted resources older than this will also be deleted, is ignored if negative
090: *
091: * @return the number of versions that were deleted
092: *
093: * @throws CmsDataAccessException if something goes wrong
094: */
095: int deleteEntries(CmsDbContext dbc,
096: I_CmsHistoryResource histResource, int versionsToKeep,
097: long time) throws CmsDataAccessException;
098:
099: /**
100: * Deletes a property definition.<p>
101: *
102: * @param dbc the current database context
103: * @param propertyDef the property definition to be deleted
104: *
105: * @throws CmsDataAccessException if something goes wrong
106: */
107: void deletePropertyDefinition(CmsDbContext dbc,
108: CmsPropertyDefinition propertyDef)
109: throws CmsDataAccessException;
110:
111: /**
112: * Destroys this driver.<p>
113: *
114: * @throws Throwable if something goes wrong
115: */
116: void destroy() throws Throwable;
117:
118: /**
119: * Returns all historical resources (of deleted resources) in the subtree
120: * of the folder identified by the given structure id.<p>
121: *
122: * @param dbc the current database context
123: * @param structureId the structrue id of the folder to get the historical resources for
124: *
125: * @return a list of {@link I_CmsHistoryResource} objects
126: *
127: * @throws CmsDataAccessException if something goes wrong
128: */
129: List getAllDeletedEntries(CmsDbContext dbc, CmsUUID structureId)
130: throws CmsDataAccessException;
131:
132: /**
133: * Returns all historical resources (of not deleted resources) in the subtree
134: * of the folder identified by the given structure id.<p>
135: *
136: * @param dbc the current database context
137: * @param structureId the structrue id of the folder to get the historical resources for
138: *
139: * @return a list of {@link I_CmsHistoryResource} objects
140: *
141: * @throws CmsDataAccessException if something goes wrong
142: */
143: List getAllNotDeletedEntries(CmsDbContext dbc, CmsUUID structureId)
144: throws CmsDataAccessException;
145:
146: /**
147: * Returns the SqlManager of this driver.<p>
148: *
149: * @return the SqlManager of this driver
150: */
151: CmsSqlManager getSqlManager();
152:
153: /**
154: * Initializes the SQL manager for this driver.<p>
155: *
156: * @param classname the classname of the SQL manager
157: *
158: * @return the SQL manager for this driver
159: */
160: org.opencms.db.generic.CmsSqlManager initSqlManager(String classname);
161:
162: /**
163: * Reads all file headers of the resource with the given structure id.<p>
164: *
165: * This method returns a list with the history of the resource, i.e.
166: * the historical resources, independent of the project they were attached to.<br>
167: *
168: * The reading excludes the file content.<p>
169: *
170: * @param dbc the current database context
171: * @param structureId the structure id
172: *
173: * @return a list of historical resources, as <code>{@link I_CmsHistoryResource}</code> objects
174: *
175: * @throws CmsDataAccessException if something goes wrong
176: */
177: List readAllAvailableVersions(CmsDbContext dbc, CmsUUID structureId)
178: throws CmsDataAccessException;
179:
180: /**
181: * Reads the content of the historical version of the resource
182: * identified by its structure id.<p>
183: *
184: * @param dbc the current database context
185: * @param resourceId the resource id of the resource to read the content for
186: * @param publishTag the publish tag of the version
187: *
188: * @return the content if found
189: *
190: * @throws CmsDataAccessException if something goes wrong
191: */
192: byte[] readContent(CmsDbContext dbc, CmsUUID resourceId,
193: int publishTag) throws CmsDataAccessException;
194:
195: /**
196: * Reads all deleted (historical) resources below the given path, that the given user deleted by itself.<p>
197: *
198: * @param dbc the current db context
199: * @param structureId the structure id of the parent resource to read the deleted resources from
200: * @param userId the id of the user that deleted the resources, or <code>null</code> to retrieve them all
201: *
202: * @return a list of <code>{@link I_CmsHistoryResource}</code> objects
203: *
204: * @throws CmsDataAccessException if something goes wrong
205: */
206: List readDeletedResources(CmsDbContext dbc, CmsUUID structureId,
207: CmsUUID userId) throws CmsDataAccessException;
208:
209: /**
210: * Reads a historical file version including the file content.<p>
211: *
212: * @param dbc the current database context
213: * @param structureId the structure id of the file to read
214: * @param publishTag the desired publish tag of the file
215: *
216: * @return the historical file version
217: *
218: * @throws CmsDataAccessException if something goes wrong
219: *
220: * @deprecated use {@link #readResource(CmsDbContext, CmsUUID, int)} instead
221: * but notice that the <code>publishTag != version</code>
222: */
223: I_CmsHistoryResource readFile(CmsDbContext dbc,
224: CmsUUID structureId, int publishTag)
225: throws CmsDataAccessException;
226:
227: /**
228: * Returns the last historical version of a resource.<p>
229: *
230: * @param dbc the current database context
231: * @param structureId the structure ID of the resource
232: *
233: * @return the last historical version of a resource
234: *
235: * @throws CmsDataAccessException if something goes wrong
236: */
237: int readLastVersion(CmsDbContext dbc, CmsUUID structureId)
238: throws CmsDataAccessException;
239:
240: /**
241: * Reads the maximal publish tag for a specified resource id.<p>
242: *
243: * @param dbc the current database context
244: * @param resourceId the id of the resource the get the publish tag for
245: *
246: * @return the maximal publish tag for the given resource
247: *
248: * @throws CmsDataAccessException if something goes wrong
249: */
250: int readMaxPublishTag(CmsDbContext dbc, CmsUUID resourceId)
251: throws CmsDataAccessException;
252:
253: /**
254: * Returns the next available history publish tag.<p>
255: *
256: * @param dbc the current database context
257: *
258: * @return the next available history publish tag
259: */
260: int readNextPublishTag(CmsDbContext dbc);
261:
262: /**
263: * Reads an historical principal entry.<p>
264: *
265: * @param dbc the current database context
266: * @param principalId the id of the principal to retrieve
267: *
268: * @return the historical principal entry
269: *
270: * @throws CmsDataAccessException if something goes wrong
271: */
272: CmsHistoryPrincipal readPrincipal(CmsDbContext dbc,
273: CmsUUID principalId) throws CmsDataAccessException;
274:
275: /**
276: * Reads an historical project version.<p>
277: *
278: * @param dbc the current database context
279: * @param publishTag the publish tag
280: *
281: * @return the requested historical project
282: *
283: * @throws CmsDataAccessException is something goes wrong
284: */
285: CmsHistoryProject readProject(CmsDbContext dbc, int publishTag)
286: throws CmsDataAccessException;
287:
288: /**
289: * Reads all resources that belong to the historical project identified by the given publish tag.<p>
290: *
291: * @param dbc the current database context
292: * @param publishTag the publish tag
293: *
294: * @return all resources that belong to the historical project identified by the given publish tag
295: *
296: * @throws CmsDataAccessException if something goes wrong
297: */
298: List readProjectResources(CmsDbContext dbc, int publishTag)
299: throws CmsDataAccessException;
300:
301: /**
302: * Returns all projects from the history.<p>
303: *
304: * @param dbc the current database context
305: *
306: * @return list of <code>{@link CmsHistoryProject}</code> objects
307: * with all projects from history.
308: *
309: * @throws CmsDataAccessException if an error occurs
310: */
311: List readProjects(CmsDbContext dbc) throws CmsDataAccessException;
312:
313: /**
314: * Returns a list of all properties of a historical file or folder.<p>
315: *
316: * @param dbc the current database context
317: * @param historicalResource the resource to read the properties from
318: *
319: * @return a list of {@link org.opencms.file.CmsProperty} objects
320: *
321: * @throws CmsDataAccessException if something goes wrong
322: */
323: List readProperties(CmsDbContext dbc,
324: I_CmsHistoryResource historicalResource)
325: throws CmsDataAccessException;
326:
327: /**
328: * Reads a property definition with the given name.<p>
329: *
330: * @param dbc the current database context
331: * @param name the name of the property definition to read
332: *
333: * @return the property definition that corresponds to the given arguments - or <code>null</code> if not found
334: *
335: * @throws CmsDataAccessException if something goes wrong
336: */
337: CmsPropertyDefinition readPropertyDefinition(CmsDbContext dbc,
338: String name) throws CmsDataAccessException;
339:
340: /**
341: * Gets the publish tag of the first historical project after a given date.<p>
342: *
343: * This method is used during the deletion process of older historical data.<p>
344: *
345: * @param dbc the current database context
346: * @param maxdate the date to compare the historical projects with
347: *
348: * @return publish tag of the first historical project after maxdate
349: *
350: * @throws CmsDataAccessException if something goes wrong
351: */
352: int readPublishTag(CmsDbContext dbc, long maxdate)
353: throws CmsDataAccessException;
354:
355: /**
356: * Reads a historical resource version without including the file content.<p>
357: *
358: * @param dbc the current database context
359: * @param structureId the structure id of the resource to read
360: * @param version the desired version number
361: *
362: * @return the historical resource version
363: *
364: * @throws CmsDataAccessException if something goes wrong
365: */
366: I_CmsHistoryResource readResource(CmsDbContext dbc,
367: CmsUUID structureId, int version)
368: throws CmsDataAccessException;
369:
370: /**
371: * Writes an historical entry for the given principal.<p>
372: *
373: * @param dbc the current database context
374: * @param principal the principal to write
375: *
376: * @throws CmsDataAccessException if something goes wrong
377: */
378: void writePrincipal(CmsDbContext dbc, I_CmsPrincipal principal)
379: throws CmsDataAccessException;
380:
381: /**
382: * Creates an historical entry for the current project.<p>
383: *
384: * @param dbc the current database context
385: * @param publishTag the publish tag
386: * @param publishDate long timestamp when the current project was published
387: *
388: * @throws CmsDataAccessException if something goes wrong
389: */
390: void writeProject(CmsDbContext dbc, int publishTag, long publishDate)
391: throws CmsDataAccessException;
392:
393: /**
394: * Writes the properties of a resource to the history.<p>
395: *
396: * @param dbc the current database context
397: * @param resource the resource of the properties
398: * @param properties the properties to write
399: * @param publishTag the publish tag
400: *
401: * @throws CmsDataAccessException if something goes wrong
402: */
403: void writeProperties(CmsDbContext dbc, CmsResource resource,
404: List properties, int publishTag)
405: throws CmsDataAccessException;
406:
407: /**
408: * Writes a resource to the history.<p>
409: *
410: * @param dbc the current database context
411: * @param resource the resource that is written to the history
412: * @param properties the properties of the resource
413: * @param publishTag the publish tag
414: *
415: * @throws CmsDataAccessException if something goes wrong
416: */
417: void writeResource(CmsDbContext dbc, CmsResource resource,
418: List properties, int publishTag)
419: throws CmsDataAccessException;
420: }
|