Class ScratchFile
- java.lang.Object
-
- org.apache.pdfbox.io.ScratchFile
-
- All Implemented Interfaces:
java.io.Closeable,java.lang.AutoCloseable,RandomAccessStreamCache
public class ScratchFile extends java.lang.Object implements RandomAccessStreamCache
Implements a memory page handling mechanism as base for creating (multiple)RandomAccessbuffers each having its set of pages (implemented byScratchFileBuffer). A buffer is created callingcreateBuffer().Pages can be stored in main memory or in a temporary file. A mixed mode is supported storing a certain amount of pages in memory and only the additional ones in temporary file (defined by maximum main memory to be used).
Pages can be marked as 'free' in order to re-use them. For in-memory pages this will release the used memory while for pages in temporary file this simply marks the area as free to re-use.
If a temporary file was created (done with the first page to be stored in temporary file) it is deleted when
close()is called.Using this class for
RandomAccessbuffers allows for a direct control on the maximum memory usage and allows processing large files for which we otherwise would get anOutOfMemoryErrorin case of usingRandomAccessReadBuffer.This base class for providing pages is thread safe (the buffer implementations are not).
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from interface org.apache.pdfbox.io.RandomAccessStreamCache
RandomAccessStreamCache.StreamCacheCreateFunction
-
-
Constructor Summary
Constructors Constructor Description ScratchFile(java.io.File scratchFileDirectory)Initializes page handler.ScratchFile(MemoryUsageSetting memUsageSetting)Initializes page handler.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description voidclose()Closes and deletes the temporary file.RandomAccesscreateBuffer()Creates a new buffer using this page handler.static ScratchFilegetMainMemoryOnlyInstance()Getter for an instance using only unrestricted main memory for buffering (same asnew ScratchFile(MemoryUsageSetting.setupMainMemoryOnly())).static ScratchFilegetMainMemoryOnlyInstance(long maxMainMemoryBytes)Getter for an instance to only use main-memory with the defined maximum.
-
-
-
Constructor Detail
-
ScratchFile
public ScratchFile(java.io.File scratchFileDirectory) throws java.io.IOExceptionInitializes page handler. If ascratchFileDirectoryis supplied, then the scratch file will be created in that directory.All pages will be stored in the scratch file.
- Parameters:
scratchFileDirectory- The directory in which to create the scratch file ornullto created it in the default temporary directory.- Throws:
java.io.IOException- If scratch file directory was given but don't exist.
-
ScratchFile
public ScratchFile(MemoryUsageSetting memUsageSetting) throws java.io.IOException
Initializes page handler. If ascratchFileDirectoryis supplied, then the scratch file will be created in that directory.Depending on the size of allowed memory usage a number of pages (memorySize/
PAGE_SIZE) will be stored in-memory and only additional pages will be written to/read from scratch file.- Parameters:
memUsageSetting- set how memory/temporary files are used for buffering streams etc.- Throws:
java.io.IOException- If scratch file directory was given but don't exist.
-
-
Method Detail
-
getMainMemoryOnlyInstance
public static ScratchFile getMainMemoryOnlyInstance()
Getter for an instance using only unrestricted main memory for buffering (same asnew ScratchFile(MemoryUsageSetting.setupMainMemoryOnly())).- Returns:
- instance configured to only use main memory with no size restriction
-
getMainMemoryOnlyInstance
public static ScratchFile getMainMemoryOnlyInstance(long maxMainMemoryBytes)
Getter for an instance to only use main-memory with the defined maximum.- Parameters:
maxMainMemoryBytes- maximum number of main-memory to be used;-1for no restriction;0will also be interpreted here as no restriction- Returns:
- instance configured to only use main memory with no size restriction or null if cannot create scratch file
-
createBuffer
public RandomAccess createBuffer() throws java.io.IOException
Creates a new buffer using this page handler.- Specified by:
createBufferin interfaceRandomAccessStreamCache- Returns:
- A new buffer.
- Throws:
java.io.IOException- If an error occurred.
-
close
public void close() throws java.io.IOExceptionCloses and deletes the temporary file. No further interaction with the scratch file or associated buffers can happen after this method is called. It also releases in-memory pages.- Specified by:
closein interfacejava.lang.AutoCloseable- Specified by:
closein interfacejava.io.Closeable- Throws:
java.io.IOException- If there was a problem closing or deleting the temporary file.
-
-