com.ccg.net
Class URLPost

java.lang.Object
  com.ccg.net.URLPost

public class URLPost
extends Object

Class designed to communicate with a HTTP server by posting arguments.

When dealing with HTTP server's one may find themselves in a position where they need to "POST" arguments to the server in a fashion similar to the way in which a web browser might post data from a form submission.

This class provides a lot of help in this regard. Basically, you use it as follows:

• Create the object.
• Add the parameter name/value pairs you want to post (you don't need to encode them, the necessary encoding will be done for you).
• Open a connection - the parameters you have specified will be posted to the server.
• Then open the InputStream from the returned URLConnection and process the server's response.
• Finally, you should then close the InputStream once you are done reading from it.

The following example demonstrates how one might do this:

 import com.ccg.io.*;
 import com.ccg.net.*;
 
 import java.io.*;
 import java.net.*;
 
 public class Foo {
 
        static public void main(String args[]) {
                try {
                        URLPost post = new URLPost();
                        if ((args.length % 2) != 1) {
                                System.err.println("usage: java com.ccg.net.URLPost URL "
                                                + "[KEY0 VAL0 [KEY1 VAL1 ...]]");
                        }
                        post.setURL(new URL(args[0]));
                        for (int i = 1; i < args.length; i += 2) {
                                post.addParameter(args[i], args[i + 1]);
                        }
                        System.err.println("URL:" + post.getURL() + "  parameters:" + post);
 
                        InputStream in = post.open().getInputStream();
                        Copy.streamToStream(in, System.out);
 
                        in.close();
                } catch (Exception e) {
                        e.printStackTrace();
                }
 
        }
 }
 

Since:

1.0

Version:

$Revision: 1.4 $

Author:

$Author: pkb $

See Also:

URLCat

Field Summary

static String

MIME_TYPE_SERIALIZED_OBJECT The mime type for serialized Java objects.

Constructor Summary

URLPost()
Initializes object with no information.

Method Summary

void	addParameter(Object name, Object val) Add a single name/value pair.
void	addParameters(Dictionary ht) Add a entire table of parameters.
void	addParameters(LookupKeyed ht) Add a entire table of parameters.
void	clearParameters() Remove all of the NAME/VALUE pairs that will be POSTed.
URL	getURL() Get the URL which we will open and post parameters to.
boolean	getUseCaches() Indicates if we should use cached results if available.
URLConnection	open() Open a connection to the URL and POST parameters.
URLConnection	open(URL url) Open a connection to a URL and POST parameters.
void	removeParameter(Object key) Remove a NAME/VALUE pair.
void	setURL(URL val) Set the URL which we will open and post parameters to.
void	setUseCaches(boolean val) Set whether we should use cached results if available.
String	toString() Return the string representation of the object.

Methods inherited from class java.lang.Object

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

Field Detail

MIME_TYPE_SERIALIZED_OBJECT

public static final String MIME_TYPE_SERIALIZED_OBJECT

The mime type for serialized Java objects.

While browsing the web one day, I came across something that indicated that there was a MIME type assigned for serialized java objects which had the form:

 application / x - java - serialized - object
 

This constant can be used to refer to this MIME type (if you use this constant and a different MIME type is found - you won't need to recompile your code).

As a side note, it looks like a file extension of "ser" is commonly used for serialized java objects.

Since:

1.0

See Also:

Constant Field Values

Constructor Detail

URLPost

public URLPost()

Initializes object with no information.

After constructing the object in this form, one will want to use one of the add methods to add name/value pairs to be posted to the server.

Since:

1.0

See Also:

addParameter(java.lang.Object, java.lang.Object), addParameters(java.util.Dictionary)

Method Detail

addParameters

public void addParameters(Dictionary ht)

Add a entire table of parameters.

This method can be used to load an entire table of parameters (such as a standard Properties object might contain). All of the key/value pairs from the passed table will be added.

Parameters:

table - The table of name/value pairs to add

Since:

1.0

See Also:

addParameter(java.lang.Object, java.lang.Object)

addParameters

public void addParameters(LookupKeyed ht)

Add a entire table of parameters.

This method can be used to load an entire table of parameters (as maintained by the generic LookupKeyed object. All of the key/value pairs from the passed table will be added.

Parameters:

table - The table of name/value pairs to add

Since:

1.0

See Also:

addParameter(java.lang.Object, java.lang.Object)

addParameter

public void addParameter(Object name,
                         Object val)

Add a single name/value pair.

This method adds a single NAME/VALUE pair to the the list of arguments to post. The NAME/VALUE pair should NOT be URL encoded (we will do that when we post the arguments to the server). For example, the following three calls:

 urlpost.addParameter("ld", "Paul Blankenbaker");
 urlpost.addParameter("first", "(hi)");
 urlpost.addParameter("fred", "");
 

Would result in the following encoded parameters being POSTed to the server when the connection is opened:

 "ld=Paul+Blankenbaker&first=%28hi%29&fred="
 

Parameters:

name - The NAME of the NAME/VALUE pair that will be POSTed

arg2 - The VALUE of the NAME/VALUE pair that will be POSTed

Since:

1.0

See Also:

removeParameter(java.lang.Object), clearParameters(), addParameters(Dictionary), addParameters(LookupKeyed)

removeParameter

public void removeParameter(Object key)

Remove a NAME/VALUE pair.

This method can be used to remove a NAME/VALUE pair from the list of parameters that will be posted to the server.

Parameters:

name - The NAME of the parameter to remove from the list of NAME/VALUE pairs to POST to the server.

Since:

1.0

See Also:

addParameter(java.lang.Object, java.lang.Object)

clearParameters

public void clearParameters()

Remove all of the NAME/VALUE pairs that will be POSTed.

This method clears ALL of the NAME/VALUE parameter pairs that will be POSTed the next time a connection is opened. Most likely you will want to add parameters after using this method.

Since:

1.0

See Also:

addParameter(java.lang.Object, java.lang.Object)

setURL

public void setURL(URL val)

Set the URL which we will open and post parameters to.

Parameters:

val - New URL value to assign.

See Also:

getURL()

getURL

public URL getURL()

Get the URL which we will open and post parameters to.

Returns:

Current URL value assigned.

See Also:

setURL(java.net.URL)

open

public URLConnection open(URL url)
                   throws IOException

Open a connection to a URL and POST parameters.

This method changes the URL associated with the object, attempts to establish a connection and POSTs the parameters that have been added.

Parameters:

url - The URL to connect to (must not be null).

Returns:

A connection to the server from which you can get the InputStream from.

Throws:

IOException - If there is a problem establishing the connection.

Since:

1.0

See Also:

open()

open

public URLConnection open()
                   throws IOException

Open a connection to the URL and POST parameters.

This method attempts to establish a connection to the current URL and POSTs the parameters that have been added.

Returns:

A connection to the server from which you can get the InputStream from.

Throws:

IOException - If there is a problem establishing the connection.

Since:

1.0

See Also:

setURL(java.net.URL), open(URL)

setUseCaches

public void setUseCaches(boolean val)

Set whether we should use cached results if available.

Parameters:

val - New boolean value to assign.

See Also:

getUseCaches()

getUseCaches

public boolean getUseCaches()

Indicates if we should use cached results if available.

Returns:

Current boolean value assigned.

See Also:

setUseCaches(boolean)

toString

public String toString()

Return the string representation of the object.

This method returns the string representation of the object which is a list of all of the NAME/VALUE pairs that will be posted to the server (they are URLEncoded in the returned string and ready to send).

Overrides:

toString in class Object

Returns:

URL encoded representation of name/value pairs to POST to the server.

Since:

1.0

See Also:

addParameter(java.lang.Object, java.lang.Object)