org.opencms.loader
Class CmsImageScaler

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

public class CmsImageScaler
extends Object

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

Since:

6.2.0

Version:

$Revision: 1.2 $

Author:

Alexander Kandzior

Field Summary

static String	COLOR_TRANSPARENT The name of the transparent color (for the backgound image).
static String	FILTER_GRAYSCALE The name of the grayscale image filter.
static String	FILTER_SHADOW The name of the shadow image filter.
static List	FILTERS The supported image filter names.
protected static Log	LOG The log object for this class.
static 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 downscaling (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 updowscaling an image using request parameters.
static String	SCALE_PARAM_COLOR The scaler parameter to indicate the requested image background color (if required).
static String	SCALE_PARAM_FILTER The scaler parameter to indicate the requested image filter.
static String	SCALE_PARAM_HEIGHT The scaler parameter to indicate the requested image height.
static String	SCALE_PARAM_POS The scaler parameter to indicate the requested image position (if required).
static 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 String	SCALE_PARAM_RENDERMODE The scaler parameter to indicate to requested RenderingHints settings.
static String	SCALE_PARAM_TYPE The scaler parameter to indicate the requested scale type.
static 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, String rootPath)
Creates a new image scaler for the given image contained in the byte array.

CmsImageScaler(CmsImageScaler original, CmsImageScaler scaler)
Creates a new image scaler that is a recale from the original size to the given scaler.

CmsImageScaler(CmsObject cms, CmsResource res)
Creates a new image scaler by reading the property CmsPropertyDefinition.PROPERTY_IMAGE_SIZE from the given resource.

CmsImageScaler(HttpServletRequest request, int maxScaleSize, int maxBlurSize)
Creates a new image scaler based on the given http request.

CmsImageScaler(String parameters)
Creates a new image scaler based on the given parameter String.

Method Summary

void	addFilter(String filter) Adds a filter name to the list of filters that should be applied to the image.
Object	clone()
Color	getColor() Returns the color.
String	getColorString() Returns the color as a String.
List	getFilters() Returns the list of image filter names (Strings) to be applied to the image.
String	getFiltersString() Returns the list of image filter names (Strings) to be applied to the image as a String.
int	getHeight() Returns the height.
String	getImageType(String filename) Returns the image type from the given file name based on the file suffix (extension) and the available image writers.
int	getPosition() Returns the position.
int	getQuality() Returns the image saving quality in percent (0 - 100).
int	getRenderMode() Returns the image rendering mode constant.
int	getType() Returns the type.
int	getWidth() Returns the width.
int	hashCode()
boolean	isValid() Returns true if all required parameters are available.
byte[]	scaleImage(CmsFile file) Returns a scaled version of the given image file according this image scalers parameters.
void	setColor(Color color) Sets the color.
void	setColor(String value) Sets the color as a String.
void	setFilters(String value) Sets the list of filters as a String.
void	setHeight(int height) Sets the height.
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.
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 direclty appended to an image URL.
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

COLOR_TRANSPARENT

public static final String COLOR_TRANSPARENT

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

See Also:

Constant Field Values

FILTER_GRAYSCALE

public static final String FILTER_GRAYSCALE

The name of the grayscale image filter.

See Also:

Constant Field Values

FILTER_SHADOW

public static final String FILTER_SHADOW

The name of the shadow image filter.

See Also:

Constant Field Values

FILTERS

public static final List FILTERS

The supported image filter names.

PARAM_SCALE

public static final 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 downscaling (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 updowscaling an image using request parameters.

See Also:

Constant Field Values

SCALE_PARAM_COLOR

public static final String SCALE_PARAM_COLOR

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

See Also:

Constant Field Values

SCALE_PARAM_FILTER

public static final String SCALE_PARAM_FILTER

The scaler parameter to indicate the requested image filter.

See Also:

Constant Field Values

SCALE_PARAM_HEIGHT

public static final String SCALE_PARAM_HEIGHT

The scaler parameter to indicate the requested image height.

See Also:

Constant Field Values

SCALE_PARAM_POS

public static final 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 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 String SCALE_PARAM_RENDERMODE

The scaler parameter to indicate to requested RenderingHints settings.

See Also:

Constant Field Values

SCALE_PARAM_TYPE

public static final String SCALE_PARAM_TYPE

The scaler parameter to indicate the requested scale type.

See Also:

Constant Field Values

SCALE_PARAM_WIDTH

public static final String SCALE_PARAM_WIDTH

The scaler parameter to indicate the requested image width.

See Also:

Constant Field Values

LOG

protected static final 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,
                      String rootPath)

Creates a new image scaler for 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 scaler)

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

Parameters:

original - the scaler that holds the original image dimensions

scaler - 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(HttpServletRequest request,
                      int maxScaleSize,
                      int maxBlurSize)

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

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 (may cause "out of memory" for large images)

CmsImageScaler

public CmsImageScaler(String parameters)

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

Parameters:

parameters - the scale parameters to use

Method Detail

addFilter

public void addFilter(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 Object clone()

Overrides:

clone in class Object

See Also:

Object.clone()

getColor

public Color getColor()

Returns the color.

Returns:

the color

getColorString

public String getColorString()

Returns the color as a String.

Returns:

the color as a String

getFilters

public 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 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 String getImageType(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

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 oly 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

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 / propotions 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 / propotions 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 / propotions intact
• fit full image inside target size (crop what does not fit)

3: Scale and keep image propotions, 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 / propotions intact
• scaled image will not be padded or cropped, so target size is likley not the exact requested size

4: Don't keep image propotions, 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 / propotions intact
• the image will be scaled exactly to the given target size and likley will be loose proportions

Returns:

the type

getWidth

public int getWidth()

Returns the width.

Returns:

the width

hashCode

public int hashCode()

Overrides:

hashCode in class Object

See Also:

Object.hashCode()

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

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(Color color)

Sets the color.

Parameters:

color - the color to set

setColor

public void setColor(String value)

Sets the color as a String.

Parameters:

value - the color to set

setFilters

public void setFilters(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

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 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 direclty 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 String toString()

Overrides:

toString in class Object

See Also:

Object.toString()