Class FingerprintTransparency

  • All Implemented Interfaces:
    com.machinezoo.noexception.CloseableScope, AutoCloseable

    public abstract class FingerprintTransparency
    extends Object
    implements com.machinezoo.noexception.CloseableScope
    Algorithm transparency API that can capture all intermediate data structures produced by SourceAFIS algorithm. See algorithm transparency pages on SourceAFIS website for more information and a tutorial on how to use this class.

    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.

    See Also:
    Algorithm transparency in SourceAFIS
    • Constructor Detail

      • FingerprintTransparency

        protected FingerprintTransparency()
        Creates an instance of 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.

        See Also:
        close()
    • Method Detail

      • accepts

        public boolean accepts​(String key)
        Filters transparency data keys that can be passed to 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.

        Parameters:
        key - transparency data key as used in take(String, String, byte[])
        Returns:
        whether transparency data under given key should be logged
        See Also:
        take(String, String, byte[])
      • take

        public void take​(String key,
                         String mime,
                         byte[] data)
        Records transparency data. Subclasses must override this method, because the default implementation does nothing. While this 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.

        Parameters:
        key - specifies the kind of transparency data being logged
        mime - MIME type of the transparency data in data parameter
        data - transparency data being logged
        See Also:
        Algorithm transparency in SourceAFIS, accepts(String), zip(OutputStream)
      • close

        public void close()
        Deactivates transparency logging and releases system resources held by this instance if any. This method is normally called automatically when 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.

        Specified by:
        close in interface AutoCloseable
        Specified by:
        close in interface com.machinezoo.noexception.CloseableScope
        See Also:
        FingerprintTransparency()
      • zip

        public static FingerprintTransparency zip​(OutputStream stream)
        Writes all transparency data to a ZIP file. This is a convenience method to enable easy exploration of the available data. Programmatic processing of transparency data should be done by subclassing 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.

        Parameters:
        stream - output stream where ZIP file will be written (will be closed when the returned FingerprintTransparency is closed)
        Returns:
        algorithm transparency logger that writes data to a ZIP file
        See Also:
        Algorithm transparency in SourceAFIS, close(), take(String, String, byte[])