/*
 * This file is a part of the RMI Plugin for Eclipse tutorials.
 * Copyright (C) 2002-7 Genady Beryozkin
 * 
 * You are free to modify this file, as long as you leave
 * the following copyright:
 * 
 * This file is based on the Remote File System example of
 * the RMI Plug-in for Eclipse. The original code is 
 * Copyright (C) 2002-7 Genady Beryozkin
 */
package demo.rmi.filesystem.common;


import java.io.File;
import java.io.InputStream;
import java.rmi.Remote;
import java.rmi.RemoteException;

/**
 * This interface lists the methods that can be invoked on a remote file. 
 * Majority of methods have signatures similar to the methods of {@link File} 
 * class to allow the implementation to extend {@link File}.
 * 
 * Methods that can modify the remote file system are not part of the 
 * interface for safety reasons. Feel free to add them.
 * 
 * Note: This is a remote interface. Invoking methods of this
 * interface on a remote object will result in remote calls which
 * can be a performance hit (for example when traversing the file 
 * system).
 * 
 * @author Genady Beryozkin, rmi-info@genady.net
 */
public interface IRemoteFile extends Remote {

	/* Methods that correspond to File methods. */	
	public String getName() throws RemoteException;	
	public String getParent() throws RemoteException;
	public String getPath() throws RemoteException;
	public boolean isAbsolute() throws RemoteException;
	public String getAbsolutePath() throws RemoteException;
	public String getCanonicalPath() throws RemoteException;
	
	/* Methods that have a different, but compatibe signatures. */
	public IRemoteFile getRemoteAbsoluteFile() throws RemoteException;
	public IRemoteFile getRemoteParentFile() throws RemoteException;
	
	/* Methods that correspond to File methods. */
	public boolean canRead() throws RemoteException;
	public boolean canWrite() throws RemoteException;
	public boolean exists() throws RemoteException;
	public boolean isDirectory() throws RemoteException;
	public boolean isFile() throws RemoteException;
	public boolean isHidden() throws RemoteException;

	public long lastModified() throws RemoteException;
	public long length() throws RemoteException;
	
	/**
	 * Return a file that is a child of the current directory. Replaces 
	 * the constructor (see {@link File#File(File, String)}), since
	 * interfaces can't declare constructors.
	 * 
	 * @param name the child's name.
	 */
	public IRemoteFile getChild(String name) throws RemoteException;
	
	/**
	 * Return the names of the files in this directory. Using this method
	 * you will get both the files and the directories.
	 */
	public String[] list() throws RemoteException;
	
	/**
	 * Return the files in this directory as {@link IRemoteFile}s.
	 */
	public IRemoteFile[] listRemoteFiles() throws RemoteException;
	
	/**
	 * This method returns the subdirectories of the current directory. 
	 * Useful for traversal of the entire directory
	 * tree (see also {@link #listByFilter(IRemoteFilenameFilter)}.
	 */
	public IRemoteFile[] listRemoteDirectories() throws RemoteException;
	
	/**
	 * Return the files in this directory that their names (only the last segment)
	 * match the regular expression supplied as the <code>regex</code> argument.
	 * 
	 * @param regex the regular expression filter for the childs filename.
	 * @param dirsOnly If <code>true</code>, only subdirectories will be considered.
	 * 
	 * @see String#matches(String);
	 */
	public IRemoteFile[] listByRegex(String regex, boolean dirsOnly) throws RemoteException;

	/**
	 * 
	 * This method uses a remote filename filter which will result
	 * in callbacks to the client (the user of this interface) for every filename
	 * (if the implementing object is exported). If the filter is exported
	 * this method is won't be very efficient. In such case it would probably 
	 * be more efficient to get the whole file list and filter it locally.
	 * If the filter is not exported, it will be serialized and sent
	 * to the server. In such case the filter's code is executed locally 
	 * inside the server VM and the method is more efficient. However,
	 * this means that client code is being executed on the server, which
	 * may not be acceptable in the real world (security-wise). 
	 * 
	 * See the client code for sample use.
	 * 
	 * @param filter the filename filter.
	 * @return
	 * @throws RemoteException
	 */
	public IRemoteFile[] listByFilter(IRemoteFilenameFilter filter) throws RemoteException;
		
	/**
	 * Return a remote input stream that can be used to read from the file.
	 * The client code contains a class that can wrap {@link IRemoteInputStream}
	 * with a conventional {@link InputStream}.
	 * 
	 * @see IRemoteInputStream
	 */
	public IRemoteInputStream getInputStream() throws RemoteException;
}