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