com.microsoft.tfs.util.temp
Class FastTempOutputStream

java.lang.Object
  extended by java.io.OutputStream
      extended by com.microsoft.tfs.util.temp.FastTempOutputStream
All Implemented Interfaces:
java.io.Closeable, java.io.Flushable

public class FastTempOutputStream
extends java.io.OutputStream

An OutputStream that writes bytes to temporary storage and can be read from multiple times before being disposed. Internally the class first writes to heap memory, then switches to a temporary file once a threshold is exceeded. The temporary file is obtained through TempStorageService so temp files can be removed automatically during JVM shutdown (if they were not already disposed of manually before).

Common usage steps for this class:

  1. Intantiate FastTempOutputStream
  2. Write data to it via write(byte[]), write(int), and write(byte[], int, int)
  3. Call close() when done writing all data
  4. Call getInputStream() to get an InputStream (this can be done multiple times)
  5. Read data via the InputStream
  6. Close each InputStream via InputStream.close()
  7. Call dispose() on FastTempOutputStream to free resources
Data cannot be read (via getInputStream()) before InputStream.close() is called (the behavior for concurrent open writer and reader is undefined). You can open multiple InputStreams, but they all must be closed before calling dispose().

Call dispose() to free temp storage when finished with an instance and all of its InputStreams have been closed.

This class is useful because creating temp files on some operating systems (Windows) is very slow compared to others (most Unixes), especially when they only store a small amount of data (a few hundred bytes) and are used for a short time (tens or hundreds of milliseconds). This class is designed for these scenarios, when the eventual size of the temp file is unknown (streaming from the network, for instance) but are often small enough to fit in main memory.

Since:
TEE-SDK-10.1
Thread-safety:
thread-safe

Field Summary
static int DEFAULT_HEAP_STORAGE_INITIAL_SIZE_BYTES
          The default initial size for heap storage when the user didn't specify a hint during construction.
static int DEFAULT_HEAP_STORAGE_LIMIT_BYTES
          The default limit on heap storage, after this size file storage is used.
 
Constructor Summary
FastTempOutputStream()
          Creates a FastTempOutputStream with default values for the size hint and heap limit.
FastTempOutputStream(int heapStorageLimitBytes, int initialHeapStorageSizeBytes)
          Creates a FastTempOutputStream that will not use more than the given limit for heap storage (before transparently switch to file storage), and starts with the given heap storage pre-allocated (for more efficient writing of smaller files).
 
Method Summary
 void close()
          
 void dispose()
          Disposes of temporary resources used by this FastTempOutputStream .
 void flush()
          
 java.io.InputStream getInputStream()
          Gets an InputStream that reads the buffer contents that were previously written before close() was called.
 void write(byte[] b)
          
 void write(byte[] b, int off, int len)
          
 void write(int b)
          
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_HEAP_STORAGE_INITIAL_SIZE_BYTES

public static final int DEFAULT_HEAP_STORAGE_INITIAL_SIZE_BYTES
The default initial size for heap storage when the user didn't specify a hint during construction. This is just the default for efficiency, it will grow automatically until the configured heap storage limit is reached.

Constant Field Value:
4096
See Also:
Constant Field Values

DEFAULT_HEAP_STORAGE_LIMIT_BYTES

public static final int DEFAULT_HEAP_STORAGE_LIMIT_BYTES
The default limit on heap storage, after this size file storage is used.

Constant Field Value:
524288
See Also:
Constant Field Values
Constructor Detail

FastTempOutputStream

public FastTempOutputStream()
Creates a FastTempOutputStream with default values for the size hint and heap limit.


FastTempOutputStream

public FastTempOutputStream(int heapStorageLimitBytes,
                            int initialHeapStorageSizeBytes)
Creates a FastTempOutputStream that will not use more than the given limit for heap storage (before transparently switch to file storage), and starts with the given heap storage pre-allocated (for more efficient writing of smaller files).

Parameters:
heapStorageLimitBytes - the (approximate) limit on heap storage before file storage is used instead. If negative, default values are used.
initialHeapStorageSizeBytes - the amount of heap storage to initially allocate. Using numbers near the ultimate size of the content written helps reduce heap allocations and fragmentation (at the expense of more initial memory used). If negative, default values are used.
Method Detail

close

public void close()
           throws java.io.IOException

Specified by:
close in interface java.io.Closeable
Overrides:
close in class java.io.OutputStream
Throws:
java.io.IOException

flush

public void flush()
           throws java.io.IOException

Specified by:
flush in interface java.io.Flushable
Overrides:
flush in class java.io.OutputStream
Throws:
java.io.IOException

write

public void write(byte[] b,
                  int off,
                  int len)
           throws java.io.IOException

Overrides:
write in class java.io.OutputStream
Throws:
java.io.IOException

write

public void write(byte[] b)
           throws java.io.IOException

Overrides:
write in class java.io.OutputStream
Throws:
java.io.IOException

write

public void write(int b)
           throws java.io.IOException

Specified by:
write in class java.io.OutputStream
Throws:
java.io.IOException

getInputStream

public java.io.InputStream getInputStream()
                                   throws java.io.IOException
Gets an InputStream that reads the buffer contents that were previously written before close() was called. This method may be invoked multiple times.

Returns:
an InputStream that reads the data that was written to this buffer
Throws:
java.io.IOException - if the stream is still writable, or if the temporary file (if a file is being used for storage) could not be opened

dispose

public void dispose()
             throws java.io.IOException
Disposes of temporary resources used by this FastTempOutputStream . Users must call this when finished writing and reading from FastTempOutputStream (all InputStreams retrieved via getInputStream() must be closed), otherwise temporary files may remain on disk.

Throws:
java.io.IOException - if an error occurred closing the temporary file stream


© 2015 Microsoft. All rights reserved.