loci.formats

Class Memoizer

java.lang.Object

loci.formats.ReaderWrapper

loci.formats.Memoizer

All Implemented Interfaces:

Closeable, AutoCloseable, IFormatHandler, IFormatReader, IMetadataConfigurable

public class Memoizer
extends ReaderWrapper

ReaderWrapper implementation which caches the state of the delegate (including and other ReaderWrapper instances) after setId has been called.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Memoizer.Deser
static class	Memoizer.KryoDeser
private static class	Memoizer.RandomAccessDeser Helper implementation that can be used to implement Memoizer.Deser classes for libraries working solely with byte arrays.

Field Summary

Fields

Modifier and Type	Field and Description
static long	DEFAULT_MINIMUM_ELAPSED Default value for minimumElapsed if none is provided in the constructor.
private File	directory Directory where all memo files should be created.
private boolean	doInPlaceCaching If True, then all memo files will be created in the same directory as the original file.
private boolean	loadedFromMemo Whether the ReaderWrapper.reader instance currently active was loaded from the memo file during setId(String).
private static org.slf4j.Logger	LOGGER
private File	memoFile
private long	minimumElapsed Minimum number of milliseconds which must elapse during the call to setId(java.lang.String) before a memo file will be created.
private Location	realFile
private MetadataStore	replacementMetadataStore MetadataStore created internally.
private boolean	savedToMemo Whether the ReaderWrapper.reader instance was saved to a memo file on setId(String).
protected Memoizer.Deser	ser
private OMEXMLService	service
private boolean	skipLoad
private boolean	skipSave
private File	tempFile
private MetadataStore	userMetadataStore MetadataStore set by the caller.
static Integer	VERSION Defines the file format.
private boolean	versionChecking Whether to invalidate the memo file based upon mismatched major/minor version numbers.

Fields inherited from class loci.formats.ReaderWrapper

reader

Fields inherited from interface loci.formats.IFormatReader

CAN_GROUP, CANNOT_GROUP, MUST_GROUP

Constructor Summary

Constructors

Constructor and Description
Memoizer() Constructs a memoizer around a new ImageReader creating memo files under the same directory as the original file only if the call to setId(java.lang.String) takes longer than 100L in milliseconds.
Memoizer(IFormatReader r) Constructs a memoizer around the given IFormatReader creating memo files under the same directory as the original file only if the call to setId(java.lang.String) takes longer than 100L in milliseconds.
Memoizer(IFormatReader r, long minimumElapsed) Constructs a memoizer around the given IFormatReader creating memo files under the same directory as the original file only if the call to setId(java.lang.String) takes longer than minimumElapsed in milliseconds.
Memoizer(IFormatReader r, long minimumElapsed, File directory) Constructs a memoizer around the given IFormatReader creating memo files under the directory argument including the full path of the original file only if the call to setId(java.lang.String) takes longer than minimumElapsed in milliseconds.
Memoizer(long minimumElapsed) Constructs a memoizer around a new ImageReader creating memo files under the same directory as the original file only if the call to setId(java.lang.String) takes longer than minimumElapsed in milliseconds.
Memoizer(long minimumElapsed, File directory) Constructs a memoizer around a new ImageReader creating memo files under the directory argument including the full path of the original file only if the call to setId(java.lang.String) takes longer than minimumElapsed in milliseconds.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	cleanup()
void	close()
void	close(boolean fileOnly) Closes the currently open file.
protected boolean	deleteQuietly(File file) Attempts to delete an existing file, logging at warn if the deletion returns false or at error if an exception is thrown.
protected Memoizer.Deser	getDeser() Returns a configured Kryo instance.
File	getMemoFile(String id) Constructs a File object from id string.
MetadataStore	getMetadataStore() Retrieves the current metadata store for this reader.
protected OMEXMLService	getService()
protected IFormatReader	handleMetadataStore(IFormatReader memo) Return the IFormatReader instance that is passed in or null if it has been invalidated, which will include the instance being closed.
boolean	isLoadedFromMemo() Returns whether the ReaderWrapper.reader instance currently active was loaded from the memo file during setId(String).
boolean	isSavedToMemo() Returns whether the ReaderWrapper.reader instance currently active was saved to the memo file during setId(String).
boolean	isVersionChecking() Returns whether or not version checking is done based upon major/minor version numbers.
private static void	load(String id, File tmp, boolean delete)
IFormatReader	loadMemo() Load a memo file if possible, returning a null if not.
static void	main(String[] args)
boolean	saveMemo()
void	setId(String id) Sets the current file name.
void	setMetadataStore(MetadataStore store) Sets the default metadata store for this reader.
void	setVersionChecking(boolean version) Set whether version checking is done based upon major/minor version numbers.
protected org.perf4j.slf4j.Slf4JStopWatch	stopWatch()
boolean	versionMismatch() Returns true if the version of the memo file as returned by Memoizer.Deser.loadReleaseVersion() and Memoizer.Deser.loadRevision() do not match the current version as specified by FormatTools.VERSION and FormatTools.VCS_REVISION, respectively.

