// Copyright 2014 The Bazel Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//    http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package com.google.devtools.build.lib.vfs;

import java.io.IOException;

/**
 * File status: mode, mtime, size, etc.
 *
 * <p>The result of calling any {@code FileStatus} instance method is not
 * guaranteed to result in I/O to the file system at the moment of the call.
 * The I/O providing the result (and hence the throwing of an I/O exception,
 * where applicable) may occur at any moment between the call to {@link
 * FileSystem#stat} and the call of the {@code FileStatus} instance method.
 *
 * <p>Callers therefore cannot assume that all the values are populated
 * atomically, or that the results of any two {@code FileStatus} methods
 * correspond to state of the file system at a single moment in time.  Nor may
 * they assume that repeated successful calls to any method of the same
 * instance will return the same value.
 *
 * <p>(This permits conforming implementations to use an atomic {@code stat(2)}
 * call on file systems where it is available, and individual accessor methods
 * on those where it is not.  Caching is possible but not required.)
 */
public interface FileStatus {

  /**
   * Returns true iff this file is a regular file or {@code isSpecial()}.
   */
  boolean isFile();

  /**
   * Returns true iff this file is a directory.
   */
  boolean isDirectory();

  /**
   * Returns true iff this file is a symbolic link.
   */
  boolean isSymbolicLink();

  /**
   * Returns true iff this file is a special file (e.g. socket, fifo or device). {@link #getSize()}
   * can't be trusted for such files.
   */
  boolean isSpecialFile();

  /**
   * Returns the total size, in bytes, of this file.
   */
  long getSize() throws IOException;

  /**
   * Returns the last modified time of this file's data (milliseconds since
   * UNIX epoch).
   */
  long getLastModifiedTime() throws IOException;

  /**
   * Returns the last change time of this file, where change means any change
   * to the file, including metadata changes (milliseconds since UNIX epoch).
   *
   * Note: UNIX uses seconds!
   */
  long getLastChangeTime() throws IOException;

  /**
   * Returns the unique file node id. Usually it is computed using both device
   * and inode numbers.
   *
   * <p>Think of this value as a reference to the underlying inode. "mv"ing file a to file b
   * ought to cause the node ID of b to change, but appending / modifying b should not.
   */
  public long getNodeId() throws IOException;
}