Package io.milton.zsync

Class Upload

java.lang.Object

io.milton.zsync.Upload

public class Upload
extends Object

A container for the information transmitted in a ZSync PUT upload. The information currently consists of some headers (file length, block size, etc...), an InputStream containing a list of RelocateRanges for relocating matching blocks, and an InputStream containing a sequence of data chunks (along with their ranges). The Upload class also contains methods for translating to/from a stream (getInputStream and parse, respectively).

Author:

Nick

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Upload.IteratorEnum<T>	An Enumeration wrapper for an Iterator.
static class	Upload.KeyValue	An object representing a (Key, Value) pair of Strings.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	BLOCKSIZE
static final String	CHARSET	The character encoding used to convert Strings to bytes.
String	DIV	A String that marks the beginning of a range of uploaded bytes.
static final String	FILELENGTH
static final char	LF	The character marking the end of a line.
static final String	NEWDATA	The total number of bytes of new data to be transmitted.
static final String	RANGE
static final String	RELOCATE
static final String	SHA_1
static final String	VERSION

Constructor Summary

Constructors

Constructor	Description
Upload()	Constructs an empty Upload object.

Method Summary

Modifier and Type	Method	Description
long	getBlocksize()	Gets the blocksize used in the upload.
InputStream	getDataStream()	Gets the list of uploaded data chunks ( byte Ranges and their associated data ).
long	getFilelength()	Gets the length of the (assembled) source file being uploaded
InputStream	getInputStream()	Returns an InputStream containing a complete ZSync upload (Params, Relocate stream, and ByteRange stream), ready to be sent as the body of a PUT request.
String	getParams()	Returns the list of headers in String format, in the proper format for upload.
InputStream	getRelocStream()	Gets the list of RelocateRanges, which tells the server which blocks of the previous file to keep, and where to place them in the new file.
String	getSha1()	Gets the checksum for the entire source file
String	getVersion()	Gets the zsync version of the upload sender (client)
static String	paramString(String key, Object value)
static Upload	parse(InputStream in)	Parses the InputStream into an Upload object.
static String	readToken(InputStream in, byte[] delimiters, int maxsearch)	Returns the next String terminated by one of the specified delimiters or the end of the InputStream.
static String	readValue(InputStream in, int maxsearch)	Helper method that reads the String preceding the first newline in the InputStream.
void	setBlocksize(long blocksize)	Sets the blocksize used in the upload.
void	setDataStream(InputStream dataStream)	Sets the list of data chunks to be uploaded ( byte Ranges and their associated data ).
void	setFilelength(long filelength)	Sets the length of the (assembled) source file being uploaded
void	setRelocStream(InputStream relocStream)	Sets the list of RelocateRanges, which tells the server which blocks of the previous file to keep, and where to place them in the new file.
void	setSha1(String sha1)	Sets the checksum for the entire source file, which allow the server to validate the new file after assembling it.
void	setVersion(String version)	Sets the zsync version of the upload sender (client)

Methods inherited from class java.lang.Object

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

Field Details

CHARSET

public static final String CHARSET

The character encoding used to convert Strings to bytes. The default is US-ASCII. The methods involved in parsing assume one byte per character.

See Also:

• Constant Field Values

LF

public static final char LF

The character marking the end of a line. The default is '\n'

See Also:

• Constant Field Values

DIV

public String DIV

A String that marks the beginning of a range of uploaded bytes. Currently unused.

VERSION

public static final String VERSION

See Also:

• Constant Field Values

BLOCKSIZE

public static final String BLOCKSIZE

See Also:

• Constant Field Values

FILELENGTH

public static final String FILELENGTH

See Also:

• Constant Field Values

NEWDATA

public static final String NEWDATA

The total number of bytes of new data to be transmitted. Currently Unused.

See Also:

• Constant Field Values

SHA_1

public static final String SHA_1

See Also:

• Constant Field Values

RELOCATE

public static final String RELOCATE

See Also:

• Constant Field Values

RANGE

public static final String RANGE

See Also:

• Constant Field Values

Constructor Details

Upload

public Upload()

Constructs an empty Upload object. Its fields need to be set individually.

Method Details

getParams

public String getParams()

Returns the list of headers in String format, in the proper format for upload. The list is terminated by the LF character.

Returns:

