001/**
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.hadoop.fs;
019
020import org.apache.hadoop.classification.InterfaceAudience;
021import org.apache.hadoop.classification.InterfaceStability;
022import org.apache.hadoop.conf.Configuration;
023import org.apache.hadoop.conf.Configured;
024import org.apache.hadoop.util.ReflectionUtils;
025
026import java.io.IOException;
027
028/** 
029 * This interface is used for implementing different Trash policies.
030 * Provides factory method to create instances of the configured Trash policy.
031 */
032@InterfaceAudience.Public
033@InterfaceStability.Evolving
034public abstract class TrashPolicy extends Configured {
035  protected FileSystem fs; // the FileSystem
036  protected Path trash; // path to trash directory
037  protected long deletionInterval; // deletion interval for Emptier
038
039  /**
040   * Used to setup the trash policy. Must be implemented by all TrashPolicy
041   * implementations.
042   * @param conf the configuration to be used
043   * @param fs the filesystem to be used
044   * @param home the home directory
045   * @deprecated Use {@link #initialize(Configuration, FileSystem)} instead.
046   */
047  @Deprecated
048  public abstract void initialize(Configuration conf, FileSystem fs, Path home);
049
050  /**
051   * Used to setup the trash policy. Must be implemented by all TrashPolicy
052   * implementations. Different from initialize(conf, fs, home), this one does
053   * not assume trash always under /user/$USER due to HDFS encryption zone.
054   * @param conf the configuration to be used
055   * @param fs the filesystem to be used
056   */
057  public void initialize(Configuration conf, FileSystem fs) {
058    throw new UnsupportedOperationException();
059  }
060
061  /**
062   * Returns whether the Trash Policy is enabled for this filesystem.
063   */
064  public abstract boolean isEnabled();
065
066  /** 
067   * Move a file or directory to the current trash directory.
068   * @return false if the item is already in the trash or trash is disabled
069   */ 
070  public abstract boolean moveToTrash(Path path) throws IOException;
071
072  /** 
073   * Create a trash checkpoint. 
074   */
075  public abstract void createCheckpoint() throws IOException;
076
077  /** 
078   * Delete old trash checkpoint(s).
079   */
080  public abstract void deleteCheckpoint() throws IOException;
081
082  /**
083   * Get the current working directory of the Trash Policy
084   * This API does not work with files deleted from encryption zone when HDFS
085   * data encryption at rest feature is enabled as rename file between
086   * encryption zones or encryption zone and non-encryption zone is not allowed.
087   *
088   * The caller is recommend to use the new API
089   * TrashPolicy#getCurrentTrashDir(Path path).
090   * It returns the trash location correctly for the path specified no matter
091   * the path is in encryption zone or not.
092   */
093  public abstract Path getCurrentTrashDir();
094
095  /**
096   * Get the current trash directory for path specified based on the Trash
097   * Policy
098   * @param path path to be deleted
099   * @return current trash directory for the path to be deleted
100   * @throws IOException
101   */
102  public Path getCurrentTrashDir(Path path) throws IOException {
103    throw new UnsupportedOperationException();
104  }
105
106  /** 
107   * Return a {@link Runnable} that periodically empties the trash of all
108   * users, intended to be run by the superuser.
109   */
110  public abstract Runnable getEmptier() throws IOException;
111
112  /**
113   * Get an instance of the configured TrashPolicy based on the value
114   * of the configuration parameter fs.trash.classname.
115   *
116   * @param conf the configuration to be used
117   * @param fs the file system to be used
118   * @param home the home directory
119   * @return an instance of TrashPolicy
120   * @deprecated Use {@link #getInstance(Configuration, FileSystem)} instead.
121   */
122  @Deprecated
123  public static TrashPolicy getInstance(Configuration conf, FileSystem fs, Path home) {
124    Class<? extends TrashPolicy> trashClass = conf.getClass(
125        "fs.trash.classname", TrashPolicyDefault.class, TrashPolicy.class);
126    TrashPolicy trash = ReflectionUtils.newInstance(trashClass, conf);
127    trash.initialize(conf, fs, home); // initialize TrashPolicy
128    return trash;
129  }
130
131  /**
132   * Get an instance of the configured TrashPolicy based on the value
133   * of the configuration parameter fs.trash.classname.
134   *
135   * @param conf the configuration to be used
136   * @param fs the file system to be used
137   * @return an instance of TrashPolicy
138   */
139  public static TrashPolicy getInstance(Configuration conf, FileSystem fs) {
140    Class<? extends TrashPolicy> trashClass = conf.getClass(
141        "fs.trash.classname", TrashPolicyDefault.class, TrashPolicy.class);
142    TrashPolicy trash = ReflectionUtils.newInstance(trashClass, conf);
143    trash.initialize(conf, fs); // initialize TrashPolicy
144    return trash;
145  }
146}