VirtualFile.java

/*******************************************************************************
 * Copyright (c) 2012-2017 Codenvy, S.A.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *   Codenvy, S.A. - initial API and implementation
 *******************************************************************************/
package org.eclipse.che.api.vfs;

import com.google.common.annotations.Beta;

import org.eclipse.che.api.core.ConflictException;
import org.eclipse.che.api.core.ForbiddenException;
import org.eclipse.che.api.core.ServerException;
import org.eclipse.che.commons.lang.Pair;

import java.io.InputStream;
import java.util.List;
import java.util.Map;

/**
 * Item of Virtual Filesystem.
 *
 * @author andrew00x
 *
 * @deprecated VFS components are now considered deprecated and will be replaced by standard JDK routines.
 */
@Deprecated
public interface VirtualFile extends Comparable<VirtualFile> {
    /**
     * Gets name.
     */
    String getName();

    /**
     * Gets internal representation of path of item.
     */
    Path getPath();

    /**
     * Tests whether this VirtualFile exists.
     */
    boolean exists();

    /**
     * Tests whether this VirtualFile is a root folder.
     */
    boolean isRoot();

    /**
     * Tests whether this VirtualFile is a regular file.
     */
    boolean isFile();

    /**
     * Tests whether this VirtualFile is a folder. Folder may contain other files.
     */
    boolean isFolder();

    /**
     * Gets time of last modification in long format or {@code -1} if time is unknown.
     */
    long getLastModificationDate();

    /**
     * Gets parent folder. If this item is root folder this method always returns {@code null}.
     *
     * @see #isRoot()
     */
    VirtualFile getParent();

    /**
     * Gets files in this folder. If this VirtualFile is not a folder this method returns empty list.
     *
     * @param filter
     *         virtual files filter
     * @throws ServerException
     *         if an error occurs
     */
    List<VirtualFile> getChildren(VirtualFileFilter filter) throws ServerException;

    /**
     * Gets files in this folder. If this VirtualFile is not a folder this method returns empty list.
     *
     * @throws ServerException
     *         if an error occurs
     */
    List<VirtualFile> getChildren() throws ServerException;

    boolean hasChild(Path path) throws ServerException;

    /**
     * Gets child by relative path. If this VirtualFile is not folder this method returns {@code null}.
     *
     * @param path
     *         child item path
     * @return child or {@code null} if path does not exist
     * @throws ServerException
     *         if an error occurs
     */
    VirtualFile getChild(Path path) throws ServerException;

    /**
     * Gets content of the file.
     *
     * @return content ot he file
     * @throws ForbiddenException
     *         if this item is not a file
     * @throws ServerException
     *         if other error occurs
     * @see #isFile()
     */
    InputStream getContent() throws ForbiddenException, ServerException;

    /**
     * Gets content of the file as bytes.
     *
     * @return content ot he file
     * @throws ForbiddenException
     *         if any of following conditions are met:
     *         <ul>
     *         <li>this item is not a file</li>
     *         <li>size of file is too big and might not be retrieved as bytes</li>
     *         </ul>
     * @throws ServerException
     *         if other error occurs
     * @see #isFile()
     */
    byte[] getContentAsBytes() throws ForbiddenException, ServerException;

    /**
     * Gets content of the file as String decoding bytes using the platform's default charset.
     *
     * @return content ot he file
     * @throws ForbiddenException
     *         if this item is not a file
     * @throws ServerException
     *         if other error occurs
     * @see #isFile()
     */
    String getContentAsString() throws ForbiddenException, ServerException;

    /**
     * Updates content of the file.
     *
     * @param content
     *         content
     * @param lockToken
     *         lock token. This parameter is required if the file is locked otherwise might be {@code null}
     * @return VirtualFile after updating content
     * @throws ForbiddenException
     *         if any of following conditions are met:
     *         <ul>
     *         <li>this item is not a file</li>
     *         <li>this item is locked file and {@code lockToken} is {@code null} or does not match</li>
     *         </ul>
     * @throws ServerException
     *         if other error occurs
     * @see #isFile()
     */
    VirtualFile updateContent(InputStream content, String lockToken) throws ForbiddenException, ServerException;

