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, 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.file;
029
030import org.opencms.db.CmsResourceState;
031import org.opencms.util.CmsUUID;
032
033import java.util.Comparator;
034
035/**
036 * Common ancestor interface for {@link CmsFile} and {@link CmsFolder}
037 * as well as for {@link org.opencms.file.history.CmsHistoryFile} and {@link org.opencms.file.history.CmsHistoryFolder}.<p>
038 *
039 * @since 8.0.0
040 */
041public interface I_CmsResource {
042
043    /**
044     * Enumeration for all attributes of a resource.<p>
045     */
046    public enum CmsResourceAttribute {
047
048        /** The date of the last modification of the content of a resource. */
049        dateContent,
050
051        /** The date of the creation of a resource. */
052        dateCreated,
053
054        /** The expiration date a resource. */
055        dateExpired,
056
057        /** The date of the last modification of a resource. */
058        dateLastModified,
059
060        /** The release date of a resource. */
061        dateReleased,
062
063        /** The flags of a resource. */
064        flags,
065
066        /** The content length of a resource. */
067        length,
068
069        /** The file name of a resource without parent folders. */
070        name,
071
072        /** The id of the {@link CmsProject} where a resource has been last modified. */
073        projectLastModified,
074
075        /** The id of the database content record of a resource. */
076        resourceId,
077
078        /** The name of a resource with it's full path from the top level root folder. */
079        rootPath,
080
081        /** The number of siblings of a resource, also counting the resource. */
082        siblingCount,
083
084        /** The state of a resource. */
085        state,
086
087        /** The id of the database structure record of a resource. */
088        structureId,
089
090        /** The resource type id for a resource. */
091        typeId,
092
093        /** The id of the {@link CmsUser} who created a resource. */
094        userCreated,
095
096        /** The id of the user who made the last modification on a resource. */
097        userLastModified,
098
099        /** The current version number of a resource. */
100        version
101    }
102
103    /**
104     * A comparator for the date last modified of two resources.<p>
105     */
106    Comparator<I_CmsResource> COMPARE_DATE_LAST_MODIFIED = new Comparator<I_CmsResource>() {
107
108        /**
109         * @see java.util.Comparator#compare(java.lang.Object, java.lang.Object)
110         */
111        public int compare(I_CmsResource r1, I_CmsResource r2) {
112
113            if (r1 == r2) {
114                return 0;
115            }
116
117            long date1 = r1.getDateLastModified();
118            long date2 = r2.getDateLastModified();
119
120            return (date1 > date2) ? -1 : (date1 < date2) ? 1 : 0;
121        }
122    };
123
124    /**
125     * A comparator for the release date of two resources.<p>
126     *
127     * If the release date of a resource is not set, the
128     * creation date is used instead.<p>
129     */
130    Comparator<I_CmsResource> COMPARE_DATE_RELEASED = new Comparator<I_CmsResource>() {
131
132        /**
133         * @see java.util.Comparator#compare(java.lang.Object, java.lang.Object)
134         */
135        public int compare(I_CmsResource r1, I_CmsResource r2) {
136
137            if (r1 == r2) {
138                return 0;
139            }
140
141            long date1 = r1.getDateReleased();
142            if (date1 == CmsResource.DATE_RELEASED_DEFAULT) {
143                // use last modification date if release date is not set
144                date1 = r1.getDateLastModified();
145            }
146
147            long date2 = r2.getDateReleased();
148            if (date2 == CmsResource.DATE_RELEASED_DEFAULT) {
149                // use last modification date if release date is not set
150                date2 = r2.getDateLastModified();
151            }
152
153            return (date1 > date2) ? -1 : (date1 < date2) ? 1 : 0;
154        }
155    };
156
157    /**
158     * A comparator for the root path of two resources.<p>
159     */
160    Comparator<I_CmsResource> COMPARE_ROOT_PATH = new Comparator<I_CmsResource>() {
161
162        /**
163         * @see java.util.Comparator#compare(java.lang.Object, java.lang.Object)
164         */
165        public int compare(I_CmsResource r1, I_CmsResource r2) {
166
167            if (r1 == r2) {
168                return 0;
169            }
170            return r1.getRootPath().compareTo(r2.getRootPath());
171        }
172    };
173
174    /**
175     * A comparator for the root path of two resources ignoring case differences.<p>
176     */
177    Comparator<I_CmsResource> COMPARE_ROOT_PATH_IGNORE_CASE = new Comparator<I_CmsResource>() {
178
179        /**
180         * @see java.util.Comparator#compare(java.lang.Object, java.lang.Object)
181         */
182        public int compare(I_CmsResource r1, I_CmsResource r2) {
183
184            if (r1 == r2) {
185                return 0;
186            }
187            return r1.getRootPath().compareToIgnoreCase(r2.getRootPath());
188        }
189    };
190
191    /**
192     * A comparator for the root path of two resources ignoring case differences, putting folders before files.<p>
193     */
194    Comparator<I_CmsResource> COMPARE_ROOT_PATH_IGNORE_CASE_FOLDERS_FIRST = new Comparator<I_CmsResource>() {
195
196        /**
197         * @see java.util.Comparator#compare(java.lang.Object, java.lang.Object)
198         */
199        public int compare(I_CmsResource r1, I_CmsResource r2) {
200
201            if (r1 == r2) {
202                return 0;
203            }
204
205            if (r1.isFolder() && !r2.isFolder()) {
206                return -1;
207            } else if (r2.isFolder() && !r1.isFolder()) {
208                return 1;
209            }
210            // if same type, compare the name of the resource
211            return r1.getRootPath().compareToIgnoreCase(r2.getRootPath());
212        }
213    };
214
215    /**
216     * Returns the date of the last modification of the content of this resource.<p>
217     *
218     * @return the date of the last modification of the content of this resource
219     */
220    long getDateContent();
221
222    /**
223     * Returns the date of the creation of this resource.<p>
224     *
225     * @return the date of the creation of this resource
226     */
227    long getDateCreated();
228
229    /**
230     * Returns the expiration date this resource.<p>
231     *
232     * @return the expiration date of this resource
233     */
234    long getDateExpired();
235
236    /**
237     * Returns the date of the last modification of this resource.<p>
238     *
239     * @return the date of the last modification of this resource
240     */
241    long getDateLastModified();
242
243    /**
244     * Returns the release date this resource.<p>
245     *
246     * @return the release date of this resource
247     */
248    long getDateReleased();
249
250    /**
251     * Returns the flags of this resource.<p>
252     *
253     * @return the flags of this resource
254     */
255    int getFlags();
256
257    /**
258     * Returns the content length of this resource.<p>
259     *
260     * If the resource is a file, then this is the byte size of the file content.
261     * If the resource is a folder, then the size is always -1.<p>
262     *
263     * @return the content length of this resource
264     */
265    int getLength();
266
267    /**
268     * Returns the file name of this resource without parent folders, for example <code>index.html</code>.<p>
269     *
270     * @return the file name of this resource without parent folders
271     */
272    String getName();
273
274    /**
275     * Returns the id of the {@link CmsProject} where this resource has been last modified.<p>
276     *
277     * @return the id of the {@link CmsProject} where this resource has been last modified, or <code>null</code>
278     */
279    CmsUUID getProjectLastModified();
280
281    /**
282     * Returns the id of the database content record of this resource.<p>
283     *
284     * @return the id of the database content record of this resource
285     */
286    CmsUUID getResourceId();
287
288    /**
289     * Returns the name of this resource with it's full path from the top level root folder,
290     * for example <code>/sites/default/myfolder/index.html</code>.<p>
291     *
292     * @return name of this resource with it's full path from the top level root folder
293     */
294    String getRootPath();
295
296    /**
297     * Returns the number of siblings of this resource, also counting this resource.<p>
298     *
299     * If a resource has no sibling, the total sibling count for this resource is <code>1</code>,
300     * if a resource has <code>n</code> siblings, the sibling count is <code>n + 1</code>.<p>
301     *
302     * @return the number of siblings of this resource, also counting this resource
303     */
304    int getSiblingCount();
305
306    /**
307     * Returns the state of this resource.<p>
308     *
309     * @return the state of this resource
310     */
311    CmsResourceState getState();
312
313    /**
314     * Returns the id of the database structure record of this resource.<p>
315     *
316     * @return the id of the database structure record of this resource
317     */
318    CmsUUID getStructureId();
319
320    /**
321     * Returns the resource type id for this resource.<p>
322     *
323     * @return the resource type id of this resource
324     */
325    int getTypeId();
326
327    /**
328     * Returns the id of the {@link CmsUser} who created this resource.<p>
329     *
330     * @return the id of the {@link CmsUser} who created this resource
331     */
332    CmsUUID getUserCreated();
333
334    /**
335     * Returns the id of the {@link CmsUser} who made the last modification on this resource.<p>
336     *
337     * @return the id of the {@link CmsUser} who made the last modification on this resource<p>
338     */
339    CmsUUID getUserLastModified();
340
341    /**
342     * Returns the current version number of this resource.<p>
343     *
344     * @return the current version number of this resource
345     */
346    int getVersion();
347
348    /**
349     * Returns <code>true</code> if this resource is expired at the given time according to the
350     * information stored in {@link #getDateExpired()}.<p>
351     *
352     * @param time the time to check the expiration date against
353     *
354     * @return <code>true</code> if this resource is expired at the given time
355     *
356     * @see #isReleased(long)
357     * @see #isReleasedAndNotExpired(long)
358     */
359    boolean isExpired(long time);
360
361    /**
362     * Returns <code>true</code> if the resource is a file, i.e. can have no sub-resources.<p>
363     *
364     * @return true if this resource is a file, false otherwise
365     */
366    boolean isFile();
367
368    /**
369     * Returns <code>true</code> if the resource is a folder, i.e. can have sub-resources.<p>
370     *
371     * @return true if this resource is a folder, false otherwise
372     */
373    boolean isFolder();
374
375    /**
376     * Checks if the resource is internal.<p>
377     *
378     * This state is stored as bit 1 in the resource flags.<p>
379     *
380     * @return true if the resource is internal, otherwise false
381     */
382    boolean isInternal();
383
384    /**
385     * Checks if the link has to be labeled with a special icon in the explorer view.<p>
386     *
387     * This state is stored as bit 2 in the resource flags.<p>
388     *
389     * @return true if a link to the resource has to be labeled, otherwise false
390     */
391    boolean isLabeled();
392
393    /**
394     * Returns <code>true</code> if this resource is released at the given time according to the
395     * information stored in {@link #getDateReleased()}.<p>
396     *
397     * @param time the time to check the release date against
398     *
399     * @return <code>true</code> if this resource is released at the given time
400     *
401     * @see #isExpired(long)
402     * @see #isReleasedAndNotExpired(long)
403     */
404    boolean isReleased(long time);
405
406    /**
407     * Returns <code>true</code> if this resource is valid at the given time according to the
408     * information stored in {@link #getDateReleased()} and {@link #getDateExpired()}.<p>
409     *
410     * A resource is valid if it is released and not yet expired.<p>
411     *
412     * @param time the time to check the release and expiration date against
413     *
414     * @return <code>true</code> if this resource is valid at the given time
415     *
416     * @see #isExpired(long)
417     * @see #isReleased(long)
418     */
419    boolean isReleasedAndNotExpired(long time);
420
421    /**
422     * Returns true if this resource was touched.<p>
423     *
424     * @return boolean true if this resource was touched
425     */
426    boolean isTouched();
427}