org.apache.excalibur.source.impl
Class HTTPClientSource

java.lang.Object
  org.apache.avalon.framework.logger.AbstractLogEnabled
      org.apache.excalibur.source.impl.HTTPClientSource

All Implemented Interfaces:

org.apache.avalon.framework.activity.Initializable, org.apache.avalon.framework.logger.LogEnabled, org.apache.avalon.framework.parameters.Parameterizable, ModifiableSource, Source

public class HTTPClientSource
extends org.apache.avalon.framework.logger.AbstractLogEnabled
implements ModifiableSource, org.apache.avalon.framework.activity.Initializable, org.apache.avalon.framework.parameters.Parameterizable

HTTP URL Source object, based on the Jakarta Commons HttpClient project.

Version:

CVS $Id: HTTPClientSource.java,v 1.4 2004/02/28 11:47:24 cziegeler Exp $

Author:

Avalon Development Team

Nested Class Summary

private class

HTTPClientSource.WrappedFileOutputStream Internal class which extends FileOutputStream to automatically upload the data written to it, upon a HTTPClientSource.WrappedFileOutputStream.close() operation.

Field Summary

static java.lang.String	CONTENT_LENGTH Constant used when obtaining the Content-Length from HTTP Headers
static java.lang.String	CONTENT_TYPE Constant used when obtaining the Content-Type from HTTP Headers
static java.lang.String	GET Constant used for identifying GET requests.
static java.lang.String	LAST_MODIFIED Constant used when obtaining the Last-Modified date from HTTP Headers
private long	m_cachedLastModificationDate Cached last modification date.
private SourceValidity	m_cachedValidity Stored SourceValidity object.
private org.apache.commons.httpclient.HttpClient	m_client The HttpClient object.
private long	m_contentLength The content length of the resource on the server.
private boolean	m_dataValid Whether the data held within this instance is currently accurate.
private boolean	m_exists Whether the resource exists on the server.
private org.apache.commons.httpclient.HttpState	m_httpState Optional http state passed from SourceFactory
private long	m_lastModified The last modified date of the resource on the server.
private java.lang.String	m_mimeType The mime type of the resource on the server.
private java.util.Map	m_parameters Contextual parameters passed via the SourceFactory.
private java.lang.String	m_proxyHost Proxy host if set via configuration.
private int	m_proxyPort Proxy port if set via configuration.
private java.lang.String	m_uri The URI being accessed.
static java.lang.String	POST Constant used for identifying POST requests.
static java.lang.String	PROXY_HOST Constant used for configuring the proxy hostname.
static java.lang.String	PROXY_PORT Constant used for configuring the proxy port number.

Constructor Summary

HTTPClientSource(java.lang.String uri, java.util.Map parameters, org.apache.commons.httpclient.HttpState httpState)
Constructor, creates a new HTTPClientSource instance.

Method Summary