    /**
     * Updates content of the file.
     *
     * @param content
     *         content
     * @return VirtualFile after updating content
     * @throws ForbiddenException
     *         if any of following conditions are met:
     *         <ul>
     *         <li>this item is not a file</li>
     *         <li>this item is locked file</li>
     *         </ul>
     * @throws ServerException
     *         if other error occurs
     * @see #isFile()
     */
    VirtualFile updateContent(InputStream content) throws ForbiddenException, ServerException;

    /**
     * Updates content of the file.
     *
     * @param content
     *         content
     * @param lockToken
     *         lock token. This parameter is required if the file is locked otherwise might be {@code null}
     * @return VirtualFile after updating content
     * @throws ForbiddenException
     *         if any of following conditions are met:
     *         <ul>
     *         <li>this item is not a file</li>
     *         <li>this item is locked file and {@code lockToken} is {@code null} or does not match</li>
     *         </ul>
     * @throws ServerException
     *         if other error occurs
     * @see #isFile()
     */
    VirtualFile updateContent(byte[] content, String lockToken) throws ForbiddenException, ServerException;

    /**
     * Updates content of the file.
     *
     * @param content
     *         content
     * @return VirtualFile after updating content
     * @throws ForbiddenException
     *         if any of following conditions are met:
     *         <ul>
     *         <li>this item is not a file</li>
     *         <li>this item is locked file</li>
     *         </ul>
     * @throws ServerException
     *         if other error occurs
     * @see #isFile()
     */
    VirtualFile updateContent(byte[] content) throws ForbiddenException, ServerException;

    /**
     * Updates content of the file.
     *
     * @param content
     *         content
     * @param lockToken
     *         lock token. This parameter is required if the file is locked otherwise might be {@code null}
     * @return VirtualFile after updating content
     * @throws ForbiddenException
     *         if any of following conditions are met:
     *         <ul>
     *         <li>this item is not a file</li>
     *         <li>this item is locked file and {@code lockToken} is {@code null} or does not match</li>
     *         </ul>
     * @throws ServerException
     *         if other error occurs
     * @see #isFile()
     */
    VirtualFile updateContent(String content, String lockToken) throws ForbiddenException, ServerException;

    /**
     * Updates content of the file.
     *
     * @param content
     *         content
     * @return VirtualFile after updating content
     * @throws ForbiddenException
     *         if any of following conditions are met:
     *         <ul>
     *         <li>this item is not a file</li>
     *         <li>this item is locked file</li>
     *         </ul>
     * @throws ServerException
     *         if other error occurs
     * @see #isFile()
     */
    VirtualFile updateContent(String content) throws ForbiddenException, ServerException;

    /**
     * Get length of content of the file. Always returns {@code 0} for folders.
     *
     * @throws ServerException
     *         if an error occurs
     */
    long getLength() throws ServerException;

    /**
     * Gets properties of the file. Updating of map returned by this method does not effect state of this file.
     *
     * @throws ServerException
     *         if an error occurs
     */
    Map<String, String> getProperties() throws ServerException;

    /**
     * Gets value of property.
     *
     * @throws ServerException
     *         if an error occurs
     */
    String getProperty(String name) throws ServerException;

    /**
     * Updates properties of the file.
     *
     * @param properties
     *         map of properties to update
     * @param lockToken
     *         lock token. This parameter is required if the file is locked otherwise might be {@code null}
     * @return VirtualFile after updating properties
     * @throws ForbiddenException
     *         if any of following conditions are met:
     *         <ul>
     *         <li>this item is locked file and {@code lockToken} is {@code null} or does not match</li>
     *         <li>at least one property can't be updated cause to any constraint, e.g. property is read only</li>
     *         </ul>
     * @throws ServerException
     *         if other error occurs
     */
    VirtualFile updateProperties(Map<String, String> properties, String lockToken) throws ForbiddenException, ServerException;

    /**
     * Updates properties of the file.
     *
     * @param properties
     *         map of properties to update
     * @return VirtualFile after updating properties
     * @throws ForbiddenException
     *         if any of following conditions are met:
     *         <ul>
     *         <li>this item is locked file</li>
     *         <li>at least one property can't be updated cause to any constraint, e.g. property is read only</li>
     *         </ul>
     * @throws ServerException
     *         if other error occurs
     */
    VirtualFile updateProperties(Map<String, String> properties) throws ForbiddenException, ServerException;

