senselogic.sitevision.api.webresource

Interface ImageUtil

@Requireable(value="ImageUtil")
public interface ImageUtil

Image utility interface that handles nodes with primary node type sv:image.

Note! This interface is used to create images. You would typically use StructureUtil to move an image and TrashcanUtil to delete an image. To render images, you would typically use ImageRenderer or ImageLinkRenderer.

An instance of the Sitevision class implementing this interface can be obtained via Utils.getImageUtil(). See Utils for how to obtain an instance of the Utils interface.

Since:

Sitevision 2.6.2

Author:

Mikael Wikblom

Method Summary

Modifier and Type	Method and Description
Node	createImage(Node aParent, String aFileName, String aUri) Creates an image using a uri string.
Node	createImageFromBase64(Node aParent, String aFileName, String aBase64EncodedString) Creates an image using a base64 string.
Node	createImageFromTemporary(Node aParent, Node aTemporaryFile) Creates an image using a sv:temporaryFile.
void	createImages(Node aParent, Map<String,String> aImages) Adds several images to a sv:localImageRepository, sv:imageRepository, sv:personalImageRepository or a sv:folder residing as sub node to an image repository.
void	renameImage(Node aImage, String aName) Alters the name of an image.
void	setAltText(Node aImage, String aAltText) Sets the alt property for an image Node.
void	setCaptionText(Node aImage, String aCaptionText) Sets the caption property for an image Node.
String	toBase64(Node aImage) The Base64 String representation of an image Node.
void	updateBinaryContent(Node aImage, String aUri) Updates the binary content of an existing image using a uri string.
void	updateBinaryContentFromBase64(Node aImage, String aBase64EncodedString) Updates the binary content of an existing image using a base64 string.
void	updateBinaryContentFromTemporary(Node aImage, Node aTemporaryFile) Updates the binary content of an existing image using a sv:temporaryFile.

Method Detail

createImages

void createImages(Node aParent,
                  Map<String,String> aImages)
           throws ConstraintViolationException,
                  RepositoryException

Adds several images to a sv:localImageRepository, sv:imageRepository, sv:personalImageRepository or a sv:folder residing as sub node to an image repository. If an other parent node is specified a ConstraintViolationException is thrown. The images map keys correspond to the file names (will correspond to the property fileName of the sv:image nodes) and the values to URIs pointing to the file resources.

Note that the images must have an image mime-type to be created.

URI note! The resource must be accessible from the Sitevision server! Sitevision opens a stream to an URL with the aUri value when creating the binary content of the image. If a firewall or such blocks outgoing communication from the server - image creation will fail.

Permission note! Current user (the invoker of this method) must have WRITE permission on the parent node (see PermissionUtil.Permission.WRITE) or a ConstraintViolationException is thrown. Creating an image for a sv:userIdentity requires PermissionUtil.Permission.MANAGE_USER_IDENTITIES on current page.

Parameters:

aParent - the parent node for the images. May not be null

aImages - a map of file name to URI pairs May not be null

Throws:

ConstraintViolationException - if the user is not authorized to alter the parent node, if an invalid parent node is specified or if image exceeds file size limit

RepositoryException - if something else goes wrong

createImage

Node createImage(Node aParent,
                 String aFileName,
                 String aUri)
          throws ConstraintViolationException,
                 RepositoryException

Creates an image using a uri string.

Note that the aParent of the file must be a sv:localImageRepository, sv:imageRepository, sv:personalImageRepository or a sv:folder residing as sub node to an image repository.

The file must have an image mime-type or an IllegalArgumentException is thrown.

URI note! The resource must be accessible from the Sitevision server! Sitevision opens a stream to an URL with the aUri value when creating the binary content of the image. If a firewall or such blocks outgoing communication from the server - image creation will fail.

Permission note! Current user (the invoker of this method) must have WRITE permission on the parent node (see PermissionUtil.Permission.WRITE) or a ConstraintViolationException is thrown. Creating an image for a sv:userIdentity requires PermissionUtil.Permission.MANAGE_USER_IDENTITIES on current page.

Parameters:

aParent - the parent node of the image. May not be null

aFileName - the fileName property of the sv:image. May not be null

aUri - the URI pointing to the file resource. May not be null

Returns:

a sv:image node corresponding to the newly created image. Will never return null

Throws:

