org.opencms.loader
Class CmsImageScaler

java.lang.Object
  org.opencms.loader.CmsImageScaler

public class CmsImageScaler
extends java.lang.Object

Creates scaled images, acting as it's own parameter container.

Since:

6.2.0

Version:

$Revision: 1.17 $

Author:

Alexander Kandzior

Field Summary

static java.lang.String	COLOR_TRANSPARENT The name of the transparent color (for the background image).
static java.lang.String	FILTER_GRAYSCALE The name of the grayscale image filter.
static java.lang.String	FILTER_SHADOW The name of the shadow image filter.
static java.util.List	FILTERS The supported image filter names.
protected static org.apache.commons.logging.Log	LOG The log object for this class.
static java.lang.String	PARAM_SCALE The (optional) parameter used for sending the scale information of an image in the http request.
static int	SCALE_DEFAULT_MAX_BLUR_SIZE The default maximum image size (width * height) to apply image blurring when down scaling (setting this to high may case "out of memory" errors).
static int	SCALE_DEFAULT_MAX_SIZE The default maximum image size (width or height) to allow when up or down scaling an image using request parameters.
static java.lang.String	SCALE_PARAM_COLOR The scaler parameter to indicate the requested image background color (if required).
static java.lang.String	SCALE_PARAM_CROP_HEIGHT The scaler parameter to indicate crop height.
static java.lang.String	SCALE_PARAM_CROP_WIDTH The scaler parameter to indicate crop width.
static java.lang.String	SCALE_PARAM_CROP_X The scaler parameter to indicate crop X coordinate.
static java.lang.String	SCALE_PARAM_CROP_Y The scaler parameter to indicate crop Y coordinate.
static java.lang.String	SCALE_PARAM_FILTER The scaler parameter to indicate the requested image filter.
static java.lang.String	SCALE_PARAM_HEIGHT The scaler parameter to indicate the requested image height.
static java.lang.String	SCALE_PARAM_POS The scaler parameter to indicate the requested image position (if required).
static java.lang.String	SCALE_PARAM_QUALITY The scaler parameter to indicate to requested image save quality in percent (if applicable, for example used with JPEG images).
static java.lang.String	SCALE_PARAM_RENDERMODE The scaler parameter to indicate to requested RenderingHints settings.
static java.lang.String	SCALE_PARAM_TYPE The scaler parameter to indicate the requested scale type.
static java.lang.String	SCALE_PARAM_WIDTH The scaler parameter to indicate the requested image width.

Constructor Summary

	CmsImageScaler() Creates a new, empty image scaler object.
	CmsImageScaler(byte[] content, java.lang.String rootPath) Creates a new image scaler initialized with the height and width of the given image contained in the byte array.
	CmsImageScaler(CmsImageScaler original, CmsImageScaler target) Deprecated. use getReScaler(CmsImageScaler) on the original scaler instead
protected	CmsImageScaler(CmsImageScaler base, int width, int height) Creates a new image scaler based on the given base scaler and the given width and height.
	CmsImageScaler(CmsObject cms, CmsResource res) Creates a new image scaler by reading the property CmsPropertyDefinition.PROPERTY_IMAGE_SIZE from the given resource.
	CmsImageScaler(javax.servlet.http.HttpServletRequest request, int maxScaleSize, int maxBlurSize) Creates a new image scaler based on the given HTTP request.
	CmsImageScaler(java.lang.String parameters) Creates a new image scaler based on the given parameter String.

Method Summary

