com.communote.server.core.image

Class HttpExternalImageProvider<C>

java.lang.Object

com.communote.server.api.core.image.ImageProvider

com.communote.server.core.image.HttpExternalImageProvider<C>

Type Parameters:

C - the type of the configuration class

Direct Known Subclasses:

HttpExternalUserImageProvider

public abstract class HttpExternalImageProvider<C>
extends ImageProvider

Image provider which loads images from an external system using HTTP GET requests.

Author:

Communote GmbH - http://www.communote.com/

Constructor Summary

Constructors

Constructor and Description
HttpExternalImageProvider(String identifier, String pathToDefaultImage, long disablingDuration) Create a new external image provider

Method Summary

Modifier and Type	Method and Description
protected void	assertNotDisabled(String imageIdentifier, C configuration) Test that the image provider was not disabled.
void	cleanup() Cleanup held resources.
protected void	disableTemporarily(String reason, C configuration) Temporarily disable the image provider
protected void	enable() Re-enable the provider if it is currently temporarily disabled.
protected ByteArrayImage	extractImageFromEntity(org.apache.http.HttpEntity entity, Date imageLastModified) Extract the image from the response entity.
protected abstract C	getConfiguration()
protected int	getConnectionManagerTimeout()
protected int	getConnectionTimeout()
String	getDefaultImageVersionString() The version string of the default image.
protected org.apache.http.client.config.RequestConfig	getDefaultRequestConfig() Prepare and return a request configuration that is used as default for all requests started by the shared HttpClient instance.
protected Long	getDisabledUntilTimestamp()
protected org.apache.http.impl.client.CloseableHttpClient	getHttpClient() Get the HTTP client to be used for all requests.
protected abstract String	getImageURL(String imageIdentifier, C configuration) Get the URL under which the image with the given identifier can be downloaded
protected Date	getLastModifiedHeaderValue(org.apache.http.client.methods.CloseableHttpResponse response) Get last modified header value as date, will fall back to current time if header is not set
protected Set<Integer>	getNotDisablingStatusCodes()
protected org.apache.http.protocol.HttpContext	getRequestContext(URI imageUrl, String imageIdentifier, C configuration) Get request context to be used when downloading the given image.
protected List<org.apache.http.Header>	getRequestHeaders(URI imageUrl, String imageIdentifier, C configuration) Get the HTTP request headers to add when downloading the given image.
protected int	getSocketTimeout()
boolean	hasDefaultImage(String imageIdentifier) Return whether the provider has a default image for the case when there is no image for a given identifier.
protected void	imageNotDownloaded(String imageIdentifier) Invoked when the image URL was null or the image could not be downloaded and the cause was not one that would disable the provider.
protected void	imageSuccessfullyDownloaded(String imageIdentifier, Date lastModificationDate, org.apache.http.client.methods.CloseableHttpResponse response) Invoked by loadImage after successfully parsing and extracting the image.
protected boolean	isDisabled(C configuration) Test whether the image provider was temporarily disabled.
protected boolean	isDisablingException(IOException e) Determines if a caught IO exception is one which should disable the image provider temporarily.
boolean	isExternalProvider() Return whether this provider loads image from an external resource (like another server) and not from the local database or file system.
boolean	isProvideDefaultImageIfDisabled()
Image	loadDefaultImage() Load the default image.
Image	loadImage(String imageIdentifier) Load the unscaled image
protected org.apache.http.impl.client.CloseableHttpClient	prepareHttpClient(org.apache.http.impl.client.HttpClientBuilder builder) Prepare the HTTP client that should be used by all requests.
protected void	setHttpClient(org.apache.http.impl.client.CloseableHttpClient httpClient, boolean replace) Set the HTTP client instance that should be used for all requests.
void	setProvideDefaultImageIfDisabled(boolean provideDefaultImageIfDisabled) Set whether the default image can be returned even if the provider is temporarily disabled.
protected void	validateContentType(String contentType) Validate that the content type of the response is an image mime type.
protected void	validateStatusCode(org.apache.http.StatusLine statusLine) Checks the status code of a response for an image request.

Methods inherited from class com.communote.server.api.core.image.ImageProvider

canLoad, getDefaultImageMimeType, getDefaultImageResourceLastModificationTimestamp, getIdentifier, getTimeToLive, getVersionString, imageChanged, isAuthorized

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HttpExternalImageProvider

public HttpExternalImageProvider(String identifier,
                                 String pathToDefaultImage,
                                 long disablingDuration)

Create a new external image provider

Parameters:

identifier - The identifier of the provider. The identifier has to be unique among all providers that are registered for an image type.

pathToDefaultImage - If the path starts with file: it is interpreted as a file URI otherwise it is interpreted as the name of a resource containing the default image. This resource will be loaded with the class loader of this class. If null, there will be no default image.

disablingDuration - the amount of milliseconds to disable the image provider temporarily in certain situations e.g. if the external server is unreachable. If 0 or less the provider is never disabled.

Method Detail

assertNotDisabled

protected void assertNotDisabled(String imageIdentifier,
                                 C configuration)
                          throws ImageNotFoundException

