gov.nasa.worldwind.retrieve
Class AbstractRetrievalPostProcessor

java.lang.Object
  gov.nasa.worldwind.retrieve.AbstractRetrievalPostProcessor

All Implemented Interfaces:

RetrievalPostProcessor

Direct Known Subclasses:

BasicDataFileStore.PostProcessor, BasicElevationModel.DownloadPostProcessor, BasicTiledImageLayer.DownloadPostProcessor, PlaceNameLayer.DownloadPostProcessor, TiledImageLayer.CompositionRetrievalPostProcessor, WMSBasicElevationModel.CompositionRetrievalPostProcessor

public abstract class AbstractRetrievalPostProcessor
extends Object
implements RetrievalPostProcessor

Abstract base class for retrieval post-processors. Verifies the retrieval operation and dispatches the content to the a subclasses content handlers.

Subclasses are expected to override the methods necessary to handle their particular post-processing operations.

Field Summary

protected AVList	avList Holds miscellaneous parameters examined by this and subclasses.
protected Retriever	retriever The retriever associated with the post-processor.

Constructor Summary

AbstractRetrievalPostProcessor()
Create a default post-processor.

AbstractRetrievalPostProcessor(AVList avList)
Create a post-processor and pass it attributes that can be examined during content handling.

Method Summary

protected ByteBuffer	convertToDDS() Converts an image to DDS.
protected abstract File	doGetOutputFile() Abstract method that subclasses must provide to identify the output file for the post-processor's retrieval content.
protected Object	getFileLock() Returns an object that can be used to synchronize writing to the output file.
protected File	getOutputFile() Determines and returns the output file for the retrieved data.
Retriever	getRetriever() Returns the retriever associarted with this post-processor.
protected ByteBuffer	handleApplicationContent() Handles application content.
protected ByteBuffer	handleContent() Process the retrieved data.
protected void	handleContentException(Exception e) Reacts to exceptions occurring during content handling.
protected ByteBuffer	handleHTMLContent() Handles HTML content.
protected ByteBuffer	handleImageContent() Handles image content.
protected void	handleInvalidResponseCode() Handle the case of an invalid response code.
protected ByteBuffer	handleSuccessfulRetrieval() Process the retrieved data if it has been retrieved successfully.
protected ByteBuffer	handleTextContent() Handles Text content.
protected ByteBuffer	handleUnknownContentType() Handles content types that are not recognized by the content handler.
protected void	handleUnsuccessfulRetrieval() Called when the retrieval state is other than Retriever.RETRIEVER_STATE_SUCCESSFUL.
protected ByteBuffer	handleWMSExceptionContent() Handles WMS exceptions.
protected ByteBuffer	handleXMLContent() Handles XML content.
protected ByteBuffer	handleZipContent() Handles zipped content.
protected boolean	isDeleteOnExit(File outFile) Indicates whether the output file should have its delete-on-exit flag set so that it's deleted when the JVM terminates.
protected boolean	isPrimaryContentType(String typeOfContent, String contentType)
protected boolean	isWMSException()
protected void	logTextBuffer(ByteBuffer buffer) Log the content of a buffer as a String.
protected void	markResourceAbsent() Marks the retrieval target absent.
protected boolean	overwriteExistingFile() Indicates whether the retrieved data should be written to the output file if a file of the same name already exists.
ByteBuffer	run(Retriever retriever) Runs the post-processor.
protected boolean	saveBuffer() Saves the retrieved and possibly transformed data.
protected boolean	saveBuffer(ByteBuffer buffer) Saves the retrieved and possibly transformed data.
protected ByteBuffer	saveDDS() Saves a DDS image file after first converting any other image format to DDS.
protected BufferedImage	transformPixels() Transform the retrieved data in some purpose-specific way.
protected boolean	validateHTTPResponseCode() Checks the retrieval's HTTP response code.
protected boolean	validateJarResponseCode() Checks the retrieval's HTTP response code.
protected boolean	validateResponseCode() Checks the retrieval response code.

Methods inherited from class java.lang.Object

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

Field Detail

avList

protected AVList avList

Holds miscellaneous parameters examined by this and subclasses.

retriever

protected Retriever retriever

The retriever associated with the post-processor. Only non-null after run(Retriever) is called.

Constructor Detail

AbstractRetrievalPostProcessor

public AbstractRetrievalPostProcessor()

Create a default post-processor.

AbstractRetrievalPostProcessor

public AbstractRetrievalPostProcessor(AVList avList)

