com.univocity.api.statistics
Class DataTransferStatistics<S,T>

java.lang.Object
  com.univocity.api.statistics.DataTransferStatistics<S,T>

Type Parameters:

S - the source of data, where data is coming from

T - the target of data, where data is being transferred into.

All Implemented Interfaces:

DataTransfer<S,T>

Direct Known Subclasses:

DownloadStatistics

public class DataTransferStatistics<S,T>
extends Object
implements DataTransfer<S,T>

A basic implementation of DataTransfer which collects statistics about a given data transfer process, and provides easy to use methods to report the progress and timing of the process.

Author:

uniVocity Software Pty Ltd - dev@univocity.com

See Also:

NotificationHandler

Constructor Summary

DataTransferStatistics()
Creates a new data transfer statistics object that doesn't notify the user of updates.

DataTransferStatistics(long notificationInterval, NotificationHandler<DataTransferStatistics<S,T>> handler)
Creates a new data transfer statistics object that notifies the user of updates at given intervals, and when the process completes.

DataTransferStatistics(NotificationHandler<DataTransferStatistics<S,T>> notificationHandler)
Creates a new data transfer statistics object that notifies the user of updates.

Method Summary

void	aborted(S source, T target, Exception error) Notifies that the data transfer has been aborted.
void	completed(S source, T target) Notifies that a data transfer has been finalized.
boolean	equals(Object o)
Exception	getAbortError() Returns the exception, if any, that caused the interruption of data transfer process.
double	getAverageRate() Returns the average transfer rate, in milliseconds.
double	getAverageRate(TimeUnit timeUnit) Returns the average transfer rate, using a given TimeUnit
long	getEndTime() Returns the data transfer end time, in milliseconds.
String	getEndTime(String dateMask) Returns the data transfer end time, in milliseconds.
String	getEndTime(String dateMask, String valueOnError) Returns the data transfer end time, in milliseconds.
String	getFormattedAverageRate() Returns a formatted String representing the average rate, per second, at which the data is being transferred to the target
String	getFormattedAverageRate(NumberFormat format, TimeUnit timeUnit, String rateSymbol) Returns a formatted String representing the average rate at which the data is being transferred to the target.
String	getFormattedRatePerSecond() Returns a formatted String representing the approximate rate, per second, at which the data was being transferred to the target during the previous second.
String	getFormattedRatePerSecond(NumberFormat format, String rateSymbol) Returns a formatted String representing the approximate rate at which the data was transferred during the previous second.
String	getFormattedTotalSize() Returns a formatted String representing the total size of the source to be transferred to the target, if available.
String	getFormattedTotalSize(NumberFormat format, String valueIfUnknown) Returns a formatted String representing the total size of the source to be transferred to the target, if available.
String	getFormattedTotalTransferredSoFar() Returns a formatted String representing the amount size of data already to be transferred to the target
String	getFormattedTotalTransferredSoFar(NumberFormat format) Returns a formatted String representing the amount size of data already to be transferred to the target
String	getFormattedTransferPercentage() Returns the percentage of data already transferred, formatted a decimal number between 0% and 100% inclusive, or ?% if unknown
String	getFormattedTransferPercentage(NumberFormat format, String valueIfUnknown) Returns a formatted String representing the percentage of data already transferred
double	getRatePerSecond() Returns the approximate transfer rate at which the data was transferred during the previous second.
S	getSource() Returns the source of data
long	getStartTime() Returns the data transfer start time, in milliseconds.
String	getStartTime(String dateMask) Returns the data transfer start time, as a formatted date.
String	getStartTime(String dateMask, String valueOnError) Returns the data transfer start time, as a formatted date.
T	getTarget() Returns the destination of the data transferred from the source.
long	getTimeElapsed() Returns the number of milliseconds the data transfer took so far.
double	getTimeElapsed(TimeUnit timeUnit) Returns how long the data transfer took so far, using a given time unit.
double	getTotalSize() Returns the total size of the source to be transferred to the target, if available.
double	getTotalTransferredSoFar() Returns the total amount transferred already.
double	getTransferPercentage() Returns the percentage of data already transferred, (where 0.0 represents 0% and 1.0 represents 100%)
String	getUnitDescription() Returns a description of the unit of data being transferred.
long	getUnitDivisor() Returns the unit divisor currently in use.
int	hashCode()
boolean	isAborted() Returns a flag indicating whether the data transfer was aborted.
boolean	isRunning() Returns a flag indicating whether the data transfer is running.
boolean	isStarted() Returns a flag indicating whether the data transfer has been started.
protected void	setNotificationHandler(long notificationInterval, NotificationHandler<DataTransferStatistics<S,T>> handler) Associates a notification handler callback to receive updates from the data transfer operation at at most after a given amount of time has elapsed.
protected void	setNotificationHandler(NotificationHandler<DataTransferStatistics<S,T>> handler) Associates a notification handler callback to receive updates from the data transfer operation
void	setUnit(String unitDescription) Defines a description of the unit of data being transferred.
void	setUnit(String unitDescription, long unitDivisor) Defines a description of the unit of data being transferred and updates the unit divisor to amounts will be returned taking into account the division of the totals by the given divisor.
void	started(S source, long totalSize, T target) Notifies a data transfer has been started.
String	toString()
void	transferred(S source, long transferred, T target) Notifies how much data has been transferred from source to target.