Test that the image provider was not disabled. This method is called from loadImage and implementations should also invoke it from other methods that return image data or information (default image, version string).

Parameters:

imageIdentifier - the Id of the image that should be loaded. Only needed to create a useful exception.

configuration - the current configuration of the image provider, can be null. Default implementation ignores this parameter.

Throws:

ImageTemporarilyNotFoundException - in case the provider is disabled and the provided image can thus not be loaded

ImageNotFoundException

cleanup

public void cleanup()

Cleanup held resources. Should be called when the provider is unregistered.

disableTemporarily

protected void disableTemporarily(String reason,
                                  C configuration)

Temporarily disable the image provider

Parameters:

reason - The reason that caused the disabling of the provider

configuration - the current configuration of the image provider, can be null. Default implementation ignores this parameter.

enable

protected void enable()

Re-enable the provider if it is currently temporarily disabled.

extractImageFromEntity

protected ByteArrayImage extractImageFromEntity(org.apache.http.HttpEntity entity,
                                                Date imageLastModified)
                                         throws ExternalImageProviderServiceException,
                                                ImageNotFoundException

Extract the image from the response entity. The caller has to take care of closing the response or ensuring that the entity is consumed.

Parameters:

entity - the entity to handle

imageLastModified - the date of the last modification of the image contained in the entity. This could for instance be the value of the Last-Modified header.

Returns:

the image

Throws:

ExternalImageProviderServiceException - in case validateContentType(String) threw this exception

ImageNotFoundException - in case the entity is not a valid image

getConfiguration

protected abstract C getConfiguration()

Returns:

the current configuration of the external image provider. During loadImage the same configuration object is passed to all called methods.

getConnectionManagerTimeout

protected int getConnectionManagerTimeout()

Returns:

timeout in milliseconds to wait for a connection from the connection manager of the HttpClient. Can be 0 for an infinite timeout. Defaults to 30s.

getConnectionTimeout

protected int getConnectionTimeout()

Returns:

timeout in milliseconds to wait until a connection to the remote host must have been established. Can be 0 for an infinite timeout. Defaults to 30s.

getDefaultImageVersionString

public String getDefaultImageVersionString()
                                    throws ImageNotFoundException

Description copied from class: ImageProvider

The version string of the default image.

Overrides:

getDefaultImageVersionString in class ImageProvider

Returns:

the version string

Throws:

ImageNotFoundException - in case there is no default image

See Also:

ImageProvider.getVersionString(String)

getDefaultRequestConfig

protected org.apache.http.client.config.RequestConfig getDefaultRequestConfig()

Prepare and return a request configuration that is used as default for all requests started by the shared HttpClient instance. The default implementation will set the socket, connection and connection manager timeouts to the values returned by getSocketTimeout(), getConnectionTimeout() and getConnectionManagerTimeout().

Returns:

the default request configuration

getDisabledUntilTimestamp

protected Long getDisabledUntilTimestamp()

Returns:

the epoch timestamp in milliseconds until the provider is currently disabled, or null if not disabled

getHttpClient

protected org.apache.http.impl.client.CloseableHttpClient getHttpClient()

Get the HTTP client to be used for all requests. If there is no current HTTP client a new one will be created and prepared with a call to prepareHttpClient(HttpClientBuilder).

Returns:

the current HTTP client

getImageURL

protected abstract String getImageURL(String imageIdentifier,
                                      C configuration)
                               throws ImageNotFoundException

Get the URL under which the image with the given identifier can be downloaded

Parameters:

imageIdentifier - the ID of the image to download

configuration - the configuration of the image provider, can be null

Returns:

the URL to the image. If null is returned the load method will throw an ImageNotFoundException

Throws:

ImageNotFoundException - can be thrown to indicate that image does not exist image

getLastModifiedHeaderValue

protected Date getLastModifiedHeaderValue(org.apache.http.client.methods.CloseableHttpResponse response)

Get last modified header value as date, will fall back to current time if header is not set

Parameters:

response - the response of the image request

Returns:

the last modification date

getNotDisablingStatusCodes

protected Set<Integer> getNotDisablingStatusCodes()

Returns:

the status codes which should not lead to disabling the image provider temporarily. The code 200 does not need to be in the result.

getRequestContext

protected org.apache.http.protocol.HttpContext getRequestContext(URI imageUrl,
                                                                 String imageIdentifier,
                                                                 C configuration)

Get request context to be used when downloading the given image. Implementations could use this method to provide authentication details. The default implementation returns null.

Parameters:

imageUrl - the URL pointing to the image

imageIdentifier - the ID of the image to get

configuration - the configuration of the image provider, can be null

Returns:

the request context

getRequestHeaders

protected List<org.apache.http.Header> getRequestHeaders(URI imageUrl,
                                                         String imageIdentifier,
                                                         C configuration)

Get the HTTP request headers to add when downloading the given image. The default implementation returns null.

Parameters:

imageUrl - the URL pointing to the image

imageIdentifier - the ID of the image to get

configuration - the configuration of the image provider, can be null

Returns:

the headers

