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 java.io.FileNotFoundException; 021import java.io.IOException; 022import java.util.EnumSet; 023 024import org.apache.hadoop.HadoopIllegalArgumentException; 025import org.apache.hadoop.classification.InterfaceAudience; 026import org.apache.hadoop.classification.InterfaceStability; 027 028/**************************************************************** 029 * CreateFlag specifies the file create semantic. Users can combine flags like: <br> 030 * <code> 031 * EnumSet.of(CreateFlag.CREATE, CreateFlag.APPEND) 032 * <code> 033 * <p> 034 * 035 * Use the CreateFlag as follows: 036 * <ol> 037 * <li> CREATE - to create a file if it does not exist, 038 * else throw FileAlreadyExists.</li> 039 * <li> APPEND - to append to a file if it exists, 040 * else throw FileNotFoundException.</li> 041 * <li> OVERWRITE - to truncate a file if it exists, 042 * else throw FileNotFoundException.</li> 043 * <li> CREATE|APPEND - to create a file if it does not exist, 044 * else append to an existing file.</li> 045 * <li> CREATE|OVERWRITE - to create a file if it does not exist, 046 * else overwrite an existing file.</li> 047 * <li> SYNC_BLOCK - to force closed blocks to the disk device. 048 * In addition {@link Syncable#hsync()} should be called after each write, 049 * if true synchronous behavior is required.</li> 050 * </ol> 051 * 052 * Following combination is not valid and will result in 053 * {@link HadoopIllegalArgumentException}: 054 * <ol> 055 * <li> APPEND|OVERWRITE</li> 056 * <li> CREATE|APPEND|OVERWRITE</li> 057 * </ol> 058 *****************************************************************/ 059@InterfaceAudience.Public 060@InterfaceStability.Evolving 061public enum CreateFlag { 062 063 /** 064 * Create a file. See javadoc for more description 065 * already exists 066 */ 067 CREATE((short) 0x01), 068 069 /** 070 * Truncate/overwrite a file. Same as POSIX O_TRUNC. See javadoc for description. 071 */ 072 OVERWRITE((short) 0x02), 073 074 /** 075 * Append to a file. See javadoc for more description. 076 */ 077 APPEND((short) 0x04), 078 079 /** 080 * Force closed blocks to disk. Similar to POSIX O_SYNC. See javadoc for description. 081 */ 082 SYNC_BLOCK((short) 0x08), 083 084 /** 085 * Create the block on transient storage (RAM) if available. If 086 * transient storage is unavailable then the block will be created 087 * on disk. 088 * 089 * HDFS will make a best effort to lazily write these files to persistent 090 * storage, however file contents may be lost at any time due to process/ 091 * node restarts, hence there is no guarantee of data durability. 092 * 093 * This flag must only be used for intermediate data whose loss can be 094 * tolerated by the application. 095 */ 096 LAZY_PERSIST((short) 0x10), 097 098 /** 099 * Advise that a block replica NOT be written to the local DataNode where 100 * 'local' means the same host as the client is being run on. 101 */ 102 @InterfaceAudience.LimitedPrivate({"HBase"}) 103 NO_LOCAL_WRITE((short) 0x40); 104 105 private final short mode; 106 107 private CreateFlag(short mode) { 108 this.mode = mode; 109 } 110 111 short getMode() { 112 return mode; 113 } 114 115 /** 116 * Validate the CreateFlag and throw exception if it is invalid 117 * @param flag set of CreateFlag 118 * @throws HadoopIllegalArgumentException if the CreateFlag is invalid 119 */ 120 public static void validate(EnumSet<CreateFlag> flag) { 121 if (flag == null || flag.isEmpty()) { 122 throw new HadoopIllegalArgumentException(flag 123 + " does not specify any options"); 124 } 125 final boolean append = flag.contains(APPEND); 126 final boolean overwrite = flag.contains(OVERWRITE); 127 128 // Both append and overwrite is an error 129 if (append && overwrite) { 130 throw new HadoopIllegalArgumentException( 131 flag + "Both append and overwrite options cannot be enabled."); 132 } 133 } 134 135 /** 136 * Validate the CreateFlag for create operation 137 * @param path Object representing the path; usually String or {@link Path} 138 * @param pathExists pass true if the path exists in the file system 139 * @param flag set of CreateFlag 140 * @throws IOException on error 141 * @throws HadoopIllegalArgumentException if the CreateFlag is invalid 142 */ 143 public static void validate(Object path, boolean pathExists, 144 EnumSet<CreateFlag> flag) throws IOException { 145 validate(flag); 146 final boolean append = flag.contains(APPEND); 147 final boolean overwrite = flag.contains(OVERWRITE); 148 if (pathExists) { 149 if (!(append || overwrite)) { 150 throw new FileAlreadyExistsException("File already exists: " 151 + path.toString() 152 + ". Append or overwrite option must be specified in " + flag); 153 } 154 } else if (!flag.contains(CREATE)) { 155 throw new FileNotFoundException("Non existing file: " + path.toString() 156 + ". Create option is not specified in " + flag); 157 } 158 } 159}