    /**
     * Set property of the file.
     *
     * @param name
     *         name of property
     * @param value
     *         value of property
     * @param lockToken
     *         lock token. This parameter is required if the file is locked otherwise might be {@code null}
     * @return VirtualFile after updating property
     * @throws ForbiddenException
     *         if any of following conditions are met:
     *         <ul>
     *         <li>this item is locked file and {@code lockToken} is {@code null} or does not match</li>
     *         <li>property can't be updated cause to any constraint, e.g. property is read only</li>
     *         </ul>
     * @throws ServerException
     *         if other error occurs
     */
    VirtualFile setProperty(String name, String value, String lockToken) throws ForbiddenException, ServerException;

    /**
     * Set property of the file.
     *
     * @param name
     *         name of property
     * @param value
     *         value of property
     * @return VirtualFile after updating property
     * @throws ForbiddenException
     *         if any of following conditions are met:
     *         <ul>
     *         <li>this item is locked file</li>
     *         <li>property can't be updated cause to any constraint, e.g. property is read only</li>
     *         </ul>
     * @throws ServerException
     *         if other error occurs
     */
    VirtualFile setProperty(String name, String value) throws ForbiddenException, ServerException;

    /**
     * Copies this file to the new parent.
     *
     * @throws ForbiddenException
     *         if specified {@code parent} does not denote a folder
     * @throws ConflictException
     *         if {@code parent} already contains item with the same name as this virtual file has
     * @throws ServerException
     *         if other error occurs
     * @see #isFolder()
     */
    VirtualFile copyTo(VirtualFile parent) throws ForbiddenException, ConflictException, ServerException;

    /**
     * Copies this file to the new parent.
     *
     * @param parent
     *         the new parent
     * @param name
     *         a new name for the moved source, can be left {@code null} or empty {@code String} for current source name
     * @param overwrite
     *         should the destination be overwritten, set to true to overwrite, false otherwise
     * @return reference to copy
     * @throws ForbiddenException
     *         if specified {@code parent} does not denote a folder
     * @throws ConflictException
     *         if {@code parent} already contains item with the same name as this virtual file has
     * @throws ServerException
     *         if other error occurs
     * @see #isFolder()
     */
    @Beta
    VirtualFile copyTo(VirtualFile parent, String name, boolean overwrite) throws ForbiddenException, ConflictException, ServerException;

    /**
     * Moves this file to the new parent.
     *
     * @param parent
     *         parent to move
     * @throws ForbiddenException
     *         if any of following conditions are met:
     *         <ul>
     *         <li>specified {@code parent} does not denote a folder</li>
     *         <li>this item is locked file</li>
     *         </ul>
     * @throws ConflictException
     *         if {@code parent} already contains item with the same name as this virtual file has
     * @throws ServerException
     *         if other error occurs
     * @see #isFolder()
     */
    VirtualFile moveTo(VirtualFile parent) throws ForbiddenException, ConflictException, ServerException;

    /**
     * Moves this VirtualFile under new parent.
     *
     * @param parent
     *         parent to move
     * @param name
     *         a new name for the moved source, can be left {@code null} or empty {@code String} for current source name
     * @param overwrite
     *         should the destination be overwritten, set to {@code true} to overwrite, {@code false} otherwise
     * @param lockToken
     *         lock token. This parameter is required if the file is
     *         locked
     * @throws ForbiddenException
     *         if any of following conditions are met:
     *         <ul>
     *         <li>specified {@code parent} does not denote a folder</li>
     *         <li>this item is locked file and {@code lockToken} is {@code null} or does not match</li>
     *         </ul>
     * @throws ConflictException
     *         if {@code parent} already contains item with the same name as this virtual file has
     * @throws ServerException
     *         if other error occurs
     * @see #isFolder()
     */
    VirtualFile moveTo(VirtualFile parent, String name, boolean overwrite, String lockToken) throws ForbiddenException, ConflictException, ServerException;

