com.algosome.common.io
Class URLConnect

java.lang.Object
  com.algosome.common.io.URLConnect

public class URLConnect
extends java.lang.Object

URLConnect is a class that can be used to connect to and read a website. This class provides functionality to perform GET and PUT methods for dynamic websites, the parameters of which are stored within a hashmap keyed with the parameters. Parameters are formatted into a query string using the getQueryString function, the default implementation uses UTF-8 encoding.

Note: WWW consortium stipulates UTF-8 encoding should always be used: UTF-8 is the default encoding of this object.

To utilize this object properly, users must

• Create a class that implements the InputStreamParser interface.
• Call setURL with a properly formatted URL
• Define any parameters necessary for a query string
• Specify if GET or PUT will be used (default: GET)
• Call doQuery to submit the URL and parse the output.

Version:

1.1

Author:

Greg Cope

Field Summary

protected java.lang.String	encoding The type of encoding to use for the URL submission.
protected java.util.Map<java.lang.String,java.lang.String>	parameters HashMap defining parameters and values for a GET or PUT query string.
protected boolean	query_method Indicates whether GET or PUT will be used to contact a server.
protected java.lang.String	url Specifies a URL to look up.

Constructor Summary

URLConnect()
Creates an empty URLConnect object containing no parameters.

URLConnect(java.lang.String url)
Creates a URLConnect object with a given URL

URLConnect(URLConnect e)
Creates an URLConnect object from a previous URLConnect object.

Method Summary

void	doQuery(InputStreamParser parser) Performs an HTTP request to NCBI: sets the URL based upon the current query method, then calls retrieveURLOutput.
java.lang.String	getEncoding() Retrieves the encoding of this object.
java.lang.String	getParameter(java.lang.String param) Retrieves the value to a parameter, or null if none has been set.
boolean	getQueryMethod() Retrieves the HTTP method for query strings.
java.lang.String	getQueryString() Retrieves a query string based upon the current parameters.
java.lang.String	getURL() Retrieves the URL associated with this object.
protected void	retrieveURLOutput(java.lang.String url, InputStreamParser parser) Retrieves the output from the given url parameter.
void	setEncoding(java.lang.String encoding) Sets the encoding of this object.
void	setParameter(java.lang.String param, java.lang.String value) Sets the value to a parameter for dynamic websites.
void	setQueryMethod(boolean b) Sets the HTTP method for query strings.
void	setURL(java.lang.String u) Sets the main URL to retrieve

Methods inherited from class java.lang.Object

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

Field Detail

parameters

protected java.util.Map<java.lang.String,java.lang.String> parameters

HashMap defining parameters and values for a GET or PUT query string.

url

protected java.lang.String url

Specifies a URL to look up. Default implementation is null. If this is NOT set via setURL, an IOException will be thrown.

query_method

protected boolean query_method

Indicates whether GET or PUT will be used to contact a server. Set to true if you wish to use GET protocol, or false if you wish to use PUT protocol.

encoding

protected java.lang.String encoding

The type of encoding to use for the URL submission. Default is UTF-8

Constructor Detail

URLConnect

public URLConnect()

Creates an empty URLConnect object containing no parameters.

URLConnect

public URLConnect(java.lang.String url)

Creates a URLConnect object with a given URL

Parameters:

url - The URL to set this object to retrieve.

URLConnect

public URLConnect(URLConnect e)

Creates an URLConnect object from a previous URLConnect object.

Parameters:

e - A pre-formed URLConnect object containing a set of parameters to use.

Method Detail

setURL

public void setURL(java.lang.String u)

Sets the main URL to retrieve

Parameters:

u - A String represention of the URL associated with this object.

getURL

public java.lang.String getURL()

Retrieves the URL associated with this object.

Returns:

A String representation of the URL associated with this object.

setQueryMethod

public void setQueryMethod(boolean b)

Sets the HTTP method for query strings. Default behavior is GET.

Parameters:

b - A boolean indicating the type of HTTP method to use

• true: GET
• false: PUT

getQueryMethod

public boolean getQueryMethod()

Retrieves the HTTP method for query strings. Default behavior is GET.

Returns:

A boolean indicating the type of HTTP method to use

• true: GET
• false: PUT

getEncoding

public java.lang.String getEncoding()

Retrieves the encoding of this object.

Returns:

String representation of the encoding type.

setEncoding

public void setEncoding(java.lang.String encoding)

Sets the encoding of this object.

Note: WWW specifies URL encoding to be UTF-8. Changing this value from the default may result in unexpected behavior.

Parameters:

encoding - String representation of the encoding type.

See Also:

WWW Consortium for more on URL encoding.

setParameter

public void setParameter(java.lang.String param,
                         java.lang.String value)

Sets the value to a parameter for dynamic websites. In the case of a query string, this equates to: param=value&

Parameters:

param - The parameter key

value - The value of the parameter.

getParameter

public java.lang.String getParameter(java.lang.String param)

Retrieves the value to a parameter, or null if none has been set. In the case of a query string, this retrieves the value portion of: param=value&

Parameters:

param - The parameter to retrieve

Returns:

A String containing the value of the parameter, or null if none was found.

retrieveURLOutput

protected void retrieveURLOutput(java.lang.String url,
                                 InputStreamParser parser)
                          throws java.io.IOException,
                                 java.io.UnsupportedEncodingException

Retrieves the output from the given url parameter. This function can be called direct, but is called indirectly through doQuery. Calls parseOutput of the input parser to parse the output depending upon implementation.

Parameters:

url - The URL to read and return the contents.

parser - An object that implements the InputStreamParser interface.

Throws:

java.io.IOException - if a connection could not be read or established.

java.io.UnsupportedEncodingException - If encoding of a POST query could not be established.

See Also:

doQuery(InputStreamParser parser), com.io.InputStreamParser

getQueryString

public java.lang.String getQueryString()
                                throws java.io.UnsupportedEncodingException

Retrieves a query string based upon the current parameters.

Returns:

A String in the format of a query string. (e.g. term=x&db=protein)

Throws:

java.io.UnsupportedEncodingException - in the case the appropriate encoding cannot be used.

doQuery

public void doQuery(InputStreamParser parser)
             throws java.io.IOException,
                    java.io.UnsupportedEncodingException

Performs an HTTP request to NCBI: sets the URL based upon the current query method, then calls retrieveURLOutput. Indirectly calls parseOutput of the parser via retrieveURLOutput.

Parameters:

parser - An object that implements the InputStreamParser interface.

Throws:

java.io.IOException - if the connecetion cannot be read or established.

java.io.UnsupportedEncodingException - If the submission cannot be UTF-8 Encoded.

See Also:

retrieveURLOutput(String url, InputStreamParser is), com.io.InputStreamParser