com.ibm.tspaces
Class URLCopy

java.lang.Object
  |
  +--com.ibm.tspaces.URLCopy

public class URLCopy

extends java.lang.Object

implements java.io.Serializable

URLCopy implements support for copying data (from a file or website) to and from a TupleSpace. This will allow the data pointed to by the URL to be passed from client to client thru a TSpaces server.

To use the URLCopy services, the Server FileStore facility must be turned on by specifing the CacheDir parameter in the tspaces.cfg file. In the distributed configuration file, it is not specified!

The advantage of sending a file to the server via URLCopy versus reading the file and sending it as an array of bytes is twofold.
- The protocol used by URLCopy to send a file is many times faster than the protocol used to serialize and deserialize an array of bytes.
- The data at the server is saved in a file instead of in memory.
Both of these are most important when the file is very large. It is also useful, when you want the file to be accessed at the server via a URL instead of directly accessing the bytes.

A typical use would be for a client to construct a URL that points to a local file or network URL. The client would then create a URLCopy object specifing this URL and write this to TSpaces in a Tuple Field just like one would do with any other object. .

   URL myurl = new URL("file:/c:/file.txt");
   URLCopy copy = new URLCopy(myurl);
   Field fieldURL = new Field(copy);
   ts.write("MyFile",fieldURL);

  an alternative form would be:
   URLCopy copy2 = new URLCopy("c:/file.txt");
   ts.write("MyFile2",copy2);
 

When passed to the TSpaces server, the actual contents of the file addressed by the URL will be bundled up and sent to the server where it will be stored in an appropriate database.

The setRetention() method can be used to set the time to keep the file on the server before making it elgible for deletion by a cleanup process. Currently the default retention period is set to 24 hours(24*60*60).

If another TSpaces client then reads or takes the Tuple, the resulting URLCopy object can be used to access and store the data on the local client using the "copyToLocal(Directory)" method which copies the data to the local client. Or the "getServerURL()" method can be used to obtain a URL to the data that resides on the server. Both methods are shown in the following example:

To obtain and access a copy of the URL data on another client.

   Tuple tup = ts.read("MyFile",new Field(URLCopy.class));
   URLCopy copy = (URLCopy)tup.getField(1).value(); 
   URL url1 = copy.getServerURL();
   copy.copyToLocal("c:/temp");  // where to put it
   URL url2 = copy.getURL();  
   // At this point the URL would be "file:/c:/temp/file.txt"
 

In the above example, "url1" would contain a URL address that points to the data on the server. For Example:
http://TSserver:8201/filestore/file95.bin

By default, the copyToLocal method will remove the data from the server. This can be overriden with an optional parameter:

copyToLocal(String fileFolder, boolean KeepData)

It is possible that the file will be left open on the server and the delete will fail. However in this case the file will be set to 0 length and the file will be garbage collected on the next server restart.

After invoking the copyToLocal method, the getURL() method will return a URL pointing to the local file. For Example:
file:/c:/temp/file.txt

Author:

John Thomas

See Also:

TupleSpace, URL, Serializable, Serialized Form

Constructor Summary

URLCopy(java.lang.String filepath)
This constructor takes a filename and builds a URL object that is used in further processing This constructor can only be used on a TSpaces client to create the original URLCopy object.

URLCopy(java.net.URL url)
This constructor can only be used on a TSpaces client to create the original URLCopy object based on a URL.

Method Summary

void	copyToLocal(java.lang.String folder) copyToLocal will copy the URL data from the Server to a local file
void	copyToLocal(java.lang.String folder, boolean keep) copyToLocal will copy the URL data from the Server to a local file It will do the copy by specifing a URL that points to the HTTP server maintained by TSpaces and using it to read the file and serve it to the client.
boolean	equals(java.lang.Object other) Provide a proper equals(Object other) method for URLCopy.
java.lang.String	getFileName() getSFileName will return the original file name based on the original URL.
java.net.URL	getOriginalURL() getOriginalURL will return the URL used to create the object.
java.net.URL	getServerURL() getServerURL will return the URL pointing to the data on the Server.
java.net.URL	getURL() getURL will return a URL that points to a valid copy of the URL data.
boolean	isCopyOK() isCopyOK will return true if the File was sucessfull written to the T Spaces Server.
static void	main(java.lang.String[] argv) Test the URLCopy Object.
void	setRetention(long retentionPeriod) setRetetion will set the time to keep the file on the server before making it elgible for deletion by a cleanup process.
java.lang.String	toString() Debug helper that displays the current object status

Methods inherited from class java.lang.Object

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

Constructor Detail

URLCopy

public URLCopy(java.lang.String filepath)
        throws java.net.MalformedURLException

This constructor takes a filename and builds a URL object that is used in further processing This constructor can only be used on a TSpaces client to create the original URLCopy object. (FUTURE WORK) NOTE: We need to do more checking of the filename!!!!!!

Parameters:

filepath - The complete filepath

URLCopy

public URLCopy(java.net.URL url)
        throws java.net.MalformedURLException

This constructor can only be used on a TSpaces client to create the original URLCopy object based on a URL. We need to do more checking of the filename!!!!!!

Parameters:

url - A URL object that represents a file.

Method Detail

getURL

public java.net.URL getURL()

getURL will return a URL that points to a valid copy of the URL data.

getOriginalURL

public java.net.URL getOriginalURL()

getOriginalURL will return the URL used to create the object.

isCopyOK

public boolean isCopyOK()

isCopyOK will return true if the File was sucessfull written to the T Spaces Server. It will return false if not. The most common cause for it not to be written would be that the Server is not running the TSFileStore component.

getServerURL

public java.net.URL getServerURL()

getServerURL will return the URL pointing to the data on the Server.

getFileName

public java.lang.String getFileName()

getSFileName will return the original file name based on the original URL.

setRetention

public void setRetention(long retentionPeriod)

setRetetion will set the time to keep the file on the server before making it elgible for deletion by a cleanup process.

The time is specified in seconds. Currently the default retention period is set to 24 hours(24*60*60).

Parameters:

Retention - time in seconds

copyToLocal

public void copyToLocal(java.lang.String folder)

copyToLocal will copy the URL data from the Server to a local file

Parameters:

folder - specifies the folder where the data is to be placed.

copyToLocal

public void copyToLocal(java.lang.String folder,
                        boolean keep)

copyToLocal will copy the URL data from the Server to a local file It will do the copy by specifing a URL that points to the HTTP server maintained by TSpaces and using it to read the file and serve it to the client.

Parameters:

folder - specifies the folder where the data is to be placed.

keep - specifies if the file should be kept on the server.

equals

public boolean equals(java.lang.Object other)

Provide a proper equals(Object other) method for URLCopy. This will return true if all of the following conditions are true:
- (Object other) is an instance of URLCopy
- The original URLs match i.e. _OriginalURL.equals(other.getOriginalURL()

Overrides:

equals in class java.lang.Object

Parameters:

Object - other is the URLCopy object to compare this to

toString

public java.lang.String toString()

Debug helper that displays the current object status

Overrides:

toString in class java.lang.Object

main

public static void main(java.lang.String[] argv)

Test the URLCopy Object.