001    /**
002     * Copyright (c) 2000-present Liferay, Inc. All rights reserved.
003     *
004     * This library is free software; you can redistribute it and/or modify it under
005     * the terms of the GNU Lesser General Public License as published by the Free
006     * Software Foundation; either version 2.1 of the License, or (at your option)
007     * any later version.
008     *
009     * This library is distributed in the hope that it will be useful, but WITHOUT
010     * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
011     * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
012     * details.
013     */
014    
015    package com.liferay.portlet.documentlibrary.util;
016    
017    import com.liferay.portal.kernel.repository.model.FileEntry;
018    import com.liferay.portal.kernel.repository.model.FileVersion;
019    import com.liferay.portal.kernel.xml.Element;
020    import com.liferay.portlet.exportimport.lar.PortletDataContext;
021    
022    /**
023     * Provides a common interface for all the processors of the document library.
024     * All document library processors must implement this interface.
025     *
026     * A DLProcessor (processor) is responsible for extracting additional metadata
027     * or assets from
028     * a Documents and Media file entry. Here are a couple examples of such metadata
029     * and assets:
030     *
031     * <ul>
032     * <li>
033     * Metadata stored in JPEG images or video files.
034     * </li>
035     * <li>
036     * Images to use as previews for PDF or Word documents.
037     * </li>
038     * </ul>
039     *
040     * Processors can be defined as OSGi components. To do that, annotate your
041     * processor and register it under the type <code>DLProcessor</code>:
042     * <pre>
043     * {@literal @}Component(service = DLProcessor.class)
044     * public class MyDLProcessor implements DLProcessor {
045     *
046     * }
047     * </pre>
048     * Implementing classes are responsible for managing any storage required by the
049     * generated resources and for providing access to any generated assets. See
050     * current implementations for examples.
051     *
052     * @author Alexander Chow
053     * @author Mika Koivisto
054     * @see    AudioProcessor
055     * @see    DLPreviewableProcessor
056     * @see    ImageProcessor
057     * @see    PDFProcessor
058     * @see    RawMetadataProcessor
059     * @see    VideoProcessor
060     */
061    public interface DLProcessor {
062    
063            public void afterPropertiesSet() throws Exception;
064    
065            /**
066             * Cleans up any resources that the processor created for the file entry.
067             * Note that all resources for all file versions of this file entry are
068             * permanently deleted.
069             *
070             * @param fileEntry the file entry for which resources are cleaned up
071             */
072            public void cleanUp(FileEntry fileEntry);
073    
074            /**
075             * Cleans up any resources that the processor created for the given file
076             * version. Note that other resources associated with other file versions
077             * for the same file entry aren't affected; use {@link #cleanUp(FileEntry)}
078             * if you want to clean up everything.
079             *
080             * @param fileVersion the file version for which resources will be cleaned
081             *        up
082             */
083            public void cleanUp(FileVersion fileVersion);
084    
085            /**
086             * Copies all resources generated for the source file version, reusing them
087             * for destination file version. Note that resources are literally copied,
088             * making the resulting resources independent (i.e., if afterwards the
089             * source file version is deleted, the destination file version resources
090             * aren't affected).
091             *
092             * @param sourceFileVersion the file version to copy resources from
093             * @param destinationFileVersion the file version to copy resources to
094             */
095            public void copy(
096                    FileVersion sourceFileVersion, FileVersion destinationFileVersion);
097    
098            /**
099             * Exports any resources generated for the file entry into file entry
100             * element.
101             *
102             * @param  portletDataContext the portlet data context to use during this
103             *         export operation
104             * @param  fileEntry the file entry for which resources are exported
105             * @param  fileEntryElement the file entry element to save resources into
106             * @throws Exception if an error occurred while exporting the file entry
107             *         resources
108             */
109            public void exportGeneratedFiles(
110                            PortletDataContext portletDataContext, FileEntry fileEntry,
111                            Element fileEntryElement)
112                    throws Exception;
113    
114            /**
115             * Returns the processor's type. See {@link
116             * com.liferay.portlet.documentlibrary.model.DLProcessorConstants} for the
117             * set of predefined processor types.
118             *
119             * @return the type of this processor
120             */
121            public String getType();
122    
123            /**
124             * Imports any existing resources from the file entry or file entry element.
125             * If the portlet data context supports direct binary import (see {@link
126             * PortletDataContext#isPerformDirectBinaryImport()}), the resources are
127             * directly copied from the file entry; otherwise, they're extracted from
128             * the file entry element.
129             *
130             * @param  portletDataContext the portlet data context to use during this
131             *         import operation
132             * @param  fileEntry the file entry to import resources from, if direct
133             *         binary import is supported
134             * @param  importedFileEntry the file entry for which resources are imported
135             * @param  fileEntryElement the file entry element to import resources from,
136             *         if direct binary import is not supported
137             * @throws Exception if an error occurred while importing the file entry
138             *         resources
139             */
140            public void importGeneratedFiles(
141                            PortletDataContext portletDataContext, FileEntry fileEntry,
142                            FileEntry importedFileEntry, Element fileEntryElement)
143                    throws Exception;
144    
145            /**
146             * Returns <code>true</code> if the file version is supported by this
147             * processor.
148             *
149             * @param  fileVersion the file version
150             * @return <code>true</code> if this processor supports the file version;
151             *         <code>false</code> otherwise
152             */
153            public boolean isSupported(FileVersion fileVersion);
154    
155            /**
156             * Returns <code>true</code> if the given file MIME type is supported by
157             * this processor.
158             *
159             * @param  mimeType the MIME type
160             * @return <code>true</code> if this processor supports the MIME type;
161             *         <code>false</code> otherwise
162             */
163            public boolean isSupported(String mimeType);
164    
165            /**
166             * Launches the processor's work with respect to the destination file
167             * version.
168             *
169             * @param sourceFileVersion the file version to copy previews and thumbnails
170             *        from (optionally <code>null</code>)
171             * @param destinationFileVersion the latest file version to process
172             */
173            public void trigger(
174                    FileVersion sourceFileVersion, FileVersion destinationFileVersion);
175    
176    }