org.apache.excalibur.source.impl
Class HTTPClientSource

java.lang.Object
  extended by org.apache.avalon.framework.logger.AbstractLogEnabled
      extended by 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