void	addFilter(java.lang.String filter) Adds a filter name to the list of filters that should be applied to the image.
java.lang.Object	clone()
java.awt.Color	getColor() Returns the color.
java.lang.String	getColorString() Returns the color as a String.
int	getCropHeigt() Returns the crop area height.
CmsImageScaler	getCropScaler(CmsImageScaler target) Returns a new image scaler that is a cropped rescaler from this cropped scaler size to the given target scaler size.
int	getCropWidth() Returns the crop area width.
int	getCropX() Returns the crop area X start coordinate.
int	getCropY() Returns the crop area Y start coordinate.
CmsImageScaler	getDownScaler(CmsImageScaler downScaler) Returns a new image scaler that is a down scale from the size of this scaler to the given scaler size.
java.util.List	getFilters() Returns the list of image filter names (Strings) to be applied to the image.
java.lang.String	getFiltersString() Returns the list of image filter names (Strings) to be applied to the image as a String.
int	getHeight() Returns the height.
java.lang.String	getImageType(java.lang.String filename) Returns the image type from the given file name based on the file suffix (extension) and the available image writers.
int	getMaxBlurSize() Returns the maximum image size (width * height) to apply image blurring when down scaling images.
int	getPixelCount() Returns the image pixel count, that is the image with multiplied by the image height.
int	getPosition() Returns the position.
int	getQuality() Returns the image saving quality in percent (0 - 100).
int	getRenderMode() Returns the image rendering mode constant.
CmsImageScaler	getReScaler(CmsImageScaler target) Returns a new image scaler that is a rescaler from this scaler size to the given target scaler size.
int	getType() Returns the type.
int	getWidth() Returns the width.
CmsImageScaler	getWidthScaler(CmsImageScaler downScaler) Returns a new image scaler that is a width based down scale from the size of this scaler to the given scaler size.
int	hashCode()
boolean	isCropping() Returns true if all required parameters for image cropping are available.
boolean	isDownScaleRequired(CmsImageScaler downScaler) Returns true if this image scaler must be down scaled when compared to the given "down scale" image scaler.
boolean	isValid() Returns true if all required parameters are available.
void	parseParameters(java.lang.String parameters) Parses the given parameters and sets the internal scaler variables accordingly.
byte[]	scaleImage(byte[] content, java.lang.String rootPath) Returns a scaled version of the given image byte content according this image scalers parameters.
byte[]	scaleImage(CmsFile file) Returns a scaled version of the given image file according this image scalers parameters.
void	setColor(java.awt.Color color) Sets the color.
void	setColor(java.lang.String value) Sets the color as a String.
void	setCropArea(int x, int y, int width, int height) Sets the image crop area.
void	setFilters(java.lang.String value) Sets the list of filters as a String.
void	setHeight(int height) Sets the height.
void	setMaxBlurSize(int maxBlurSize) Sets the maximum image size (width * height) to apply image blurring when downscaling images.
void	setPosition(int position) Sets the scale position.
void	setQuality(int quality) Sets the image saving quality in percent.
void	setRenderMode(int renderMode) Sets the image rendering mode constant.
void	setType(int type) Sets the scale type.
void	setWidth(int width) Sets the width.
java.lang.String	toRequestParam() Creates a request parameter configured with the values from this image scaler, also appends a '?'
java.lang.String	toString()

Methods inherited from class java.lang.Object

equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

COLOR_TRANSPARENT

public static final java.lang.String COLOR_TRANSPARENT

The name of the transparent color (for the background image).

See Also:

Constant Field Values

FILTER_GRAYSCALE

public static final java.lang.String FILTER_GRAYSCALE

The name of the grayscale image filter.

See Also:

Constant Field Values

FILTER_SHADOW

public static final java.lang.String FILTER_SHADOW

The name of the shadow image filter.

See Also:

Constant Field Values

FILTERS

public static final java.util.List FILTERS

The supported image filter names.

PARAM_SCALE

public static final java.lang.String PARAM_SCALE

The (optional) parameter used for sending the scale information of an image in the http request.

See Also:

Constant Field Values

SCALE_DEFAULT_MAX_BLUR_SIZE

public static final int SCALE_DEFAULT_MAX_BLUR_SIZE

The default maximum image size (width * height) to apply image blurring when down scaling (setting this to high may case "out of memory" errors).

See Also:

Constant Field Values

SCALE_DEFAULT_MAX_SIZE

public static final int SCALE_DEFAULT_MAX_SIZE

The default maximum image size (width or height) to allow when up or down scaling an image using request parameters.