ConstraintViolationException - if the user is not authorized to alter the parent node, if an invalid parent node is specified or if image exceeds file size limit

RepositoryException - if something else goes wrong

createImageFromBase64

Node createImageFromBase64(Node aParent,
                           String aFileName,
                           String aBase64EncodedString)
                    throws ConstraintViolationException,
                           RepositoryException

Creates an image using a base64 string.

The base64 decoder uses "The Base64 Alphabet" as specified in Table 1 of RFC 4648 and RFC 2045 for decoding operation. The decoder rejects data that contains characters outside the base64 alphabet.

Note that the aParent of the file must be a sv:localImageRepository, sv:imageRepository, sv:personalImageRepository or a sv:folder residing as sub node to an image repository.

The file name must correspond to an image mime-type or an IllegalArgumentException is thrown.

Permission note! Current user (the invoker of this method) must have WRITE permission on the parent node (see PermissionUtil.Permission.WRITE) or a ConstraintViolationException is thrown. Creating an image for a sv:userIdentity requires PermissionUtil.Permission.MANAGE_USER_IDENTITIES on current page.

Parameters:

aParent - the parent node of the image. May not be null

aFileName - the fileName property of the sv:image. May not be null

aBase64EncodedString - a base64 encoded string. May not be null

Returns:

a sv:image node corresponding to the newly created image. Will never return null

Throws:

ConstraintViolationException - if the user is not authorized to alter the parent node, if an invalid parent node is specified, if aBase64EncodedString is not base64 encoded or if image exceeds file size limit

RepositoryException - if something else goes wrong

Since:

Sitevision 4.5.4

createImageFromTemporary

Node createImageFromTemporary(Node aParent,
                              Node aTemporaryFile)
                       throws ConstraintViolationException,
                              RepositoryException

Creates an image using a sv:temporaryFile.

Note that the aParent of the file must be a sv:localImageRepository, sv:imageRepository, sv:personalImageRepository or a sv:folder residing as sub node to an image repository.

The file name must correspond to an image mime-type or an IllegalArgumentException is thrown.

Permission note! Current user (the invoker of this method) must have WRITE permission on the parent node (see PermissionUtil.Permission.WRITE) or a ConstraintViolationException is thrown. Creating an image for a sv:userIdentity requires PermissionUtil.Permission.MANAGE_USER_IDENTITIES on current page.

Parameters:

aParent - the parent node of the image

aTemporaryFile - a sv:temporaryFile (typically created via TemporaryFileNodeBuilder)

Returns:

a sv:image node corresponding to the newly created image. Will never return null

Throws:

ConstraintViolationException - if the user is not authorized to alter the parent node, if an invalid parent node is specified, if an invalid temporary node is specified or if image exceeds file size limit

RepositoryException - if something else goes wrong

Since:

Sitevision 4.5.4

updateBinaryContent

void updateBinaryContent(Node aImage,
                         String aUri)
                  throws ConstraintViolationException,
                         RepositoryException

Updates the binary content of an existing image using a uri string.

Properties related to the binary content will also be updated (e.g. length, width and height).

URI note! The URI must be accessible from the Sitevision server and the ending part of the URI must match the file extension of the existing image that should be updated!

Permission note! Current user (the invoker of this method) must have WRITE permission on the image node that should be updated (see PermissionUtil.Permission.WRITE). Updating an image for a sv:userIdentity requires PermissionUtil.Permission.MANAGE_USER_IDENTITIES on current page.

Parameters:

aImage - the image. May not be null

aUri - the URI pointing to the file resource to fetch new binary content from. May not be null

Throws:

ConstraintViolationException - if the user is not authorized to alter the image node, if an invalid node is specified, if the end part of aUri doesn't match the file extension of aImage or if image exceeds file size limit

RepositoryException - if something else goes wrong

Since:

Sitevision 3.6.3

updateBinaryContentFromBase64

void updateBinaryContentFromBase64(Node aImage,
                                   String aBase64EncodedString)
                            throws ConstraintViolationException,
                                   RepositoryException

Updates the binary content of an existing image using a base64 string.

The base64 decoder uses "The Base64 Alphabet" as specified in Table 1 of RFC 4648 and RFC 2045 for decoding operation. The decoder rejects data that contains characters outside the base64 alphabet.

Properties related to the binary content will also be updated (e.g. length, width and height).

