From 7d6344a6fb24de98599f6d8b289bc9e6a9416022 Mon Sep 17 00:00:00 2001 From: Google Code Exporter Date: Wed, 27 Apr 2016 23:49:32 -0400 Subject: [PATCH] Migrating wiki contents from Google Code --- ConfigurableProperties.md | 160 +++++++++++++++++++ Flow.md | 64 ++++++++ JavaLargeFileUploader.md | 318 ++++++++++++++++++++++++++++++++++++++ PendingFile.md | 48 ++++++ ProjectHome.md | 88 +++++++++++ Setup.md | 52 +++++++ Usage.md | 44 ++++++ 7 files changed, 774 insertions(+) create mode 100644 ConfigurableProperties.md create mode 100644 Flow.md create mode 100644 JavaLargeFileUploader.md create mode 100644 PendingFile.md create mode 100644 ProjectHome.md create mode 100644 Setup.md create mode 100644 Usage.md diff --git a/ConfigurableProperties.md b/ConfigurableProperties.md new file mode 100644 index 0000000..7fc989a --- /dev/null +++ b/ConfigurableProperties.md @@ -0,0 +1,160 @@ +## Java properties ## + +Some Java properties are exposed and can be configured using a properties file. + +You can add a _java-large-file-uploader.properties_ file to your classpath which can include: + + + +#### maximumRatePerClientInKiloBytes #### + +``` +jlfu.ratelimiter.maximumRatePerClientInKiloBytes +``` + +The maximum upload rate per client in kilo bytes. (Default is 10240 (10MB/s)) + +Exposed as MBean. + + + +#### maximumOverAllRateInKiloBytes #### + +``` +jlfu.ratelimiter.maximumOverAllRateInKiloBytes +``` + +The maximum total upload rate in kilo bytes. (Default is 10240 (10MB/s)) + +Exposed as MBean. + + +#### sliceSizeInBytes #### + +``` +jlfu.sliceSizeInBytes +``` + +The size of the slice that javascript read and send. (Default is 10485760 (10MB)) + +#### maximumInactivityInHoursBeforeDelete #### + +``` +jlfu.filecleaner.maximumInactivityInHoursBeforeDelete +``` + +The maximum time files can stay inactive on the server (Default is 48) + +Exposed as MBean. + + + +#### uploadFolder #### + +``` +jlfu.defaultUploadFolder +``` + +The folder where the files and state are stored on the server (Default is "/JavaLargeFileUploader") + + + +#### uploadFolderRelativePath #### + +``` +jlfu.uploadFolderRelativePath +``` + +Boolean specifying whether the defaultUploaderFolder described previously is a relative path (true) or an absolute path (false) (Default is `true`) + + + +#### keepOriginalFileName #### + +``` +jlfu.keepOriginalFileName +``` + +Boolean specifying whether the originalFileName should be kept while preparing the upload of a file. If set to false, a name generated from a UUID will be assigned to avoid name collision. (Default is `false`) + + + + + +--- + + + + +## javascript-attributes ## + +#### maxNumberOfConcurrentUploads #### + +_default value is **5**_ + +All browsers are limiting the number of concurrent requests that are active against a similar domain. Chrome and Firefox limit is set to 6. + +All requests are then queued but the problem is that the upload streaming requests are (as you can imagine) quite long. If that limit is more than 6, the progress poller requests would be queued and no progress would be retrieved for as long as the files are streamed. + +Also, depending of what you want to achieve, it could make sense to allow a maximum of 1 concurrent request as the bandwidth is shared anyway between all the concurrent uploads. + +It is advised to use a number between 1 and 5 so that there is always at least one request left for progress poller. + +Use [JavaLargeFileUploader#setMaxNumberOfConcurrentUploads](JavaLargeFileUploader#setMaxNumberOfConcurrentUploads.md). + +#### errorMessages #### + +The error messages can be modified and/or translated by the page using the API. +They are stored inside a map that can be modified from the page. + +The initial content of the map is: +``` +errorMessages[0] = "Request failed for an unknown reason, please contact an administrator if the problem persists."; +errorMessages[1] = "The request is not multipart."; +errorMessages[2] = "No file to upload found in the request."; +errorMessages[3] = "CRC32 Validation of the part failed."; +errorMessages[4] = "The request cannot be processed because a parameter is missing."; +errorMessages[5] = "Cannot retrieve the configuration."; +errorMessages[6] = "No files have been selected, please select at least one file!"; +errorMessages[7] = "Resuming file upload with previous slice as the last part is invalid."; +errorMessages[8] = "Error while uploading a slice of the file"; +errorMessages[9] = "Maximum number of concurrent uploads reached, the upload is queued and waiting for one to finish."; +errorMessages[10] = "An exception occurred. Retrying ..."; +errorMessages[11] = "Connection lost. Automatically retrying in a moment."; +errorMessages[12] = "You do not have the permission to perform this action."; +errorMessages[13] = "FireBug is enabled, you may experience issues if you do not disable it while uploading."; +errorMessages[14] = "File corrupted. An unknown error has occured and the file is corrupted. The usual cause is that the file has been modified during the upload. Please clear it and re-upload it."; +errorMessages[15] = "File is currently locked, retrying in a moment..."; +errorMessages[16] = "Uploads are momentarily disabled, retrying in a moment..."; +``` +You can retrieve this map using [JavaLargeFileUploader#getErrorMessages](JavaLargeFileUploader#getErrorMessages.md) and modify them directly. + +#### progressPollerRefreshRate #### + +_default value is **1000**_ + +The [progress poller](Flow#Progress-Poller.md) is sending a new request to the server every _x_ amount of milliseconds, _x_ being the value of this variable. + +Use [JavaLargeFileUploader#setProgressPollerRefreshRate](JavaLargeFileUploader#setProgressPollerRefreshRate.md) to set this value up. + +#### autoretry #### + +_default autoretry value is **true**_ + +_default autoretry delay is **5000**_ + +Whenever the connection is lost, the API can try to resume the file upload automatically. + +If the autoretry value is true, it will retry every _x_ milliseconds, _x_ being the delay. + +Use [JavaLargeFileUploader#setAutoRetry](JavaLargeFileUploader#setAutoRetry.md) to set these values up. + +#### javaLargeFileUploaderHost #### + +_default value is **empty** (same host than the server hosting the resource)_ + +If your javascript resources are hosted on a different machine, you can specify the server handling the calls with this value. + +Watch out for same origin policy ! + +Use [JavaLargeFileUploader#setJavaLargeFileUploaderHost](JavaLargeFileUploader#setJavaLargeFileUploaderHost.md) to set this value. \ No newline at end of file diff --git a/Flow.md b/Flow.md new file mode 100644 index 0000000..a63c8e8 --- /dev/null +++ b/Flow.md @@ -0,0 +1,64 @@ +The [JavaLargeFileUploader#initialize](JavaLargeFileUploader#initialize.md) step retrieves information from the server. +The information retrieved is: + * The size of the slices that will be streamed +For all the files: + * The [id](PendingFile#id.md) of the file on the server + * The [completion](PendingFile#fileCompletionInBytes.md) of the file + * The [original file size](PendingFile#originalFileSizeInBytes.md) + * The [original file name](PendingFile#originalFileName.md) + * The [number of bytes that have been validated](PendingFile#crcedBytes.md) + * The [crc32](PendingFile#firstChunkCrc.md) information related to the beginning of this file + * The [percentage of completion](PendingFile#percentageCompleted.md) +These information will be stored in a new instance of PendingFile for each of these files. + +At that point, the [#Progress-Poller](#Progress-Poller.md) is started. + +When the [JavaLargeFileUploader#fileUploadProcess](JavaLargeFileUploader#fileUploadProcess.md) method is executed, the API will extract the information related to all the files and fill a new PendingFile object without an ID for each of these files. + + +All of the files will be compared against the pending files retrieved from the server, that first validation is performed against the file name and the file size. + +If the file name and the file size are similar, the API will process a second validation processing a CRC32 of a small slice of this file on the javascript side compared to the crc32 of the same slice of the file on the server to ensure these files are the same one. +That crc32 is performed by default on the 8192 first bytes of this file or the available validated size if below this value. + +If the result of that crc32 is matching the one of the server, the file is assumed as the same, the two PendingFile objects are merged and the upload is resumed. => [#Resume-Upload](#Resume-Upload.md) + +If the crc32 differs from the server, a new upload will be processed. => [#New-Upload](#New-Upload.md) + +### New-Upload ### + +When a new upload is initiated, a first server-call is performed to prepare the upload with all the file information. An ID is generated by the server and returned to the client-side to identify the PendingFile object. + +Once this preparation step is performed, the JavaLargeFileUploader#startCallback is called for each of the files. + +The [#File-Streaming](#File-Streaming.md) is then started for the file. + +### Resume-Upload ### + +The first step when resuming a file is to check that what has been last uploaded is valid. + +On initialization, we have retrieved the [number of bytes that have been validated](PendingFile#crcedBytes.md), +if this value is below the [completion](PendingFile#fileCompletionInBytes.md) of the file, we have to perform a crc32 hash of the part of the file that has not been verified and check it against the crc32 value of that same part on the server. + +If the crc32 are matching, the [#File-Streaming](#File-Streaming.md) is started from that [completion](PendingFile#fileCompletionInBytes.md) value. +If the crc32 are not matching, the file is truncated to match the [number of bytes that have been validated](PendingFile#crcedBytes.md) and the [#File-Streaming](#File-Streaming.md) is started from there. + +### File-Streaming ### + +The file streaming process is started only if the number of files currently uploading is below the value of the [ConfigurableProperties#maxNumberOfConcurrentUploads](ConfigurableProperties#maxNumberOfConcurrentUploads.md). If this value is reached, the file is queued until another one is finished or cancelled. + +The file streaming process slices the file and stream them to the server. The size of the slice is defined by the configuration retrieved on [JavaLargeFileUploader#initialize](JavaLargeFileUploader#initialize.md). + +For each of these slice, the file is first read using the [FileReader API](http://developer.mozilla.org/en/DOM/FileReader) to generate a crc32 hash. That crc32 is sent with the actual slice and will be used to ensure that the transmitted data is correct. + +When the upload of this slice is complete, the next slice is processed using the same method. + +When the file has been completely uploaded, the [PendingFile#finishCallback](PendingFile#finishCallback.md) is executed. + +### Progress-Poller ### + +The progress poller is an infinite loop which retrieves from the server the completion and upload rate of all the pending uploads if at least one upload is currently being processed. + +It will trigger the [PendingFile#progressCallback](PendingFile#progressCallback.md) for each of them. + +The rate can be configured, see [here](ConfigurableProperties#progressPollerRefreshRate.md). \ No newline at end of file diff --git a/JavaLargeFileUploader.md b/JavaLargeFileUploader.md new file mode 100644 index 0000000..b5cbe12 --- /dev/null +++ b/JavaLargeFileUploader.md @@ -0,0 +1,318 @@ +This object is the main class of the API and provides method to interact with the server. + +``` +jlfu = new JavaLargeFileUploader(); +``` + +It has to be first initialized using [JavaLargeFileUploader#initialize](JavaLargeFileUploader#initialize.md) before any other operation. + +This object have a few attributes that are configurable, please see [ConfigurableProperties#javascript-attributes](ConfigurableProperties#javascript-attributes.md). + +You can find a complete working example in the demo project. The html/js file managing jlfu is [here](http://code.google.com/p/java-large-file-uploader/source/browse/trunk/java-large-file-uploader-demo/src/main/webapp/index.html). + +This object provides the following interaction methods: + + +--- + +### initialize ### +``` +jlfu.initialize(initializationCallback, exceptionCallback); +``` +This method has to be called before any other one and will initialize the object with the configuration defined on the server. It will also retrieve all the pending files that could potentially exist and provide some information about them (see PendingFile). + * initializationCallback: +> Callback function containing a map of the files previously uploaded as parameter. +> The key of this map is the fileIdentifier. +> The value is a pendingFile (see PendingFile object description). + * exceptionCallback: +> A callback function with a string formatted describing the exception as parameter triggered if an exception occurred. +Example: +``` +jlfu.initialize(function(pendingFiles) { + //treat pending file +}, function(message){ + //treat exception +)); +``` + +--- + +### clearFileUpload ### +``` +jlfu.clearFileUpload(callback); +``` +Clears all state on the server. +Any pending upload will be stopped and deleted on the file system. + * callback: +> A function with no parameter that will be executed once all files have been removed. +Example: +``` +jlfu.clearFileUpload(function() { + //do something when the call is complete +}); +``` + +--- + +### cancelFileUpload ### +``` +jlfu.cancelFileUpload(pendingFileId, callback); +``` +Clears the file with the specified id on the server. +This upload will be stopped and the file deleted on the file system. + * pendingFileId (string) : +> the id of the file to remove. + * callback: +> A function with that will be executed once all files have been removed which includes the following parameters: + 1. fileId (string) : the id of the file that has been removed. +Example: +``` +jlfu.cancelFileUpload("4ec798ec-eba1-4ef7-afbe-df6f4635783d", function(fileId) { + //do something when the call is complete +}); +``` + +--- + +### pauseFileUpload ### +``` +jlfu.pauseFileUpload(pendingFileId, callback); +``` +Pauses the file with the specified id on the server. +The upload can be resumed using [JavaLargeFileUploader#resumeFileUpload](JavaLargeFileUploader#resumeFileUpload.md). + * pendingFileId (string) : +> the id of the file to pause. + * callback: +> A function with that will be executed once the file has been paused containing the following parameters: + 1. pendingFile (PendingFile) : the pending file object instance that has been paused. +Example: +``` +jlfu.pauseFileUpload("4ec798ec-eba1-4ef7-afbe-df6f4635783d", function(pendingFile) { + //do something when the call is complete +}); +``` + +--- + +### pauseAllFileUploads ### +``` +jlfu.pauseAllFileUploads(callback); +``` + +_since 1.1.2_ + +Pauses all the uploads of all the files (does not start the files queued). +The uploads can be resumed independently using [JavaLargeFileUploader#resumeFileUpload](JavaLargeFileUploader#resumeFileUpload.md) or [JavaLargeFileUploader#resumeAllFileUploads](JavaLargeFileUploader#resumeAllFileUploads.md). + * callback: +> A function with that will be executed for all the files once the files have been paused containing the following parameters: + 1. pendingFile (PendingFile) : the pending file object instance that has been paused. +Example: +``` +jlfu.pauseAllFileUploads(function(pendingFile) { + //do something when the call is complete +}); +``` + +--- + +### resumeFileUpload ### +``` +jlfu.resumeFileUpload(pendingFileId, callback); +``` +Resumes the file with the specified id on the server that has been previously paused using [JavaLargeFileUploader#pauseFileUpload](JavaLargeFileUploader#pauseFileUpload.md). + * pendingFileId (string) : +> the id of the file to resume. + * callback: +> A function which will be executed once the file has been resumed containing the following parameters: + 1. pendingFile (PendingFile) : the pending file object instance that has been resumed. +Example: +``` +jlfu.resumeFileUpload("4ec798ec-eba1-4ef7-afbe-df6f4635783d", function(pendingFile) { + //do something when the call is complete +}); +``` + +--- + +### resumeAllFileUploads ### +``` +jlfu.resumeAllFileUploads(callback); +``` + +_since 1.1.2_ + +Resumes all the file that have been paused using [JavaLargeFileUploader#pauseFileUpload](JavaLargeFileUploader#pauseFileUpload.md) or [JavaLargeFileUploader#pauseAllFileUploads](JavaLargeFileUploader#pauseAllFileUploads.md). + * callback: +> A function which will be executed for all the files once the file has been resumed containing the following parameters: + 1. pendingFile (PendingFile) : the pending file object instance that has been resumed. +Example: +``` +jlfu.resumeAllFileUploads(function(pendingFile) { + //do something when the call is complete +}); +``` + +--- + +### retryFileUpload ### +``` +jlfu.retryFileUpload(pendingFileId, callback); +``` +If the connection is lost or another error occurs, you can retry to resume the upload for the file with the specified id. + * pendingFileId (string) : +> the id of the file to resume. + * callback: +> A function which will be executed once the file has been resumed containing the following parameters: + 1. success (boolean) : true if the resume is successful, false otherwise. +Example: +``` +jlfu.retryFileUpload("4ec798ec-eba1-4ef7-afbe-df6f4635783d", function(ok) { + //do something when the call is complete +}); +``` + +--- + +### setRateInKiloBytes ### +``` +jlfu.setRateInKiloBytes(pendingFileId, rate); +``` +Specifies a maximum upload rate in kilo bytes that will be applied to the PendingFile identified by the specified id. + * pendingFileId (string) : +> the id of the file on which this rate shall be applied. + * rate (long) : +> the maximum rate in kilobytes. +Example: +``` +jlfu.setRateInKiloBytes("4ec798ec-eba1-4ef7-afbe-df6f4635783d", 20); +``` + +--- + +### fileUploadProcess ### +``` +jlfu.fileUploadProcess(referenceToFileElement, startCallback, progressCallback, finishCallback, exceptionCallback); +``` +Starts or resumes the upload of all the files selected in the file input element specified as parameter. +See the Flow to get more information about how these uploads are actually processed. +Parameters: + * referenceToFileElement (file input) : +> The input type="file" html element which contains the selection of files that will be processed. + * startCallback: +> see [PendingFile#startCallback](PendingFile#startCallback.md). + * progressCallback: +> > see [PendingFile#progressCallback](PendingFile#progressCallback.md). + * finishCallback: +> > see [PendingFile#finishCallback](PendingFile#finishCallback.md). + * exceptionCallback: +> > see [PendingFile#exceptionCallback](PendingFile#exceptionCallback.md). +Example: +``` +//process the file upload +jlfu.fileUploadProcess(fileElement, + + //define a start callback + function(pendingFile, referenceToFileElement) { + }, + + //define a progressCallback + function(pendingFile, percentageCompleted, uploadRate, estimatedRemainingTime, referenceToFileElement) { + }, + + //define a finishCallback showing the completion in the em element + function(pendingFile, referenceToFileElement) { + }, + + //define an exception callback + function(message, referenceToFileElement, potentialfileIdThatCanBeUndefined) { + } +); +``` + +--- + +### setMaxNumberOfConcurrentUploads ### +``` +jlfu.setMaxNumberOfConcurrentUploads(number); +``` +Specifies the maximum number of uploads that are streamed concurrently. + * number (int) : +> > the number (between 1 and 5) + +Please see [ConfigurableProperties#maxNumberOfConcurrentUploads](ConfigurableProperties#maxNumberOfConcurrentUploads.md). + +Example: +``` +jlfu.setMaxNumberOfConcurrentUploads(1); +``` + +--- + +### getErrorMessages ### +``` +jlfu.getErrorMessages(); +``` +Retrieves the map of all the error messages. + +Please see [ConfigurableProperties#errorMessages](ConfigurableProperties#errorMessages.md). + +This map can be modified directly: + +Example: +``` +jlfu.getErrorMessages()[9] = "File queued!"; +``` + +--- + +### setProgressPollerRefreshRate ### +``` +jlfu.setProgressPollerRefreshRate(newRate); +``` +Specifies the progress poller refresh rate in milliseconds. + * newRate (int) : + +> the new rate + +Please see [ConfigurableProperties#progressPollerRefreshRate](ConfigurableProperties#progressPollerRefreshRate.md). + +Example: +``` +jlfu.setProgressPollerRefreshRate(1000); +``` + +--- + +### setAutoRetry ### +``` +jlfu.setAutoRetry(autoRetryBoolean, autoRetryDelay); +``` +Specifies the auto retry configuration + * autoRetryBoolean (boolean) : +> true to enable auto retry, false to disable. + * autoRetryDelay (int) : +> the amount of time in milliseconds between each retry. + +Please see [ConfigurableProperties#autoretry](ConfigurableProperties#autoretry.md). + +Example: +``` +jlfu.setAutoRetry(true, 5000); +``` + +--- + +### setJavaLargeFileUploaderHost ### +``` +jlfu.setJavaLargeFileUploaderHost(javaLargeFileUploaderHost); +``` +Specifies the full url of the application hosting the servlet handlers. + * javaLargeFileUploaderHost(string) : +> host url + +Please see [ConfigurableProperties#javaLargeFileUploaderHost](ConfigurableProperties#javaLargeFileUploaderHost.md). + +Example: +``` +jlfu.setJavaLargeFileUploaderHost("http://localhost:8888/demo/"); +``` \ No newline at end of file diff --git a/PendingFile.md b/PendingFile.md new file mode 100644 index 0000000..f108acb --- /dev/null +++ b/PendingFile.md @@ -0,0 +1,48 @@ +#### id #### +> (string) : identifier of the pending file upload +#### fileComplete #### +> (boolean) : specifies if the file is complete or not. +#### originalFileName #### +> (string) : the original file name. +#### fileCompletionInBytes #### +> (long) : the file completion in bytes. +#### fileCompletion #### +> (string) : the file completion formatted with its unit. +#### originalFileSizeInBytes #### +> (long) : the original file size in bytes. +#### originalFileSize #### +> (string) : the original file size formatted with its unit. +#### percentageCompleted #### +> (float) : completion of the file in percent (2 decimal places) +#### started #### +> (boolean) : true if the file is currently being uploaded, false if it is a file present on the server filesystem and can be resumed. +#### crcedBytes #### +> (long) : amount of bytes that are validated on the server +#### firstChunkCrc #### +> (object) : the crc32 information of the first bytes of the file + * value (string) : the actual crc32 value + * read (int) : number of bytes which have been used to compute firstChunkCrc +#### blob #### +> (object) : the file submitted with a file input element +#### paused #### +> (boolean) : specifies whether this upload is paused or not. +#### startCallback #### +> (function) : function that is called once the upload is pre initialized if the file id is not specified. It contains the following parameters: + 1. the PendingFile object + 1. the origin element +#### progressCallback #### +> (function) : function that will be called to monitor the progress + 1. the PendingFile object + 1. the percentage + 1. the current upload rate formatted as a String + 1. the estimated remaining time formatted as a String + 1. the origin element +#### finishCallback #### +> (function): function that will be called when the process is fully complete. + 1. the PendingFile object + 1. the origin element +#### exceptionCallback #### +> (function): function that will be called when an exception occurs. + 1. a string formatted describing the exception + 1. the origin element + 1. the optional PendingFile object. If the exception is related to the control and not a pending file, this parameter is undefined. \ No newline at end of file diff --git a/ProjectHome.md b/ProjectHome.md new file mode 100644 index 0000000..0d69ca4 --- /dev/null +++ b/ProjectHome.md @@ -0,0 +1,88 @@ +Latest stable version : 1.1.8 + + +--- + + +The goal of this project is to provide an easy way to upload large files directly from a browser without applets or external components. + +Thanks to the new html5 features including reading and slicing files, it is now possible to proceed in sending very large files over http.
+ +This library cuts the file in slices and stream them to the server. Each slice is validated using a js and java crc32 verification. + +You can see exactly how the flow is processed [here](Flow.md) + +The unfinished files can stay on the server for an amount of configurable days before an automatic removal. + +The information related to this upload are stored on the filesystem of the server. + +The writing of the files on the filesystem is optimized using servlet 3.0 asynchronous features and a rate limiter algorithm which allows the user to define a custom upload rate for each file individually. +A maximum upload rate for all the uploads of a client and a maximum overall upload rate can be configured.
+ + +**1.0** + * upload large files: + * pause/resume + * current upload rate per file + * total progress of the upload per file + * file upload state persisted on file system (user can resume an upload after an amount of configurable days) + * crc validation of all the chunks + * multiple file uploads within the same control + * clean up of the pending files after a configured time + * independent upload rate configuration per file + * master upload rate configuration (bandwidth divided per all the current uploads) + * per client upload rate configuration (bandwidth divided per all the current client uploads) + +**1.1** + * [listener system](http://code.google.com/p/java-large-file-uploader/source/browse/trunk/java-large-file-uploader-parent/java-large-file-uploader-jar/src/main/java/com/am/jlfu/notifier/JLFUListener.java) getting events when uploads are started,paused,resumed etc... + * [authorizer plugin system](http://code.google.com/p/java-large-file-uploader/source/browse/trunk/java-large-file-uploader-parent/java-large-file-uploader-jar/src/main/java/com/am/jlfu/authorizer/Authorizer.java) (default to allow any client to perform anything) + * [identifier plugin system](http://code.google.com/p/java-large-file-uploader/source/browse/trunk/java-large-file-uploader-parent/java-large-file-uploader-jar/src/main/java/com/am/jlfu/identifier/IdentifierProvider.java) (default to store id in cookie) + * firebug detection (having firebug enabled can cause trouble) + + + +--- + + +This project is separated in two parts: + +### Client side ### + +Written in javascript, it sends a file splitted in chunks to a java web server and provides methods to be able to monitor the progress. + +The javascript object JavaLargeFileUploader can manage multiple concurrent uploads. + +### Server side ### + +The server-side part is a Java ARchive that shall be integrated in a Web application ARchive. Using web fragments, it exposes a servlet which handles the upload. + + +--- + + +### Setup ### + +See [Setup](http://code.google.com/p/java-large-file-uploader/wiki/Setup). + + +--- + + +### Usage ### + +The client API is managed using an instance of JavaLargeFileUploader on the javascript side. Please consult [its documentation](JavaLargeFileUploader.md) to know more about how to interact with the API. + + + +--- + + +You can download the last war of the demo [here](http://code.google.com/p/java-large-file-uploader/downloads/detail?name=demo.war) to test it. (Note that your server has to support servlet 3.0) + + +--- + + +## Known issues ## + * does not work on Internet Explorer as ie does not provide an api to slice files. + * might cause chrome to crash when uploading large files veryfast (client/server over a lan or same machine)([filereader api bug](http://code.google.com/p/chromium/issues/detail?id=114548)). I recommend you to limit the maximum bandwidth to 10MB/s per client \ No newline at end of file diff --git a/Setup.md b/Setup.md new file mode 100644 index 0000000..64b78eb --- /dev/null +++ b/Setup.md @@ -0,0 +1,52 @@ +### java ### + +This project is really easy to configure as the dependencies are a war containing a simple javascript file and a jar which includes all the web configuration (using web fragment from servlet 3.0 specification). +[Some properties](ConfigurableProperties.md) are exposed as MBeans and can be changed at runtime and others can be set directly in the javascript. + +#### Maven #### + +Just define the maven dependencies: +``` + + com.am + java-large-file-uploader-war + 1.1.8 + war + + + com.am + java-large-file-uploader-jar + 1.1.8 + +``` +And the repository: +``` + + java large file uploader repository + http://java-large-file-uploader.googlecode.com/svn/mvnrepo + +``` + +#### Spring #### + +If you are not defining a `contextConfigLocation`, no action is required. +But if you are using Spring and you are defining your own `contextConfigLocation` in your web.xml, it will override the one defined in the web fragment. + +Please add '`classpath*:/META-INF/jlfu-web-fragment-context.xml`' inside the param value. + +Example: +``` + + contextConfigLocation + + classpath*:/META-INF/jlfu-web-fragment-context.xml + /WEB-INF/spring/another-spring-configuration-file.xml + + +``` + +**/!\** And do not forget to specify `version="3.0"` in the `web-app` element of your web.xml ! + +### javascript ### + +See [JavaLargeFileUploader](JavaLargeFileUploader.md) \ No newline at end of file diff --git a/Usage.md b/Usage.md new file mode 100644 index 0000000..27e4a6b --- /dev/null +++ b/Usage.md @@ -0,0 +1,44 @@ +## Javascript ## + +All the operations available on the client side are performed using a single object instance: [JavaLargeFileUploader](http://code.google.com/p/java-large-file-uploader/wiki/JavaLargeFileUploader). + +## Java ## + +On the Java side, there are two kind of possible interactions: + +### Service ### + +JLFU also provides a few methods in [JavaLargeFileUploaderService](http://code.google.com/p/java-large-file-uploader/source/browse/trunk/java-large-file-uploader-parent/java-large-file-uploader-jar/src/main/java/com/am/jlfu/staticstate/JavaLargeFileUploaderService.java) like: +``` +getProgress(clientId, fileId) +updateEntity(clientId, entity) +writeEntity(clientId, entity) +writeEntity(File, entity) +getEntityIfPresent(clientId) +clearFile(clientId, fileId) +clearClient(clientId) +enableFileUploader() +disableFileUploader() +``` +Consult the JavaDoc for more details about all these methods. + +### Listener ### + +JLFU provides a Listener system that lets you listen to pretty much everything happening on the server side: + +``` +onNewClient(clientId) +onClientBack(clientId) +onClientInactivity(clientId, inactivityTime) +onFileUploadEnd(clientId, fileId) +onFileUploadPrepared(clientId, fileId) +onAllFileUploadsPrepared(clientId, fileIds) +onFileUploadCancelled(clientId, fileId) +onFileUploadPaused(clientId, fileId) +onFileUploadResumed(clientId, fileId) +onFileUploadProgress(clientId, fileId, FileProgressStatus) +onFileUploaderDisabled() +onFileUploaderEnabled() +``` + +You can register a [JLFUListener](http://code.google.com/p/java-large-file-uploader/source/browse/trunk/java-large-file-uploader-parent/java-large-file-uploader-jar/src/main/java/com/am/jlfu/notifier/JLFUListener.java) (or an [JLFUListenerAdapter](http://code.google.com/p/java-large-file-uploader/source/browse/trunk/java-large-file-uploader-parent/java-large-file-uploader-jar/src/main/java/com/am/jlfu/notifier/JLFUListenerAdapter.java)) to the [JLFUListenerPropagator](http://code.google.com/p/java-large-file-uploader/source/browse/trunk/java-large-file-uploader-parent/java-large-file-uploader-jar/src/main/java/com/am/jlfu/notifier/JLFUListenerPropagator.java) which will propagates all the events to the registered listeners. \ No newline at end of file