content: /*
   * The Alluxio Open Foundation licenses this work under the Apache License, version 2.0
   * (the "License"). You may not use this work except in compliance with the License, which is
   * available at www.apache.org/licenses/LICENSE-2.0
   *
   * This software is distributed on an "AS IS" basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
   * either express or implied, as more fully set forth in the License.
   *
   * See the NOTICE file distributed with this work for information regarding copyright ownership.
   */
  
  package alluxio.client.file;
  
  import alluxio.AlluxioURI;
  import alluxio.Client;
  import alluxio.exception.status.AlluxioStatusException;
  import alluxio.exception.status.AlreadyExistsException;
  import alluxio.exception.status.NotFoundException;
  import alluxio.grpc.CancelSyncMetadataPResponse;
  import alluxio.grpc.CheckAccessPOptions;
  import alluxio.grpc.CheckConsistencyPOptions;
  import alluxio.grpc.CompleteFilePOptions;
  import alluxio.grpc.CreateDirectoryPOptions;
  import alluxio.grpc.CreateFilePOptions;
  import alluxio.grpc.DeletePOptions;
  import alluxio.grpc.ExistsPOptions;
  import alluxio.grpc.FreePOptions;
  import alluxio.grpc.GetStatusPOptions;
  import alluxio.grpc.GetSyncProgressPResponse;
  import alluxio.grpc.JobProgressReportFormat;
  import alluxio.grpc.ListStatusPOptions;
  import alluxio.grpc.ListStatusPartialPOptions;
  import alluxio.grpc.MountPOptions;
  import alluxio.grpc.RenamePOptions;
  import alluxio.grpc.ScheduleAsyncPersistencePOptions;
  import alluxio.grpc.SetAclAction;
  import alluxio.grpc.SetAclPOptions;
  import alluxio.grpc.SetAttributePOptions;
  import alluxio.grpc.SyncMetadataAsyncPResponse;
  import alluxio.grpc.SyncMetadataPOptions;
  import alluxio.grpc.SyncMetadataPResponse;
  import alluxio.grpc.UpdateUfsModePOptions;
  import alluxio.job.JobDescription;
  import alluxio.job.JobRequest;
  import alluxio.master.MasterClientContext;
  import alluxio.security.authorization.AclEntry;
  import alluxio.wire.MountPointInfo;
  import alluxio.wire.SyncPointInfo;
  
  import java.util.List;
  import java.util.Map;
  import java.util.Optional;
  import java.util.function.Consumer;
  
  /**
   * A client to use for interacting with a file system master.
   */
  public interface FileSystemMasterClient extends Client {
  
    /**
     * Factory for {@link FileSystemMasterClient}.
     */
    class Factory {
  
      private Factory() {} // prevent instantiation
  
      /**
       * Factory method for {@link FileSystemMasterClient}.
       *
       * @param conf master client configuration
       * @return a new {@link FileSystemMasterClient} instance
       */
      public static FileSystemMasterClient create(MasterClientContext conf) {
        return new RetryHandlingFileSystemMasterClient(conf);
      }
    }
  
    /**
     * Check access to a path.
     *
     * @param path the path to check
     * @param options method options
     * @throws alluxio.exception.AccessControlException if the access is denied
     */
    void checkAccess(AlluxioURI path, CheckAccessPOptions options)
        throws AlluxioStatusException;
  
    /**
     * Checks the consistency of Alluxio metadata against the under storage for all files and
     * directories in a given subtree.
     *
     * @param path the root of the subtree to check
     * @param options method options
     * @return a list of inconsistent files and directories
     */
    List<AlluxioURI> checkConsistency(AlluxioURI path, CheckConsistencyPOptions options)
        throws AlluxioStatusException;
  
    /**
     * Creates a new directory.
     *
     * @param path the directory path
     * @param options method options
     * @throws AlreadyExistsException if the directory already exists
     */
    void createDirectory(AlluxioURI path, CreateDirectoryPOptions options)
        throws AlluxioStatusException;
  
    /**
     * Creates a new file.
     *
     * @param path the file path
     * @param options method options
     * @throws AlreadyExistsException if the file already exists
     * @return the uri status of the newly created file
     */
    URIStatus createFile(AlluxioURI path, CreateFilePOptions options) throws AlluxioStatusException;
  
    /**
     * Marks a file as completed.
     *
     * @param path the file path
     * @param options the method options
     */
    void completeFile(AlluxioURI path, CompleteFilePOptions options) throws AlluxioStatusException;
  
    /**
     * Deletes a file or a directory.
     *
     * @param path the path to delete
     * @param options method options
     */
    void delete(AlluxioURI path, DeletePOptions options) throws AlluxioStatusException;
  
    /**
     * Checks whether a file or directory exists.
     *
     * @param path the file path to check existence
     * @param options the method options
     * @return whether the file path exists
     */
    boolean exists(AlluxioURI path, ExistsPOptions options) throws AlluxioStatusException;
  
    /**
     * Frees a file.
     *
     * @param path the path to free
     * @param options method options
     * @throws NotFoundException if the path does not exist
     */
    void free(AlluxioURI path, FreePOptions options) throws AlluxioStatusException;
  
    /**
     * @param fileId a file id
     * @return the file path for the given file id
     */
    String getFilePath(long fileId) throws AlluxioStatusException;
  
    /**
     * @param path the file path
     * @param options the getStatus options
     * @return the file info for the given file id
     * @throws NotFoundException if the path does not exist
     */
    URIStatus getStatus(AlluxioURI path, GetStatusPOptions options) throws AlluxioStatusException;
  
    /**
     * @param path the file path
     * @return the next blockId for the file
     */
    long getNewBlockIdForFile(AlluxioURI path) throws AlluxioStatusException;
  
    /**
     * get the list of paths that are currently being actively synced.
     *
     * @return the list of paths
     */
    List<SyncPointInfo> getSyncPathList() throws AlluxioStatusException;
  
    /**
     * Performs a specific action on each {@code URIStatus} in the result of {@link #listStatus}.
     * This method is preferred when iterating over directories with a large number of files or
     * sub-directories inside. The caller can proceed with partial result without waiting for all
     * result returned.
     *
     * @param path the path to list information about
     * @param options options to associate with this operation
     * @param action action to apply on each {@code URIStatus}
     * @throws NotFoundException if the path does not exist
     */
    void iterateStatus(AlluxioURI path, ListStatusPOptions options,
        Consumer<? super URIStatus> action) throws AlluxioStatusException;
  
    /**
     * @param path the path to list
     * @param options the listStatus options
     * @return the list of file information for the given path
     * @throws NotFoundException if the path does not exist
     */
    List<URIStatus> listStatus(AlluxioURI path, ListStatusPOptions options)
        throws AlluxioStatusException;
  
    /**
     * @param path the path to list
     * @param options the listStatus partial options
     * @return the list of file information for the given path
     * @throws NotFoundException if the path does not exist
     */
    ListStatusPartialResult listStatusPartial(
        AlluxioURI path, ListStatusPartialPOptions options)
        throws AlluxioStatusException;
  
    /**
     * Mounts the given UFS path under the given Alluxio path.
     *
     * @param alluxioPath the Alluxio path
     * @param ufsPath the UFS path
     * @param options mount options
     */
    void mount(AlluxioURI alluxioPath, AlluxioURI ufsPath, MountPOptions options)
        throws AlluxioStatusException;
  
    /**
     * Updates options of a mount point for the given Alluxio path.
     *
     * @param alluxioPath the Alluxio path
     * @param options mount options
     */
    void updateMount(AlluxioURI alluxioPath, MountPOptions options) throws AlluxioStatusException;
  
    /**
     * Lists all mount points and their corresponding under storage addresses.
     * This is the same as calling {@link #getMountTable(boolean)} with true argument.
     *
     * @return a map from String to {@link MountPointInfo}
     */
    default Map<String, MountPointInfo> getMountTable() throws AlluxioStatusException {
      return getMountTable(true);
    }
  
    /**
     * Lists all mount points and their corresponding under storage addresses.
     *
     * @param checkUfs whether to get UFS usage info
     *
     * @return a map from String to {@link MountPointInfo}
     */
    Map<String, MountPointInfo> getMountTable(boolean checkUfs) throws AlluxioStatusException;
  
    /**
     * Renames a file or a directory.
     *
     * @param src the path to rename
     * @param dst new file path
     * @throws NotFoundException if the path does not exist
     */
    void rename(AlluxioURI src, AlluxioURI dst) throws AlluxioStatusException;
  
    /**
     * Renames a file or a directory.
     *
     * @param src the path to rename
     * @param dst new file path
     * @param options rename options
     * @throws NotFoundException if the path does not exist
     */
    void rename(AlluxioURI src, AlluxioURI dst, RenamePOptions options) throws AlluxioStatusException;
  
    /**
     * Reverse resolve a ufs uri.
     *
     * @param ufsUri the ufs uri
     * @return the alluxio path for the ufsUri
     * @throws AlluxioStatusException
     */
    AlluxioURI reverseResolve(AlluxioURI ufsUri) throws AlluxioStatusException;
  
    /**
     * Sets the ACL for a path.
     *
     * @param path the file or directory path
     * @param action the set action to perform
     * @param entries the ACL entries to use
     * @param options the options for setting ACL
     * @throws NotFoundException if the path does not exist
     */
    void setAcl(AlluxioURI path, SetAclAction action, List<AclEntry> entries, SetAclPOptions options)
        throws AlluxioStatusException;
  
    /**
     * Sets the file or directory attributes.
     *
     * @param path the file or directory path
     * @param options the file or directory attribute options to be set
     * @throws NotFoundException if the path does not exist
     */
    void setAttribute(AlluxioURI path, SetAttributePOptions options) throws AlluxioStatusException;
  
    /**
     * Start the active syncing process for a specified path.
     *
     * @param path the file or directory to be synced
     * @throws AlluxioStatusException
     */
    void startSync(AlluxioURI path) throws AlluxioStatusException;
  
    /**
     * Stop the active syncing process for a specified path.
     *
     * @param path the file or directory to stop syncing
     * @throws AlluxioStatusException
     */
    void stopSync(AlluxioURI path) throws AlluxioStatusException;
  
    /**
     * Schedules the async persistence of the given file.
     *
     * @param path the file path
     * @param options options to use when scheduling the persist
     */
    void scheduleAsyncPersist(AlluxioURI path, ScheduleAsyncPersistencePOptions options)
        throws AlluxioStatusException;
  
    /**
     * Unmounts the given Alluxio path.
     *
     * @param alluxioPath the Alluxio path
     */
    void unmount(AlluxioURI alluxioPath) throws AlluxioStatusException;
  
    /**
     * Updates the operation mode for the given ufs path. The path is required to be the scheme and
     * authority only. For example, to update the mode for under storage at hdfs://ns/folder1
     * specify the argument as hdfs://ns/. Note: the mode for any other mounted under storage which
     * shares the prefix (such as hdfs://ns/folder2) is also updated.
     *
     * @param ufsUri the ufs path
     * @param options the options to update ufs operation mode
     */
    void updateUfsMode(AlluxioURI ufsUri, UpdateUfsModePOptions options)
        throws AlluxioStatusException;
  
    /**
     * @return the state lock waiters and holders thread identifiers
     */
    List<String> getStateLockHolders() throws AlluxioStatusException;
  
    /**
     * Mark a path as needed synchronization with the UFS, when this path or any
     * of its children are accessed, a sync with the UFS will be performed.
     * @param path the path to invalidate
     */
    void needsSync(AlluxioURI path) throws AlluxioStatusException;
  
    /**
     * Submit a job to scheduler.
     *
     * @param job the job request to submit
     * @return jobId if job is submitted, empty if a job already exists
     */
    Optional<String> submitJob(JobRequest job);
  
    /**
     * Stop a job.
     *
     * @param jobDescription job description be stopped
     * @return true if job is stopped, false if we cannot find job
     */
    boolean stopJob(JobDescription jobDescription);
  
    /**
     * Get progress of a job.
     *
     * @param jobDescription   job description to get progress
     * @param format  progress report format
     * @param verbose whether to return verbose report
     * @return the job progress
     */
    String getJobProgress(JobDescription jobDescription,
        JobProgressReportFormat format, boolean verbose);
  
    /**
     * Syncs metadata for a given alluxio path.
     *
     * @param path    the path to sync metadata on
     * @param options options to associate with this operation
     * @return the sync metadata response
     */
    SyncMetadataPResponse syncMetadata(AlluxioURI path, SyncMetadataPOptions options)
        throws AlluxioStatusException;
  
    /**
     * Syncs metadata for a given alluxio path asynchronously.
     *
     * @param path the path to sync metadata on
     * @param options options to associate with this operation
     * @return the sync metadata response
     */
    SyncMetadataAsyncPResponse syncMetadataAsync(AlluxioURI path, SyncMetadataPOptions options)
        throws AlluxioStatusException;
  
    /**
     * Gets the sync progress.
     * @param taskGroupId the task group id
     * @return the sync progress
     */
    GetSyncProgressPResponse getSyncProgress(long taskGroupId) throws AlluxioStatusException;
  
    /**
     * Cancels an ongoing metadata sync.
     * @param taskGroupId the task group id
     * @return the cancellation result
     */
    CancelSyncMetadataPResponse cancelSyncMetadata(long taskGroupId) throws AlluxioStatusException;
  }
  