boolean	canCancel(java.io.OutputStream stream) Method to determine whether writing to the supplied OutputStream (which must be that returned from getOutputStream()) can be cancelled
void	cancel(java.io.OutputStream stream) Cancels any data sent to the HTTPClientSource.WrappedFileOutputStream returned by getOutputStream().
private org.apache.commons.httpclient.methods.DeleteMethod	createDeleteMethod(java.lang.String uri) Factory method to create a DeleteMethod object.
private org.apache.commons.httpclient.methods.GetMethod	createGetMethod(java.lang.String uri) Factory method to create a GetMethod object.
private org.apache.commons.httpclient.methods.HeadMethod	createHeadMethod(java.lang.String uri) Factory method to create a HeadMethod object.
private org.apache.commons.httpclient.methods.PostMethod	createPostMethod(java.lang.String uri, SourceParameters params) Factory method to create a new PostMethod with the given SourceParameters object.
private org.apache.commons.httpclient.methods.PutMethod	createPutMethod(java.lang.String uri, java.io.File uploadFile) Factory method to create a PutMethod object.
void	delete() Deletes the referenced resource.
private boolean	deleteSuccessful(int response) According to RFC2616 (HTTP 1.1) valid responses for a HTTP DELETE are 200 (OK), 202 (Accepted) and 204 (No Content).
protected int	executeMethod(org.apache.commons.httpclient.HttpMethod method) Executes a particular HttpMethod and updates internal data storage.
boolean	exists() Method to ascertain whether the given resource actually exists.
private java.lang.String	findMethodType() Method to discover what kind of request is being made from the parameters map passed in to this Source's constructor.
long	getContentLength() Obtain the content length of the referenced resource.
java.io.InputStream	getInputStream() Method to obtain an InputStream to read the response from the server.
long	getLastModified() Get the last modification date of this source.
private org.apache.commons.httpclient.HttpMethod	getMethod() Helper method to create the required HttpMethod object based on parameters passed to this HTTPClientSource object.
java.lang.String	getMimeType() Obtain the mime-type for the referenced resource.
java.io.OutputStream	getOutputStream() Obtain an HTTPClientSource.WrappedFileOutputStream to write to.
java.lang.String	getScheme() Return the URI scheme identifier, ie.
java.lang.String	getURI() Obtain the absolute URI this Source object references.
SourceValidity	getValidity() Obtain a SourceValidity object.
void	initialize() Initializes this HTTPClientSource instance.
void	parameterize(org.apache.avalon.framework.parameters.Parameters params) Parameterizes this HTTPClientSource instance.
private void	recycle() Recycles this HTTPClientSource object so that it may be reused to refresh it's content.
void	refresh() Refreshes this Source object.
private void	updateContentLength(org.apache.commons.httpclient.HttpMethod method) Method to update the content length of a resource after executing a particular HttpMethod.
private void	updateData() Method to make response data available if possible without actually making an actual request (ie.
private void	updateExists(org.apache.commons.httpclient.HttpMethod method) Method to update whether a referenced resource exists, after executing a particular HttpMethod.
private void	updateLastModified(org.apache.commons.httpclient.HttpMethod method) Method to update the last modified date of a resource after executing a particular HttpMethod.
private void	updateMimeType(org.apache.commons.httpclient.HttpMethod method) Method to update the mime type of a resource after executing a particular HttpMethod.

Methods inherited from class org.apache.avalon.framework.logger.AbstractLogEnabled

enableLogging, getLogger, setupLogger, setupLogger, setupLogger

Methods inherited from class java.lang.Object

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

Field Detail

POST

public static final java.lang.String POST

Constant used for identifying POST requests.

See Also:

Constant Field Values

GET

public static final java.lang.String GET

Constant used for identifying GET requests.

See Also:

Constant Field Values

PROXY_HOST

public static final java.lang.String PROXY_HOST

Constant used for configuring the proxy hostname.

See Also:

Constant Field Values

PROXY_PORT

public static final java.lang.String PROXY_PORT

Constant used for configuring the proxy port number.

See Also:

Constant Field Values

CONTENT_TYPE

public static final java.lang.String CONTENT_TYPE

Constant used when obtaining the Content-Type from HTTP Headers

See Also:

Constant Field Values

CONTENT_LENGTH

public static final java.lang.String CONTENT_LENGTH

Constant used when obtaining the Content-Length from HTTP Headers

See Also:

Constant Field Values

LAST_MODIFIED

public static final java.lang.String LAST_MODIFIED

Constant used when obtaining the Last-Modified date from HTTP Headers

See Also:

Constant Field Values

m_uri

private final java.lang.String m_uri

The URI being accessed.

m_parameters

private final java.util.Map m_parameters

Contextual parameters passed via the SourceFactory.

m_httpState

private final org.apache.commons.httpclient.HttpState m_httpState

Optional http state passed from SourceFactory

m_client

private org.apache.commons.httpclient.HttpClient m_client

The HttpClient object.

m_proxyPort

private int m_proxyPort

Proxy port if set via configuration.

m_proxyHost

private java.lang.String m_proxyHost

Proxy host if set via configuration.

m_dataValid

private boolean m_dataValid

Whether the data held within this instance is currently accurate.

m_exists

private boolean m_exists

Whether the resource exists on the server.

m_mimeType

private java.lang.String m_mimeType

The mime type of the resource on the server.

m_contentLength

private long m_contentLength

The content length of the resource on the server.

m_lastModified

private long m_lastModified

The last modified date of the resource on the server.

m_cachedValidity

private SourceValidity m_cachedValidity

Stored SourceValidity object.

m_cachedLastModificationDate

private long m_cachedLastModificationDate

Cached last modification date.

Constructor Detail

HTTPClientSource

public HTTPClientSource(java.lang.String uri,
                        java.util.Map parameters,
                        org.apache.commons.httpclient.HttpState httpState)
                 throws java.lang.Exception

Constructor, creates a new HTTPClientSource instance.

Parameters:

uri - URI

parameters - contextual parameters passed to this instance

Throws:

java.lang.Exception - if an error occurs

Method Detail

parameterize

public void parameterize(org.apache.avalon.framework.parameters.Parameters params)
                  throws org.apache.avalon.framework.parameters.ParameterException

Parameterizes this HTTPClientSource instance.

Specified by:

parameterize in interface org.apache.avalon.framework.parameters.Parameterizable

Parameters:

params - a Parameters instance.

Throws:

org.apache.avalon.framework.parameters.ParameterException - if an error occurs

initialize

public void initialize()
                throws java.lang.Exception

Initializes this HTTPClientSource instance.

Specified by:

initialize in interface org.apache.avalon.framework.activity.Initializable

Throws:

java.lang.Exception - if an error occurs

findMethodType

private java.lang.String findMethodType()

Method to discover what kind of request is being made from the parameters map passed in to this Source's constructor.

Returns:

the method type, or if no method type can be found, HTTP GET is assumed.

getMethod

private org.apache.commons.httpclient.HttpMethod getMethod()

Helper method to create the required HttpMethod object based on parameters passed to this HTTPClientSource object.

Returns:

a HttpMethod object.

createPostMethod

private org.apache.commons.httpclient.methods.PostMethod createPostMethod(java.lang.String uri,
                                                                          SourceParameters params)

Factory method to create a new PostMethod with the given SourceParameters object.

Parameters:

uri - URI

params - SourceParameters

Returns:

a PostMethod instance

createGetMethod

private org.apache.commons.httpclient.methods.GetMethod createGetMethod(java.lang.String uri)

Factory method to create a GetMethod object.

Parameters:

uri - URI

Returns:

a GetMethod instance

createHeadMethod

private org.apache.commons.httpclient.methods.HeadMethod createHeadMethod(java.lang.String uri)

Factory method to create a HeadMethod object.

Parameters:

uri - URI

Returns:

a HeadMethod instance

createPutMethod

private org.apache.commons.httpclient.methods.PutMethod createPutMethod(java.lang.String uri,
                                                                        java.io.File uploadFile)
                                                                 throws java.io.IOException

Factory method to create a PutMethod object.

Parameters:

uri - URI to upload uploadFile to

uploadFile - File to be uploaded

Returns:

a PutMethod instance

Throws:

java.io.IOException - if an error occurs

createDeleteMethod

private org.apache.commons.httpclient.methods.DeleteMethod createDeleteMethod(java.lang.String uri)

Factory method to create a DeleteMethod object.

Parameters:

uri - URI to delete

Returns:

DeleteMethod instance.

updateData

private void updateData()

Method to make response data available if possible without actually making an actual request (ie. via HTTP HEAD).

executeMethod

protected int executeMethod(org.apache.commons.httpclient.HttpMethod method)
                     throws java.io.IOException

Executes a particular HttpMethod and updates internal data storage.

Parameters:

method - HttpMethod to execute

Returns:

response code from server

Throws:

java.io.IOException - if an error occurs

updateExists

private void updateExists(org.apache.commons.httpclient.HttpMethod method)

Method to update whether a referenced resource exists, after executing a particular HttpMethod.

REVISIT: exists() would be better called canRead() or similar, as a resource can exist but not be readable.

Parameters:

method - HttpMethod executed.

exists

public boolean exists()

Method to ascertain whether the given resource actually exists.

Specified by:

exists in interface Source

Returns:

true if the resource pointed to by the URI during construction exists, false otherwise.

getInputStream

public java.io.InputStream getInputStream()
                                   throws java.io.IOException,
                                          SourceNotFoundException

Method to obtain an InputStream to read the response from the server.

Specified by:

getInputStream in interface Source

Returns:

InputStream containing data sent from the server.

Throws:

java.io.IOException - if some I/O problem occurs.

SourceNotFoundException - if the source doesn't exist.

getURI

public java.lang.String getURI()

Obtain the absolute URI this Source object references.

Specified by:

getURI in interface Source

Returns:

the absolute URI this String object references.

getScheme

public java.lang.String getScheme()

Return the URI scheme identifier, ie. the part preceding the fist ':' in the URI (see RFC 2396).

Specified by:

getScheme in interface Source

Returns:

the URI scheme identifier

getValidity

public SourceValidity getValidity()

Obtain a SourceValidity object.

Specified by:

getValidity in interface Source

Returns:

a SourceValidity object, or null if this is not possible.

refresh

public void refresh()

Refreshes this Source object.

Specified by:

refresh in interface Source

updateMimeType

private void updateMimeType(org.apache.commons.httpclient.HttpMethod method)

Method to update the mime type of a resource after executing a particular HttpMethod.

Parameters:

method - HttpMethod executed

getMimeType

public java.lang.String getMimeType()

Obtain the mime-type for the referenced resource.

Specified by:

getMimeType in interface Source

Returns:

mime-type for the referenced resource.

updateContentLength

private void updateContentLength(org.apache.commons.httpclient.HttpMethod method)

Method to update the content length of a resource after executing a particular HttpMethod.

Parameters:

method - HttpMethod executed

getContentLength

public long getContentLength()

Obtain the content length of the referenced resource.

Specified by:

getContentLength in interface Source

Returns:

content length of the referenced resource, or -1 if unknown/uncalculatable

updateLastModified

private void updateLastModified(org.apache.commons.httpclient.HttpMethod method)

Method to update the last modified date of a resource after executing a particular HttpMethod.

Parameters:

method - HttpMethod executed

getLastModified

public long getLastModified()

Get the last modification date of this source. This date is measured in milliseconds since the Epoch (00:00:00 GMT, January 1, 1970).

Specified by:

getLastModified in interface Source

Returns:

the last modification date or 0 if unknown.

recycle

private void recycle()

Recycles this HTTPClientSource object so that it may be reused to refresh it's content.

getOutputStream

public java.io.OutputStream getOutputStream()
                                     throws java.io.IOException

Obtain an HTTPClientSource.WrappedFileOutputStream to write to. The HTTPClientSource.WrappedFileOutputStream returned actually references a temporary local file, which will be written to the server upon closing. The returned stream must be closed or cancelled by the calling code.

Specified by:

getOutputStream in interface ModifiableSource

Returns:

an HTTPClientSource.WrappedFileOutputStream instance

Throws:

java.io.IOException - if an error occurs

delete

public void delete()
            throws SourceException

Deletes the referenced resource.

Specified by:

delete in interface ModifiableSource

Throws:

SourceException - if an error occurs

deleteSuccessful

private boolean deleteSuccessful(int response)

According to RFC2616 (HTTP 1.1) valid responses for a HTTP DELETE are 200 (OK), 202 (Accepted) and 204 (No Content).

Parameters:

response - response code from the HTTP PUT

Returns:

true if upload was successful, false otherwise.

canCancel

public boolean canCancel(java.io.OutputStream stream)

Method to determine whether writing to the supplied OutputStream (which must be that returned from getOutputStream()) can be cancelled

Specified by:

canCancel in interface ModifiableSource

Returns:

true if writing to the stream can be cancelled, false otherwise

cancel

public void cancel(java.io.OutputStream stream)
            throws java.io.IOException

Cancels any data sent to the HTTPClientSource.WrappedFileOutputStream returned by getOutputStream(). After calling this method, the supplied HTTPClientSource.WrappedFileOutputStream should no longer be used.

Specified by:

cancel in interface ModifiableSource

Throws:

java.io.IOException