Methods inherited from class java.lang.Object

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

Constructor Detail

DataTransferStatistics

public DataTransferStatistics()

Creates a new data transfer statistics object that doesn't notify the user of updates. Users are expected to query this object at their discretion to obtain the process' status

DataTransferStatistics

public DataTransferStatistics(NotificationHandler<DataTransferStatistics<S,T>> notificationHandler)

Creates a new data transfer statistics object that notifies the user of updates. Users can query this object at their discretion to obtain the process' status and will receive notification of any updates to this process as soon as they occur.

Parameters:

notificationHandler - the notification callback that will receive updates as soon as the statistics are changed.

DataTransferStatistics

public DataTransferStatistics(long notificationInterval,
                              NotificationHandler<DataTransferStatistics<S,T>> handler)

Creates a new data transfer statistics object that notifies the user of updates at given intervals, and when the process completes. Users can query this object at their discretion to obtain the process' status and will receive notification of updates to this process, after a given interval to avoid excessive processing.

Parameters:

notificationInterval - the minimum interval, in milliseconds, before notifying the provided callback of updates.

handler - the notification callback that will receive updates as soon as the statistics are changed.

Method Detail

setNotificationHandler

protected final void setNotificationHandler(NotificationHandler<DataTransferStatistics<S,T>> handler)

Associates a notification handler callback to receive updates from the data transfer operation

Parameters:

handler - the callback that will be used every time the data transfer statistics are updated

setNotificationHandler

protected final void setNotificationHandler(long notificationInterval,
                                            NotificationHandler<DataTransferStatistics<S,T>> handler)

Associates a notification handler callback to receive updates from the data transfer operation at at most after a given amount of time has elapsed.

Parameters:

notificationInterval - the minimum interval in milliseconds to wait before the next call to NotificationHandler.notify(Object, boolean) should be performed. Prevents excessive notifications.

handler - the callback that will be used every time the data transfer statistics are updated

getUnitDescription

public final String getUnitDescription()

Returns a description of the unit of data being transferred.

Returns:

a description of the unit of data being transferred.

setUnit

public final void setUnit(String unitDescription)

Defines a description of the unit of data being transferred.

Parameters:

unitDescription - the description of what is being transferred

setUnit

public void setUnit(String unitDescription,
                    long unitDivisor)

Defines a description of the unit of data being transferred and updates the unit divisor to amounts will be returned taking into account the division of the totals by the given divisor. This allows you to convert totals accumulated as bytes into kilobytes (unitDivisor = 1024) or megabytes (unitDivisor = 1024*1024) for example.

Parameters:

unitDescription - the description of what unit of data is being transferred

unitDivisor - the divisor to be applied over the totals accumulated by this class, so that the units

getUnitDivisor

public final long getUnitDivisor()

Returns the unit divisor currently in use. The unit divisor allows you to convert totals accumulated as bytes into kilobytes (unitDivisor = 1024) or megabytes (unitDivisor = 1024*1024) for example.

Returns:

the divisor to be applied over the totals accumulated by this class

started

public final void started(S source,
                          long totalSize,
                          T target)

Description copied from interface: DataTransfer

Notifies a data transfer has been started.