Methods inherited from class loci.formats.ReaderWrapper

coreIndexToSeries, duplicate, fileGroupOption, get16BitLookupTable, get8BitLookupTable, getAdvancedSeriesUsedFiles, getAdvancedUsedFiles, getBitsPerPixel, getCoreIndex, getCoreMetadataList, getCurrentFile, getDatasetStructureDescription, getDimensionOrder, getDomains, getEffectiveSizeC, getFormat, getGlobalMetadata, getImageCount, getIndex, getIndex, getMetadataOptions, getMetadataStoreRoot, getMetadataValue, getModuloC, getModuloT, getModuloZ, getNativeDataType, getOptimalTileHeight, getOptimalTileWidth, getPixelType, getPossibleDomains, getReader, getRequiredDirectories, getResolution, getResolutionCount, getRGBChannelCount, getSeries, getSeriesCount, getSeriesMetadata, getSeriesMetadataValue, getSeriesUsedFiles, getSeriesUsedFiles, getSizeC, getSizeT, getSizeX, getSizeY, getSizeZ, getSuffixes, getSupportedMetadataLevels, getThumbSizeX, getThumbSizeY, getUnderlyingReaders, getUsedFiles, getUsedFiles, getZCTCoords, getZCTModuloCoords, hasCompanionFiles, hasFlattenedResolutions, isFalseColor, isGroupFiles, isIndexed, isInterleaved, isInterleaved, isLittleEndian, isMetadataComplete, isMetadataFiltered, isNormalized, isOrderCertain, isOriginalMetadataPopulated, isRGB, isSingleFile, isThisType, isThisType, isThisType, isThisType, isThumbnailSeries, openBytes, openBytes, openBytes, openBytes, openPlane, openThumbBytes, reopenFile, seriesToCoreIndex, setCoreIndex, setFlattenedResolutions, setGroupFiles, setMetadataFiltered, setMetadataOptions, setNormalized, setOriginalMetadataPopulated, setResolution, setSeries, unwrap, unwrap, unwrap

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

VERSION

public static final Integer VERSION

Defines the file format. Bumping this number will invalidate all other cached items. This should happen when the order and type of objects stored in the memo file changes.

DEFAULT_MINIMUM_ELAPSED

public static final long DEFAULT_MINIMUM_ELAPSED

Default value for minimumElapsed if none is provided in the constructor.

See Also:

Constant Field Values

LOGGER

private static final org.slf4j.Logger LOGGER

minimumElapsed

private final long minimumElapsed

Minimum number of milliseconds which must elapse during the call to setId(java.lang.String) before a memo file will be created.

directory

private final File directory

Directory where all memo files should be created. If this value is non-null, then all memo files will be created under it. Can be overriden by inPlaceCaching.

doInPlaceCaching

private boolean doInPlaceCaching

If True, then all memo files will be created in the same directory as the original file.

ser

protected transient Memoizer.Deser ser

