Package ch.systemsx.cisd.openbis.dss.client.api.v1

Interface IDataSetDss

  • All Known Implementing Classes:
    DataSetDss
    public interface IDataSetDss
    The representation of a Data Set managed by a DSS server. It is safe to use instances in multiple threads.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      java.lang.String getCode()
      The code of this data set.
      java.io.InputStream getFile​(java.lang.String path)
      Get an InputStream with contents of a file contained in this data set.
      java.io.File getLinkOrCopyOfContent​(java.lang.String overrideStoreRootPathOrNull, java.io.File downloadDir, java.lang.String pathInDataSet)
      Returns a File, if possible, that directly references some specified content of a data set in the data store server.
      java.io.File getLinkOrCopyOfContents​(java.lang.String overrideStoreRootPathOrNull, java.io.File downloadDir)
      Returns a File, if possible, that directly references the contents of a data set in the data store server.
      java.lang.String getSessionURLForFile​(java.lang.String path)
      Get a URL that will return the contents of a file contained in this data set.
      java.lang.String getURLForFileWithTimeout​(java.lang.String path, long validityDurationInSeconds)
      Get a URL that will return the contents of a file contained in this data set.
      FileInfoDssDTO[] listFiles​(java.lang.String startPath, boolean isRecursive)
      List files contained in this data set.
      java.lang.String tryGetInternalPathInDataStore()
      Returns the internal storage path of this data set in the datastore.
      java.io.File tryLinkToContents​(java.lang.String overrideStoreRootPathOrNull)
      Returns a File, if possible, that directly references the contents of a data set in the data store server.

    • Method Detail

      • getCode

        java.lang.String getCode()
        The code of this data set.

      • listFiles

        FileInfoDssDTO[] listFiles​(java.lang.String startPath,
                           boolean isRecursive)
                    throws java.lang.IllegalArgumentException,
                           InvalidSessionException
        List files contained in this data set.
        Parameters:
        startPath - The path for the listing. The path must be relative with respect to the data set, such as the path returned by FileInfoDssDTO.getPathInDataSet(). Use "/" or "" for the root of the hierarchy for this data set.
        isRecursive - If true, the contents of any subdirectories will be listed as well.
        Throws:
        java.lang.IllegalArgumentException
        InvalidSessionException

      • getFile

        java.io.InputStream getFile​(java.lang.String path)
                     throws java.lang.IllegalArgumentException,
                            InvalidSessionException
        Get an InputStream with contents of a file contained in this data set.
        Parameters:
        path - The path of the file to retrieve. The path must be relative with respect to the data set, such as the path returned by FileInfoDssDTO.getPathInDataSet().
        Throws:
        java.lang.IllegalArgumentException
        InvalidSessionException

      • getSessionURLForFile

        java.lang.String getSessionURLForFile​(java.lang.String path)
                               throws java.lang.IllegalArgumentException,
                                      InvalidSessionException
        Get a URL that will return the contents of a file contained in this data set. The URL will be valid for the lifetime of the session.
        Parameters:
        path - The path of the file to retrieve. The path must be relative with respect to the data set, such as the path returned by FileInfoDssDTO.getPathInDataSet().
        Throws:
        java.lang.IllegalArgumentException
        InvalidSessionException

      • getURLForFileWithTimeout

        java.lang.String getURLForFileWithTimeout​(java.lang.String path,
                                          long validityDurationInSeconds)
                                   throws java.lang.IllegalArgumentException,
                                          InvalidSessionException
        Get a URL that will return the contents of a file contained in this data set. The URL will be valid for specified time duration.
        Parameters:
        path - The path of the file to retrieve. The path must be relative with respect to the data set, such as the path returned by FileInfoDssDTO.getPathInDataSet().
        validityDurationInSeconds - The number of seconds for which the URL is valid.
        Throws:
        java.lang.IllegalArgumentException
        InvalidSessionException

      • tryLinkToContents

        java.io.File tryLinkToContents​(java.lang.String overrideStoreRootPathOrNull)
                        throws InvalidSessionException
        Returns a File, if possible, that directly references the contents of a data set in the data store server. This is only possible if the file system used by the DSS is also mounted locally.
        Parameters:
        overrideStoreRootPathOrNull - A path, in the context of the local file system mounts, to the DSS' store root. If null, paths are returned in the context of the DSS' file system mounts.
        Returns:
        Returns null if the operation is not possible (e.g. when the data set is a container), a File that references the contents of the data set otherwise.
        Throws:
        InvalidSessionException
        Since:
        1.1

      • tryGetInternalPathInDataStore

        java.lang.String tryGetInternalPathInDataStore()
                                        throws InvalidSessionException
        Returns the internal storage path of this data set in the datastore.

        Caution: using the return value of this methods to perform any operation on the dataset, e.g. in your own scripts, scripts opens you to a set of race conditions, e.g. when the dataset is moved to another share or deleted. Consider using tryLinkToContents(String) if you are actually interested in the data set content.

        Returns:
        Returns null if the operation is not possible (e.g. when the data set is a container), the path of the data set in the data store otherwise.
        Throws:
        InvalidSessionException
        Since:
        1.1 (API call)

      • getLinkOrCopyOfContents

        java.io.File getLinkOrCopyOfContents​(java.lang.String overrideStoreRootPathOrNull,
                                     java.io.File downloadDir)
                              throws java.lang.IllegalArgumentException,
                                     InvalidSessionException
        Returns a File, if possible, that directly references the contents of a data set in the data store server. If not possible, downloads the data set contents and returns a File in the downloadDir containing the contents of the data set.
        Parameters:
        overrideStoreRootPathOrNull - A path, in the context of the local file system mounts, to the DSS' store root. If null, datasets are copied to the downloadDir folder.
        downloadDir - The directory in which to place the contents of the data set if they must be downloaded.
        Returns:
        A File containing the contents of the data set.
        Throws:
        java.lang.IllegalArgumentException
        InvalidSessionException
        Since:
        1.1

      • getLinkOrCopyOfContent

        java.io.File getLinkOrCopyOfContent​(java.lang.String overrideStoreRootPathOrNull,
                                    java.io.File downloadDir,
                                    java.lang.String pathInDataSet)
                             throws java.lang.IllegalArgumentException,
                                    InvalidSessionException
        Returns a File, if possible, that directly references some specified content of a data set in the data store server. If not possible, downloads that content and returns a File in the downloadDir containing that content.
        Parameters:
        overrideStoreRootPathOrNull - A path, in the context of the local file system mounts, to the DSS' store root. If null, datasets are copied to the downloadDir folder.
        downloadDir - The directory in which to place the contents of the data set if they must be downloaded.
        pathInDataSet - Path of requested content inside the data set.
        Returns:
        A File containing the requested content.
        Throws:
        java.lang.IllegalArgumentException
        InvalidSessionException