Create a post-processor and pass it attributes that can be examined during content handling.

Parameters:

avList - an attribute-value list with values that might be used during post-processing.

Method Detail

convertToDDS

protected ByteBuffer convertToDDS()
                           throws IOException

Converts an image to DDS. If the image format is not originally DDS, calls transformPixels() to perform any defined image transform.

Returns:

the converted image data if a conversion is performed, otherwise the original image data.

Throws:

IOException - if an IO error occurs while converting the image.

doGetOutputFile

protected abstract File doGetOutputFile()

Abstract method that subclasses must provide to identify the output file for the post-processor's retrieval content.

Returns:

the output file.

getFileLock

protected Object getFileLock()

Returns an object that can be used to synchronize writing to the output file. Superclasses should override this method and return the object used as a lock by other objects that read or otherwise interact with the output file.

Returns:

an object to use for read/write synchronization, or null if no lock is needed.

getOutputFile

protected File getOutputFile()

Determines and returns the output file for the retrieved data.

Returns:

the output file, or null if a file could not be determined.

getRetriever

public Retriever getRetriever()

Returns the retriever associarted with this post-processor.

Returns:

the retriever associated with the post-processor, or null if no retriever is associated.

handleApplicationContent

protected ByteBuffer handleApplicationContent()
                                       throws IOException

Handles application content. The default implementation saves the retrieved data without modification via saveBuffer() without.

Returns:

a buffer containing the retrieved data.

Throws:

IOException - if an IO error occurs while processing the data.

handleContent

protected ByteBuffer handleContent()
                            throws IOException

Process the retrieved data. Dispatches content handling to content-type specific handlers: handleZipContent() for content types containing "zip", handleTextContent() for content types starting with "text", and handleImageContent() for contents types starting with "image".

Returns:

a buffer containing the retrieved data, which may have been transformed during content handling.

Throws:

IOException - if an IO error occurs while processing the data.

handleContentException

protected void handleContentException(Exception e)

Reacts to exceptions occurring during content handling. Subclasses may override this method to perform special exception handling. The default implementation logs a message specific to the exception.

Parameters:

e - the exception to handle.

handleHTMLContent

protected ByteBuffer handleHTMLContent()
                                throws IOException

Handles HTML content. The default implementation only calls logTextBuffer(java.nio.ByteBuffer) and returns.

Returns:

a buffer containing the retrieved HTML.

Throws:

IOException - if an IO error occurs while processing the data.

handleImageContent

protected ByteBuffer handleImageContent()
                                 throws IOException

Handles image content. The default implementation simply saves the retrieved data via saveBuffer(), first converting it to DDS if the suffix of the output file is .dds.

The default implementation of this method returns immediately if the output file cannot be determined or it exists and overwriteExistingFile() returns false.

Returns:

a buffer containing the retrieved data.

Throws:

IOException - if an IO error occurs while processing the data.

handleInvalidResponseCode

protected void handleInvalidResponseCode()

Handle the case of an invalid response code. Subclasses can override this method to handle special cases. The default implementation calls markResourceAbsent() and logs the contents of the retrieval buffer if it contains content of type "text".

handleSuccessfulRetrieval

protected ByteBuffer handleSuccessfulRetrieval()

Process the retrieved data if it has been retrieved successfully.

Returns:

a buffer containing the downloaded data, perhaps converted during content handling.

handleTextContent

protected ByteBuffer handleTextContent()
                                throws IOException

Handles Text content. If the content type is text/xml, handleXMLContent() is called. If the content type is text/html, handleHTMLContent() is called. For all other sub-types the content is logged as a message with level Level.SEVERE.

Returns:

a buffer containing the retrieved text.

Throws:

IOException - if an IO error occurs while processing the data.

handleUnknownContentType

protected ByteBuffer handleUnknownContentType()

Handles content types that are not recognized by the content handler. Subclasses may override this method to handle such cases. The default implementation logs an error message and returns null.

Returns:

null if no further processing should occur, otherwise the retrieved data, perhaps transformed.

handleUnsuccessfulRetrieval

protected void handleUnsuccessfulRetrieval()

Called when the retrieval state is other than Retriever.RETRIEVER_STATE_SUCCESSFUL. Can be overridden by subclasses to handle special error cases. The default implementation calls markResourceAbsent() if the retrieval state is Retriever.RETRIEVER_STATE_ERROR.

handleWMSExceptionContent

protected ByteBuffer handleWMSExceptionContent()

Handles WMS exceptions.

Returns:

