ThreadedStorageService (JetS3t API : Amazon S3 Toolkit)

java.lang.Object
- org.jets3t.service.multi.ThreadedStorageService

Direct Known Subclasses:

ThreadedS3Service
```
public class ThreadedStorageService
extends java.lang.Object
```
Storage service wrapper that performs multiple service requests at a time using multi-threading and an underlying thread-safe StorageService implementation.
This service is designed to be run in non-blocking threads that therefore communicates information about its progress by firing ServiceEvent events. It is the responsibility of applications using this service to correctly handle these events - see the JetS3t application Synchronize for examples of how an application can use these events.

For cases where the full power, and complexity, of the event notification mechanism is not required the simplified multi-threaded service SimpleThreadedStorageService can be used.

This class uses properties obtained through Jets3tProperties. For more information on these properties please refer to JetS3t Configuration

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`protected class`	`ThreadedStorageService.AbstractRunnable` All the operation threads used by this service extend this class, which provides common methods used to retrieve the result object from a completed thread (via `ThreadedStorageService.AbstractRunnable.getResult()` or force a thread to be interrupted (via `ThreadedStorageService.AbstractRunnable.forceInterrupt()`.
`protected class`	`ThreadedStorageService.ThreadGroupManager` The thread group manager is responsible for starting, running and stopping the set of threads required to perform an operation.

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean[]`	`isShutdown`
`protected java.util.List<StorageServiceEventListener>`	`serviceEventListeners`
`protected long`	`sleepTime`
`protected StorageService`	`storageService`

Constructor Summary

Constructors
Constructor and Description
`ThreadedStorageService(StorageService service, StorageServiceEventListener listener)` Construct a multi-threaded service based on a StorageService and which sends event notifications to an event listening class.
`ThreadedStorageService(StorageService service, StorageServiceEventListener listener, long threadSleepTimeMS)` Construct a multi-threaded service based on an storage service and which sends event notifications to an event listening class, and which will send EVENT_IN_PROGRESS events at the specified time interval.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addServiceEventListener(StorageServiceEventListener listener)` Adds a service event listener to the set of listeners that will be notified of events.
`boolean`	`copyObjects(java.lang.String sourceBucketName, java.lang.String destinationBucketName, java.lang.String[] sourceObjectKeys, StorageObject[] destinationObjects, boolean replaceMetadata)` Copies multiple objects within or between buckets, while sending `CopyObjectsEvent` notification events.
`boolean`	`createBuckets(java.lang.String[] bucketNames)` Creates multiple buckets, and sends `CreateBucketsEvent` notification events.
`boolean`	`deleteObjects(java.lang.String bucketName, StorageObject[] objects)` Deletes multiple objects from a bucket, and sends `DeleteObjectsEvent` notification events.
`boolean`	`deleteObjects(java.lang.String bucketName, java.lang.String[] objectKeys)` Deletes multiple objects from a bucket, and sends `DeleteObjectsEvent` notification events.
`boolean`	`downloadObjects(java.lang.String bucketName, DownloadPackage[] downloadPackages)` A convenience method to download multiple objects to pre-existing output streams, which is particularly useful for downloading objects to files.
`boolean`	`downloadObjects(java.lang.String bucketName, DownloadPackage[] downloadPackages, ErrorPermitter errorPermitter)` A convenience method to download multiple objects to pre-existing output streams, which is particularly useful for downloading objects to files.
`protected void`	`fireServiceEvent(ServiceEvent event)` Sends a service event to each of the listeners registered with this service.
`boolean`	`getObjectACLs(java.lang.String bucketName, StorageObject[] objects)` Retrieves Access Control List (ACL) information for multiple objects from a bucket, and sends `LookupACLEvent` notification events.
`boolean`	`getObjects(java.lang.String bucketName, StorageObject[] objects)` Retrieves multiple objects (details and data) from a bucket, and sends `GetObjectsEvent` notification events.
`boolean`	`getObjects(java.lang.String bucketName, java.lang.String[] objectKeys)` Retrieves multiple objects (details and data) from a bucket, and sends `GetObjectsEvent` notification events.
`boolean`	`getObjects(java.lang.String bucketName, java.lang.String[] objectKeys, ErrorPermitter errorPermitter)` Retrieves multiple objects (details and data) from a bucket, and sends `GetObjectsEvent` notification events.
`boolean`	`getObjectsHeads(java.lang.String bucketName, StorageObject[] objects)` Retrieves details (but no data) about multiple objects from a bucket, and sends `GetObjectHeadsEvent` notification events.
`boolean`	`getObjectsHeads(java.lang.String bucketName, java.lang.String[] objectKeys)` Retrieves details (but no data) about multiple objects from a bucket, and sends `GetObjectHeadsEvent` notification events.
`boolean`	`getObjectsHeads(java.lang.String bucketName, java.lang.String[] objectKeys, ErrorPermitter errorPermitter)` Retrieves details (but no data) about multiple objects from a bucket, and sends `GetObjectHeadsEvent` notification events.
`ProviderCredentials`	`getProviderCredentials()`
`StorageService`	`getStorageService()`
`boolean`	`isAuthenticatedConnection()`
`boolean`	`isShutdown()`
`boolean`	`listObjects(java.lang.String bucketName, java.lang.String[] prefixes, java.lang.String delimiter, long maxListingLength)` Lists the objects in a bucket based on an array of prefix strings, and sends `ListObjectsEvent` notification events.
`boolean`	`putACLs(java.lang.String bucketName, StorageObject[] objects)` Updates/sets Access Control List (ACL) information for multiple objects in a bucket, and sends `UpdateACLEvent` notification events.
`boolean`	`putObjects(java.lang.String bucketName, StorageObject[] objects)` Creates multiple objects in a bucket, and sends `CreateObjectsEvent` notification events.
`void`	`removeServiceEventListener(StorageServiceEventListener listener)` Removes a service event listener from the set of listeners that will be notified of events.
`void`	`shutdown()` Make a best-possible effort to shutdown and clean up any resources used by this service such as HTTP connections, connection pools, threads etc.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - storageService
```
protected StorageService storageService
```
  - isShutdown
```
protected final boolean[] isShutdown
```
  - serviceEventListeners
```
protected final java.util.List<StorageServiceEventListener> serviceEventListeners
```
  - sleepTime
```
protected final long sleepTime
```
- Constructor Detail
  - ThreadedStorageService
```
public ThreadedStorageService(StorageService service,
                              StorageServiceEventListener listener)
                       throws ServiceException
```
    Construct a multi-threaded service based on a StorageService and which sends event notifications to an event listening class. EVENT_IN_PROGRESS events are sent at the default time interval of 500ms.
    
    Parameters:
    
    service - an storage service implementation that will be used to perform requests.
    
    listener - the event listener which will handle event notifications.
    
    Throws:
    
    ServiceException
  - ThreadedStorageService
```
public ThreadedStorageService(StorageService service,
                              StorageServiceEventListener listener,
                              long threadSleepTimeMS)
                       throws ServiceException
```
    Construct a multi-threaded service based on an storage service and which sends event notifications to an event listening class, and which will send EVENT_IN_PROGRESS events at the specified time interval.
    
    Parameters:
    
    service - a storage service implementation that will be used to perform requests.
    
    listener - the event listener which will handle event notifications.
    
    threadSleepTimeMS - how many milliseconds to wait before sending each EVENT_IN_PROGRESS notification event.
    
    Throws:
    
    ServiceException
- Method Detail
  - shutdown
```
public void shutdown()
              throws ServiceException
```
    Make a best-possible effort to shutdown and clean up any resources used by this service such as HTTP connections, connection pools, threads etc. After calling this method the service instance will no longer be usable -- a new instance must be created to do more work.
    
    Throws:
    
    ServiceException
  - isShutdown
```
public boolean isShutdown()
```
    Returns:
    
    true if the shutdown() method has been used to shut down and clean up this service. If this function returns true this service instance can no longer be used to do work.
  - getStorageService
```
public StorageService getStorageService()
```
    Returns:
    
    the underlying service implementation.
  - addServiceEventListener
```
public void addServiceEventListener(StorageServiceEventListener listener)
```
    Adds a service event listener to the set of listeners that will be notified of events.
    
    Parameters:
    
    listener - an event listener to add to the event notification chain.
  - removeServiceEventListener
```
public void removeServiceEventListener(StorageServiceEventListener listener)
```
    Removes a service event listener from the set of listeners that will be notified of events.
    
    Parameters:
    
    listener - an event listener to remove from the event notification chain.
  - fireServiceEvent
```
protected void fireServiceEvent(ServiceEvent event)
```
    Sends a service event to each of the listeners registered with this service.
    
    Parameters:
    
    event - the event to send to this service's registered event listeners.
  - isAuthenticatedConnection
```
public boolean isAuthenticatedConnection()
```
    Returns:
    
    true if the underlying service implementation is authenticated.
  - getProviderCredentials
```
public ProviderCredentials getProviderCredentials()
```
    Returns:
    
    the credentials in the underlying storage service.
  - listObjects
```
public boolean listObjects(java.lang.String bucketName,
                           java.lang.String[] prefixes,
                           java.lang.String delimiter,
                           long maxListingLength)
```
    Lists the objects in a bucket based on an array of prefix strings, and sends ListObjectsEvent notification events. The objects that match each prefix are listed in a separate background thread, potentially allowing you to list the contents of large buckets more quickly than if you had to list all the objects in sequence.
    Objects in the bucket that do not match one of the prefixes will not be listed.
    
    Parameters:
    
    bucketName - the name of the bucket in which the objects are stored.
    
    prefixes - an array of prefix strings. A separate listing thread will be run for each of these prefix strings, and the method will only complete once the entire object listing for each prefix has been obtained (unless the operation is cancelled, or an error occurs)
    
    delimiter - an optional delimiter string to apply to each listing operation. This parameter should be null if you do not wish to apply a delimiter.
    
    maxListingLength - the maximum number of objects to list in each iteration. This should be a value between 1 and 1000, where 1000 will be the best choice in almost all circumstances. Regardless of this value, all the objects in the bucket that match the criteria will be returned.
    The maximum number of threads is controlled by the JetS3t configuration property threaded-service.admin-max-thread-count.
    
    Returns:
    
    true if all the threaded tasks completed successfully, false otherwise.
  - createBuckets
```
public boolean createBuckets(java.lang.String[] bucketNames)
```
    Creates multiple buckets, and sends CreateBucketsEvent notification events.
    The maximum number of threads is controlled by the JetS3t configuration property threaded-service.admin-max-thread-count.
    
    Parameters:
    
    bucketNames - names of buckets to create.
    
    Returns:
    
    true if all the threaded tasks completed successfully, false otherwise.
  - copyObjects
```
public boolean copyObjects(java.lang.String sourceBucketName,
                           java.lang.String destinationBucketName,
                           java.lang.String[] sourceObjectKeys,
                           StorageObject[] destinationObjects,
                           boolean replaceMetadata)
```
    Copies multiple objects within or between buckets, while sending CopyObjectsEvent notification events.
    The maximum number of threads is controlled by the JetS3t configuration property threaded-service.admin-max-thread-count.
    
    Parameters:
    
    sourceBucketName - the name of the bucket containing the objects that will be copied.
    
    destinationBucketName - the name of the bucket to which the objects will be copied. The destination bucket may be the same as the source bucket.
    
    sourceObjectKeys - the key names of the objects that will be copied.
    
    destinationObjects - objects that will be created by the copy operation. The AccessControlList setting of each object will determine the access permissions of the resultant object, and if the replaceMetadata flag is true the metadata items in each object will also be applied to the resultant object.
    
    replaceMetadata - if true, the metadata items in the destination objects will be stored in using the REPLACE metadata copying option. If false, the metadata items will be copied unchanged from the original objects using the COPY metadata copying option.
    
    Returns:
    
    true if all the threaded tasks completed successfully, false otherwise.
  - putObjects
```
public boolean putObjects(java.lang.String bucketName,
                          StorageObject[] objects)
```
    Creates multiple objects in a bucket, and sends CreateObjectsEvent notification events.
    The maximum number of threads is controlled by the JetS3t configuration property threaded-service.max-admin-thread-count.
    
    Parameters:
    
    bucketName - name of the bucket where objects will be stored
    
    objects - the objects to create/upload.
    
    Returns:
    
    true if all the threaded tasks completed successfully, false otherwise.
  - deleteObjects
```
public boolean deleteObjects(java.lang.String bucketName,
                             java.lang.String[] objectKeys)
```
    Deletes multiple objects from a bucket, and sends DeleteObjectsEvent notification events.
    The maximum number of threads is controlled by the JetS3t configuration property threaded-service.admin-max-thread-count.
    
    Parameters:
    
    bucketName - name of the bucket containing objects to delete
    
    objectKeys - key names of objects to delete
    
    Returns:
    
    true if all the threaded tasks completed successfully, false otherwise.
  - deleteObjects
```
public boolean deleteObjects(java.lang.String bucketName,
                             StorageObject[] objects)
```
    Deletes multiple objects from a bucket, and sends DeleteObjectsEvent notification events.
    The maximum number of threads is controlled by the JetS3t configuration property threaded-service.admin-max-thread-count.
    
    Parameters:
    
    bucketName - name of the bucket containing the objects to be deleted
    
    objects - the objects to delete
    
    Returns:
    
    true if all the threaded tasks completed successfully, false otherwise.
  - getObjects
```
public boolean getObjects(java.lang.String bucketName,
                          StorageObject[] objects)
```
    Retrieves multiple objects (details and data) from a bucket, and sends GetObjectsEvent notification events.
    
    Parameters:
    
    bucketName - name of the bucket containing the objects.
    
    objects - the objects to retrieve.
    
    Returns:
    
    true if all the threaded tasks completed successfully, false otherwise.
  - getObjects
```
public boolean getObjects(java.lang.String bucketName,
                          java.lang.String[] objectKeys)
```
    Retrieves multiple objects (details and data) from a bucket, and sends GetObjectsEvent notification events.
    The maximum number of threads is controlled by the JetS3t configuration property threaded-service.max-thread-count.
    
    Parameters:
    
    bucketName - the bucket containing the objects.
    
    objectKeys - the key names of the objects to retrieve.
    
    Returns:
    
    true if all the threaded tasks completed successfully, false otherwise.
  - getObjects
```
public boolean getObjects(java.lang.String bucketName,
                          java.lang.String[] objectKeys,
                          ErrorPermitter errorPermitter)
```
    Retrieves multiple objects (details and data) from a bucket, and sends GetObjectsEvent notification events.
    The maximum number of threads is controlled by the JetS3t configuration property threaded-service.max-thread-count.
    
    Parameters:
    
    bucketName - the bucket containing the objects.
    
    objectKeys - the key names of the objects to retrieve.
    
    errorPermitter - callback handler to decide which errors will cause a ThrowableBearingStorageObject to pass through the system instead of raising an exception and aborting the operation.
    
    Returns:
    
    true if all the threaded tasks completed successfully, false otherwise.
  - getObjectsHeads
```
public boolean getObjectsHeads(java.lang.String bucketName,
                               StorageObject[] objects)
```
    Retrieves details (but no data) about multiple objects from a bucket, and sends GetObjectHeadsEvent notification events.
    
    Parameters:
    
    bucketName - name of the bucket containing the objects whose details will be retrieved.
    
    objects - the objects with details to retrieve.
    
    Returns:
    
    true if all the threaded tasks completed successfully, false otherwise.
  - getObjectsHeads
```
public boolean getObjectsHeads(java.lang.String bucketName,
                               java.lang.String[] objectKeys)
```
    Retrieves details (but no data) about multiple objects from a bucket, and sends GetObjectHeadsEvent notification events.
    The maximum number of threads is controlled by the JetS3t configuration property threaded-service.admin-max-thread-count.
    
    Parameters:
    
    bucketName - name of the bucket containing the objects.
    
    objectKeys - the key names of the objects with details to retrieve.
    
    Returns:
    
    true if all the threaded tasks completed successfully, false otherwise.
  - getObjectsHeads
```
public boolean getObjectsHeads(java.lang.String bucketName,
                               java.lang.String[] objectKeys,
                               ErrorPermitter errorPermitter)
```
    Retrieves details (but no data) about multiple objects from a bucket, and sends GetObjectHeadsEvent notification events.
    The maximum number of threads is controlled by the JetS3t configuration property threaded-service.admin-max-thread-count.
    
    Parameters:
    
    bucketName - name of the bucket containing the objects.
    
    objectKeys - the key names of the objects with details to retrieve.
    
    errorPermitter - callback handler to decide which errors will cause a ThrowableBearingStorageObject to pass through the system instead of raising an exception and aborting the operation.
    
    Returns:
    
    true if all the threaded tasks completed successfully, false otherwise.
  - getObjectACLs
```
public boolean getObjectACLs(java.lang.String bucketName,
                             StorageObject[] objects)
```
    Retrieves Access Control List (ACL) information for multiple objects from a bucket, and sends LookupACLEvent notification events.
    The maximum number of threads is controlled by the JetS3t configuration property threaded-service.admin-max-thread-count.
    
    Parameters:
    
    bucketName - name of the bucket containing the objects
    
    objects - the objects to retrieve ACL details for.
    
    Returns:
    
    true if all the threaded tasks completed successfully, false otherwise.
  - putACLs
```
public boolean putACLs(java.lang.String bucketName,
                       StorageObject[] objects)
```
    Updates/sets Access Control List (ACL) information for multiple objects in a bucket, and sends UpdateACLEvent notification events.
    The maximum number of threads is controlled by the JetS3t configuration property threaded-service.admin-max-thread-count.
    
    Parameters:
    
    bucketName - name of the bucket containing the objects.
    
    objects - the objects to update/set ACL details for.
    
    Returns:
    
    true if all the threaded tasks completed successfully, false otherwise.
  - downloadObjects
```
public boolean downloadObjects(java.lang.String bucketName,
                               DownloadPackage[] downloadPackages)
                        throws ServiceException
```
    A convenience method to download multiple objects to pre-existing output streams, which is particularly useful for downloading objects to files.
    The maximum number of threads is controlled by the JetS3t configuration property threaded-service.max-thread-count.
    If the JetS3t configuration property downloads.restoreLastModifiedDate is set to true, any files created by this method will have their last modified date set according to the value of the object's Constants.METADATA_JETS3T_LOCAL_FILE_DATE metadata item.
    
    Parameters:
    
    bucketName - name of the bucket containing the objects
    
    downloadPackages - an array of download packages containing the object to be downloaded, and able to build an output stream where the object's contents will be written to.
    
    Returns:
    
    true if all the threaded tasks completed successfully, false otherwise.
    
    Throws:
    
    ServiceException
  - downloadObjects
```
public boolean downloadObjects(java.lang.String bucketName,
                               DownloadPackage[] downloadPackages,
                               ErrorPermitter errorPermitter)
                        throws ServiceException
```
    A convenience method to download multiple objects to pre-existing output streams, which is particularly useful for downloading objects to files.
    The maximum number of threads is controlled by the JetS3t configuration property threaded-service.max-thread-count.
    If the JetS3t configuration property downloads.restoreLastModifiedDate is set to true, any files created by this method will have their last modified date set according to the value of the object's Constants.METADATA_JETS3T_LOCAL_FILE_DATE metadata item.
    
    Parameters:
    
    bucketName - name of the bucket containing the objects
    
    downloadPackages - an array of download packages containing the object to be downloaded, and able to build an output stream where the object's contents will be written to.
    
    errorPermitter - callback handler to decide which errors will cause a ThrowableBearingStorageObject to pass through the system instead of raising an exception and aborting the operation.
    
    Returns:
    
    true if all the threaded tasks completed successfully, false otherwise.
    
    Throws:
    
    ServiceException

Class ThreadedStorageService

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

storageService

isShutdown

serviceEventListeners

sleepTime

Constructor Detail

ThreadedStorageService

ThreadedStorageService

Method Detail

shutdown

isShutdown

getStorageService

addServiceEventListener

removeServiceEventListener

fireServiceEvent

isAuthenticatedConnection

getProviderCredentials

listObjects

createBuckets

copyObjects

putObjects

deleteObjects

deleteObjects

getObjects

getObjects

getObjects

getObjectsHeads

getObjectsHeads

getObjectsHeads

getObjectACLs

putACLs

downloadObjects

downloadObjects