getSocketTimeout

protected int getSocketTimeout()

Returns:

timeout in milliseconds to wait for data after a connection was established. Can be 0 for an infinite timeout. Defaults to 30s.

hasDefaultImage

public boolean hasDefaultImage(String imageIdentifier)

Description copied from class: ImageProvider

Return whether the provider has a default image for the case when there is no image for a given identifier. This implementation will return true if the resource identified by the constructor parameter pathToDefaultImage exists.

Overrides:

hasDefaultImage in class ImageProvider

Parameters:

imageIdentifier - the identifier for which no image was found

Returns:

whether there is a default image

imageNotDownloaded

protected void imageNotDownloaded(String imageIdentifier)

Invoked when the image URL was null or the image could not be downloaded and the cause was not one that would disable the provider. Default implementation does nothing but subclasses could use this method to update or reset the version string of the image if necessary.

Parameters:

imageIdentifier - the ID of the image that failed

imageSuccessfullyDownloaded

protected void imageSuccessfullyDownloaded(String imageIdentifier,
                                           Date lastModificationDate,
                                           org.apache.http.client.methods.CloseableHttpResponse response)

Invoked by loadImage after successfully parsing and extracting the image. Default implementation does nothing but subclasses could use this method to update the version string of the image if necessary.

Parameters:

imageIdentifier - the ID of the image

lastModificationDate - the last modification date of the as returned by getLastModifiedHeaderValue(CloseableHttpResponse)

response - the response that contained the image

isDisabled

protected boolean isDisabled(C configuration)

Test whether the image provider was temporarily disabled.

Parameters:

configuration - the current configuration of the image provider, can be null. Default implementation ignores this parameter.

Returns:

true if the provider was disabled

isDisablingException

protected boolean isDisablingException(IOException e)

Determines if a caught IO exception is one which should disable the image provider temporarily. By default the exceptions ConnectTimeoutException, SocketTimeoutException and SocketException are considered as disabling exceptions.

Parameters:

e - the exception to check

Returns:

true if the image provider should be disabled

isExternalProvider

public boolean isExternalProvider()

Description copied from class: ImageProvider

Return whether this provider loads image from an external resource (like another server) and not from the local database or file system.

Specified by:

isExternalProvider in class ImageProvider

Returns:

true, if it is a provider for external images

isProvideDefaultImageIfDisabled

public boolean isProvideDefaultImageIfDisabled()

Returns:

whether to return the default image even if the provider is temporarily disabled. Defaults to false.

loadDefaultImage

public Image loadDefaultImage()
                       throws ImageNotFoundException

Description copied from class: ImageProvider

Load the default image.

Overrides:

loadDefaultImage in class ImageProvider

Returns:

the default image

Throws:

ImageNotFoundException - in case there is no default image.

loadImage

public Image loadImage(String imageIdentifier)
                throws ImageNotFoundException,
                       AuthorizationException

Description copied from class: ImageProvider

Load the unscaled image

Specified by:

loadImage in class ImageProvider

Parameters:

imageIdentifier - The identifier of the image

Returns:

The image.

Throws:

ImageNotFoundException - in case there is no image for the imageIdentifier or loading failed

AuthorizationException - in case the current user is not allowed to access the image

prepareHttpClient

protected org.apache.http.impl.client.CloseableHttpClient prepareHttpClient(org.apache.http.impl.client.HttpClientBuilder builder)

Prepare the HTTP client that should be used by all requests. The default implementations sets the request config as returned by getDefaultRequestConfig().

Parameters:

builder - the HTTP client builder

Returns:

the HTTP client

setHttpClient

protected void setHttpClient(org.apache.http.impl.client.CloseableHttpClient httpClient,
                             boolean replace)

Set the HTTP client instance that should be used for all requests. This instance will be returned by getHttpClient().

Parameters:

httpClient - the HTTP client to set. Can be null, to reset the client.

replace - if true the current HTTP client instance will be closed and replaced with the new one. If false and there is a current HTTP client the current one is not updated.

setProvideDefaultImageIfDisabled

public void setProvideDefaultImageIfDisabled(boolean provideDefaultImageIfDisabled)

Set whether the default image can be returned even if the provider is temporarily disabled.

Parameters:

provideDefaultImageIfDisabled - true to return the default image

validateContentType

protected void validateContentType(String contentType)
                            throws ExternalImageProviderServiceException

Validate that the content type of the response is an image mime type.

Parameters:

contentType - the content type

Throws:

ExternalImageProviderServiceException - in case the content type is not an image/* mime type. This exception will lead to temporarily disabling the provider.

validateStatusCode

protected void validateStatusCode(org.apache.http.StatusLine statusLine)
                           throws ImageNotFoundException,
                                  ExternalImageProviderServiceException

Checks the status code of a response for an image request.

Parameters:

statusLine - the status line containing the status code

Throws:

ImageNotFoundException - in case the status code is one of the codes in getNotDisablingStatusCodes()

ExternalImageProviderServiceException - in case the status code is not 200 and not one of the codes returned by getNotDisablingStatusCodes(). The image provider will be disabled temporarily.