a buffer containing the retrieved XML.

handleXMLContent

protected ByteBuffer handleXMLContent()
                               throws IOException

Handles XML content. The default implementation only calls logTextBuffer(java.nio.ByteBuffer) and returns.

Returns:

a buffer containing the retrieved XML.

Throws:

IOException - if an IO error occurs while processing the data.

handleZipContent

protected ByteBuffer handleZipContent()
                               throws IOException

Handles zipped content. The default implementation saves the data to the retriever's output file without unzipping it.

Returns:

a buffer containing the retrieved data.

Throws:

IOException - if an IO error occurs while processing the data.

isDeleteOnExit

protected boolean isDeleteOnExit(File outFile)

Indicates whether the output file should have its delete-on-exit flag set so that it's deleted when the JVM terminates.

Parameters:

outFile - the output file.

Returns:

true if the output file's delete-on-exit flag should be set, otherwise false.

isPrimaryContentType

protected boolean isPrimaryContentType(String typeOfContent,
                                       String contentType)

isWMSException

protected boolean isWMSException()

logTextBuffer

protected void logTextBuffer(ByteBuffer buffer)

Log the content of a buffer as a String. If the buffer is null or empty, nothing is logged. Only the first 2,048 characters of the buffer are included in the log message.

Parameters:

buffer - the content to log. The content is assumed to be of type "text".

markResourceAbsent

protected void markResourceAbsent()

Marks the retrieval target absent. Subclasses should override this method if they keep track of absent-resources. The default implementation does nothing.

overwriteExistingFile

protected boolean overwriteExistingFile()

Indicates whether the retrieved data should be written to the output file if a file of the same name already exists. The default implementation of this method returns false (files are not overwritten).

Returns:

true if an existing file should be overwritten, otherwise false.

run

public ByteBuffer run(Retriever retriever)

Runs the post-processor.

Specified by:

run in interface RetrievalPostProcessor

Parameters:

retriever - the retriever to associate with the post-processor.

Returns:

a buffer containing the downloaded data, perhaps converted during content handling. null is returned if a fatal problem occurred during post-processing.

Throws:

IllegalArgumentException - if the retriever is null.

saveBuffer

protected boolean saveBuffer()
                      throws IOException

Saves the retrieved and possibly transformed data. The data may have been transformed during content handling.

The default implementation of this method simply calls saveBuffer(java.nio.ByteBuffer) with an argument of null.

Returns:

true if the buffer was saved, false if the output file could not be determined or already exists and not overwritten.

Throws:

IOException - if an IO error occurs while attempting to save the buffer.

saveBuffer

protected boolean saveBuffer(ByteBuffer buffer)
                      throws IOException

Saves the retrieved and possibly transformed data. The data may have been transformed during content handling. The data is not saved if the output file already exists unless overwriteExistingFile() returns true.

Parameters:

buffer - the buffer to save.

Returns:

true if the buffer was saved, false if the output file could not be determined or already exists and not overwritten.

Throws:

IOException - if an IO error occurred when attempting to save the buffer.

saveDDS

protected ByteBuffer saveDDS()
                      throws IOException

Saves a DDS image file after first converting any other image format to DDS.

Returns:

the converted image data if a conversion is performed, otherwise the original image data.

Throws:

IOException - if an IO error occurs while converting or saving the image.

transformPixels

protected BufferedImage transformPixels()

Transform the retrieved data in some purpose-specific way. May be overridden by subclasses to perform special transformations. The default implementation calls ImageUtil.mapTransparencyColors(java.awt.image.BufferedImage, int[]) if the attribute-value list specified at construction contains transparency colors (includes the AVKey.TRANSPARENCY_COLORS key).

Returns:

returns the transformed data if a transform is performed, otherwise returns the original data.

validateHTTPResponseCode

protected boolean validateHTTPResponseCode()

Checks the retrieval's HTTP response code. Must only be called when the retriever is a subclass of HTTPRetriever.

Returns:

true if the response code is HttpURLConnection.HTTP_OK, otherwise false.

validateJarResponseCode

protected boolean validateJarResponseCode()

Checks the retrieval's HTTP response code. Must only be called when the retriever is a subclass of HTTPRetriever.

Returns:

true if the response code is HttpURLConnection.HTTP_OK, otherwise false.

validateResponseCode

protected boolean validateResponseCode()

Checks the retrieval response code.

Returns:

true if the response code is the OK value for the protocol, e.g., (HttpURLConnection.HTTP_OK for HTTP protocol), otherwise false.