public abstract class FingerprintTransparency extends Object implements AutoCloseable
Applications can subclass FingerprintTransparency
and override take(String, String, byte[])
method to define new transparency data logger. One default implementation of FingerprintTransparency
is returned by zip(OutputStream)
method. Applications can control what transparency data gets produced by overriding accepts(String)
.
FingerprintTransparency
instance should be created in a try-with-resources construct. It will be capturing transparency data from all operations on current thread between invocation of the constructor and invocation of close()
method, which is called automatically in the try-with-resources construct.
Modifier | Constructor and Description |
---|---|
protected |
FingerprintTransparency()
Creates an instance of FingerprintTransparency and activates it.
|
Modifier and Type | Method and Description |
---|---|
boolean |
accepts(String key)
Filters transparency data keys that can be passed to take(String, String, byte[]) .
|
protected void |
capture(String key, Map<String,Supplier<byte[]>> data)
Deprecated.
|
void |
close()
Deactivates transparency logging and releases system resources held by this instance if any.
|
protected void |
log(String key, Map<String,Supplier<ByteBuffer>> data)
Deprecated.
|
void |
take(String key, String mime, byte[] data)
Records transparency data.
|
static FingerprintTransparency |
zip(OutputStream stream)
Writes all transparency data to a ZIP file.
|
protected FingerprintTransparency()
FingerprintTransparency
and activates it.
Activation places the new FingerprintTransparency
instance in thread-local storage, which causes all operations executed by current thread to log data to this FingerprintTransparency
instance. If activations are nested, data is only logged to the currently innermost FingerprintTransparency
.
Deactivation happens in close()
method. Instances of FingerprintTransparency
should be created in try-with-resources construct to ensure that close()
is always called.
FingerprintTransparency
is an abstract class. This constructor is only called by subclasses.
close()
public boolean accepts(String key)
take(String, String, byte[])
. Default implementation always returns true
, i.e. all transparency data is passed to take(String, String, byte[])
. Implementation can override this method to filter some keys out, which improves performance.
This method should always return the same result for the same key. Result may be cached and this method might not be called every time something is about to be logged.
key
- transparency data key as used in take(String, String, byte[])
take(String, String, byte[])
public void take(String key, String mime, byte[] data)
FingerprintTransparency
object is active (between call to the constructor and call to close()
), this method is called with transparency data in its parameters.
Parameter key
specifies the kind of transparency data being logged, usually corresponding to some stage in the algorithm. Parameter data
then contains the actual transparency data. This method may be called multiple times with the same key
if the algorithm produces that kind of transparency data repeatedly. See algorithm transparency on SourceAFIS website for documentation of the structure of the transparency data.
Transparency data is offered only if accepts(String)
returns true
for the same key
. This allows applications to efficiently collect only transparency data that is actually needed.
MIME type of the transparency data is provided, which may be useful for generic implementations, for example transparency data browser app that changes type of visualization based on the MIME type. Most transparency data is serialized in CBOR format (MIME application/cbor).
Implementations of this method should be synchronized. Although the current SourceAFIS algorithm is single-threaded, future versions of SourceAFIS might run some parts of the algorithm in parallel, which would result in concurrent calls to this method.
If this method throws, exception is propagated through SourceAFIS code.
key
- specifies the kind of transparency data being logged
mime
- MIME type of the transparency data in data
parameter
data
- transparency data being logged
accepts(String)
, zip(OutputStream)
@Deprecated protected void capture(String key, Map<String,Supplier<byte[]>> data)
take(String, String, byte[])
. This method is only called if take(String, String, byte[])
is not overridden.
key
- specifies the kind of transparency data being reported
data
- a map of suffixes (like .cbor
or .dat
) to Supplier
of the available transparency data
take(String, String, byte[])
@Deprecated protected void log(String key, Map<String,Supplier<ByteBuffer>> data)
take(String, String, byte[])
. This method is only called if take(String, String, byte[])
and capture(String, Map)
are not overridden.
key
- specifies the kind of transparency data being reported
data
- a map of suffixes (like .cbor
or .dat
) to Supplier
of the available transparency data
take(String, String, byte[])
public void close()
FingerprintTransparency
is used in try-with-resources construct.
Deactivation stops transparency data logging to this instance of FingerprintTransparency
. Logging thus takes place between invocation of constructor (FingerprintTransparency()
) and invocation of this method. If activations were nested, this method reactivates the outer FingerprintTransparency
.
Subclasses can override this method to perform cleanup. Default implementation of this method performs deactivation. It must be called by overriding methods for deactivation to work correctly.
This method doesn't declare any checked exceptions in order to spare callers of mandatory exception handling. If your code needs to throw a checked exception, wrap it in an unchecked exception.
close
in interface AutoCloseable
FingerprintTransparency()
public static FingerprintTransparency zip(OutputStream stream)
FingerprintTransparency
and overriding take(String, String, byte[])
method.
ZIP file entries have filenames like NNN-key.ext
where NNN
is a sequentially assigned ID, key
comes from take(String, String, byte[])
parameter, and ext
is derived from MIME type.
The returned FingerprintTransparency
object holds system resources and callers are responsible for calling close()
method, perhaps using try-with-resources construct. Failure to close the returned FingerprintTransparency
instance may result in damaged ZIP file.
If the provided stream
throws IOException
, the exception will be wrapped in an unchecked exception and propagated.
stream
- output stream where ZIP file will be written (will be closed when the returned FingerprintTransparency
is closed)
close()
, take(String, String, byte[])
Copyright © 2009–2020 Robert Važan. All rights reserved.