    /**
     * Renames this VirtualFile.
     *
     * @param newName
     *         new name
     * @param lockToken
     *         lock token. This parameter is required if the file is locked otherwise might be {@code null}
     * @throws ForbiddenException
     *         if this item is locked file and {@code lockToken} is {@code null} or does not match
     * @throws ConflictException
     *         if parent of this item already contains other item with {@code newName}
     * @throws ServerException
     *         if other error occurs
     */
    VirtualFile rename(String newName, String lockToken) throws ForbiddenException, ConflictException, ServerException;

    /**
     * Renames this VirtualFile.
     *
     * @param newName
     *         new name
     * @throws ForbiddenException
     *         if this item is locked file
     * @throws ConflictException
     *         if parent of this item already contains other item with {@code newName}
     * @throws ServerException
     *         if other error occurs
     */
    VirtualFile rename(String newName) throws ForbiddenException, ConflictException, ServerException;

    /**
     * Deletes this VirtualFile.
     *
     * @param lockToken
     *         lock token. This parameter is required if the file is locked otherwise might be {@code null}
     * @throws ForbiddenException
     *         if any of following conditions are met:
     *         <ul>
     *         <li>this item is locked file and {@code lockToken} is {code null} or does not match</li>
     *         <li>this item is folder that contains at least one locked file</li>
     *         </ul>
     * @throws ServerException
     *         if other error occurs
     */
    void delete(String lockToken) throws ForbiddenException, ServerException;

    /**
     * Deletes this VirtualFile.
     *
     * @throws ForbiddenException
     *         if any of following conditions are met:
     *         <ul>
     *         <li>this item is locked file</li>
     *         <li>this item is folder that contains at least one locked file</li>
     *         </ul>
     * @throws ServerException
     *         if other error occurs
     */
    void delete() throws ForbiddenException, ServerException;

    /**
     * Gets content of folder denoted by this VirtualFile as zip archive.
     *
     * @return zipped content of folder denoted by this VirtualFile
     * @throws ForbiddenException
     *         if this item does not denote a folder
     * @throws ServerException
     *         if other error occurs
     */
    InputStream zip() throws ForbiddenException, ServerException;

    /**
     * Extracts zip archive to the folder denoted by this VirtualFile.
     *
     * @param zipped
     *         ZIP archive
     * @param overwrite
     *         overwrite existing files
     * @param stripNumber
     *         strip number leading components from file names on extraction.
     * @throws ForbiddenException
     *         if any of following conditions are met:
     *         <ul>
     *         <li>this item does not denote a folder</li>
     *         <li>this folder contains at least one locked child that need to be updated</li>
     *         </ul>
     * @throws ConflictException
     *         if {@code overwrite} is {@code false} and any item in zip archive causes name conflict
     * @throws ServerException
     *         if other error occurs
     */
    void unzip(InputStream zipped, boolean overwrite, int stripNumber) throws ForbiddenException, ConflictException, ServerException;

    /**
     * Gets content of folder denoted by this VirtualFile as TAR archive.
     *
     * @return content of folder denoted by this VirtualFile as TAR archive
     * @throws ForbiddenException
     *         if this item does not denote a folder
     * @throws ServerException
     *         if other error occurs
     */
    InputStream tar() throws ForbiddenException, ServerException;

    /**
     * Extracts tar archive to the folder denoted by this VirtualFile.
     *
     * @param tarArchive
     *         TAR archive
     * @param overwrite
     *         overwrite existing files
     * @param stripNumber
     *         strip number leading components from file names on extraction.
     * @throws ForbiddenException
     *         if any of following conditions are met:
     *         <ul>
     *         <li>this item does not denote a folder</li>
     *         <li>this folder contains at least one locked child that need to be updated</li>
     *         </ul>
     * @throws ConflictException
     *         if {@code overwrite} is {@code false} and any item in tar archive causes name conflict
     * @throws ServerException
     *         if other error occurs
     */
    void untar(InputStream tarArchive, boolean overwrite, int stripNumber) throws ForbiddenException, ConflictException, ServerException;

    /**
     * Locks this VirtualFile.
     *
     * @param timeout
     *         lock timeout in milliseconds, pass {@code 0} to create lock without timeout
     * @return lock token. User should pass this token when tries update, delete, rename or unlock locked file
     * @throws ForbiddenException
     *         if this VirtualFile does not denote a regular file
     * @throws ConflictException
     *         if this file already locked
     * @throws ServerException
     *         if other error occurs
     */
    String lock(long timeout) throws ForbiddenException, ConflictException, ServerException;

