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.db.urlname.CmsUrlNameMappingEntry;
031import org.opencms.db.urlname.CmsUrlNameMappingFilter;
032import org.opencms.file.CmsDataAccessException;
033import org.opencms.file.CmsFile;
034import org.opencms.file.CmsFolder;
035import org.opencms.file.CmsProject;
036import org.opencms.file.CmsProperty;
037import org.opencms.file.CmsPropertyDefinition;
038import org.opencms.file.CmsResource;
039import org.opencms.relations.CmsRelation;
040import org.opencms.relations.CmsRelationFilter;
041import org.opencms.security.CmsOrganizationalUnit;
042import org.opencms.util.CmsUUID;
043
044import java.sql.ResultSet;
045import java.sql.SQLException;
046import java.util.Collection;
047import java.util.List;
048import java.util.Map;
049
050/**
051 * Definitions of all required VFS driver methods.<p>
052 *
053 * @since 6.0.0
054 */
055public interface I_CmsVfsDriver {
056
057    /** The type ID to identify user driver implementations. */
058    int DRIVER_TYPE_ID = 3;
059
060    /** The internal request attribute to indicate that the permissions have to be checked. */
061    String REQ_ATTR_CHECK_PERMISSIONS = "CHECK_PERMISSIONS";
062
063    /** The internal request attribute to indicate that resource organizational units have to be retrieved. */
064    String REQ_ATTR_RESOURCE_OUS = "RETRIEVE_RESOURCE_OUS";
065
066    /**
067     * Adds a new URL name mapping entry.<p>
068     *
069     * @param dbc the current database context
070     * @param online if true, writes to the online tables, else to the offline tables
071     * @param entry the entry to add
072     *
073     * @throws CmsDataAccessException if something goes wrong
074     */
075    void addUrlNameMappingEntry(CmsDbContext dbc, boolean online, CmsUrlNameMappingEntry entry)
076    throws CmsDataAccessException;
077
078    /**
079     * Counts the number of siblings of a resource.<p>
080     *
081     * @param dbc the current database context
082     * @param projectId the current project id
083     * @param resourceId the resource id to count the number of siblings from
084     *
085     * @return number of siblings
086     * @throws CmsDataAccessException if something goes wrong
087     */
088    int countSiblings(CmsDbContext dbc, CmsUUID projectId, CmsUUID resourceId) throws CmsDataAccessException;
089
090    /**
091     * Creates a content entry for the resource identified by the specified resource id.<p>
092     *
093     * @param dbc the current database context
094     * @param projectId the id of the current project
095     * @param resourceId the resource id of the resource to create the content for
096     * @param content the content to write
097     *
098     * @throws CmsDataAccessException if something goes wrong
099     */
100    void createContent(CmsDbContext dbc, CmsUUID projectId, CmsUUID resourceId, byte[] content)
101    throws CmsDataAccessException;
102
103    /**
104     * Creates a {@link CmsFile} instance from a JDBC ResultSet.<p>
105     *
106     * @param res the JDBC ResultSet
107     * @param projectId the project id
108     *
109     * @return the created file
110     * @throws SQLException in case the result set does not include a requested table attribute
111     */
112    CmsFile createFile(ResultSet res, CmsUUID projectId) throws SQLException;
113
114    /**
115     * Creates a {@link CmsFile} instance from a JDBC ResultSet.<p>
116     *
117     * @param res the JDBC ResultSet
118     * @param projectId the project id
119     * @param hasFileContentInResultSet flag to include the file content
120     *
121     * @return the created file
122     * @throws SQLException in case the result set does not include a requested table attribute
123     */
124    CmsFile createFile(ResultSet res, CmsUUID projectId, boolean hasFileContentInResultSet) throws SQLException;
125
126    /**
127     * Creates a {@link CmsFolder} instance from a JDBC ResultSet.<p>
128     *
129     * @param res the JDBC ResultSet
130     * @param projectId the ID of the current project
131     * @param hasProjectIdInResultSet true if the SQL select query includes the PROJECT_ID table attribute
132     *
133     * @return the created folder
134     * @throws SQLException in case the result set does not include a requested table attribute
135     */
136    CmsFolder createFolder(ResultSet res, CmsUUID projectId, boolean hasProjectIdInResultSet) throws SQLException;
137
138    /**
139     * Creates a new content in the offline project.<p>
140     *
141     * @param dbc the current database context
142     * @param resourceId the resource id of the content to write
143     * @param contents the content to publish
144     * @param publishTag the publish tag
145     * @param keepOnline if the content is online or has to be put in the history
146     * @param needToUpdateContent if the content blob has to be updated
147     *
148     * @throws CmsDataAccessException if something goes wrong
149     */
150    void createOnlineContent(
151        CmsDbContext dbc,
152        CmsUUID resourceId,
153        byte[] contents,
154        int publishTag,
155        boolean keepOnline,
156        boolean needToUpdateContent) throws CmsDataAccessException;
157
158    /**
159     * Creates a new property definition in the database.<p>
160     *
161     * @param dbc the current database context
162     * @param projectId the project in which the property definition is created
163     * @param name the name of the property definition
164     * @param type the type of the property definition
165     *
166     * @return the new property definition
167     *
168     * @throws CmsDataAccessException if something goes wrong
169     */
170    CmsPropertyDefinition createPropertyDefinition(
171        CmsDbContext dbc,
172        CmsUUID projectId,
173        String name,
174        CmsPropertyDefinition.CmsPropertyType type) throws CmsDataAccessException;
175
176    /**
177     * Creates a new {@link CmsRelation} object in the database.<p>
178     *
179     * @param dbc the current database context
180     * @param projectId the id of the project to execute the query in
181     * @param relation the relation to create
182     *
183     * @throws CmsDataAccessException if something goes wrong
184     */
185    void createRelation(CmsDbContext dbc, CmsUUID projectId, CmsRelation relation) throws CmsDataAccessException;
186
187    /**
188     * Creates a new resource from a given {@link CmsResource} object.<p>
189     *
190     * This method works for both files and folders. Existing resources get overwritten.<p>
191     *
192     * @param dbc the current database context
193     * @param projectId the id of the current project
194     * @param resource the resource to be created
195     * @param content the file content, or null in case of a folder
196     * @return the created Cms resource
197     *
198     * @throws CmsDataAccessException if something goes wrong
199     *
200     * @see org.opencms.file.types.I_CmsResourceType#createResource(org.opencms.file.CmsObject, CmsSecurityManager, String, byte[], List)
201     * @see org.opencms.file.types.I_CmsResourceType#importResource(org.opencms.file.CmsObject, CmsSecurityManager, String, CmsResource, byte[], List)
202     * @see org.opencms.file.CmsObject#createResource(String, int, byte[], List)
203     * @see org.opencms.file.CmsObject#importResource(String, CmsResource, byte[], List)
204     */
205    CmsResource createResource(CmsDbContext dbc, CmsUUID projectId, CmsResource resource, byte[] content)
206    throws CmsDataAccessException;
207
208    /**
209     * Creates a CmsResource instance from a JDBC ResultSet.<p>
210     *
211     * @param res the JDBC ResultSet
212     * @param projectId the ID of the current project to adjust the modification date in case the resource is a VFS link
213     *
214     * @return the created resource
215     * @throws SQLException in case the result set does not include a requested table attribute
216     */
217    CmsResource createResource(ResultSet res, CmsUUID projectId) throws SQLException;
218
219    /**
220     * Creates a new sibling for a specified resource.<p>
221     * @param dbc the current database context
222     * @param project the project where to create the link
223     * @param resource the link prototype
224     *
225     * @throws CmsDataAccessException if something goes wrong
226     */
227    void createSibling(CmsDbContext dbc, CmsProject project, CmsResource resource) throws CmsDataAccessException;
228
229    /**
230     * Deletes the aliases matching a given filter.<p>
231     *
232     * @param dbc the database context
233     * @param project the current project
234     * @param filter the alias filter
235     * @throws CmsDataAccessException if something goes wrong
236     */
237    void deleteAliases(CmsDbContext dbc, CmsProject project, CmsAliasFilter filter) throws CmsDataAccessException;
238
239    /**
240     * Deletes a property definition.<p>
241     *
242     * @param dbc the current database context
243     * @param name the property definitions to be deleted
244     *
245     * @throws CmsDataAccessException if something goes wrong
246     */
247    void deletePropertyDefinition(CmsDbContext dbc, CmsPropertyDefinition name) throws CmsDataAccessException;
248
249    /**
250     * Deletes all property values of a file or folder.<p>
251     *
252     * You may specify which whether just structure or resource property values should
253     * be deleted, or both of them.<p>
254     *
255     * @param dbc the current database context
256     * @param projectId the id of the project
257     * @param resource the resource
258     * @param deleteOption determines which property values should be deleted
259     *
260     * @throws CmsDataAccessException if something goes wrong
261     *
262     * @see org.opencms.file.CmsProperty#DELETE_OPTION_DELETE_STRUCTURE_AND_RESOURCE_VALUES
263     * @see org.opencms.file.CmsProperty#DELETE_OPTION_DELETE_STRUCTURE_VALUES
264     * @see org.opencms.file.CmsProperty#DELETE_OPTION_DELETE_RESOURCE_VALUES
265     */
266    void deletePropertyObjects(CmsDbContext dbc, CmsUUID projectId, CmsResource resource, int deleteOption)
267    throws CmsDataAccessException;
268
269    /**
270     * Deletes all relations with the given filter for the given resource.<p>
271     *
272     * @param dbc the current database context
273     * @param projectId the id of the project to execute the query in
274     * @param resource the base resource. May be <code>null</code> for all
275     * @param filter the filter to restrict the relations to remove
276     *
277     * @throws CmsDataAccessException if something goes wrong
278     */
279    void deleteRelations(CmsDbContext dbc, CmsUUID projectId, CmsResource resource, CmsRelationFilter filter)
280    throws CmsDataAccessException;
281
282    /**
283     * Deletes rewrite aliases matching a given filter.<p>
284     *
285     * @param dbc the current database context
286     * @param filter the filter describing which rewrite aliases to delete
287     *
288     * @throws CmsDataAccessException if something goes wrong
289     */
290    void deleteRewriteAliases(CmsDbContext dbc, CmsRewriteAliasFilter filter) throws CmsDataAccessException;
291
292    /**
293     * Deletes the URL name mapping entries which match a given filter.<p>
294     *
295     * @param dbc the current database context
296     * @param online if true, changes the online URL name mappings, else the offline URL name mappings
297     * @param filter the URL name mapping entries to delete
298     *
299     * @throws CmsDataAccessException if something goes wrong
300     */
301    void deleteUrlNameMappingEntries(CmsDbContext dbc, boolean online, CmsUrlNameMappingFilter filter)
302    throws CmsDataAccessException;
303
304    /**
305     * Destroys this driver.<p>
306     *
307     * @throws Throwable if something goes wrong
308     */
309    void destroy() throws Throwable;
310
311    /**
312     * Returns all organizational units for the given resource.<p>
313     *
314     * @param dbc the database context
315     * @param projectId the id of the project
316     * @param resource the resource
317     *
318     * @return a list of {@link org.opencms.security.CmsOrganizationalUnit} objects
319     *
320     * @throws CmsDataAccessException if something goes wrong
321     */
322    List<CmsOrganizationalUnit> getResourceOus(CmsDbContext dbc, CmsUUID projectId, CmsResource resource)
323    throws CmsDataAccessException;
324
325    /**
326     * Returns the SqlManager of this driver.<p>
327     *
328     * @return the SqlManager of this driver
329     */
330    CmsSqlManager getSqlManager();
331
332    /**
333     * Gets the current value of a counter, creates it if it doesn't already exist, and increments it.<p>
334     *
335     * @param dbc the database context
336     * @param name the name of the counter
337     *
338     * @return the counter value before incrementing
339     *
340     * @throws CmsDataAccessException if something goes wrong
341     */
342    int incrementCounter(CmsDbContext dbc, String name) throws CmsDataAccessException;
343
344    /**
345     * Initializes the SQL manager for this driver.<p>
346     *
347     * To obtain JDBC connections from different pools, further
348     * {online|offline|history} pool Urls have to be specified.<p>
349     *
350     * @param classname the class name of the SQL manager
351     *
352     * @return the SQL manager for this driver
353     */
354    CmsSqlManager initSqlManager(String classname);
355
356    /**
357     * Adds an alias to the database.<p>
358     *
359     * @param dbc the current database context
360     * @param project the current project
361     * @param alias the alias to write
362     *
363     * @throws CmsDataAccessException if something goes wrong
364     */
365    void insertAlias(CmsDbContext dbc, CmsProject project, CmsAlias alias) throws CmsDataAccessException;
366
367    /**
368     * Adds a list of rewrite aliases.<p>
369     *
370     * When adding a rewrite alias, make sure that no alias with the same id is present in the database.<p>
371     *
372     * @param dbc the current database context
373     * @param rewriteAliases the rewrite aliases to save
374     *
375     * @throws CmsDataAccessException if something goes wrong
376     */
377    void insertRewriteAliases(CmsDbContext dbc, Collection<CmsRewriteAlias> rewriteAliases)
378    throws CmsDataAccessException;
379
380    /**
381     * Moves the given resource to the specified destination path.<p>
382     *
383     * @param dbc the current database context
384     * @param projectId the Id of the project
385     * @param source the resource to move
386     * @param destinationPath the root path of the destination resource
387     *
388     * @throws CmsDataAccessException if something goes wrong
389     */
390    void moveResource(CmsDbContext dbc, CmsUUID projectId, CmsResource source, String destinationPath)
391    throws CmsDataAccessException;
392
393    /**
394     * Publishes the structure and resource records of an
395     * offline resource into it's online counterpart.<p>
396     *
397     * @param dbc the current database context
398     * @param onlineProject the online project
399     * @param onlineResource the online resource
400     * @param offlineResource the offline resource
401     *
402     * @throws CmsDataAccessException if something goes wrong
403     */
404    void publishResource(
405        CmsDbContext dbc,
406        CmsProject onlineProject,
407        CmsResource onlineResource,
408        CmsResource offlineResource) throws CmsDataAccessException;
409
410    /**
411     * Copies the version number from the offline resource to the online resource,
412     * this has to be done during publishing, direct after copying the resource itself.<p>
413     *
414     * @param dbc the current database context
415     * @param resource the resource that has been publish
416     * @param firstSibling if this is the first sibling to be publish
417     *
418     * @throws CmsDataAccessException if something goes wrong
419     */
420    void publishVersions(CmsDbContext dbc, CmsResource resource, boolean firstSibling) throws CmsDataAccessException;
421
422    /**
423     * Reads the aliases matching a given filter.<p>
424     *
425     * @param dbc the database context
426     * @param project the current project
427     * @param filter the alias filter
428     * @return the list of aliases which were read
429     *
430     * @throws CmsDataAccessException if something goes wrong
431     */
432    List<CmsAlias> readAliases(CmsDbContext dbc, CmsProject project, CmsAliasFilter filter)
433    throws CmsDataAccessException;
434
435    /**
436     * Reads all child-files and/or child-folders of a specified parent resource.<p>
437     *
438     * @param dbc the current database context
439     * @param currentProject the current project
440     * @param resource the parent folder
441     * @param getFolders if true the child folders of the parent folder are returned in the result set
442     * @param getFiles if true the child files of the parent folder are returned in the result set
443     *
444     * @return a list of all sub folders or sub files
445     * @throws CmsDataAccessException if something goes wrong
446     */
447    List<CmsResource> readChildResources(
448        CmsDbContext dbc,
449        CmsProject currentProject,
450        CmsResource resource,
451        boolean getFolders,
452        boolean getFiles) throws CmsDataAccessException;
453
454    /**
455     * Reads the content of a file specified by it's resource ID.<p>
456     *
457     * @param dbc the current database context
458     * @param projectId the ID of the current project
459     * @param resourceId the id of the resource
460     *
461     * @return the file content
462     *
463     * @throws CmsDataAccessException if something goes wrong
464     */
465    byte[] readContent(CmsDbContext dbc, CmsUUID projectId, CmsUUID resourceId) throws CmsDataAccessException;
466
467    /**
468     * Reads a folder specified by it's structure ID.<p>
469     *
470     * @param dbc the current database context
471     * @param projectId the project in which the resource will be used
472     * @param folderId the structure id of the folder to be read
473     *
474     * @return the read folder
475     *
476     * @throws CmsDataAccessException if something goes wrong
477     */
478    CmsFolder readFolder(CmsDbContext dbc, CmsUUID projectId, CmsUUID folderId) throws CmsDataAccessException;
479
480    /**
481     * Reads a folder specified by it's resource name.<p>
482     *
483     * @param dbc the current database context
484     * @param projectId the project in which the resource will be used
485     * @param foldername the name of the folder to be read
486     *
487     * @return the read folder
488     * @throws CmsDataAccessException if something goes wrong
489     */
490    CmsFolder readFolder(CmsDbContext dbc, CmsUUID projectId, String foldername) throws CmsDataAccessException;
491
492    /**
493     * Reads the parent folder of a resource specified by it's structure ID.<p>
494     *
495     * The parent folder for the root '/' is defined as <code>null</code>.<p>
496     *
497     * @param dbc the current database context
498     * @param projectId the project in which the resource will be used
499     * @param structureId the id of the resource to read the parent folder for
500     *
501     * @return the read folder, or <code>null</code>
502     *
503     * @throws CmsDataAccessException if something goes wrong
504     */
505    CmsFolder readParentFolder(CmsDbContext dbc, CmsUUID projectId, CmsUUID structureId) throws CmsDataAccessException;
506
507    /**
508     * Reads a property definition for the specified resource type.<p>
509     *
510     * If no property definition with the given name is found,
511     * <code>null</code> is returned.<p>
512     *
513     * @param dbc the current database context
514     * @param name the name of the property definition to read
515     * @param projectId the id of the project
516     *
517     * @return the property definition that was read
518     *
519     * @throws CmsDataAccessException a CmsDbEntryNotFoundException is thrown if the property definition does not exist
520     */
521    CmsPropertyDefinition readPropertyDefinition(CmsDbContext dbc, String name, CmsUUID projectId)
522    throws CmsDataAccessException;
523
524    /**
525     * Reads all property definitions for the specified mapping type.<p>
526     *
527     * @param dbc the current database context
528     * @param projectId the id of the project
529     *
530     * @return a list with the <code>{@link CmsPropertyDefinition}</code> objects (may be empty)
531     *
532     * @throws CmsDataAccessException if something goes wrong
533     */
534    List<CmsPropertyDefinition> readPropertyDefinitions(CmsDbContext dbc, CmsUUID projectId)
535    throws CmsDataAccessException;
536
537    /**
538     * Reads a property object from the database specified by it's key name mapped to a resource.<p>
539     *
540     * The implementation must return {@link CmsProperty#getNullProperty()} if the property is not found.<p>
541     *
542     * TODO: change project parameter to project id
543     *
544     * @param dbc the current database context
545     * @param key the key of the property
546     * @param project the current project
547     * @param resource the resource where the property is attached to
548     *
549     * @return a CmsProperty object containing both the structure and resource value of the property
550     *
551     * @throws CmsDataAccessException if something goes wrong
552     */
553    CmsProperty readPropertyObject(CmsDbContext dbc, String key, CmsProject project, CmsResource resource)
554    throws CmsDataAccessException;
555
556    /**
557     * Reads all property objects mapped to a specified resource from the database.<p>
558     *
559     * The implementation must return an empty list if no properties are found at all.<p>
560     *
561     * TODO: change project parameter to project id
562     *
563     * @param dbc the current database context
564     * @param project the current project
565     * @param resource the resource where the property is attached to
566     *
567     * @return a list with CmsProperty objects containing both the structure and resource value of the property
568     * @throws CmsDataAccessException if something goes wrong
569     */
570    List<CmsProperty> readPropertyObjects(CmsDbContext dbc, CmsProject project, CmsResource resource)
571    throws CmsDataAccessException;
572
573    /**
574     * Reads all relations with the given filter for the given resource.<p>
575     *
576     * @param dbc the current database context
577     * @param projectId the id of the project to execute the query in
578     * @param resource the resource to read the relations for, may be <code>null</code> for all
579     * @param filter the filter to restrict the relations to retrieve
580     *
581     * @return the read relations
582     *
583     * @throws CmsDataAccessException if something goes wrong
584     */
585    List<CmsRelation> readRelations(CmsDbContext dbc, CmsUUID projectId, CmsResource resource, CmsRelationFilter filter)
586    throws CmsDataAccessException;
587
588    /**
589     * Reads a resource specified by it's structure ID.<p>
590     *
591     * @param dbc the current database context
592     * @param projectId the Id of the project
593     * @param structureId the Id of the resource
594     * @param includeDeleted true if already deleted files are included
595     *
596     * @return the resource that was read
597     * @throws CmsDataAccessException if something goes wrong
598     */
599    CmsResource readResource(CmsDbContext dbc, CmsUUID projectId, CmsUUID structureId, boolean includeDeleted)
600    throws CmsDataAccessException;
601
602    /**
603     * Reads a resource specified by it's resource name.<p>
604     *
605     * @param dbc the current database context
606     * @param projectId the Id of the project in which the resource will be used
607     * @param filename the name of the file
608     * @param includeDeleted true if already deleted files are included
609     *
610     * @return the resource that was read
611     * @throws CmsDataAccessException if something goes wrong
612     */
613    CmsResource readResource(CmsDbContext dbc, CmsUUID projectId, String filename, boolean includeDeleted)
614    throws CmsDataAccessException;
615
616    /**
617     * Reads all resources inside a given project and with a given state.<p>
618     *
619     * @param dbc the current database context
620     * @param currentProject the current project
621     * @param state the state to match
622     * @param mode flag signaling the read mode
623     *
624     * @return a list with all resources that where read
625     * @throws CmsDataAccessException if something goes wrong
626     */
627    List<CmsResource> readResources(CmsDbContext dbc, CmsUUID currentProject, CmsResourceState state, int mode)
628    throws CmsDataAccessException;
629
630    /**
631     * Returns all resources associated to a given principal via an ACE.<p>
632     *
633     * @param dbc the current database context
634     * @param project the to read the entries from
635     * @param principalId the id of the principal
636
637     * @return a list of <code>{@link org.opencms.file.CmsResource}</code> objects
638     *
639     * @throws CmsDataAccessException if something goes wrong
640     */
641    List<CmsResource> readResourcesForPrincipalACE(CmsDbContext dbc, CmsProject project, CmsUUID principalId)
642    throws CmsDataAccessException;
643
644    /**
645     * Returns all resources associated to a given principal through some of following attributes.<p>
646     *
647     * <ul>
648     *    <li>User Created</li>
649     *    <li>User Last Modified</li>
650     * </ul><p>
651     *
652     * @param dbc the current database context
653     * @param project the to read the entries from
654     * @param principalId the id of the principal
655
656     * @return a list of <code>{@link org.opencms.file.CmsResource}</code> objects
657     *
658     * @throws CmsDataAccessException if something goes wrong
659     */
660    List<CmsResource> readResourcesForPrincipalAttr(CmsDbContext dbc, CmsProject project, CmsUUID principalId)
661    throws CmsDataAccessException;
662
663    /**
664     * Reads all resources that have a value (containing the specified value)
665     * set for the specified property (definition), in the given path.<p>
666     *
667     * Both individual and shared properties of a resource are checked.<p>
668     *
669     * If the <code>value</code> parameter is <code>null</code>, all resources having the
670     * given property set are returned.<p>
671     *
672     * @param dbc the current database context
673     * @param projectId the id of the project
674     * @param propertyDefinition the id of the property definition
675     * @param path the folder to get the resources with the property from
676     * @param value the string to search in the value of the property
677     *
678     * @return a list of all <code>{@link CmsResource}</code> objects
679     *          that have a value set for the specified property.
680     *
681     * @throws CmsDataAccessException if something goes wrong
682     */
683    List<CmsResource> readResourcesWithProperty(
684        CmsDbContext dbc,
685        CmsUUID projectId,
686        CmsUUID propertyDefinition,
687        String path,
688        String value) throws CmsDataAccessException;
689
690    /**
691     * Reads all resources inside a given project matching the criteria specified by parameter values.<p>
692     *
693     * Important: If {@link CmsDriverManager#READMODE_EXCLUDE_TREE} is true (or {@link CmsDriverManager#READMODE_INCLUDE_TREE} is false),
694     * the provided parent String must be the UUID of the parent folder, NOT the parent folder path.<p>
695     *
696     * @param dbc the current database context
697     * @param projectId the project id for matching resources
698     * @param parent the path to the resource used as root of the searched subtree or {@link CmsDriverManager#READ_IGNORE_PARENT},
699     *               {@link CmsDriverManager#READMODE_EXCLUDE_TREE} means to read immediate children only
700     * @param type the resource type of matching resources or {@link CmsDriverManager#READ_IGNORE_TYPE} (meaning inverted by {@link CmsDriverManager#READMODE_EXCLUDE_TYPE}
701     * @param state the state of matching resources (meaning inverted by {@link CmsDriverManager#READMODE_EXCLUDE_STATE} or <code>null</code> to ignore
702     * @param startTime the start of the time range for the last modification date of matching resources or READ_IGNORE_TIME
703     * @param endTime the end of the time range for the last modification date of matching resources or READ_IGNORE_TIME
704     * @param releasedAfter the start of the time range for the release date of matching resources
705     * @param releasedBefore the end of the time range for the release date of matching resources
706     * @param expiredAfter the start of the time range for the expire date of matching resources
707     * @param expiredBefore the end of the time range for the expire date of matching resources
708     * @param mode additional mode flags:
709     * <ul>
710     *  <li>{@link CmsDriverManager#READMODE_INCLUDE_TREE}
711     *  <li>{@link CmsDriverManager#READMODE_EXCLUDE_TREE}
712     *  <li>{@link CmsDriverManager#READMODE_INCLUDE_PROJECT}
713     *  <li>{@link CmsDriverManager#READMODE_EXCLUDE_TYPE}
714     *  <li>{@link CmsDriverManager#READMODE_EXCLUDE_STATE}
715     * </ul>
716     *
717     * @return a list of CmsResource objects matching the given criteria
718     *
719     * @throws CmsDataAccessException if something goes wrong
720     */
721    List<CmsResource> readResourceTree(
722        CmsDbContext dbc,
723        CmsUUID projectId,
724        String parent,
725        int type,
726        CmsResourceState state,
727        long startTime,
728        long endTime,
729        long releasedAfter,
730        long releasedBefore,
731        long expiredAfter,
732        long expiredBefore,
733        int mode) throws CmsDataAccessException;
734
735    /**
736     * Reads the rewrite aliases matching a given filter.<p>
737     *
738     * @param dbc the current database context
739     * @param filter the filter describing which rewrite aliases should be returned
740     *
741     * @return the rewrite aliases which were found
742     *
743     * @throws CmsDataAccessException if something goes wrong
744     */
745    List<CmsRewriteAlias> readRewriteAliases(CmsDbContext dbc, CmsRewriteAliasFilter filter)
746    throws CmsDataAccessException;
747
748    /**
749     * Reads all siblings that point to the resource record of a specified resource.<p>
750     *
751     * @param dbc the current database context
752     * @param projectId the id of the current project
753     * @param resource the specified resource
754     * @param includeDeleted <code>true</code> if deleted siblings should be included in the result list
755     *
756     * @return a list of <code>{@link CmsResource}</code>s that
757     *          are siblings to the specified resource,
758     *          including the specified resource itself.
759     *
760     * @throws CmsDataAccessException if something goes wrong
761     */
762    List<CmsResource> readSiblings(CmsDbContext dbc, CmsUUID projectId, CmsResource resource, boolean includeDeleted)
763    throws CmsDataAccessException;
764
765    /**
766     * Reads the URL name mapping entries which match a given filter.<p>
767     *
768     * @param dbc the database context
769     * @param online if true, reads from the online mapping, else from the offline mapping
770     * @param filter the filter which the entries to be read should match
771     *
772     * @return the mapping entries which match the given filter
773     *
774     * @throws CmsDataAccessException if something goes wrong
775     */
776    List<CmsUrlNameMappingEntry> readUrlNameMappingEntries(
777        CmsDbContext dbc,
778        boolean online,
779        CmsUrlNameMappingFilter filter) throws CmsDataAccessException;
780
781    /**
782     * Reads a resource version numbers.<p>
783     *
784     * @param dbc the current database context
785     * @param projectId the project to read the versions from
786     * @param resourceId the resource id of the resource to read the versions from
787     * @param structureId the structure id of the resource to read the versions from
788     *
789     * @return a map with two entries with keys "structure" and "resource" for the
790     *         structure and resource version number respectively, the values are {@link Integer}
791     *         objects and may be <code>-1</code> if an entry could be found
792     *
793     * @throws CmsDataAccessException if something goes wrong
794     */
795    Map<String, Integer> readVersions(CmsDbContext dbc, CmsUUID projectId, CmsUUID resourceId, CmsUUID structureId)
796    throws CmsDataAccessException;
797
798    /**
799     * Removes a file physically in the database.<p>
800     *
801     * @param dbc the current database context
802     * @param projectId the id of the current project
803     * @param resource the resource
804     *
805     * @throws CmsDataAccessException if something goes wrong
806     */
807    void removeFile(CmsDbContext dbc, CmsUUID projectId, CmsResource resource) throws CmsDataAccessException;
808
809    /**
810     * Removes a folder physically in the database.<p>
811     *
812     * @param dbc the current database context
813     * @param currentProject the current project
814     * @param resource the folder
815     *
816     * @throws CmsDataAccessException if something goes wrong
817     */
818    void removeFolder(CmsDbContext dbc, CmsProject currentProject, CmsResource resource) throws CmsDataAccessException;
819
820    /**
821     * Replaces the content and properties of an existing resource.<p>
822     * @param dbc the current database context
823     * @param newResource the new resource
824     * @param newResourceContent the new content
825     * @param newResourceType the resource type
826     *
827     * @throws CmsDataAccessException if something goes wrong
828     */
829    void replaceResource(CmsDbContext dbc, CmsResource newResource, byte[] newResourceContent, int newResourceType)
830    throws CmsDataAccessException;
831
832    /**
833     * Sets the driver manager for this driver if possible.<p>
834     *
835     * @param driverManager the new driver manager
836     */
837    void setDriverManager(CmsDriverManager driverManager);
838
839    /**
840     * Sets the SQL manager for this driver if possible.<p>
841     *
842     * @param sqlManager the new SQL manager
843     */
844    void setSqlManager(CmsSqlManager sqlManager);
845
846    /**
847     * Transfers the attributes of a resource from to the given users.<p>
848     *
849     * @param dbc the current database context
850     * @param project the current project
851     * @param resource the resource to modify
852     * @param createdUser the id of the user to be set as the creator of the resource
853     * @param lastModifiedUser the id of the user to be set as the last modificator of the resource
854     *
855     * @throws CmsDataAccessException if something goes wrong
856     */
857    void transferResource(
858        CmsDbContext dbc,
859        CmsProject project,
860        CmsResource resource,
861        CmsUUID createdUser,
862        CmsUUID lastModifiedUser) throws CmsDataAccessException;
863
864    /**
865     * Updates the relations on the online project copying the relations from the offline project.<p>
866     * TODO: add offlineProject parameter
867     *
868     * @param dbc the current database context
869     * @param onlineProject the online project
870     * @param offlineResource the resource to update the relations for
871     *
872     * @throws CmsDataAccessException is something goes wrong
873     */
874    void updateRelations(CmsDbContext dbc, CmsProject onlineProject, CmsResource offlineResource)
875    throws CmsDataAccessException;
876
877    /**
878     * Validates if the specified resource ID in the tables of the specified project {offline|online} exists.<p>
879     *
880     * @param dbc the current database context
881     * @param projectId the project id
882     * @param resourceId the resource id to test for
883     *
884     * @return true if a resource with the given id was found, false otherwise
885     *
886     * @throws CmsDataAccessException if something goes wrong
887     */
888    boolean validateResourceIdExists(CmsDbContext dbc, CmsUUID projectId, CmsUUID resourceId)
889    throws CmsDataAccessException;
890
891    /**
892     * Validates if the specified structure ID in the tables of the specified project {offline|online} exists.<p>
893     *
894     * @param dbc the current database context
895     * @param projectId the ID of current project
896     * @param structureId the structure id
897     *
898     * @return true, if the specified structure ID in the tables of the specified project {offline|online} exists
899     * @throws CmsDataAccessException if something goes wrong
900     */
901    boolean validateStructureIdExists(CmsDbContext dbc, CmsUUID projectId, CmsUUID structureId)
902    throws CmsDataAccessException;
903
904    /**
905     * Writes the resource content with the specified resource id.<p>
906     *
907     * @param dbc the current database context
908     * @param resourceId the id of the resource used to identify the content to update
909     * @param content the new content of the file
910     *
911     * @throws CmsDataAccessException if something goes wrong
912     */
913    void writeContent(CmsDbContext dbc, CmsUUID resourceId, byte[] content) throws CmsDataAccessException;
914
915    /**
916     * Writes the "last-modified-in-project" ID of a resource.<p>
917     *
918     * @param dbc the current database context
919     * @param project the resource record is updated with the ID of this project
920     * @param projectId the project id to write into the resource
921     * @param resource the resource that gets updated
922     *
923     * @throws CmsDataAccessException if something goes wrong
924     */
925    void writeLastModifiedProjectId(CmsDbContext dbc, CmsProject project, CmsUUID projectId, CmsResource resource)
926    throws CmsDataAccessException;
927
928    /**
929     * Writes a property object to the database mapped to a specified resource.<p>
930     *
931     * @param dbc the current database context
932     * @param project the current project
933     * @param resource the resource where the property should be attached to
934     * @param property a CmsProperty object containing both the structure and resource value of the property
935     *
936     * @throws CmsDataAccessException if something goes wrong
937     */
938    void writePropertyObject(CmsDbContext dbc, CmsProject project, CmsResource resource, CmsProperty property)
939    throws CmsDataAccessException;
940
941    /**
942     * Writes a list of property objects to the database mapped to a specified resource.<p>
943     *
944     * @param dbc the current database context
945     * @param project the current project
946     * @param resource the resource where the property should be attached to
947     * @param properties a list of CmsProperty objects
948     *
949     * @throws CmsDataAccessException if something goes wrong
950     */
951    void writePropertyObjects(CmsDbContext dbc, CmsProject project, CmsResource resource, List<CmsProperty> properties)
952    throws CmsDataAccessException;
953
954    /**
955     * Writes the structure and/or resource record(s) of an existing file.<p>
956     *
957     * Common usages of this method are saving the resource information
958     * after creating, importing or restoring complete files
959     * where all file header attributes are changed. Both the structure and resource
960     * records get written. Thus, using this method affects all siblings of
961     * a resource! Use {@link #writeResourceState(CmsDbContext, CmsProject, CmsResource, int, boolean)}
962     * instead if you just want to update the file state, e.g. of a single sibling.<p>
963     *
964     * The file state is set to "changed", unless the current state is "new"
965     * or "deleted". The "changed" argument allows to choose whether the structure
966     * or resource state, or none of them, is set to "changed".<p>
967     *
968     * The rating of the file state values is as follows:<br>
969     * unchanged &lt; changed &lt; new &lt; deleted<p>
970     *
971     * Second, the "state" of the resource is the structure state, if the structure state
972     * has a higher file state value than the resource state. Otherwise the file state is
973     * the resource state.<p>
974     *
975     * @param dbc the current database context
976     * @param projectId the id of the current project
977     * @param resource the resource to be updated
978     * @param changed determines whether the structure or resource state, or none of them, is set to "changed"
979     *
980     * @throws CmsDataAccessException if something goes wrong
981     *
982     * @see org.opencms.db.CmsDriverManager#UPDATE_RESOURCE_STATE
983     * @see org.opencms.db.CmsDriverManager#UPDATE_STRUCTURE_STATE
984     * @see org.opencms.db.CmsDriverManager#NOTHING_CHANGED
985     * @see #writeResourceState(CmsDbContext, CmsProject, CmsResource, int, boolean)
986     */
987    void writeResource(CmsDbContext dbc, CmsUUID projectId, CmsResource resource, int changed)
988    throws CmsDataAccessException;
989
990    /**
991     * Writes file state in either the structure or resource record, or both of them.<p>
992     *
993     * This method allows to change the resource state to any state by setting the
994     * desired state value in the specified CmsResource instance.<p>
995     *
996     * This method is frequently used while resources are published to set the file state
997     * back to "unchanged".<p>
998     *
999     * Only file state attributes. get updated here. Use {@link #writeResource(CmsDbContext, CmsUUID, CmsResource, int)}
1000     * instead to write the complete file header.<p>
1001     *
1002     * Please refer to the javadoc of {@link #writeResource(CmsDbContext, CmsUUID, CmsResource, int)} to read
1003     * how setting resource state values affects the file state.<p>
1004     *
1005     * @param dbc the current database context
1006     * @param project the current project
1007     * @param resource the resource to be updated
1008     * @param changed determines whether the structure or resource state, or none of them, is set to "changed"
1009     * @param isPublishing if this method is called during publishing to version numbers are updated
1010     *
1011     * @throws CmsDataAccessException if something goes wrong
1012     *
1013     * @see org.opencms.db.CmsDriverManager#UPDATE_RESOURCE_STATE
1014     * @see org.opencms.db.CmsDriverManager#UPDATE_STRUCTURE_STATE
1015     * @see org.opencms.db.CmsDriverManager#UPDATE_ALL
1016     */
1017    void writeResourceState(
1018        CmsDbContext dbc,
1019        CmsProject project,
1020        CmsResource resource,
1021        int changed,
1022        boolean isPublishing) throws CmsDataAccessException;
1023
1024}