/* * Copyright (C) 2018, Thomas Wolf * and other copyright owners as documented in the project's IP log. * * This program and the accompanying materials are made available * under the terms of the Eclipse Distribution License v1.0 which * accompanies this distribution, is reproduced below, and is * available at http://www.eclipse.org/org/documents/edl-v10.php * * All rights reserved. * * Redistribution and use in source and binary forms, with or * without modification, are permitted provided that the following * conditions are met: * * - Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * - Redistributions in binary form must reproduce the above * copyright notice, this list of conditions and the following * disclaimer in the documentation and/or other materials provided * with the distribution. * * - Neither the name of the Eclipse Foundation, Inc. nor the * names of its contributors may be used to endorse or promote * products derived from this software without specific prior * written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ package org.eclipse.jgit.transport; import java.io.FileNotFoundException; import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; import java.util.Collection; import java.util.concurrent.TimeUnit; /** * An interface providing FTP operations over a {@link RemoteSession}. All * operations are supposed to throw {@link FtpException} for remote file system * errors and other IOExceptions on connection errors. * * @since 5.2 */ public interface FtpChannel { /** * An {@link Exception} for reporting SFTP errors. */ static class FtpException extends IOException { private static final long serialVersionUID = 7176525179280330876L; public static final int OK = 0; public static final int EOF = 1; public static final int NO_SUCH_FILE = 2; public static final int NO_PERMISSION = 3; public static final int UNSPECIFIED_FAILURE = 4; public static final int PROTOCOL_ERROR = 5; public static final int UNSUPPORTED = 8; private final int status; public FtpException(String message, int status) { super(message); this.status = status; } public FtpException(String message, int status, Throwable cause) { super(message, cause); this.status = status; } public int getStatus() { return status; } } /** * Connects the {@link FtpChannel} to the remote end. * * @param timeout * for establishing the FTP connection * @param unit * of the {@code timeout} * @throws IOException */ void connect(int timeout, TimeUnit unit) throws IOException; /** * Disconnects and {@link FtpChannel}. */ void disconnect(); /** * @return whether the {@link FtpChannel} is connected */ boolean isConnected(); /** * Changes the current remote directory. * * @param path * target directory * @throws IOException * if the operation could not be performed remotely */ void cd(String path) throws IOException; /** * @return the current remote directory path * @throws IOException */ String pwd() throws IOException; /** * Simplified remote directory entry. */ interface DirEntry { String getFilename(); long getModifiedTime(); boolean isDirectory(); } /** * Lists contents of a remote directory * * @param path * of the directory to list * @return the directory entries * @throws IOException */ Collection ls(String path) throws IOException; /** * Deletes a directory on the remote file system. The directory must be * empty. * * @param path * to delete * @throws IOException */ void rmdir(String path) throws IOException; /** * Creates a directory on the remote file system. * * @param path * to create * @throws IOException */ void mkdir(String path) throws IOException; /** * Obtain an {@link InputStream} to read the contents of a remote file. * * @param path * of the file to read * * @return the stream to read from * @throws IOException */ InputStream get(String path) throws IOException; /** * Obtain an {@link OutputStream} to write to a remote file. If the file * exists already, it will be overwritten. * * @param path * of the file to read * * @return the stream to read from * @throws IOException */ OutputStream put(String path) throws IOException; /** * Deletes a file on the remote file system. * * @param path * to delete * @throws IOException * if the file does not exist or could otherwise not be deleted */ void rm(String path) throws IOException; /** * Deletes a file on the remote file system. If the file does not exist, no * exception is thrown. * * @param path * to delete * @throws IOException * if the file exist but could not be deleted */ default void delete(String path) throws IOException { try { rm(path); } catch (FileNotFoundException e) { // Ignore; it's OK if the file doesn't exist } catch (FtpException f) { if (f.getStatus() == FtpException.NO_SUCH_FILE) { return; } throw f; } } /** * Renames a file on the remote file system. If {@code to} exists, it is * replaced by {@code from}. (POSIX rename() semantics) * * @param from * original name of the file * @param to * new name of the file * @throws IOException * @see stdio.h: * rename() */ void rename(String from, String to) throws IOException; }