Specified by:

started in interface DataTransfer<S,T>

Parameters:

source - the source of data

totalSize - the total size of the data. The meaning of the amount provided depends on the underlying implementation: this can be bytes, number of records, etc. If -1, the total size is unknown ahead of time.

target - the data target

transferred

public final void transferred(S source,
                              long transferred,
                              T target)

Description copied from interface: DataTransfer

Notifies how much data has been transferred from source to target. Can be invoked multiple times until the data transfer is completed or aborted.

Specified by:

transferred in interface DataTransfer<S,T>

Parameters:

source - the source of data

transferred - the amount of data transferred since the last time this method was called. The meaning of the amount provided depends on the underlying implementation: this can be bytes, number of records, etc.

target - the data target

completed

public final void completed(S source,
                            T target)

Description copied from interface: DataTransfer

Notifies that a data transfer has been finalized.

Specified by:

completed in interface DataTransfer<S,T>

Parameters:

source - the source of data

target - the data target

aborted

public final void aborted(S source,
                          T target,
                          Exception error)

Description copied from interface: DataTransfer

Notifies that the data transfer has been aborted.

Specified by:

aborted in interface DataTransfer<S,T>

Parameters:

source - the source of data

target - the data target

error - exception that caused the process abortion.

getAverageRate

public final double getAverageRate()

Returns the average transfer rate, in milliseconds.

Returns:

the number number of data elements measured by the underlying implementation transferred per millisecond.

getAverageRate

public final double getAverageRate(TimeUnit timeUnit)

Returns the average transfer rate, using a given TimeUnit

Parameters:

timeUnit - the time unit used to calculate the transfer rate.

Returns:

the number number of data elements measured by the underlying implementation transferred per a given unit of time

getTimeElapsed

public final long getTimeElapsed()

Returns the number of milliseconds the data transfer took so far.

Returns:

the number of milliseconds the data transfer took so far.

getTimeElapsed

public final double getTimeElapsed(TimeUnit timeUnit)

Returns how long the data transfer took so far, using a given time unit.

Parameters:

timeUnit - the unit of time to use to represent the time elapsed.

Returns:

how long the data transfer took so far.

getTotalTransferredSoFar

public final double getTotalTransferredSoFar()

Returns the total amount transferred already.

Returns:

the total amount transferred already.

getTotalSize

public final double getTotalSize()

Returns the total size of the source to be transferred to the target, if available. If the process completed successfully, returns the amount transferred. The meaning of the amount returned depends on the underlying implementation: this can be bytes, number of records, etc. If negative, the total size is unknown ahead of time.

Returns:

the total size to transfer, if known. Otherwise, returns a negative value. If the process completed successfully, returns the amount transferred.

getStartTime

public final long getStartTime()

Returns the data transfer start time, in milliseconds.

Returns:

the start time

getStartTime

public final String getStartTime(String dateMask,
                                 String valueOnError)

Returns the data transfer start time, as a formatted date.

Parameters:

dateMask - a date mask following the rules specified by SimpleDateFormat

valueOnError - a default value to be returned in case of errors generating the formatted date.

Returns:

the start time

getStartTime

public final String getStartTime(String dateMask)

Returns the data transfer start time, as a formatted date.

Parameters:

dateMask - a date mask following the rules specified by SimpleDateFormat

Returns:

the start time

getEndTime

public final long getEndTime()

Returns the data transfer end time, in milliseconds. If it is still ongoing, returns -1

Returns:

the end time, or -1 of the process is still running.

getEndTime

public final String getEndTime(String dateMask,
                               String valueOnError)

Returns the data transfer end time, in milliseconds. If it is still ongoing, returns -1

Parameters:

dateMask - a date mask following the rules specified by SimpleDateFormat

valueOnError - a default value to be returned in case of errors generating the formatted date.

Returns:

the end time, or -1 of the process is still running.

getEndTime

public final String getEndTime(String dateMask)

Returns the data transfer end time, in milliseconds. If it is still ongoing, returns -1

Parameters:

dateMask - a date mask following the rules specified by SimpleDateFormat

Returns:

the end time, or -1 of the process is still running.

getTransferPercentage

public final double getTransferPercentage()

Returns the percentage of data already transferred, (where 0.0 represents 0% and 1.0 represents 100%)