See Also:

Constant Field Values

SCALE_PARAM_COLOR

public static final java.lang.String SCALE_PARAM_COLOR

The scaler parameter to indicate the requested image background color (if required).

See Also:

Constant Field Values

SCALE_PARAM_CROP_HEIGHT

public static final java.lang.String SCALE_PARAM_CROP_HEIGHT

The scaler parameter to indicate crop height.

See Also:

Constant Field Values

SCALE_PARAM_CROP_WIDTH

public static final java.lang.String SCALE_PARAM_CROP_WIDTH

The scaler parameter to indicate crop width.

See Also:

Constant Field Values

SCALE_PARAM_CROP_X

public static final java.lang.String SCALE_PARAM_CROP_X

The scaler parameter to indicate crop X coordinate.

See Also:

Constant Field Values

SCALE_PARAM_CROP_Y

public static final java.lang.String SCALE_PARAM_CROP_Y

The scaler parameter to indicate crop Y coordinate.

See Also:

Constant Field Values

SCALE_PARAM_FILTER

public static final java.lang.String SCALE_PARAM_FILTER

The scaler parameter to indicate the requested image filter.

See Also:

Constant Field Values

SCALE_PARAM_HEIGHT

public static final java.lang.String SCALE_PARAM_HEIGHT

The scaler parameter to indicate the requested image height.

See Also:

Constant Field Values

SCALE_PARAM_POS

public static final java.lang.String SCALE_PARAM_POS

The scaler parameter to indicate the requested image position (if required).

See Also:

Constant Field Values

SCALE_PARAM_QUALITY

public static final java.lang.String SCALE_PARAM_QUALITY

The scaler parameter to indicate to requested image save quality in percent (if applicable, for example used with JPEG images).

See Also:

Constant Field Values

SCALE_PARAM_RENDERMODE

public static final java.lang.String SCALE_PARAM_RENDERMODE

The scaler parameter to indicate to requested RenderingHints settings.

See Also:

Constant Field Values

SCALE_PARAM_TYPE

public static final java.lang.String SCALE_PARAM_TYPE

The scaler parameter to indicate the requested scale type.

See Also:

Constant Field Values

SCALE_PARAM_WIDTH

public static final java.lang.String SCALE_PARAM_WIDTH

The scaler parameter to indicate the requested image width.

See Also:

Constant Field Values

LOG

protected static final org.apache.commons.logging.Log LOG

The log object for this class.

Constructor Detail

CmsImageScaler

public CmsImageScaler()

Creates a new, empty image scaler object.

CmsImageScaler

public CmsImageScaler(byte[] content,
                      java.lang.String rootPath)

Creates a new image scaler initialized with the height and width of the given image contained in the byte array.

Please note:The image itself is not stored in the scaler, only the width and height dimensions of the image. To actually scale an image, you need to use scaleImage(CmsFile). This constructor is commonly used only to extract the image dimensions, for example when creating a String value for the CmsPropertyDefinition.PROPERTY_IMAGE_SIZE property.

In case the byte array can not be decoded to an image, or in case of other errors, isValid() will return false.

Parameters:

content - the image to calculate the dimensions for

rootPath - the root path of the resource (for error logging)

CmsImageScaler

public CmsImageScaler(CmsImageScaler original,
                      CmsImageScaler target)

Deprecated. use getReScaler(CmsImageScaler) on the original scaler instead

Creates a new image scaler that is a rescale from the original size to the given scaler.

Parameters:

original - the scaler that holds the original image dimensions

target - the image scaler to be used for rescaling this image scaler

CmsImageScaler

public CmsImageScaler(CmsObject cms,
                      CmsResource res)

Creates a new image scaler by reading the property CmsPropertyDefinition.PROPERTY_IMAGE_SIZE from the given resource.

In case of any errors reading or parsing the property, isValid() will return false.

Parameters:

cms - the OpenCms user context to use when reading the property

res - the resource to read the property from

CmsImageScaler

