Add capability to report files composing a store reader

Proposal: Add capability to report files composing a store/reader

• Contact: dromagnoli
• Tracker: https://osgeo-org.atlassian.net/browse/GEOT-5247
• TLDR: Add capability to report files composing a store/reader
• Branch: https://github.com/dromagnoli/geotools/tree/GEOT-5247

Description

The goal of this work is to add a way to determine which files compose a store or a reader. This new capability will be helpful for modules like, as an instance, the GeoServer Importer which needs to get knowledge about the associated files for an imported element. Or for the incoming CSW's DirectDownload vendor operation which basically allows to get the raw data associated with a layer.

We need to define a couple of new interfaces and classes to do this.

FileResourceInfo extending ResourceInfo, providing file resource content, for a single element in the source (feature source, coverage)

FileServiceInfo extending ServiceInfo, providing file info content, for the whole store.

Both interfaces also extend a new FileGroupProvider interface which is delegated to be queried to return a CloseableIterator of FileGroups.

CloseableIterator is a new interface exposing a close method. Note that the ShapeFile module already defines a CloseableIterator interface defining a close method. We can take the occasion with this proposal to deprecate this interface and copy it in gt-api. Returning an iterator instead of a simple List allows to deal with cases of sources composed of thousands of hundreds of files (think about a big imageMosaic) making the Files retrieval scalable.

FileGroup is a container Class composed of

• a main File
• a List of support files
• a metadata map.

You may think about a World image file made of a .TIF, .PRJ, .TFW triplet where the main file is the .TIF one and support files are the other two. Finally, a Metadata map will be used to contain any kind of information we need to associate to the group itself. This can be used as an instance when dealing with a data file related to a format which has multidimensional content. We will use the metadata map to report the domains (temporal/vertical/others) of validity of that file.

GridCoverage2DReader interface will be updated to define:

• a getInfo(name) method returning ResourceInfo associated with a specific coverage.
• a getInfo() method returning generic ServiceInfo

References:

• geotools-devel email discussion

Status

Choose one of:

• Under Discussion
• In Progress
• Completed
• Rejected,
• Deferred

Voting:

• Andrea Aime +1
• Ben Caradoc-Davies
• Christian Mueller
• Ian Turton
• Justin Deoliveira
• Jody Garnett
• Simone Giannecchini +1

Tasks

1. Update implementation
2. Pull request

API Change

New interfaces

public interface FileServiceInfo extends ServiceInfo, FileGroupProvider {

    /**
     * FileGroups providing info content. 
     *
     * @return A CloseableIterator<FileGroup> providing info content.
     */
    CloseableIterator<FileGroup> getFiles(Query query);
}

public interface FileResourceInfo extends ResourceInfo, FileGroupProvider {

    /**
     * FileGroups providing resource content. 
     *
     * @return A CloseableIterator<FileGroup> providing info content.
     */
    CloseableIterator<FileGroup> getFiles(Query query);
}

public interface FileGroupProvider {

    /** 
     * Return {@link FileGroup}s matching the specified query (if any).
     * 
     * Specifying a <code>null</code> query will result in returning
     * all the available {@link FileGroup}s.
     *   
     */
    CloseableIterator<FileGroup> getFiles(Query query);

    /**
     * A Group of Files consisting of a reference to a mainFile, plus a set of 
     * support Files (if any) and metadata map. 
     */
    public static class FileGroup {

        /** The main File of the group */
        File mainFile = null;

        /** The support files (if any) */
        List<File> supportFiles = null;

        /**
         * Metadata for this group.
         * As an instance, domain information) 
         * A sample entry of that mapping could be <"time",DateRange> 
         * to indicate that this group is covering the reported time range.
         */
        Map<String, Object> metadata;

        public void setMainFile(File mainFile) {
            this.mainFile = mainFile;
        }

        public void setSupportFiles(List<File> supportFiles) {
            this.supportFiles = supportFiles;
        }

        public void setMetadata(Map<String, Object> metadata) {
            this.metadata = metadata;
        }

        public File getMainFile() {
            return mainFile;
        }

        public List<File> getSupportFiles() {
            return supportFiles;
        }

        public Map<String, Object> getMetadata() {
            return metadata;
        }

    }

/**
 * An iterator backed by some resource that needs closing when done using it
 */
public interface CloseableIterator<T> extends Iterator<T>, Closeable {

    /**
     * @throws IOException if an I/O error occurs
     */
    @Override
    public void close() throws IOException;

}