| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you 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 org.apache.twill.filesystem; |
| |
| import java.io.IOException; |
| import java.io.InputStream; |
| import java.io.OutputStream; |
| import java.net.URI; |
| import java.nio.file.attribute.PosixFilePermissions; |
| import java.util.List; |
| import javax.annotation.Nullable; |
| |
| /** |
| * This interface defines the location and operations of a resource on the filesystem. |
| * <p> |
| * {@link Location} is agnostic to the type of file system the resource is on. |
| * </p> |
| */ |
| public interface Location { |
| /** |
| * Suffix added to every temp file name generated with {@link #getTempFile(String)}. |
| */ |
| String TEMP_FILE_SUFFIX = ".tmp"; |
| |
| /** |
| * Checks if the this location exists. |
| * |
| * @return true if found; false otherwise. |
| * @throws IOException |
| */ |
| boolean exists() throws IOException; |
| |
| /** |
| * @return Returns the name of the file or directory denoteed by this abstract pathname. |
| */ |
| String getName(); |
| |
| /** |
| * Atomically creates a new, empty file named by this abstract pathname if and only if a file with this name |
| * does not yet exist. |
| * @return {@code true} if the file is successfully create, {@code false} otherwise. |
| * @throws IOException if error encountered during creation of the file |
| */ |
| boolean createNew() throws IOException; |
| |
| /** |
| * Atomically creates a new, empty file named by this abstract pathname if and only if a file with this name |
| * does not yet exist. The newly created file will have permission set based on the given permission settings. |
| * |
| * @param permission A permission string. It has to be either a three digit or a nine character string. |
| * For the three digit string, it is similar to the UNIX permission numeric representation. |
| * The first digit is the permission for owner, second digit is the permission for group and |
| * the third digit is the permission for all. |
| * For the nine character string, it uses the format as specified by the |
| * {@link PosixFilePermissions#fromString(String)} method. |
| * @return {@code true} if the file is successfully create, {@code false} otherwise. |
| * @throws IOException if error encountered during creation of the file |
| */ |
| boolean createNew(String permission) throws IOException; |
| |
| /** |
| * Returns the permissions of this {@link Location}. The permission string is a nine character string as the format |
| * specified by the {@link PosixFilePermissions#fromString(String)} method. |
| * |
| * @throws IOException if failed to get the permissions of the location |
| * @throws UnsupportedOperationException if Posix file permissions are not supported by the local file system |
| */ |
| String getPermissions() throws IOException; |
| |
| /** |
| * Returns the owner of the location. |
| * |
| * @throws IOException if failed to get the owner of the location |
| */ |
| String getOwner() throws IOException; |
| |
| /** |
| * Returns the group of the location. |
| * |
| * @throws IOException if failed to get the group of the location |
| * @throws UnsupportedOperationException if Posix style groups are not supported by the local file system |
| */ |
| String getGroup() throws IOException; |
| |
| /** |
| * Sets the group of the location. |
| * |
| * @throws IOException if failed to set the group of the location |
| * @throws UnsupportedOperationException if Posix style groups are not supported by the local file system |
| */ |
| void setGroup(String group) throws IOException; |
| |
| /** |
| * Sets the permissions on this location. |
| * |
| * @param permission A permission string. See {@link #createNew(String)} for the format. |
| * |
| * @throws IOException if failed to set the permission |
| * @throws UnsupportedOperationException if Posix file permissions are not supported by the local file system |
| */ |
| void setPermissions(String permission) throws IOException; |
| |
| /** |
| * @return An {@link java.io.InputStream} for this location. |
| * @throws IOException |
| */ |
| InputStream getInputStream() throws IOException; |
| |
| /** |
| * @return An {@link java.io.OutputStream} for this location. |
| * @throws IOException |
| */ |
| OutputStream getOutputStream() throws IOException; |
| |
| /** |
| * Creates an {@link OutputStream} for this location with the given permission. The actual permission supported |
| * depends on implementation. |
| * |
| * @param permission A permission string. It has to be either a three digit or a nine character string. |
| * For the three digit string, it is similar to the UNIX permission numeric representation. |
| * The first digit is the permission for owner, second digit is the permission for group and |
| * the third digit is the permission for all. |
| * For the nine character string, it uses the format as specified by the |
| * {@link PosixFilePermissions#fromString(String)} method. |
| * @return An {@link OutputStream} for writing to this location. |
| * @throws IOException If failed to create the {@link OutputStream}. |
| */ |
| OutputStream getOutputStream(String permission) throws IOException; |
| |
| /** |
| * Appends the child to the current {@link Location}. |
| * <p> |
| * Returns a new instance of Location. |
| * </p> |
| * |
| * @param child to be appended to this location. |
| * @return A new instance of {@link Location} |
| * @throws IOException |
| */ |
| Location append(String child) throws IOException; |
| |
| /** |
| * Returns unique location for temporary file to be placed near this location. |
| * Allows all temp files to follow same pattern for easier management of them. |
| * @param suffix part of the file name to include in the temp file name |
| * @return location of the temp file |
| * @throws IOException |
| */ |
| Location getTempFile(String suffix) throws IOException; |
| |
| /** |
| * @return A {@link java.net.URI} for this location. |
| */ |
| URI toURI(); |
| |
| /** |
| * Deletes the file or directory denoted by this abstract pathname. If this |
| * pathname denotes a directory, then the directory must be empty in order |
| * to be deleted. |
| * |
| * @return true if and only if the file or directory is successfully deleted; false otherwise. |
| */ |
| boolean delete() throws IOException; |
| |
| /** |
| * Deletes the file or directory denoted by this abstract pathname. If this |
| * pathname denotes a directory and {@code recursive} is {@code true}, then content of the |
| * directory will be deleted recursively, otherwise the directory must be empty in order to be deleted. |
| * Note that when calling this method with {@code recursive = true} for a directory, any |
| * failure during deletion will have some entries inside the directory being deleted while some are not. |
| * |
| * @param recursive Indicate if recursively delete a directory. Ignored if the pathname represents a file. |
| * @return true if and only if the file or directory is successfully deleted; false otherwise. |
| */ |
| boolean delete(boolean recursive) throws IOException; |
| |
| /** |
| * Moves the file or directory denoted by this abstract pathname. |
| * |
| * @param destination destination location |
| * @return new location if and only if the file or directory is successfully moved; null otherwise. |
| */ |
| @Nullable |
| Location renameTo(Location destination) throws IOException; |
| |
| /** |
| * Creates the directory named by this abstract pathname, including any necessary |
| * but nonexistent parent directories. |
| * |
| * @return true if and only if the directory was created; false otherwise |
| */ |
| boolean mkdirs() throws IOException; |
| |
| /** |
| * Creates the directory named by this abstract pathname, including any necessary |
| * but nonexistent parent directories. The directories will be created with the |
| * exact given permissions, regardless of a possible umask setting. |
| * |
| * @param permission A permission string. It has to be either a three digit or a nine character string. |
| * For the three digit string, it is similar to the UNIX permission numeric representation. |
| * The first digit is the permission for owner, second digit is the permission for group and |
| * the third digit is the permission for all. |
| * For the nine character string, it uses the format as specified by the |
| * {@link PosixFilePermissions#fromString(String)} method. |
| * |
| * @return true if and only if the directory was created; false otherwise |
| */ |
| boolean mkdirs(String permission) throws IOException; |
| |
| /** |
| * @return Length of file. |
| */ |
| long length() throws IOException; |
| |
| /** |
| * @return Last modified time of file. |
| */ |
| long lastModified() throws IOException; |
| |
| /** |
| * Checks if this location represents a directory. |
| * |
| * @return {@code true} if it is a directory, {@code false} otherwise. |
| */ |
| boolean isDirectory() throws IOException; |
| |
| /** |
| * List the locations under this location. |
| * |
| * @return Immutable List of locations under this location. |
| * An empty list is returned if this location is not a directory. |
| */ |
| List<Location> list() throws IOException; |
| |
| /** |
| * Returns the location factory used to create this instance. |
| * |
| * @return The {@link LocationFactory} instance for creating this instance. |
| */ |
| LocationFactory getLocationFactory(); |
| } |