public CmsImageScaler(javax.servlet.http.HttpServletRequest request,
                      int maxScaleSize,
                      int maxBlurSize)

Creates a new image scaler based on the given HTTP request.

The maximum scale size is checked in order to prevent DOS attacks. Without this, it would be possible to request arbitrary huge images with a simple GET request, which would result in Out-Of-Memory errors if the image is just requested large enough.

The maximum blur size is checked since this operation is know to also cause memory issues with large images. If the original image is larger then this, no blur is applied before scaling down, which will result in a less optimal but still usable scale result.

Parameters:

request - the HTTP request to read the parameters from

maxScaleSize - the maximum scale size (width or height) for the image

maxBlurSize - the maximum size of the image (width * height) to apply blur

CmsImageScaler

public CmsImageScaler(java.lang.String parameters)

Creates a new image scaler based on the given parameter String.

Parameters:

parameters - the scale parameters to use

CmsImageScaler

protected CmsImageScaler(CmsImageScaler base,
                         int width,
                         int height)

Creates a new image scaler based on the given base scaler and the given width and height.

Parameters:

base - the base scaler to initialize the values with

width - the width to set for this scaler

height - the height to set for this scaler

Method Detail

addFilter

public void addFilter(java.lang.String filter)

Adds a filter name to the list of filters that should be applied to the image.

Parameters:

filter - the filter name to add

clone

public java.lang.Object clone()

Overrides:

clone in class java.lang.Object

See Also:

Object.clone()

getColor

public java.awt.Color getColor()

Returns the color.

Returns:

the color

getColorString

public java.lang.String getColorString()

Returns the color as a String.

Returns:

the color as a String

getCropHeigt

public int getCropHeigt()

Returns the crop area height.

Use setCropArea(int, int, int, int) to set this value.

Returns:

the crop area height

getCropScaler

public CmsImageScaler getCropScaler(CmsImageScaler target)

Returns a new image scaler that is a cropped rescaler from this cropped scaler size to the given target scaler size.

Parameters:

target - the image scaler that holds the target image dimensions

Returns:

a new image scaler that is a cropped rescaler from this cropped scaler size to the given target scaler size

See Also:

getReScaler(CmsImageScaler), setCropArea(int, int, int, int)

getCropWidth

public int getCropWidth()

Returns the crop area width.

Use setCropArea(int, int, int, int) to set this value.

Returns:

the crop area width

getCropX

public int getCropX()

Returns the crop area X start coordinate.

Use setCropArea(int, int, int, int) to set this value.

Returns:

the crop area X start coordinate

getCropY

public int getCropY()

Returns the crop area Y start coordinate.

Use setCropArea(int, int, int, int) to set this value.

Returns:

the crop area Y start coordinate

getDownScaler

public CmsImageScaler getDownScaler(CmsImageScaler downScaler)

Returns a new image scaler that is a down scale from the size of this scaler to the given scaler size.

If no down scale from this to the given scaler is required according to isDownScaleRequired(CmsImageScaler), then null is returned.

Parameters:

downScaler - the image scaler that holds the down scaled target image dimensions

Returns:

a new image scaler that is a down scale from the size of this scaler to the given target scaler size, or null

getFilters

public java.util.List getFilters()

Returns the list of image filter names (Strings) to be applied to the image.

Returns:

the list of image filter names (Strings) to be applied to the image

getFiltersString

public java.lang.String getFiltersString()

Returns the list of image filter names (Strings) to be applied to the image as a String.

Returns:

the list of image filter names (Strings) to be applied to the image as a String

getHeight

public int getHeight()

Returns the height.

Returns:

the height

getImageType

public java.lang.String getImageType(java.lang.String filename)

Returns the image type from the given file name based on the file suffix (extension) and the available image writers.

For example, for the file name "opencms.gif" the type is GIF, for "opencms.jpg" is is "JPEG" etc.

In case the input filename has no suffix, or there is no known image writer for the format defined by the suffix, null is returned.

Any non-null result can be used if an image type input value is required.

Parameters:

filename - the file name to get the type for

