Source code

001/*
002 * This library is part of OpenCms -
003 * the Open Source Content Management System
004 *
005 * Copyright (c) Alkacon Software GmbH (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.loader;
029
030import org.opencms.cache.CmsVfsNameBasedDiskCache;
031import org.opencms.configuration.CmsParameterConfiguration;
032import org.opencms.file.CmsFile;
033import org.opencms.file.CmsObject;
034import org.opencms.file.CmsResource;
035import org.opencms.main.CmsEvent;
036import org.opencms.main.CmsException;
037import org.opencms.main.CmsLog;
038import org.opencms.main.I_CmsEventListener;
039import org.opencms.main.OpenCms;
040import org.opencms.scheduler.jobs.CmsImageCacheCleanupJob;
041import org.opencms.util.CmsStringUtil;
042
043import java.io.IOException;
044import java.util.Map;
045
046import javax.servlet.http.HttpServletRequest;
047import javax.servlet.http.HttpServletResponse;
048
049import org.apache.commons.logging.Log;
050
051/**
052 * Loader for images from the OpenCms VSF with integrated image scaling and processing capabilities.<p>
053 * 
054 * To scale or process an image, the parameter <code>{@link org.opencms.loader.CmsImageScaler#PARAM_SCALE}</code>
055 * has to be appended to the image URI. The value for the parameter needs to be composed from the <code>SCALE_PARAM</code>
056 * options provided by the constants in the <code>{@link org.opencms.file.types.CmsResourceTypeImage}</code> class.<p>
057 * 
058 * For example, to scale an image to exact 800x600 pixel with center fitting and a background color of grey, 
059 * the following parameter String can be used: <code>w:800,h:600,t:0,c:c0c0c0</code>.<p> 
060 * 
061 * @since 6.2.0 
062 */
063public class CmsImageLoader extends CmsDumpLoader implements I_CmsEventListener {
064
065    /** The configuration parameter for the OpenCms XML configuration to set the image down scale operation. */
066    public static final String CONFIGURATION_DOWNSCALE = "image.scaling.downscale";
067
068    /** The configuration parameter for the OpenCms XML configuration to set the image cache repository. */
069    public static final String CONFIGURATION_IMAGE_FOLDER = "image.folder";
070
071    /** The configuration parameter for the OpenCms XML configuration to set the maximum image blur size. */
072    public static final String CONFIGURATION_MAX_BLUR_SIZE = "image.scaling.maxblursize";
073
074    /** The configuration parameter for the OpenCms XML configuration to set the maximum image scale size. */
075    public static final String CONFIGURATION_MAX_SCALE_SIZE = "image.scaling.maxsize";
076
077    /** The configuration parameter for the OpenCms XML configuration to enable the image scaling. */
078    public static final String CONFIGURATION_SCALING_ENABLED = "image.scaling.enabled";
079
080    /** Default name for the image cache repository. */
081    public static final String IMAGE_REPOSITORY_DEFAULT = "/WEB-INF/imagecache/";
082
083    /** Clear event parameter. */
084    public static final String PARAM_CLEAR_IMAGES_CACHE = "_IMAGES_CACHE_";
085
086    /** The id of this loader. */
087    public static final int RESOURCE_LOADER_ID_IMAGE_LOADER = 2;
088
089    /** The log object for this class. */
090    protected static final Log LOG = CmsLog.getLog(CmsImageLoader.class);
091
092    /** The (optional) image down scale parameters for image write operations. */
093    protected static String m_downScaleParams;
094
095    /** Indicates if image scaling is active. */
096    protected static boolean m_enabled;
097
098    /** The maximum image size (width * height) to apply image blurring when down scaling (setting this to high may cause "out of memory" errors). */
099    protected static int m_maxBlurSize = CmsImageScaler.SCALE_DEFAULT_MAX_BLUR_SIZE;
100
101    /** The disk cache to use for saving scaled image versions. */
102    protected static CmsVfsNameBasedDiskCache m_vfsDiskCache;
103
104    /** The name of the configured image cache repository. */
105    protected String m_imageRepositoryFolder;
106
107    /** The maximum image size (width or height) to allow when up scaling an image using request parameters. */
108    protected int m_maxScaleSize = CmsImageScaler.SCALE_DEFAULT_MAX_SIZE;
109
110    /**
111     * Creates a new image loader.<p>
112     */
113    public CmsImageLoader() {
114
115        super();
116    }
117
118    /**
119     * Returns the image down scale parameters, 
120     * which is set with the {@link #CONFIGURATION_DOWNSCALE} configuration option.<p> 
121     * 
122     * If no down scale parameters have been set in the configuration, this will return <code>null</code>.
123     * 
124     * @return the image down scale parameters
125     */
126    public static String getDownScaleParams() {
127
128        return m_downScaleParams;
129    }
130
131    /**
132     * Returns the path of the image cache repository folder in the RFS,
133     * which is set with the {@link #CONFIGURATION_IMAGE_FOLDER} configuration option.<p> 
134     * 
135     * @return the path of the image cache repository folder in the RFS
136     */
137    public static String getImageRepositoryPath() {
138
139        return m_vfsDiskCache.getRepositoryPath();
140    }
141
142    /**
143     * The maximum blur size for image re-scale operations, 
144     * which is set with the {@link #CONFIGURATION_MAX_BLUR_SIZE} configuration option.<p>
145     * 
146     * The default is 2500 * 2500 pixel.<p>
147     * 
148     * @return the maximum blur size for image re-scale operations
149     */
150    public static int getMaxBlurSize() {
151
152        return m_maxBlurSize;
153    }
154
155    /**
156     * Returns <code>true</code> if the image scaling and processing capabilities for the 
157     * OpenCms VFS images have been enabled, <code>false</code> if not.<p>
158     * 
159     * Image scaling is enabled by setting the loader parameter <code>image.scaling.enabled</code>
160     * to the value <code>true</code> in the configuration file <code>opencms-vfs.xml</code>.<p>
161     * 
162     * Enabling image processing in OpenCms may require several additional configuration steps
163     * on the server running OpenCms, especially in UNIX systems. Here it is often required to have an X window server
164     * configured and accessible so that the required Java ImageIO operations work.
165     * Therefore the image scaling capabilities in OpenCms are disabled by default.<p>
166     * 
167     * @return <code>true</code> if the image scaling and processing capabilities for the 
168     *      OpenCms VFS images have been enabled
169     */
170    public static boolean isEnabled() {
171
172        return m_enabled;
173    }
174
175    /**
176     * @see org.opencms.configuration.I_CmsConfigurationParameterHandler#addConfigurationParameter(java.lang.String, java.lang.String)
177     */
178    @Override
179    public void addConfigurationParameter(String paramName, String paramValue) {
180
181        if (CmsStringUtil.isNotEmpty(paramName) && CmsStringUtil.isNotEmpty(paramValue)) {
182            if (CONFIGURATION_SCALING_ENABLED.equals(paramName)) {
183                m_enabled = Boolean.valueOf(paramValue).booleanValue();
184            }
185            if (CONFIGURATION_IMAGE_FOLDER.equals(paramName)) {
186                m_imageRepositoryFolder = paramValue.trim();
187            }
188            if (CONFIGURATION_MAX_SCALE_SIZE.equals(paramName)) {
189                m_maxScaleSize = CmsStringUtil.getIntValue(paramValue, CmsImageScaler.SCALE_DEFAULT_MAX_SIZE, paramName);
190            }
191            if (CONFIGURATION_MAX_BLUR_SIZE.equals(paramName)) {
192                m_maxBlurSize = CmsStringUtil.getIntValue(
193                    paramValue,
194                    CmsImageScaler.SCALE_DEFAULT_MAX_BLUR_SIZE,
195                    paramName);
196            }
197            if (CONFIGURATION_DOWNSCALE.equals(paramName)) {
198                m_downScaleParams = paramValue.trim();
199            }
200        }
201        super.addConfigurationParameter(paramName, paramValue);
202    }
203
204    /**
205     * @see org.opencms.main.I_CmsEventListener#cmsEvent(org.opencms.main.CmsEvent)
206     */
207    public void cmsEvent(CmsEvent event) {
208
209        if (event == null) {
210            return;
211        }
212        // only react on the clear caches event
213        int type = event.getType();
214        if (type != I_CmsEventListener.EVENT_CLEAR_CACHES) {
215            return;
216        }
217        // only react if the clear images cache parameter is set
218        Map<String, ?> data = event.getData();
219        if (data == null) {
220            return;
221        }
222        Object param = data.get(PARAM_CLEAR_IMAGES_CACHE);
223        if (param == null) {
224            return;
225        }
226        float age = -1;
227        if (param instanceof String) {
228            age = Float.valueOf((String)param).floatValue();
229        } else if (param instanceof Number) {
230            age = ((Number)param).floatValue();
231        }
232        CmsImageCacheCleanupJob.cleanImageCache(age);
233    }
234
235    /**
236     * @see org.opencms.loader.I_CmsResourceLoader#destroy()
237     */
238    @Override
239    public void destroy() {
240
241        m_enabled = false;
242        m_imageRepositoryFolder = null;
243        m_vfsDiskCache = null;
244    }
245
246    /**
247     * @see org.opencms.configuration.I_CmsConfigurationParameterHandler#getConfiguration()
248     */
249    @Override
250    public CmsParameterConfiguration getConfiguration() {
251
252        CmsParameterConfiguration result = new CmsParameterConfiguration();
253        CmsParameterConfiguration config = super.getConfiguration();
254        if (config != null) {
255            result.putAll(config);
256        }
257        result.put(CONFIGURATION_SCALING_ENABLED, String.valueOf(m_enabled));
258        result.put(CONFIGURATION_IMAGE_FOLDER, m_imageRepositoryFolder);
259        return result;
260    }
261
262    /**
263     * @see org.opencms.loader.I_CmsResourceLoader#getLoaderId()
264     */
265    @Override
266    public int getLoaderId() {
267
268        return RESOURCE_LOADER_ID_IMAGE_LOADER;
269    }
270
271    /**
272     * @see org.opencms.configuration.I_CmsConfigurationParameterHandler#initConfiguration()
273     */
274    @Override
275    public void initConfiguration() {
276
277        if (CmsStringUtil.isEmpty(m_imageRepositoryFolder)) {
278            m_imageRepositoryFolder = IMAGE_REPOSITORY_DEFAULT;
279        }
280        // initialize the image cache
281        if (m_vfsDiskCache == null) {
282            m_vfsDiskCache = new CmsVfsNameBasedDiskCache(
283                OpenCms.getSystemInfo().getWebApplicationRfsPath(),
284                m_imageRepositoryFolder);
285        }
286        OpenCms.addCmsEventListener(this);
287        // output setup information
288        if (CmsLog.INIT.isInfoEnabled()) {
289            CmsLog.INIT.info(Messages.get().getBundle().key(
290                Messages.INIT_IMAGE_REPOSITORY_PATH_1,
291                m_vfsDiskCache.getRepositoryPath()));
292            CmsLog.INIT.info(Messages.get().getBundle().key(
293                Messages.INIT_IMAGE_SCALING_ENABLED_1,
294                Boolean.valueOf(m_enabled)));
295        }
296    }
297
298    /**
299     * @see org.opencms.loader.I_CmsResourceLoader#load(org.opencms.file.CmsObject, org.opencms.file.CmsResource, javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)
300     */
301    @Override
302    public void load(CmsObject cms, CmsResource resource, HttpServletRequest req, HttpServletResponse res)
303    throws IOException, CmsException {
304
305        if (m_enabled) {
306            if (canSendLastModifiedHeader(resource, req, res)) {
307                // no image processing required at all
308                return;
309            }
310            // get the scale information from the request
311            CmsImageScaler scaler = new CmsImageScaler(req, m_maxScaleSize, m_maxBlurSize);
312            // load the file from the cache
313            CmsFile file = getScaledImage(cms, resource, scaler);
314            // now perform standard load operation inherited from dump loader
315            super.load(cms, file, req, res);
316        } else {
317            // scaling is disabled
318            super.load(cms, resource, req, res);
319        }
320    }
321
322    /**
323     * Returns a scaled version of the given OpenCms VFS image resource.<p>
324     * 
325     * All results are cached in disk.
326     * If the scaled version does not exist in the cache, it is created. 
327     * Unscaled versions of the images are also stored in the cache.<p>
328     * 
329     * @param cms the current users OpenCms context
330     * @param resource the base VFS resource for the image
331     * @param scaler the configured image scaler
332     * 
333     * @return a scaled version of the given OpenCms VFS image resource
334     * 
335     * @throws IOException in case of errors accessing the disk based cache
336     * @throws CmsException in case of errors accessing the OpenCms VFS
337     */
338    protected CmsFile getScaledImage(CmsObject cms, CmsResource resource, CmsImageScaler scaler)
339    throws IOException, CmsException {
340
341        String cacheParam = scaler.isValid() ? scaler.toString() : null;
342        String cacheName = m_vfsDiskCache.getCacheName(resource, cacheParam);
343        byte[] content = m_vfsDiskCache.getCacheContent(cacheName);
344
345        CmsFile file;
346        if (content != null) {
347            if (resource instanceof CmsFile) {
348                // the original file content must be modified (required e.g. for static export)
349                file = (CmsFile)resource;
350            } else {
351                // this is no file, but we don't want to use "upgrade" since we don't need to read the content from the VFS
352                file = new CmsFile(resource);
353            }
354            // save the content in the file
355            file.setContents(content);
356        } else {
357            // we must read the content from the VFS (if this has not been done yet)
358            file = cms.readFile(resource);
359            // upgrade the file (load the content)
360            if (scaler.isValid()) {
361                // valid scaling parameters found, scale the content
362                content = scaler.scaleImage(file);
363                // exchange the content of the file with the scaled version
364                file.setContents(content);
365            }
366            // save the file content in the cache
367            m_vfsDiskCache.saveCacheFile(cacheName, file.getContents());
368        }
369        return file;
370    }
371}