/*
* ProActive Parallel Suite(TM):
* The Open Source library for parallel and distributed
* Workflows & Scheduling, Orchestration, Cloud Automation
* and Big Data Analysis on Enterprise Grids & Clouds.
*
* Copyright (c) 2007 - 2017 ActiveEon
* Contact: contact@activeeon.com
*
* This library is free software: you can redistribute it and/or
* modify it under the terms of the GNU Affero General Public License
* as published by the Free Software Foundation: version 3 of
* the License.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
* If needed, contact us to obtain a release under GPL Version 2 or 3
* or a different license than the AGPL.
*/
package org.ow2.proactive.scheduler.common.task.dataspaces;
import java.io.File;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.List;
import java.util.Set;
import org.objectweb.proactive.annotation.PublicAPI;
import org.ow2.proactive.scheduler.common.exception.NotConnectedException;
import org.ow2.proactive.scheduler.common.exception.PermissionException;
/**
* RemoteSpace is the interface used to access remote file spaces
*
* @author The ProActive Team
* @since ProActive Scheduling 4.0
*/
@PublicAPI
public interface RemoteSpace {
/**
* List the content of the given remote directory, using a glob pattern
* <p>
* The following special characters can be used inside the pattern : <br>
* ** matches zero or more directories <br>
* * matches zero or more characters<br>
* ? matches one character
*
* @param remotePath path in the RemoteSpace where files should be listed. Use "." for remote root path.
* @param pattern pattern to locate files
* @return a list of remote paths matching the pattern
* @throws FileSystemException
* @see "https://docs.oracle.com/javase/7/docs/api/java/nio/file/FileSystem.html#getPathMatcher(java.lang.String)"
*/
List<String> listFiles(String remotePath, String pattern) throws FileSystemException;
/**
* Push the given file or directory(including its content) from the local space to the remote space.
*
* When pushing a file or directory, the remotePath must contain the target new file or directory
* @param localPath path to the local file or directory
* @param remotePath path in the RemoteSpace where to put the file or folder. Use "." for remote root path.
* @throws FileSystemException
*/
void pushFile(File localPath, String remotePath) throws FileSystemException;
/**
* Push the local files described by the given pattern to the remote space
*
* The following special characters can be used inside the pattern : <br>
* ** matches zero or more directories <br>
* * matches zero or more characters<br>
* ? matches one character
*
* @param localDirectory local directory used as base
* @param pattern pattern to locate files inside the localDirectory
* @param remotePath path in the RemoteSpace where to put the files. Use "." for remote root path.
* @throws FileSystemException
* @see "https://docs.oracle.com/javase/7/docs/api/java/nio/file/FileSystem.html#getPathMatcher(java.lang.String)"
*/
void pushFiles(File localDirectory, String pattern, String remotePath) throws FileSystemException;
/**
* Pull the given file or folder(including its content) from the remote space to the local space
*
* @param remotePath path to the remote file (relative to the RemoteSpace root)
* @param localPath path in the local file system where to put the file or folder
* @return the path to the file or directory pulled
* @throws FileSystemException
*/
File pullFile(String remotePath, File localPath) throws FileSystemException;
/**
* Pull the remote files described by the given pattern to the local space
*
* The following special characters can be used inside the pattern : <br>
* ** matches zero or more directories <br>
* * matches zero or more characters<br>
* ? matches one character
*
* @param remotePath path in the RemoteSpace used as base for the pattern (e.g. "/")
* @param pattern pattern to locate files inside the RemoteSpace
* @param localPath path in the local file system where to put the files
* @return a set of files pulled
* @throws FileSystemException
* @see "https://docs.oracle.com/javase/7/docs/api/java/nio/file/FileSystem.html#getPathMatcher(java.lang.String)"
*/
Set<File> pullFiles(String remotePath, String pattern, File localPath) throws FileSystemException;
/**
* Delete the given file or folder(including its content) inside the remote space
* @param remotePath path to the remote file (relative to the RemoteSpace root) to delete
* @throws FileSystemException
*/
void deleteFile(String remotePath) throws FileSystemException;
/**
* Delete the remote files described by the given pattern
*
* The following special characters can be used inside the pattern : <br>
* ** matches zero or more directories <br>
* * matches zero or more characters<br>
* ? matches one character
*
* @param remotePath path in the RemoteSpace used as base for the pattern (e.g. "/")
* @param pattern pattern to locate files inside the RemoteSpace
* @throws FileSystemException
* @see "https://docs.oracle.com/javase/7/docs/api/java/nio/file/FileSystem.html#getPathMatcher(java.lang.String)"
*/
void deleteFiles(String remotePath, String pattern) throws FileSystemException;
/**
* Returns the URLs of the RemoteSpace
* @return URL to the space
*/
List<String> getSpaceURLs() throws NotConnectedException, PermissionException, FileSystemException;
/**
* Returns an input stream on the specified remote file. It will throw an exception if the file does not exist.
* @param remotePath path to the remote file
* @return an input stream
* @throws FileSystemException
*/
InputStream getInputStream(String remotePath) throws FileSystemException;
/**
* Returns an output stream on the specified remote file. If the file does not exist, it will be created.
* @param remotePath path to the remote file
* @return an output stream
* @throws FileSystemException
*/
OutputStream getOutputStream(String remotePath) throws FileSystemException;
}