Returns:

the percentage of data already transferred.

getSource

public final S getSource()

Returns the source of data

Returns:

the source of data

getTarget

public final T getTarget()

Returns the destination of the data transferred from the source.

Returns:

the data destination.

getAbortError

public final Exception getAbortError()

Returns the exception, if any, that caused the interruption of data transfer process.

Returns:

the cause of the interruption of this data transfer.

isStarted

public final boolean isStarted()

Description copied from interface: DataTransfer

Returns a flag indicating whether the data transfer has been started.

Specified by:

isStarted in interface DataTransfer<S,T>

Returns:

a flag indicating whether the data transfer has been started.

isRunning

public final boolean isRunning()

Description copied from interface: DataTransfer

Returns a flag indicating whether the data transfer is running.

Specified by:

isRunning in interface DataTransfer<S,T>

Returns:

a flag indicating whether the data transfer is running.

isAborted

public final boolean isAborted()

Description copied from interface: DataTransfer

Returns a flag indicating whether the data transfer was aborted.

Specified by:

isAborted in interface DataTransfer<S,T>

Returns:

a flag indicating whether the data transfer was aborted.

equals

public final boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public final int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object

getFormattedTransferPercentage

public String getFormattedTransferPercentage(NumberFormat format,
                                             String valueIfUnknown)

Returns a formatted String representing the percentage of data already transferred

Parameters:

format - the numeric format to use to represent the percentage.

valueIfUnknown - the String to return if the percentage cannot be determined.

Returns:

the formatted percentage of data already transferred.

getFormattedTransferPercentage

public String getFormattedTransferPercentage()

Returns the percentage of data already transferred, formatted a decimal number between 0% and 100% inclusive, or ?% if unknown

Returns:

the formatted percentage of data already transferred.

getRatePerSecond

public final double getRatePerSecond()

Returns the approximate transfer rate at which the data was transferred during the previous second.

Returns:

the number number of data elements measured by the underlying implementation transferred during the previous second.

getFormattedRatePerSecond

public String getFormattedRatePerSecond(NumberFormat format,
                                        String rateSymbol)

Returns a formatted String representing the approximate rate at which the data was transferred during the previous second.

Parameters:

format - the numeric format to use to represent the rate.

rateSymbol - the symbol to be displayed after the rate

Returns:

the formatted approximate rate at which the data was transferred during the previous second.

getFormattedRatePerSecond

public String getFormattedRatePerSecond()

Returns a formatted String representing the approximate rate, per second, at which the data was being transferred to the target during the previous second.

Returns:

the formatted rate at which the data is being transferred during the previous second.

getFormattedAverageRate

public String getFormattedAverageRate(NumberFormat format,
                                      TimeUnit timeUnit,
                                      String rateSymbol)

Returns a formatted String representing the average rate at which the data is being transferred to the target.

Parameters:

format - the numeric format to use to represent thea average rate.

timeUnit - the unit of time to be used to calculate the average rate.

rateSymbol - the symbol to be displayed after the rate

Returns:

the formatted average rate at which the data is being transferred

getFormattedAverageRate

public String getFormattedAverageRate()

Returns a formatted String representing the average rate, per second, at which the data is being transferred to the target

Returns:

the formatted average rate at which the data is being transferred

getFormattedTotalTransferredSoFar

public String getFormattedTotalTransferredSoFar(NumberFormat format)

Returns a formatted String representing the amount size of data already to be transferred to the target

Parameters:

format - the numeric format to use to represent the amount.

Returns:

the formatted total amount already transferred

getFormattedTotalTransferredSoFar

public String getFormattedTotalTransferredSoFar()

Returns a formatted String representing the amount size of data already to be transferred to the target

Returns:

the formatted total amount already transferred

getFormattedTotalSize

public String getFormattedTotalSize(NumberFormat format,
                                    String valueIfUnknown)

Returns a formatted String representing the total size of the source to be transferred to the target, if available.

Parameters:

format - the numeric format to use to represent the total.

valueIfUnknown - the String to return if the total size cannot be determined.

Returns:

the formatted total amount to be transferred

getFormattedTotalSize

public String getFormattedTotalSize()

Returns a formatted String representing the total size of the source to be transferred to the target, if available.

Returns:

the formatted total amount to be transferred