Returns:

the image type from the given file name based on the suffix and the available image writers, or null if no image writer is available for the format

getMaxBlurSize

public int getMaxBlurSize()

Returns the maximum image size (width * height) to apply image blurring when down scaling images.

Image blurring is required to achieve the best results for down scale operations when the target image size is 2 times or more smaller then the original image size. This parameter controls the maximum size (width * height) of an image that is blurred before it is down scaled. If the image is larger, no blurring is done. Image blurring is an expensive operation in both CPU usage and memory consumption. Setting the blur size to large may case "out of memory" errors.

Returns:

the maximum image size (width * height) to apply image blurring when down scaling images

getPixelCount

public int getPixelCount()

Returns the image pixel count, that is the image with multiplied by the image height.

If this scaler is not valid (see isValid()) the result is undefined.

Returns:

the image pixel count, that is the image with multiplied by the image height

getPosition

public int getPosition()

Returns the position.

Returns:

the position

getQuality

public int getQuality()

Returns the image saving quality in percent (0 - 100).

This is used only if applicable, for example when saving JPEG images.

Returns:

the image saving quality in percent

getRenderMode

public int getRenderMode()

Returns the image rendering mode constant.

Possible values are:

Simapi.RENDER_QUALITY (default)

Use best possible image processing - this may be slow sometimes.

Simapi.RENDER_SPEED

Fastest image processing but worse results - use this for thumbnails or where speed is more important then quality.

Simapi.RENDER_MEDIUM

Use default rendering hints from JVM - not recommended since it's almost as slow as the Simapi.RENDER_QUALITY mode.

Returns:

the image rendering mode constant

getReScaler

public CmsImageScaler getReScaler(CmsImageScaler target)

Returns a new image scaler that is a rescaler from this scaler size to the given target scaler size.

The height of the target image is calculated in proportion to the original image width. If the width of the the original image is not known, the target image width is calculated in proportion to the original image height.

Parameters:

target - the image scaler that holds the target image dimensions

Returns:

a new image scaler that is a rescaler from the this scaler size to the given target scaler size

getType

public int getType()

Returns the type.

Possible values are:

0 (default): Scale to exact target size with background padding

• enlarge image to fit in target size (if required)
• reduce image to fit in target size (if required)
• keep image aspect ratio / proportions intact
• fill up with bgcolor to reach exact target size
• fit full image inside target size (only applies if reduced)

1: Thumbnail generation mode (like 0 but no image enlargement)

• dont't enlarge image
• reduce image to fit in target size (if required)
• keep image aspect ratio / proportions intact
• fill up with bgcolor to reach exact target size
• fit full image inside target size (only applies if reduced)

2: Scale to exact target size, crop what does not fit

• enlarge image to fit in target size (if required)
• reduce image to fit in target size (if required)
• keep image aspect ratio / proportions intact
• fit full image inside target size (crop what does not fit)

3: Scale and keep image proportions, target size variable

• enlarge image to fit in target size (if required)
• reduce image to fit in target size (if required)
• keep image aspect ratio / proportions intact
• scaled image will not be padded or cropped, so target size is likely not the exact requested size

4: Don't keep image proportions, use exact target size

• enlarge image to fit in target size (if required)
• reduce image to fit in target size (if required)
• don't keep image aspect ratio / proportions intact
• the image will be scaled exactly to the given target size and likely will be loose proportions

Returns:

the type

getWidth

public int getWidth()

Returns the width.

Returns:

the width

getWidthScaler

public CmsImageScaler getWidthScaler(CmsImageScaler downScaler)

Returns a new image scaler that is a width based down scale from the size of this scaler to the given scaler size.

If no down scale from this to the given scaler is required because the width of this scaler is not larger than the target width, then the image dimensions of this scaler are unchanged in the result scaler. No up scaling is done!

Parameters:

downScaler - the image scaler that holds the down scaled target image dimensions

Returns:

a new image scaler that is a down scale from the size of this scaler to the given target scaler size

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

See Also:

Object.hashCode()

