View Javadoc

1   /**
2    * Copyright 2009 The Apache Software Foundation
3    *
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *     http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing, software
15   * distributed under the License is distributed on an "AS IS" BASIS,
16   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17   * See the License for the specific language governing permissions and
18   * limitations under the License.
19   */
20  package org.apache.hadoop.hbase;
21  
22  import java.io.DataInput;
23  import java.io.DataOutput;
24  import java.io.IOException;
25  import java.util.ArrayList;
26  import java.util.Collection;
27  import java.util.Collections;
28  import java.util.HashMap;
29  import java.util.Iterator;
30  import java.util.List;
31  import java.util.Map;
32  import java.util.Set;
33  import java.util.HashSet;
34  import java.util.TreeSet;
35  import java.util.TreeMap;
36  import java.util.regex.Matcher;
37  
38  import org.apache.hadoop.conf.Configuration;
39  import org.apache.hadoop.fs.Path;
40  import org.apache.hadoop.hbase.io.ImmutableBytesWritable;
41  import org.apache.hadoop.hbase.security.User;
42  import org.apache.hadoop.hbase.util.Bytes;
43  import org.apache.hadoop.io.WritableComparable;
44  
45  /**
46   * HTableDescriptor contains the details about an HBase table  such as the descriptors of
47   * all the column families, is the table a catalog table, <code> -ROOT- </code> or 
48   * <code> .META. </code>, is the table is read only, the maximum size of the memstore, 
49   * when the region split should occur, coprocessors associated with it etc...
50   */
51  public class HTableDescriptor implements WritableComparable<HTableDescriptor> {
52  
53    /**
54     *  Changes prior to version 3 were not recorded here.
55     *  Version 3 adds metadata as a map where keys and values are byte[].
56     *  Version 4 adds indexes
57     *  Version 5 removed transactional pollution -- e.g. indexes
58     */
59    private static final byte TABLE_DESCRIPTOR_VERSION = 5;
60  
61    private byte [] name = HConstants.EMPTY_BYTE_ARRAY;
62  
63    private String nameAsString = "";
64  
65    /**
66     * A map which holds the metadata information of the table. This metadata 
67     * includes values like IS_ROOT, IS_META, DEFERRED_LOG_FLUSH, SPLIT_POLICY,
68     * MAX_FILE_SIZE, READONLY, MEMSTORE_FLUSHSIZE etc...
69     */
70    protected final Map<ImmutableBytesWritable, ImmutableBytesWritable> values =
71      new HashMap<ImmutableBytesWritable, ImmutableBytesWritable>();
72  
73    private static final String FAMILIES = "FAMILIES";
74  
75    public static final String SPLIT_POLICY = "SPLIT_POLICY";
76    
77    /**
78     * <em>INTERNAL</em> Used by HBase Shell interface to access this metadata 
79     * attribute which denotes the maximum size of the store file after which 
80     * a region split occurs
81     * 
82     * @see #getMaxFileSize()
83     */
84    public static final String MAX_FILESIZE = "MAX_FILESIZE";
85    private static final ImmutableBytesWritable MAX_FILESIZE_KEY =
86      new ImmutableBytesWritable(Bytes.toBytes(MAX_FILESIZE));
87  
88    public static final String OWNER = "OWNER";
89    public static final ImmutableBytesWritable OWNER_KEY =
90      new ImmutableBytesWritable(Bytes.toBytes(OWNER));
91  
92    /**
93     * <em>INTERNAL</em> Used by rest interface to access this metadata 
94     * attribute which denotes if the table is Read Only
95     * 
96     * @see #isReadOnly()
97     */
98    public static final String READONLY = "READONLY";
99    private static final ImmutableBytesWritable READONLY_KEY =
100     new ImmutableBytesWritable(Bytes.toBytes(READONLY));
101 
102   /**
103    * <em>INTERNAL</em> Used by HBase Shell interface to access this metadata 
104    * attribute which represents the maximum size of the memstore after which 
105    * its contents are flushed onto the disk
106    * 
107    * @see #getMemStoreFlushSize()
108    */
109   public static final String MEMSTORE_FLUSHSIZE = "MEMSTORE_FLUSHSIZE";
110   private static final ImmutableBytesWritable MEMSTORE_FLUSHSIZE_KEY =
111     new ImmutableBytesWritable(Bytes.toBytes(MEMSTORE_FLUSHSIZE));
112 
113   /**
114    * <em>INTERNAL</em> Used by rest interface to access this metadata 
115    * attribute which denotes if the table is a -ROOT- region or not
116    * 
117    * @see #isRootRegion()
118    */
119   public static final String IS_ROOT = "IS_ROOT";
120   private static final ImmutableBytesWritable IS_ROOT_KEY =
121     new ImmutableBytesWritable(Bytes.toBytes(IS_ROOT));
122 
123   /**
124    * <em>INTERNAL</em> Used by rest interface to access this metadata 
125    * attribute which denotes if it is a catalog table, either
126    * <code> .META. </code> or <code> -ROOT- </code>
127    * 
128    * @see #isMetaRegion()
129    */
130   public static final String IS_META = "IS_META";
131   private static final ImmutableBytesWritable IS_META_KEY =
132     new ImmutableBytesWritable(Bytes.toBytes(IS_META));
133 
134   /**
135    * <em>INTERNAL</em> Used by HBase Shell interface to access this metadata 
136    * attribute which denotes if the deferred log flush option is enabled
137    */
138   public static final String DEFERRED_LOG_FLUSH = "DEFERRED_LOG_FLUSH";
139   private static final ImmutableBytesWritable DEFERRED_LOG_FLUSH_KEY =
140     new ImmutableBytesWritable(Bytes.toBytes(DEFERRED_LOG_FLUSH));
141 
142   /*
143    *  The below are ugly but better than creating them each time till we
144    *  replace booleans being saved as Strings with plain booleans.  Need a
145    *  migration script to do this.  TODO.
146    */
147   private static final ImmutableBytesWritable FALSE =
148     new ImmutableBytesWritable(Bytes.toBytes(Boolean.FALSE.toString()));
149 
150   private static final ImmutableBytesWritable TRUE =
151     new ImmutableBytesWritable(Bytes.toBytes(Boolean.TRUE.toString()));
152 
153   private static final boolean DEFAULT_DEFERRED_LOG_FLUSH = false;
154   
155   /**
156    * Constant that denotes whether the table is READONLY by default and is false
157    */
158   public static final boolean DEFAULT_READONLY = false;
159 
160   /**
161    * Constant that denotes the maximum default size of the memstore after which 
162    * the contents are flushed to the store files
163    */
164   public static final long DEFAULT_MEMSTORE_FLUSH_SIZE = 1024*1024*128L;
165   private final static Map<String, String> DEFAULT_VALUES
166     = new HashMap<String, String>();
167   private final static Set<ImmutableBytesWritable> RESERVED_KEYWORDS
168     = new HashSet<ImmutableBytesWritable>();
169   static {
170     DEFAULT_VALUES.put(MAX_FILESIZE,
171         String.valueOf(HConstants.DEFAULT_MAX_FILE_SIZE));
172     DEFAULT_VALUES.put(READONLY, String.valueOf(DEFAULT_READONLY));
173     DEFAULT_VALUES.put(MEMSTORE_FLUSHSIZE,
174         String.valueOf(DEFAULT_MEMSTORE_FLUSH_SIZE));
175     DEFAULT_VALUES.put(DEFERRED_LOG_FLUSH,
176         String.valueOf(DEFAULT_DEFERRED_LOG_FLUSH));
177     for (String s : DEFAULT_VALUES.keySet()) {
178       RESERVED_KEYWORDS.add(new ImmutableBytesWritable(Bytes.toBytes(s)));
179     }
180     RESERVED_KEYWORDS.add(IS_ROOT_KEY);
181     RESERVED_KEYWORDS.add(IS_META_KEY);
182   }
183 
184   
185 
186   private volatile Boolean meta = null;
187   private volatile Boolean root = null;
188   private Boolean isDeferredLog = null;
189 
190   /**
191    * Maps column family name to the respective HColumnDescriptors
192    */
193   private final Map<byte [], HColumnDescriptor> families =
194     new TreeMap<byte [], HColumnDescriptor>(Bytes.BYTES_RAWCOMPARATOR);
195 
196   /**
197    * <em> INTERNAL </em> Private constructor used internally creating table descriptors for
198    * catalog tables, <code>.META.</code> and <code>-ROOT-</code>.
199    */
200   protected HTableDescriptor(final byte [] name, HColumnDescriptor[] families) {
201     this.name = name.clone();
202     this.nameAsString = Bytes.toString(this.name);
203     setMetaFlags(name);
204     for(HColumnDescriptor descriptor : families) {
205       this.families.put(descriptor.getName(), descriptor);
206     }
207   }
208 
209   /**
210    * <em> INTERNAL </em>Private constructor used internally creating table descriptors for
211    * catalog tables, <code>.META.</code> and <code>-ROOT-</code>.
212    */
213   protected HTableDescriptor(final byte [] name, HColumnDescriptor[] families,
214       Map<ImmutableBytesWritable,ImmutableBytesWritable> values) {
215     this.name = name.clone();
216     this.nameAsString = Bytes.toString(this.name);
217     setMetaFlags(name);
218     for(HColumnDescriptor descriptor : families) {
219       this.families.put(descriptor.getName(), descriptor);
220     }
221     for (Map.Entry<ImmutableBytesWritable, ImmutableBytesWritable> entry:
222         values.entrySet()) {
223       this.values.put(entry.getKey(), entry.getValue());
224     }
225   }
226 
227   /**
228    * Default constructor which constructs an empty object.
229    * For deserializing an HTableDescriptor instance only.
230    * @see #HTableDescriptor(byte[])
231    */
232   public HTableDescriptor() {
233     super();
234   }
235 
236   /**
237    * Construct a table descriptor specifying table name.
238    * @param name Table name.
239    * @throws IllegalArgumentException if passed a table name
240    * that is made of other than 'word' characters, underscore or period: i.e.
241    * <code>[a-zA-Z_0-9.].
242    * @see <a href="HADOOP-1581">HADOOP-1581 HBASE: Un-openable tablename bug</a>
243    */
244   public HTableDescriptor(final String name) {
245     this(Bytes.toBytes(name));
246   }
247 
248   /**
249    * Construct a table descriptor specifying a byte array table name
250    * @param name - Table name as a byte array.
251    * @throws IllegalArgumentException if passed a table name
252    * that is made of other than 'word' characters, underscore or period: i.e.
253    * <code>[a-zA-Z_0-9-.].
254    * @see <a href="HADOOP-1581">HADOOP-1581 HBASE: Un-openable tablename bug</a>
255    */
256   public HTableDescriptor(final byte [] name) {
257     super();
258     setMetaFlags(this.name);
259     this.name = this.isMetaRegion()? name: isLegalTableName(name);
260     this.nameAsString = Bytes.toString(this.name);
261   }
262 
263   /**
264    * Construct a table descriptor by cloning the descriptor passed as a parameter.
265    * <p>
266    * Makes a deep copy of the supplied descriptor.
267    * Can make a modifiable descriptor from an UnmodifyableHTableDescriptor.
268    * @param desc The descriptor.
269    */
270   public HTableDescriptor(final HTableDescriptor desc) {
271     super();
272     this.name = desc.name.clone();
273     this.nameAsString = Bytes.toString(this.name);
274     setMetaFlags(this.name);
275     for (HColumnDescriptor c: desc.families.values()) {
276       this.families.put(c.getName(), new HColumnDescriptor(c));
277     }
278     for (Map.Entry<ImmutableBytesWritable, ImmutableBytesWritable> e:
279         desc.values.entrySet()) {
280       this.values.put(e.getKey(), e.getValue());
281     }
282   }
283 
284   /*
285    * Set meta flags on this table. 
286    * IS_ROOT_KEY is set if its a -ROOT- table
287    * IS_META_KEY is set either if its a -ROOT- or a .META. table 
288    * Called by constructors.
289    * @param name
290    */
291   private void setMetaFlags(final byte [] name) {
292     setRootRegion(Bytes.equals(name, HConstants.ROOT_TABLE_NAME));
293     setMetaRegion(isRootRegion() ||
294       Bytes.equals(name, HConstants.META_TABLE_NAME));
295   }
296 
297   /**
298    * Check if the descriptor represents a <code> -ROOT- </code> region.
299    * 
300    * @return true if this is a <code> -ROOT- </code> region 
301    */
302   public boolean isRootRegion() {
303     if (this.root == null) {
304       this.root = isSomething(IS_ROOT_KEY, false)? Boolean.TRUE: Boolean.FALSE;
305     }
306     return this.root.booleanValue();
307   }
308 
309   /**
310    * <em> INTERNAL </em> Used to denote if the current table represents 
311    * <code> -ROOT- </code> region. This is used internally by the 
312    * HTableDescriptor constructors 
313    * 
314    * @param isRoot true if this is the <code> -ROOT- </code> region 
315    */
316   protected void setRootRegion(boolean isRoot) {
317     // TODO: Make the value a boolean rather than String of boolean.
318     values.put(IS_ROOT_KEY, isRoot? TRUE: FALSE);
319   }
320 
321   /**
322    * Checks if this table is either <code> -ROOT- </code> or <code> .META. </code>
323    * region. 
324    *  
325    * @return true if this is either a <code> -ROOT- </code> or <code> .META. </code> 
326    * region 
327    */
328   public boolean isMetaRegion() {
329     if (this.meta == null) {
330       this.meta = calculateIsMetaRegion();
331     }
332     return this.meta.booleanValue();
333   }
334 
335   private synchronized Boolean calculateIsMetaRegion() {
336     byte [] value = getValue(IS_META_KEY);
337     return (value != null)? Boolean.valueOf(Bytes.toString(value)): Boolean.FALSE;
338   }
339 
340   private boolean isSomething(final ImmutableBytesWritable key,
341       final boolean valueIfNull) {
342     byte [] value = getValue(key);
343     if (value != null) {
344       // TODO: Make value be a boolean rather than String of boolean.
345       return Boolean.valueOf(Bytes.toString(value)).booleanValue();
346     }
347     return valueIfNull;
348   }
349 
350   /**
351    * <em> INTERNAL </em> Used to denote if the current table represents 
352    * <code> -ROOT- </code> or <code> .META. </code> region. This is used 
353    * internally by the HTableDescriptor constructors 
354    * 
355    * @param isMeta true if its either <code> -ROOT- </code> or 
356    * <code> .META. </code> region 
357    */
358   protected void setMetaRegion(boolean isMeta) {
359     values.put(IS_META_KEY, isMeta? TRUE: FALSE);
360   }
361 
362   /** 
363    * Checks if the table is a <code>.META.</code> table 
364    *  
365    * @return true if table is <code> .META. </code> region.
366    */
367   public boolean isMetaTable() {
368     return isMetaRegion() && !isRootRegion();
369   }
370  
371   /**
372    * Checks of the tableName being passed represents either 
373    * <code > -ROOT- </code> or <code> .META. </code>
374    *  
375    * @return true if a tablesName is either <code> -ROOT- </code> 
376    * or <code> .META. </code>
377    */
378   public static boolean isMetaTable(final byte [] tableName) {
379     return Bytes.equals(tableName, HConstants.ROOT_TABLE_NAME) ||
380       Bytes.equals(tableName, HConstants.META_TABLE_NAME);
381   }
382 
383   // A non-capture group so that this can be embedded.
384   public static final String VALID_USER_TABLE_REGEX = "(?:[a-zA-Z_0-9][a-zA-Z_0-9.-]*)";
385 
386   public static byte [] isLegalTableName(final byte [] tableName) {
387     return isLegalTableName(tableName, false);
388   }
389 
390   /**
391    * Check passed byte buffer, "tableName", is legal user-space table name.
392    * @return Returns passed <code>tableName</code> param
393    * @throws NullPointerException If passed <code>tableName</code> is null
394    * @throws IllegalArgumentException if passed a tableName
395    * that is made of other than 'word' characters or underscores: i.e.
396    * <code>[a-zA-Z_0-9].
397    */
398   public static byte [] isLegalTableName(final byte [] tableName, boolean isSnapshot) {
399     if (tableName == null || tableName.length <= 0) {
400       throw new IllegalArgumentException("Name is null or empty");
401     }
402     if (tableName[0] == '.' || tableName[0] == '-') {
403       throw new IllegalArgumentException("Illegal first character <" + tableName[0] +
404           "> at 0. " + (isSnapshot ? "snapshot" : "User-space table") +
405           " can only start with 'word characters': i.e. [a-zA-Z_0-9]: " +
406           Bytes.toString(tableName));
407     }
408     for (int i = 0; i < tableName.length; i++) {
409       if (Character.isLetterOrDigit(tableName[i]) || tableName[i] == '_' ||
410           tableName[i] == '-' || tableName[i] == '.') {
411         continue;
412       }
413       throw new IllegalArgumentException("Illegal character <" + tableName[i] +
414         "> at " + i + ". " + (isSnapshot ? "snapshot" : "User-space table") +
415         " can only contain 'word characters': i.e. [a-zA-Z_0-9-.]: " +
416         Bytes.toString(tableName));
417     }
418     return tableName;
419   }
420 
421   /**
422    * Getter for accessing the metadata associated with the key
423    *  
424    * @param key The key.
425    * @return The value.
426    * @see #values
427    */
428   public byte[] getValue(byte[] key) {
429     return getValue(new ImmutableBytesWritable(key));
430   }
431 
432   private byte[] getValue(final ImmutableBytesWritable key) {
433     ImmutableBytesWritable ibw = values.get(key);
434     if (ibw == null)
435       return null;
436     return ibw.get();
437   }
438 
439   /**
440    * Getter for accessing the metadata associated with the key
441    *  
442    * @param key The key.
443    * @return The value.
444    * @see #values
445    */
446   public String getValue(String key) {
447     byte[] value = getValue(Bytes.toBytes(key));
448     if (value == null)
449       return null;
450     return Bytes.toString(value);
451   }
452 
453   /**
454    * Getter for fetching an unmodifiable {@link #values} map.
455    *  
456    * @return unmodifiable map {@link #values}.
457    * @see #values
458    */
459   public Map<ImmutableBytesWritable,ImmutableBytesWritable> getValues() {
460     // shallow pointer copy 
461     return Collections.unmodifiableMap(values);
462   }
463 
464   /**
465    * Setter for storing metadata as a (key, value) pair in {@link #values} map
466    *  
467    * @param key The key.
468    * @param value The value.
469    * @see #values
470    */
471   public void setValue(byte[] key, byte[] value) {
472     setValue(new ImmutableBytesWritable(key), value);
473   }
474 
475   /*
476    * @param key The key.
477    * @param value The value.
478    */
479   private void setValue(final ImmutableBytesWritable key,
480       final byte[] value) {
481     values.put(key, new ImmutableBytesWritable(value));
482   }
483 
484   /*
485    * Setter for storing metadata as a (key, value) pair in {@link #values} map
486    *
487    * @param key The key.
488    * @param value The value.
489    */
490   public void setValue(final ImmutableBytesWritable key,
491       final ImmutableBytesWritable value) {
492     values.put(key, value);
493   }
494 
495   /**
496    * Setter for storing metadata as a (key, value) pair in {@link #values} map
497    *  
498    * @param key The key.
499    * @param value The value.
500    * @see #values
501    */
502   public void setValue(String key, String value) {
503     if (value == null) {
504       remove(Bytes.toBytes(key));
505     } else {
506       setValue(Bytes.toBytes(key), Bytes.toBytes(value));
507     }
508   }
509 
510   /**
511    * Remove metadata represented by the key from the {@link #values} map
512    * 
513    * @param key Key whose key and value we're to remove from HTableDescriptor
514    * parameters.
515    */
516   public void remove(final byte [] key) {
517     values.remove(new ImmutableBytesWritable(key));
518   }
519   
520   /**
521    * Remove metadata represented by the key from the {@link #values} map
522    * 
523    * @param key Key whose key and value we're to remove from HTableDescriptor
524    * parameters.
525    */
526   public void remove(final String key) {
527     remove(Bytes.toBytes(key));
528   }
529 
530   /**
531    * Check if the readOnly flag of the table is set. If the readOnly flag is 
532    * set then the contents of the table can only be read from but not modified.
533    * 
534    * @return true if all columns in the table should be read only
535    */
536   public boolean isReadOnly() {
537     return isSomething(READONLY_KEY, DEFAULT_READONLY);
538   }
539 
540   /**
541    * Setting the table as read only sets all the columns in the table as read
542    * only. By default all tables are modifiable, but if the readOnly flag is 
543    * set to true then the contents of the table can only be read but not modified.
544    *  
545    * @param readOnly True if all of the columns in the table should be read
546    * only.
547    */
548   public void setReadOnly(final boolean readOnly) {
549     setValue(READONLY_KEY, readOnly? TRUE: FALSE);
550   }
551 
552   /**
553    * Check if deferred log edits are enabled on the table.  
554    * 
555    * @return true if that deferred log flush is enabled on the table
556    * 
557    * @see #setDeferredLogFlush(boolean)
558    */
559   public synchronized boolean isDeferredLogFlush() {
560     if(this.isDeferredLog == null) {
561       this.isDeferredLog =
562           isSomething(DEFERRED_LOG_FLUSH_KEY, DEFAULT_DEFERRED_LOG_FLUSH);
563     }
564     return this.isDeferredLog;
565   }
566 
567   /**
568    * This is used to defer the log edits syncing to the file system. Everytime 
569    * an edit is sent to the server it is first sync'd to the file system by the 
570    * log writer. This sync is an expensive operation and thus can be deferred so 
571    * that the edits are kept in memory for a specified period of time as represented
572    * by <code> hbase.regionserver.optionallogflushinterval </code> and not flushed
573    * for every edit.
574    * <p>
575    * NOTE:- This option might result in data loss if the region server crashes
576    * before these deferred edits in memory are flushed onto the filesystem. 
577    * </p>
578    * 
579    * @param isDeferredLogFlush
580    */
581   public void setDeferredLogFlush(final boolean isDeferredLogFlush) {
582     setValue(DEFERRED_LOG_FLUSH_KEY, isDeferredLogFlush? TRUE: FALSE);
583     this.isDeferredLog = isDeferredLogFlush;
584   }
585 
586   /**
587    * Get the name of the table as a byte array.
588    * 
589    * @return name of table 
590    */
591   public byte [] getName() {
592     return name;
593   }
594 
595   /**
596    * Get the name of the table as a String
597    * 
598    * @return name of table as a String 
599    */
600   public String getNameAsString() {
601     return this.nameAsString;
602   }
603   
604   /**
605    * This get the class associated with the region split policy which 
606    * determines when a region split should occur.  The class used by
607    * default is {@link org.apache.hadoop.hbase.regionserver.ConstantSizeRegionSplitPolicy}
608    * which split the region base on a constant {@link #getMaxFileSize()}
609    * 
610    * @return the class name of the region split policy for this table.
611    * If this returns null, the default constant size based split policy
612    * is used.
613    */
614    public String getRegionSplitPolicyClassName() {
615     return getValue(SPLIT_POLICY);
616   }
617 
618   /**
619    * Set the name of the table. 
620    * 
621    * @param name name of table 
622    */
623   public void setName(byte[] name) {
624     this.name = name;
625     this.nameAsString = Bytes.toString(this.name);
626     setMetaFlags(this.name);
627   }
628 
629   /** 
630    * Returns the maximum size upto which a region can grow to after which a region
631    * split is triggered. The region size is represented by the size of the biggest
632    * store file in that region.
633    *
634    * @return max hregion size for table, -1 if not set.
635    *
636    * @see #setMaxFileSize(long)
637    */
638   public long getMaxFileSize() {
639     byte [] value = getValue(MAX_FILESIZE_KEY);
640     if (value != null) {
641       return Long.parseLong(Bytes.toString(value));
642     }
643     return -1;
644   }
645 
646   /**
647    * Sets the maximum size upto which a region can grow to after which a region
648    * split is triggered. The region size is represented by the size of the biggest 
649    * store file in that region, i.e. If the biggest store file grows beyond the 
650    * maxFileSize, then the region split is triggered. This defaults to a value of 
651    * 256 MB.
652    * <p>
653    * This is not an absolute value and might vary. Assume that a single row exceeds 
654    * the maxFileSize then the storeFileSize will be greater than maxFileSize since
655    * a single row cannot be split across multiple regions 
656    * </p>
657    * 
658    * @param maxFileSize The maximum file size that a store file can grow to
659    * before a split is triggered.
660    */
661   public void setMaxFileSize(long maxFileSize) {
662     setValue(MAX_FILESIZE_KEY, Bytes.toBytes(Long.toString(maxFileSize)));
663   }
664 
665   /**
666    * Returns the size of the memstore after which a flush to filesystem is triggered.
667    *
668    * @return memory cache flush size for each hregion, -1 if not set.
669    *
670    * @see #setMemStoreFlushSize(long)
671    */
672   public long getMemStoreFlushSize() {
673     byte [] value = getValue(MEMSTORE_FLUSHSIZE_KEY);
674     if (value != null) {
675       return Long.parseLong(Bytes.toString(value));
676     }
677     return -1;
678   }
679 
680   /**
681    * Represents the maximum size of the memstore after which the contents of the 
682    * memstore are flushed to the filesystem. This defaults to a size of 64 MB.
683    * 
684    * @param memstoreFlushSize memory cache flush size for each hregion
685    */
686   public void setMemStoreFlushSize(long memstoreFlushSize) {
687     setValue(MEMSTORE_FLUSHSIZE_KEY,
688       Bytes.toBytes(Long.toString(memstoreFlushSize)));
689   }
690 
691   /**
692    * Adds a column family.
693    * @param family HColumnDescriptor of family to add.
694    */
695   public void addFamily(final HColumnDescriptor family) {
696     if (family.getName() == null || family.getName().length <= 0) {
697       throw new NullPointerException("Family name cannot be null or empty");
698     }
699     this.families.put(family.getName(), family);
700   }
701 
702   /**
703    * Checks to see if this table contains the given column family
704    * @param familyName Family name or column name.
705    * @return true if the table contains the specified family name
706    */
707   public boolean hasFamily(final byte [] familyName) {
708     return families.containsKey(familyName);
709   }
710 
711   /**
712    * @return Name of this table and then a map of all of the column family
713    * descriptors.
714    * @see #getNameAsString()
715    */
716   @Override
717   public String toString() {
718     StringBuilder s = new StringBuilder();
719     s.append('\'').append(Bytes.toString(name)).append('\'');
720     s.append(getValues(true));
721     for (HColumnDescriptor f : families.values()) {
722       s.append(", ").append(f);
723     }
724     return s.toString();
725   }
726 
727   /**
728    * @return Name of this table and then a map of all of the column family
729    * descriptors (with only the non-default column family attributes)
730    */
731   public String toStringCustomizedValues() {
732     StringBuilder s = new StringBuilder();
733     s.append('\'').append(Bytes.toString(name)).append('\'');
734     s.append(getValues(false));
735     for(HColumnDescriptor hcd : families.values()) {
736       s.append(", ").append(hcd.toStringCustomizedValues());
737     }
738     return s.toString();
739   }
740 
741   private StringBuilder getValues(boolean printDefaults) {
742     StringBuilder s = new StringBuilder();
743 
744     // step 1: set partitioning and pruning
745     Set<ImmutableBytesWritable> reservedKeys = new TreeSet<ImmutableBytesWritable>();
746     Set<ImmutableBytesWritable> configKeys = new TreeSet<ImmutableBytesWritable>();
747     for (ImmutableBytesWritable k : values.keySet()) {
748       if (k == null || k.get() == null) continue;
749       String key = Bytes.toString(k.get());
750       // in this section, print out reserved keywords + coprocessor info
751       if (!RESERVED_KEYWORDS.contains(k) && !key.startsWith("coprocessor$")) {
752         configKeys.add(k);        
753         continue;
754       }
755       // only print out IS_ROOT/IS_META if true
756       String value = Bytes.toString(values.get(k).get());
757       if (key.equalsIgnoreCase(IS_ROOT) || key.equalsIgnoreCase(IS_META)) {
758         // Skip. Don't bother printing out read-only values if false.
759         if (value.toLowerCase().equals(Boolean.FALSE.toString())) {
760           continue;
761         }
762       }
763 
764       // see if a reserved key is a default value. may not want to print it out
765       if (printDefaults
766           || !DEFAULT_VALUES.containsKey(key)
767           || !DEFAULT_VALUES.get(key).equalsIgnoreCase(value)) {
768         reservedKeys.add(k);
769       }
770     }
771 
772 
773 
774     // early exit optimization
775     if (reservedKeys.isEmpty() && configKeys.isEmpty()) return s;
776 
777     // step 2: printing
778     s.append(", {METHOD => 'table_att'");
779 
780     // print all reserved keys first
781     for (ImmutableBytesWritable k : reservedKeys) {
782       String key = Bytes.toString(k.get());
783       String value = Bytes.toString(values.get(k).get());
784 
785       s.append(", ");
786       s.append(key);
787       s.append(" => ");
788       s.append('\'').append(value).append('\'');
789     }
790     if (!configKeys.isEmpty()) {
791       // print all non-reserved, advanced config keys as a separate subset
792       s.append(", ");
793       s.append(HConstants.CONFIG).append(" => ");
794       s.append("{");
795       boolean printComma = false;
796       for (ImmutableBytesWritable k : configKeys) {
797         String key = Bytes.toString(k.get());
798         String value = Bytes.toString(values.get(k).get());
799         if (printComma) s.append(", ");
800         printComma = true;
801         s.append('\'').append(key).append('\'');
802         s.append(" => ");
803         s.append('\'').append(value).append('\'');
804       }
805       s.append("}");
806     }
807 
808     s.append('}'); // end METHOD
809     return s;
810   }
811                 
812   public static Map<String, String> getDefaultValues() {
813     return Collections.unmodifiableMap(DEFAULT_VALUES);
814   }
815 
816   /**
817    * Compare the contents of the descriptor with another one passed as a parameter. 
818    * Checks if the obj passed is an instance of HTableDescriptor, if yes then the
819    * contents of the descriptors are compared.
820    * 
821    * @return true if the contents of the the two descriptors exactly match
822    * 
823    * @see java.lang.Object#equals(java.lang.Object)
824    */
825   @Override
826   public boolean equals(Object obj) {
827     if (this == obj) {
828       return true;
829     }
830     if (obj == null) {
831       return false;
832     }
833     if (!(obj instanceof HTableDescriptor)) {
834       return false;
835     }
836     return compareTo((HTableDescriptor)obj) == 0;
837   }
838 
839   /**
840    * @see java.lang.Object#hashCode()
841    */
842   @Override
843   public int hashCode() {
844     int result = Bytes.hashCode(this.name);
845     result ^= Byte.valueOf(TABLE_DESCRIPTOR_VERSION).hashCode();
846     if (this.families != null && this.families.size() > 0) {
847       for (HColumnDescriptor e: this.families.values()) {
848         result ^= e.hashCode();
849       }
850     }
851     result ^= values.hashCode();
852     return result;
853   }
854 
855   // Writable
856   /**
857    * <em> INTERNAL </em> This method is a part of {@link WritableComparable} interface 
858    * and is used for de-serialization of the HTableDescriptor over RPC
859    */
860   @Override
861   public void readFields(DataInput in) throws IOException {
862     int version = in.readInt();
863     if (version < 3)
864       throw new IOException("versions < 3 are not supported (and never existed!?)");
865     // version 3+
866     name = Bytes.readByteArray(in);
867     nameAsString = Bytes.toString(this.name);
868     setRootRegion(in.readBoolean());
869     setMetaRegion(in.readBoolean());
870     values.clear();
871     int numVals = in.readInt();
872     for (int i = 0; i < numVals; i++) {
873       ImmutableBytesWritable key = new ImmutableBytesWritable();
874       ImmutableBytesWritable value = new ImmutableBytesWritable();
875       key.readFields(in);
876       value.readFields(in);
877       values.put(key, value);
878     }
879     families.clear();
880     int numFamilies = in.readInt();
881     for (int i = 0; i < numFamilies; i++) {
882       HColumnDescriptor c = new HColumnDescriptor();
883       c.readFields(in);
884       families.put(c.getName(), c);
885     }
886     if (version < 4) {
887       return;
888     }
889   }
890 
891   /**
892    * <em> INTERNAL </em> This method is a part of {@link WritableComparable} interface 
893    * and is used for serialization of the HTableDescriptor over RPC
894    */
895   @Override
896   public void write(DataOutput out) throws IOException {
897 	out.writeInt(TABLE_DESCRIPTOR_VERSION);
898     Bytes.writeByteArray(out, name);
899     out.writeBoolean(isRootRegion());
900     out.writeBoolean(isMetaRegion());
901     out.writeInt(values.size());
902     for (Map.Entry<ImmutableBytesWritable, ImmutableBytesWritable> e:
903         values.entrySet()) {
904       e.getKey().write(out);
905       e.getValue().write(out);
906     }
907     out.writeInt(families.size());
908     for(Iterator<HColumnDescriptor> it = families.values().iterator();
909         it.hasNext(); ) {
910       HColumnDescriptor family = it.next();
911       family.write(out);
912     }
913   }
914 
915   // Comparable
916 
917   /**
918    * Compares the descriptor with another descriptor which is passed as a parameter.
919    * This compares the content of the two descriptors and not the reference.
920    * 
921    * @return 0 if the contents of the descriptors are exactly matching, 
922    * 		 1 if there is a mismatch in the contents 
923    */
924   @Override
925   public int compareTo(final HTableDescriptor other) {
926     int result = Bytes.compareTo(this.name, other.name);
927     if (result == 0) {
928       result = families.size() - other.families.size();
929     }
930     if (result == 0 && families.size() != other.families.size()) {
931       result = Integer.valueOf(families.size()).compareTo(
932           Integer.valueOf(other.families.size()));
933     }
934     if (result == 0) {
935       for (Iterator<HColumnDescriptor> it = families.values().iterator(),
936           it2 = other.families.values().iterator(); it.hasNext(); ) {
937         result = it.next().compareTo(it2.next());
938         if (result != 0) {
939           break;
940         }
941       }
942     }
943     if (result == 0) {
944       // punt on comparison for ordering, just calculate difference
945       result = this.values.hashCode() - other.values.hashCode();
946       if (result < 0)
947         result = -1;
948       else if (result > 0)
949         result = 1;
950     }
951     return result;
952   }
953 
954   /**
955    * Returns an unmodifiable collection of all the {@link HColumnDescriptor} 
956    * of all the column families of the table.
957    *  
958    * @return Immutable collection of {@link HColumnDescriptor} of all the
959    * column families. 
960    */
961   public Collection<HColumnDescriptor> getFamilies() {
962     return Collections.unmodifiableCollection(this.families.values());
963   }
964 
965   /**
966    * Returns all the column family names of the current table. The map of 
967    * HTableDescriptor contains mapping of family name to HColumnDescriptors. 
968    * This returns all the keys of the family map which represents the column 
969    * family names of the table. 
970    * 
971    * @return Immutable sorted set of the keys of the families.
972    */
973   public Set<byte[]> getFamiliesKeys() {
974     return Collections.unmodifiableSet(this.families.keySet());
975   }
976 
977   /** 
978    * Returns an array all the {@link HColumnDescriptor} of the column families 
979    * of the table.
980    *  
981    * @return Array of all the HColumnDescriptors of the current table 
982    * 
983    * @see #getFamilies()
984    */
985   public HColumnDescriptor[] getColumnFamilies() {
986     return getFamilies().toArray(new HColumnDescriptor[0]);
987   }
988   
989 
990   /**
991    * Returns the HColumnDescriptor for a specific column family with name as 
992    * specified by the parameter column.
993    * 
994    * @param column Column family name 
995    * @return Column descriptor for the passed family name or the family on
996    * passed in column.
997    */
998   public HColumnDescriptor getFamily(final byte [] column) {
999     return this.families.get(column);
1000   }
1001   
1002 
1003   /**
1004    * Removes the HColumnDescriptor with name specified by the parameter column 
1005    * from the table descriptor
1006    * 
1007    * @param column Name of the column family to be removed.
1008    * @return Column descriptor for the passed family name or the family on
1009    * passed in column.
1010    */
1011   public HColumnDescriptor removeFamily(final byte [] column) {
1012     return this.families.remove(column);
1013   }
1014   
1015 
1016   /**
1017    * Add a table coprocessor to this table. The coprocessor
1018    * type must be {@link org.apache.hadoop.hbase.coprocessor.RegionObserver}
1019    * or Endpoint.
1020    * It won't check if the class can be loaded or not.
1021    * Whether a coprocessor is loadable or not will be determined when
1022    * a region is opened.
1023    * @param className Full class name.
1024    * @throws IOException
1025    */
1026   public void addCoprocessor(String className) throws IOException {
1027     addCoprocessor(className, null, Coprocessor.PRIORITY_USER, null);
1028   }
1029 
1030   
1031   /**
1032    * Add a table coprocessor to this table. The coprocessor
1033    * type must be {@link org.apache.hadoop.hbase.coprocessor.RegionObserver}
1034    * or Endpoint.
1035    * It won't check if the class can be loaded or not.
1036    * Whether a coprocessor is loadable or not will be determined when
1037    * a region is opened.
1038    * @param jarFilePath Path of the jar file. If it's null, the class will be
1039    * loaded from default classloader.
1040    * @param className Full class name.
1041    * @param priority Priority
1042    * @param kvs Arbitrary key-value parameter pairs passed into the coprocessor.
1043    * @throws IOException
1044    */
1045   public void addCoprocessor(String className, Path jarFilePath,
1046                              int priority, final Map<String, String> kvs)
1047   throws IOException {
1048     if (hasCoprocessor(className)) {
1049       throw new IOException("Coprocessor " + className + " already exists.");
1050     }
1051     // validate parameter kvs
1052     StringBuilder kvString = new StringBuilder();
1053     if (kvs != null) {
1054       for (Map.Entry<String, String> e: kvs.entrySet()) {
1055         if (!e.getKey().matches(HConstants.CP_HTD_ATTR_VALUE_PARAM_KEY_PATTERN)) {
1056           throw new IOException("Illegal parameter key = " + e.getKey());
1057         }
1058         if (!e.getValue().matches(HConstants.CP_HTD_ATTR_VALUE_PARAM_VALUE_PATTERN)) {
1059           throw new IOException("Illegal parameter (" + e.getKey() +
1060               ") value = " + e.getValue());
1061         }
1062         if (kvString.length() != 0) {
1063           kvString.append(',');
1064         }
1065         kvString.append(e.getKey());
1066         kvString.append('=');
1067         kvString.append(e.getValue());
1068       }
1069     }
1070 
1071     // generate a coprocessor key
1072     int maxCoprocessorNumber = 0;
1073     Matcher keyMatcher;
1074     for (Map.Entry<ImmutableBytesWritable, ImmutableBytesWritable> e:
1075         this.values.entrySet()) {
1076       keyMatcher =
1077           HConstants.CP_HTD_ATTR_KEY_PATTERN.matcher(
1078               Bytes.toString(e.getKey().get()));
1079       if (!keyMatcher.matches()) {
1080         continue;
1081       }
1082       maxCoprocessorNumber = Math.max(Integer.parseInt(keyMatcher.group(1)),
1083           maxCoprocessorNumber);
1084     }
1085     maxCoprocessorNumber++;
1086 
1087     String key = "coprocessor$" + Integer.toString(maxCoprocessorNumber);
1088     String value = ((jarFilePath == null)? "" : jarFilePath.toString()) +
1089         "|" + className + "|" + Integer.toString(priority) + "|" +
1090         kvString.toString();
1091     setValue(key, value);
1092   }
1093 
1094 
1095   /**
1096    * Check if the table has an attached co-processor represented by the name className
1097    *
1098    * @param className - Class name of the co-processor
1099    * @return true of the table has a co-processor className
1100    */
1101   public boolean hasCoprocessor(String className) {
1102     Matcher keyMatcher;
1103     Matcher valueMatcher;
1104     for (Map.Entry<ImmutableBytesWritable, ImmutableBytesWritable> e:
1105         this.values.entrySet()) {
1106       keyMatcher =
1107           HConstants.CP_HTD_ATTR_KEY_PATTERN.matcher(
1108               Bytes.toString(e.getKey().get()));
1109       if (!keyMatcher.matches()) {
1110         continue;
1111       }
1112       valueMatcher =
1113         HConstants.CP_HTD_ATTR_VALUE_PATTERN.matcher(
1114             Bytes.toString(e.getValue().get()));
1115       if (!valueMatcher.matches()) {
1116         continue;
1117       }
1118       // get className and compare
1119       String clazz = valueMatcher.group(2).trim(); // classname is the 2nd field
1120       if (clazz.equals(className.trim())) {
1121         return true;
1122       }
1123     }
1124     return false;
1125   }
1126 
1127   /**
1128    * Return the list of attached co-processor represented by their name className
1129    *
1130    * @return The list of co-processors classNames
1131    */
1132   public List<String> getCoprocessors() {
1133     List<String> result = new ArrayList<String>();
1134     Matcher keyMatcher;
1135     Matcher valueMatcher;
1136     for (Map.Entry<ImmutableBytesWritable, ImmutableBytesWritable> e : this.values.entrySet()) {
1137       keyMatcher = HConstants.CP_HTD_ATTR_KEY_PATTERN.matcher(Bytes.toString(e.getKey().get()));
1138       if (!keyMatcher.matches()) {
1139         continue;
1140       }
1141       valueMatcher = HConstants.CP_HTD_ATTR_VALUE_PATTERN.matcher(Bytes
1142           .toString(e.getValue().get()));
1143       if (!valueMatcher.matches()) {
1144         continue;
1145       }
1146       result.add(valueMatcher.group(2).trim()); // classname is the 2nd field
1147     }
1148     return result;
1149   }
1150 
1151   /**
1152    * Remove a coprocessor from those set on the table
1153    * @param className Class name of the co-processor
1154    */
1155   public void removeCoprocessor(String className) {
1156     ImmutableBytesWritable match = null;
1157     Matcher keyMatcher;
1158     Matcher valueMatcher;
1159     for (Map.Entry<ImmutableBytesWritable, ImmutableBytesWritable> e : this.values
1160         .entrySet()) {
1161       keyMatcher = HConstants.CP_HTD_ATTR_KEY_PATTERN.matcher(Bytes.toString(e
1162           .getKey().get()));
1163       if (!keyMatcher.matches()) {
1164         continue;
1165       }
1166       valueMatcher = HConstants.CP_HTD_ATTR_VALUE_PATTERN.matcher(Bytes
1167           .toString(e.getValue().get()));
1168       if (!valueMatcher.matches()) {
1169         continue;
1170       }
1171       // get className and compare
1172       String clazz = valueMatcher.group(2).trim(); // classname is the 2nd field
1173       // remove the CP if it is present
1174       if (clazz.equals(className.trim())) {
1175         match = e.getKey();
1176         break;
1177       }
1178     }
1179     // if we found a match, remove it
1180     if (match != null)
1181       this.values.remove(match);
1182   }
1183   
1184   /**
1185    * Returns the {@link Path} object representing the table directory under 
1186    * path rootdir 
1187    * 
1188    * @param rootdir qualified path of HBase root directory
1189    * @param tableName name of table
1190    * @return {@link Path} for table
1191    */
1192   public static Path getTableDir(Path rootdir, final byte [] tableName) {
1193     return new Path(rootdir, Bytes.toString(tableName));
1194   }
1195 
1196   /** Table descriptor for <core>-ROOT-</code> catalog table */
1197   public static final HTableDescriptor ROOT_TABLEDESC = new HTableDescriptor(
1198       HConstants.ROOT_TABLE_NAME,
1199       new HColumnDescriptor[] {
1200           new HColumnDescriptor(HConstants.CATALOG_FAMILY)
1201               // Ten is arbitrary number.  Keep versions to help debugging.
1202               .setMaxVersions(10)
1203               .setInMemory(true)
1204               .setBlocksize(8 * 1024)
1205               .setTimeToLive(HConstants.FOREVER)
1206               .setScope(HConstants.REPLICATION_SCOPE_LOCAL)
1207       });
1208 
1209   /** Table descriptor for <code>.META.</code> catalog table */
1210   public static final HTableDescriptor META_TABLEDESC = new HTableDescriptor(
1211       HConstants.META_TABLE_NAME, new HColumnDescriptor[] {
1212           new HColumnDescriptor(HConstants.CATALOG_FAMILY)
1213               // Ten is arbitrary number.  Keep versions to help debugging.
1214               .setMaxVersions(10)
1215               .setInMemory(true)
1216               .setBlocksize(8 * 1024)
1217               .setScope(HConstants.REPLICATION_SCOPE_LOCAL)
1218       });
1219 
1220   @Deprecated
1221   public void setOwner(User owner) {
1222     setOwnerString(owner != null ? owner.getShortName() : null);
1223   }
1224 
1225   // used by admin.rb:alter(table_name,*args) to update owner.
1226   @Deprecated
1227   public void setOwnerString(String ownerString) {
1228     if (ownerString != null) {
1229       setValue(OWNER_KEY, Bytes.toBytes(ownerString));
1230     } else {
1231       values.remove(OWNER_KEY);
1232     }
1233   }
1234 
1235   @Deprecated
1236   public String getOwnerString() {
1237     if (getValue(OWNER_KEY) != null) {
1238       return Bytes.toString(getValue(OWNER_KEY));
1239     }
1240     // Note that every table should have an owner (i.e. should have OWNER_KEY set).
1241     // .META. and -ROOT- should return system user as owner, not null (see
1242     // MasterFileSystem.java:bootstrap()).
1243     return null;
1244   }
1245 }