Permission note! Current user (the invoker of this method) must have WRITE permission on the image node that should be updated (see PermissionUtil.Permission.WRITE). Updating an image for a sv:userIdentity requires PermissionUtil.Permission.MANAGE_USER_IDENTITIES on current page.

Parameters:

aImage - the image. May not be null

aBase64EncodedString - a base64 encoded string. May not be null

Throws:

ConstraintViolationException - if the user is not authorized to alter the image node, if an invalid node is specified, if aBase64EncodedString is not base64 encoded or if image exceeds file size limit

RepositoryException - if something else goes wrong

Since:

Sitevision 4.5.4

updateBinaryContentFromTemporary

void updateBinaryContentFromTemporary(Node aImage,
                                      Node aTemporaryFile)
                               throws ConstraintViolationException,
                                      RepositoryException

Updates the binary content of an existing image using a sv:temporaryFile.

Properties related to the binary content will also be updated (e.g. length, width and height).

Permission note! Current user (the invoker of this method) must have WRITE permission on the image node that should be updated (see PermissionUtil.Permission.WRITE). Updating an image for a sv:userIdentity requires PermissionUtil.Permission.MANAGE_USER_IDENTITIES on current page.

Parameters:

aImage - the image. May not be null

aTemporaryFile - the sv:temporaryFile (typically created via TemporaryFileNodeBuilder)

Throws:

ConstraintViolationException - if the user is not authorized to alter the image node, if an invalid node is specified, if the end part of the file represented by aTemporaryFile doesn't match the file extension of aImage or if image exceeds file size limit

RepositoryException - if something else goes wrong

Since:

Sitevision 4.5.4

renameImage

void renameImage(Node aImage,
                 String aName)
          throws ConstraintViolationException,
                 RepositoryException

Alters the name of an image.

If no image is specified a NullPointerException is thrown. If the node is not a sv:image an IllegalArgumentException is thrown. If no name is provided a NullPointerException is thrown.

Permission note! Current user (the invoker of this method) must have WRITE permission on the image node that should be updated (see PermissionUtil.Permission.WRITE). Updating an image for a sv:userIdentity requires PermissionUtil.Permission.MANAGE_USER_IDENTITIES on current page.

Parameters:

aImage - the sv:image that should be renamed. May not be null

aName - the new name of the image. May not be null

Throws:

ConstraintViolationException - if the current user is not authorized to alter the name of the image or if the image extension doesn't match

RepositoryException - if something else goes wrong

Since:

Sitevision 4.5.2

toBase64

String toBase64(Node aImage)
         throws RepositoryException

The Base64 String representation of an image Node.

Reads the binary content of an image and encodes the bytes using EndecUtil.base64encodeToString(byte[]).

Parameters:

aImage - the image Node (sv:image or sv:temporaryFile), may not be null

Returns:

aImage as base64-encoded String

Throws:

ConstraintViolationException - if aImage is not a sv:image or sv:temporaryFile

RepositoryException - if something else goes wrong

Since:

Sitevision 4.5.5.2

setAltText

void setAltText(Node aImage,
                String aAltText)
         throws ConstraintViolationException,
                RepositoryException

Sets the alt property for an image Node.

Permission note! Current user (the invoker of this method) must have WRITE permission on the image node that should be updated. Updating an image for a sv:userIdentity requires MANAGE_USER_IDENTITIES permission on current page.

Parameters:

aImage - the sv:image Node, may not be null

aAltText - the alt text to set

Throws:

ConstraintViolationException - if aImage is not a sv:image or if current user is not authorized to alter the image node

RepositoryException - if something else goes wrong

Since:

Sitevision 2024.07.1

setCaptionText

void setCaptionText(Node aImage,
                    String aCaptionText)
             throws ConstraintViolationException,
                    RepositoryException

Sets the caption property for an image Node.

Permission note! Current user (the invoker of this method) must have WRITE permission on the image node that should be updated. Updating an image for a sv:userIdentity requires MANAGE_USER_IDENTITIES permission on current page.

Parameters:

aImage - the sv:image Node, may not be null

aCaptionText - the caption text to set

Throws:

ConstraintViolationException - if aImage is not a sv:image or if current user is not authorized to alter the image node

RepositoryException - if something else goes wrong

Since:

Sitevision 2024.07.1