service

private transient OMEXMLService service

realFile

private Location realFile

memoFile

private File memoFile

tempFile

private File tempFile

skipLoad

private boolean skipLoad

skipSave

private boolean skipSave

versionChecking

private boolean versionChecking

Whether to invalidate the memo file based upon mismatched major/minor version numbers. By default, the Git commit hash is used to invalidate the memo file.

loadedFromMemo

private boolean loadedFromMemo

Whether the ReaderWrapper.reader instance currently active was loaded from the memo file during setId(String).

savedToMemo

private boolean savedToMemo

Whether the ReaderWrapper.reader instance was saved to a memo file on setId(String).

userMetadataStore

private MetadataStore userMetadataStore

MetadataStore set by the caller. This value will be held locally and not set on the ReaderWrapper.reader delegate until the execution of setId(String). If no value has been set by the caller, then no special actions are taken during setId(String). If a value is set, however, we must be careful with attempting to serialize it

See Also:

handleMetadataStore(IFormatReader)

replacementMetadataStore

private MetadataStore replacementMetadataStore

MetadataStore created internally.

See Also:

handleMetadataStore(IFormatReader)

Constructor Detail

Memoizer

public Memoizer()

Constructs a memoizer around a new ImageReader creating memo files under the same directory as the original file only if the call to setId(java.lang.String) takes longer than 100L in milliseconds.

Memoizer

public Memoizer(long minimumElapsed)

Constructs a memoizer around a new ImageReader creating memo files under the same directory as the original file only if the call to setId(java.lang.String) takes longer than minimumElapsed in milliseconds.

Parameters:

minimumElapsed - a long specifying the number of milliseconds which must elapse during the call to setId(java.lang.String) before a memo file will be created.

Memoizer

public Memoizer(long minimumElapsed,
        File directory)

Constructs a memoizer around a new ImageReader creating memo files under the directory argument including the full path of the original file only if the call to setId(java.lang.String) takes longer than minimumElapsed in milliseconds.

Parameters:

minimumElapsed - a long specifying the number of milliseconds which must elapse during the call to setId(java.lang.String) before a memo file will be created.

directory - a File specifying the directory where all memo files should be created. If null, disable memoization.

Memoizer

public Memoizer(IFormatReader r)

Constructs a memoizer around the given IFormatReader creating memo files under the same directory as the original file only if the call to setId(java.lang.String) takes longer than 100L in milliseconds.

Parameters:

r - an IFormatReader instance

Memoizer

public Memoizer(IFormatReader r,
        long minimumElapsed)

Constructs a memoizer around the given IFormatReader creating memo files under the same directory as the original file only if the call to setId(java.lang.String) takes longer than minimumElapsed in milliseconds.

Parameters:

r - an IFormatReader instance

minimumElapsed - a long specifying the number of milliseconds which must elapse during the call to setId(java.lang.String) before a memo file will be created.

Memoizer

public Memoizer(IFormatReader r,
        long minimumElapsed,
        File directory)

Constructs a memoizer around the given IFormatReader creating memo files under the directory argument including the full path of the original file only if the call to setId(java.lang.String) takes longer than minimumElapsed in milliseconds.

Parameters:

r - an IFormatReader instance

minimumElapsed - a long specifying the number of milliseconds which must elapse during the call to setId(java.lang.String) before a memo file will be created.

directory - a File specifying the directory where all memo files should be created. If null, disable memoization.

Method Detail

isLoadedFromMemo

public boolean isLoadedFromMemo()

Returns whether the ReaderWrapper.reader instance currently active was loaded from the memo file during setId(String).

isSavedToMemo

public boolean isSavedToMemo()

Returns whether the ReaderWrapper.reader instance currently active was saved to the memo file during setId(String).

isVersionChecking

public boolean isVersionChecking()

Returns whether or not version checking is done based upon major/minor version numbers.

versionMismatch

public boolean versionMismatch()
                        throws IOException