A String containing the headers

paramString

public static String paramString(String key,
 Object value)

parse

public static Upload parse(InputStream in)

Parses the InputStream into an Upload object.

The method initially parses the headers from the InputStream by reading the sequence of keys (the String preceding the first colon in each line) and values ( the String following the colon and terminated by the LF character ) and invoking parseParam(java.lang.String, java.lang.String) on each key value pair. If the key is RELOCATE, then the value is not read, but is copied into a BufferingOutputStream and stored in the relocStream field. Parsing of headers continues until a "blank" line is reached, ie a line that is null or contains only whitespace, which indicates the beginning of the data section. A reference to the remaining InputStream is then stored in the dataStream field.

Parameters:

in - The InputStream containing the ZSync upload

Returns:

A filled in Upload object

readToken

public static String readToken(InputStream in,
 byte[] delimiters,
 int maxsearch)
                        throws ParseException,
IOException

Returns the next String terminated by one of the specified delimiters or the end of the InputStream.

This method simply reads from an InputStream one byte at a time, up to maxsearch bytes, until it reads a byte equal to one of the delimiters or reaches the end of the stream. It uses the CHARSET encoding to translate the bytes read into a String, which it returns with delimiter excluded, or it throws a ParseException if maxSearch bytes are read without reaching a delimiter or the end of the stream.

A non-buffering method is used because a buffering reader would likely pull in part of the binary data from the InputStream. An alternative is to use a BufferedReader with a given buffer size and use mark and reset to get back binary data pulled into the buffer.

Parameters:

in - The InputStream to read from

delimiters - A list of byte values, each of which indicates the end of a token

maxsearch - The maximum number of bytes to search for a delimiter

Returns:

The String containing the CHARSET decoded String with delimiter excluded

Throws:

IOException

ParseException - If a delimiter byte is not found within maxsearch reads

readValue

public static String readValue(InputStream in,
 int maxsearch)
                        throws ParseException,
IOException

Helper method that reads the String preceding the first newline in the InputStream.

Parameters:

in - The InputStream to read from

maxsearch - The maximum number of bytes allowed in the value

Returns:

The CHARSET encoded String that was read

Throws:

ParseException - If a newline or end of input is not reached within maxsearch reads

IOException

getInputStream

public InputStream getInputStream()
                           throws UnsupportedEncodingException,
IOException

Returns an InputStream containing a complete ZSync upload (Params, Relocate stream, and ByteRange stream), ready to be sent as the body of a PUT request.

Note: In this implementation, any temporary file used to store the RelocateRanges will be automatically deleted when this stream is closed, so a second invocation of this method on the same Upload object is likely to throw an exception. Therefore, this method should be used only once per Upload object.

Returns:

The complete ZSync upload

Throws:

UnsupportedEncodingException

IOException

getVersion

public String getVersion()

Gets the zsync version of the upload sender (client)

setVersion

public void setVersion(String version)

Sets the zsync version of the upload sender (client)

getSha1

public String getSha1()

Gets the checksum for the entire source file

setSha1

public void setSha1(String sha1)

Sets the checksum for the entire source file, which allow the server to validate the new file after assembling it.

getBlocksize

public long getBlocksize()

Gets the blocksize used in the upload.

setBlocksize

public void setBlocksize(long blocksize)

Sets the blocksize used in the upload. The server needs this to translate block ranges into byte ranges

getFilelength

public long getFilelength()

Gets the length of the (assembled) source file being uploaded

setFilelength

public void setFilelength(long filelength)

Sets the length of the (assembled) source file being uploaded

getRelocStream

public InputStream getRelocStream()

Gets the list of RelocateRanges, which tells the server which blocks of the previous file to keep, and where to place them in the new file. The current format is a comma separated list terminated by LF.

setRelocStream

public void setRelocStream(InputStream relocStream)

Sets the list of RelocateRanges, which tells the server which blocks of the previous file to keep, and where to place them in the new file. The current format is a comma separated list terminated by LF.

Parameters:

relocStream -

getDataStream

public InputStream getDataStream()

Gets the list of uploaded data chunks ( byte Ranges and their associated data ).

setDataStream

public void setDataStream(InputStream dataStream)

Sets the list of data chunks to be uploaded ( byte Ranges and their associated data ). The stream should contain no leading whitespace.