    /**
     * Unlocks this VirtualFile.
     *
     * @param lockToken
     *         lock token
     * @return VirtualFile after unlock
     * @throws ForbiddenException
     *         if {@code lockToken} is {@code null} or does not match
     * @throws ConflictException
     *         if this item is not locked
     * @throws ServerException
     *         if any other errors occur
     */
    VirtualFile unlock(String lockToken) throws ForbiddenException, ConflictException, ServerException;

    /**
     * Tests whether this VirtualFile is locked.
     *
     * @throws ServerException
     *         if an error occurs
     */
    boolean isLocked() throws ServerException;

    /**
     * Creates new VirtualFile which denotes regular file and use this one as parent folder.
     *
     * @param name
     *         name
     * @param content
     *         content. In case of {@code null} empty file is created
     * @return newly create VirtualFile
     * @throws ForbiddenException
     *         if this VirtualFile does not denote a folder
     * @throws ConflictException
     *         if parent already contains item with specified {@code name}
     * @throws ServerException
     *         if other error occurs
     */
    VirtualFile createFile(String name, InputStream content)
            throws ForbiddenException, ConflictException, ServerException;

    /**
     * Creates new VirtualFile which denotes regular file and use this one as parent folder.
     *
     * @param name
     *         name
     * @param content
     *         content. In case of {@code null} empty file is created
     * @return newly create VirtualFile
     * @throws ForbiddenException
     *         if this VirtualFile does not denote a folder
     * @throws ConflictException
     *         if parent already contains item with specified {@code name}
     * @throws ServerException
     *         if other error occurs
     */
    VirtualFile createFile(String name, byte[] content)
            throws ForbiddenException, ConflictException, ServerException;

    /**
     * Creates new VirtualFile which denotes regular file and use this one as parent folder.
     *
     * @param name
     *         name
     * @param content
     *         content. In case of {@code null} empty file is created
     * @return newly create VirtualFile
     * @throws ForbiddenException
     *         if this VirtualFile does not denote a folder
     * @throws ConflictException
     *         if parent already contains item with specified {@code name}
     * @throws ServerException
     *         if other error occurs
     */
    VirtualFile createFile(String name, String content)
            throws ForbiddenException, ConflictException, ServerException;

    /**
     * Creates new VirtualFile which denotes folder and use this one as parent folder.
     *
     * @param name
     *         name. If name is string separated by '/' all nonexistent parent folders must be created.
     * @return newly create VirtualFile that denotes folder
     * @throws ForbiddenException
     *         if this VirtualFile does not denote a folder
     * @throws ConflictException
     *         if item with specified {@code name} already exists
     * @throws ServerException
     *         if other error occurs
     */
    VirtualFile createFolder(String name) throws ForbiddenException, ConflictException, ServerException;

    /**
     * Gets {@link VirtualFileSystem} to which this VirtualFile belongs.
     *
     * @return VirtualFileSystem
     */
    VirtualFileSystem getFileSystem();

    /**
     * Accepts an {@code VirtualFileVisitor}. Calls the {@link VirtualFileVisitor#visit(VirtualFile)} method.
     *
     * @param visitor
     *         VirtualFileVisitor to be accepted
     * @throws ServerException
     *         if an error occurs
     */
    void accept(VirtualFileVisitor visitor) throws ServerException;

    /**
     * Traverses recursively all files in current folder and count md5sum for each file. Method returns {@code Pair<String, String>}
     * for each file, all folders are omitted. Each {@code Pair} contains following structure:
     * <pre>
     *     Pair<String,String> pair = ...
     *     pair.first // md5sum of file represented as HEX String
     *     pair.second // Path of file that is relative to this file
     * </pre>
     * If this VirtualFile is not a folder this method returns empty list. Note: any order of items in the returned list is not
     * guaranteed.
     *
     * @throws ServerException
     *         if any error occurs
     */
    List<Pair<String, String>> countMd5Sums() throws ServerException;

    /**
     * Gets java.io.File if implementation uses java.io.File as backend.
     *
     * @return java.io.File or {@code null} is java.io.File is not available
     */
    java.io.File toIoFile();
}