Returns true if the version of the memo file as returned by Memoizer.Deser.loadReleaseVersion() and Memoizer.Deser.loadRevision() do not match the current version as specified by FormatTools.VERSION and FormatTools.VCS_REVISION, respectively.

Throws:

IOException

setVersionChecking

public void setVersionChecking(boolean version)

Set whether version checking is done based upon major/minor version numbers. If 'true' is passed in, then a mismatch between the major/minor version of the calling code (e.g. 4.4) and the major/minor version saved in the memo file (e.g. 5.0) will result in the memo file being invalidated. By default, a mismatch in the Git commit hashes will invalidate the memo file; this method allows for less strict version checking.

cleanup

protected void cleanup()

close

public void close()
           throws IOException

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Overrides:

close in class ReaderWrapper

Throws:

IOException

close

public void close(boolean fileOnly)
           throws IOException

Description copied from interface: IFormatReader

Closes the currently open file. If the flag is set, this is all that happens; if unset, it is equivalent to calling Closeable.close().

Specified by:

close in interface IFormatReader

Overrides:

close in class ReaderWrapper

Throws:

IOException

setId

public void setId(String id)
           throws FormatException,
                  IOException

Description copied from interface: IFormatHandler

Sets the current file name.

Specified by:

setId in interface IFormatHandler

Overrides:

setId in class ReaderWrapper

Throws:

FormatException

IOException

setMetadataStore

public void setMetadataStore(MetadataStore store)

Description copied from interface: IFormatReader

Sets the default metadata store for this reader.

Specified by:

setMetadataStore in interface IFormatReader

Overrides:

setMetadataStore in class ReaderWrapper

Parameters:

store - a metadata store implementation.

getMetadataStore

public MetadataStore getMetadataStore()

Description copied from interface: IFormatReader

Retrieves the current metadata store for this reader. You can be assured that this method will never return a null metadata store.

Specified by:

getMetadataStore in interface IFormatReader

Overrides:

getMetadataStore in class ReaderWrapper

Returns:

A metadata store implementation.

deleteQuietly

protected boolean deleteQuietly(File file)

Attempts to delete an existing file, logging at warn if the deletion returns false or at error if an exception is thrown.

Returns:

the result from File.delete() or false if an exception is thrown.

getDeser

protected Memoizer.Deser getDeser()

Returns a configured Kryo instance. This method can be modified by consumers. The returned instance is not thread-safe.

Returns:

a non-null Kryo instance.

getService

protected OMEXMLService getService()
                            throws MissingLibraryException

Throws:

MissingLibraryException

stopWatch

protected org.perf4j.slf4j.Slf4JStopWatch stopWatch()

getMemoFile

public File getMemoFile(String id)

Constructs a File object from id string. This method can be modified by consumers, but then existing memo files will not be found.

Parameters:

id - the path passed to setId(java.lang.String)

Returns:

a File object pointing at the location of the memo file

loadMemo

public IFormatReader loadMemo()
                       throws IOException,
                              FormatException

Load a memo file if possible, returning a null if not. Corrupt memo files will be deleted if possible. Kryo exceptions should never propagate to the caller. Only the regular Bio-Formats exceptions should be thrown.

Throws:

IOException

FormatException

saveMemo

public boolean saveMemo()

handleMetadataStore

protected IFormatReader handleMetadataStore(IFormatReader memo)
                                     throws MissingLibraryException

Return the IFormatReader instance that is passed in or null if it has been invalidated, which will include the instance being closed.

• Serialization: If an unknown MetadataStore implementation is passed in when no memo file exists, then a replacement MetadataStore will be created and set on the ReaderWrapper.reader delegate before calling ReaderWrapper.setId(String). This stack will then be serialized, before any values are copied into userMetadataStore.
• Deserialization: If an unknown MetadataStore implementation is set before calling setId(String) then ...

Throws:

MissingLibraryException

main

public static void main(String[] args)
                 throws Exception

Throws:

Exception

load

private static void load(String id,
        File tmp,
        boolean delete)
                  throws Exception

Throws:

Exception