isCropping

public boolean isCropping()

Returns true if all required parameters for image cropping are available.

Required parameters are "cx","cy" (x, y start coordinate), and "ch","cw" (crop height and width).

Returns:

true if all required cropping parameters are available

isDownScaleRequired

public boolean isDownScaleRequired(CmsImageScaler downScaler)

Returns true if this image scaler must be down scaled when compared to the given "down scale" image scaler.

If either this scaler or the given downScaler is invalid according to isValid(), then false is returned.

The use case: this scaler represents an image (that is contains width and height of an image). The downScaler represents the maximum wanted image. The scalers are compared and if the image represented by this scaler is too large, true is returned. Image orientation is ignored, so for example an image with 600x800 pixel will NOT be down scaled if the target size is 800x600 but kept unchanged.

Parameters:

downScaler - the down scaler to compare this image scaler with

Returns:

true if this image scaler must be down scaled when compared to the given "down scale" image scaler

isValid

public boolean isValid()

Returns true if all required parameters are available.

Required parameters are "h" (height), and "w" (width).

Returns:

true if all required parameters are available

parseParameters

public void parseParameters(java.lang.String parameters)

Parses the given parameters and sets the internal scaler variables accordingly.

The parameter String must have a format like "h:100,w:200,t:1", that is a comma separated list of attributes followed by a colon ":", followed by a value. As possible attributes, use the constants from this class that start with SCALE_PARAM for example SCALE_PARAM_HEIGHT or SCALE_PARAM_WIDTH.

Parameters:

parameters - the parameters to parse

scaleImage

public byte[] scaleImage(byte[] content,
                         java.lang.String rootPath)

Returns a scaled version of the given image byte content according this image scalers parameters.

Parameters:

content - the image byte content to scale

rootPath - the root path of the image file in the VFS

Returns:

a scaled version of the given image byte content according to the provided scaler parameters

scaleImage

public byte[] scaleImage(CmsFile file)

Returns a scaled version of the given image file according this image scalers parameters.

Parameters:

file - the image file to scale

Returns:

a scaled version of the given image file according to the provided scaler parameters

setColor

public void setColor(java.awt.Color color)

Sets the color.

Parameters:

color - the color to set

setColor

public void setColor(java.lang.String value)

Sets the color as a String.

Parameters:

value - the color to set

setCropArea

public void setCropArea(int x,
                        int y,
                        int width,
                        int height)

Sets the image crop area.

Parameters:

x - the x coordinate for the crop

y - the y coordinate for the crop

width - the crop width

height - the crop height

setFilters

public void setFilters(java.lang.String value)

Sets the list of filters as a String.

Parameters:

value - the list of filters to set

setHeight

public void setHeight(int height)

Sets the height.

Parameters:

height - the height to set

setMaxBlurSize

public void setMaxBlurSize(int maxBlurSize)

Sets the maximum image size (width * height) to apply image blurring when downscaling images.

Parameters:

maxBlurSize - the maximum image blur size to set

See Also:

for a more detailed description about this parameter

setPosition

public void setPosition(int position)

Sets the scale position.

Parameters:

position - the position to set

setQuality

public void setQuality(int quality)

Sets the image saving quality in percent.

Parameters:

quality - the image saving quality (in percent) to set

setRenderMode

public void setRenderMode(int renderMode)

Sets the image rendering mode constant.

Parameters:

renderMode - the image rendering mode to set

See Also:

for a list of allowed values for the rendering mode

setType

public void setType(int type)

Sets the scale type.

Parameters:

type - the scale type to set

See Also:

for a detailed description of the possible values for the type

setWidth

public void setWidth(int width)

Sets the width.

Parameters:

width - the width to set

toRequestParam

public java.lang.String toRequestParam()

Creates a request parameter configured with the values from this image scaler, also appends a '?' char as a prefix so that this may be directly appended to an image URL.

This can be appended to an image request in order to apply image scaling parameters.

Returns:

a request parameter configured with the values from this image scaler

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

See Also:

Object.toString()