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   /**
387    * Check passed byte buffer, "tableName", is legal user-space table name.
388    * @return Returns passed <code>tableName</code> param
389    * @throws NullPointerException If passed <code>tableName</code> is null
390    * @throws IllegalArgumentException if passed a tableName
391    * that is made of other than 'word' characters or underscores: i.e.
392    * <code>[a-zA-Z_0-9].
393    */
394   public static byte [] isLegalTableName(final byte [] tableName) {
395     if (tableName == null || tableName.length <= 0) {
396       throw new IllegalArgumentException("Name is null or empty");
397     }
398     if (tableName[0] == '.' || tableName[0] == '-') {
399       throw new IllegalArgumentException("Illegal first character <" + tableName[0] +
400           "> at 0. User-space table names can only start with 'word " +
401           "characters': i.e. [a-zA-Z_0-9]: " + Bytes.toString(tableName));
402     }
403     for (int i = 0; i < tableName.length; i++) {
404       if (Character.isLetterOrDigit(tableName[i]) || tableName[i] == '_' || 
405     		  tableName[i] == '-' || tableName[i] == '.') {
406         continue;
407       }
408       throw new IllegalArgumentException("Illegal character <" + tableName[i] +
409         "> at " + i + ". User-space table names can only contain " +
410         "'word characters': i.e. [a-zA-Z_0-9-.]: " + Bytes.toString(tableName));
411     }
412     return tableName;
413   }
414 
415   /**
416    * Getter for accessing the metadata associated with the key
417    *  
418    * @param key The key.
419    * @return The value.
420    * @see #values
421    */
422   public byte[] getValue(byte[] key) {
423     return getValue(new ImmutableBytesWritable(key));
424   }
425 
426   private byte[] getValue(final ImmutableBytesWritable key) {
427     ImmutableBytesWritable ibw = values.get(key);
428     if (ibw == null)
429       return null;
430     return ibw.get();
431   }
432 
433   /**
434    * Getter for accessing the metadata associated with the key
435    *  
436    * @param key The key.
437    * @return The value.
438    * @see #values
439    */
440   public String getValue(String key) {
441     byte[] value = getValue(Bytes.toBytes(key));
442     if (value == null)
443       return null;
444     return Bytes.toString(value);
445   }
446 
447   /**
448    * Getter for fetching an unmodifiable {@link #values} map.
449    *  
450    * @return unmodifiable map {@link #values}.
451    * @see #values
452    */
453   public Map<ImmutableBytesWritable,ImmutableBytesWritable> getValues() {
454     // shallow pointer copy 
455     return Collections.unmodifiableMap(values);
456   }
457 
458   /**
459    * Setter for storing metadata as a (key, value) pair in {@link #values} map
460    *  
461    * @param key The key.
462    * @param value The value.
463    * @see #values
464    */
465   public void setValue(byte[] key, byte[] value) {
466     setValue(new ImmutableBytesWritable(key), value);
467   }
468 
469   /*
470    * @param key The key.
471    * @param value The value.
472    */
473   private void setValue(final ImmutableBytesWritable key,
474       final byte[] value) {
475     values.put(key, new ImmutableBytesWritable(value));
476   }
477 
478   /*
479    * @param key The key.
480    * @param value The value.
481    */
482   private void setValue(final ImmutableBytesWritable key,
483       final ImmutableBytesWritable value) {
484     values.put(key, value);
485   }
486 
487   /**
488    * Setter for storing metadata as a (key, value) pair in {@link #values} map
489    *  
490    * @param key The key.
491    * @param value The value.
492    * @see #values
493    */
494   public void setValue(String key, String value) {
495     if (value == null) {
496       remove(Bytes.toBytes(key));
497     } else {
498       setValue(Bytes.toBytes(key), Bytes.toBytes(value));
499     }
500   }
501 
502   /**
503    * Remove metadata represented by the key from the {@link #values} map
504    * 
505    * @param key Key whose key and value we're to remove from HTableDescriptor
506    * parameters.
507    */
508   public void remove(final byte [] key) {
509     values.remove(new ImmutableBytesWritable(key));
510   }
511   
512   /**
513    * Remove metadata represented by the key from the {@link #values} map
514    * 
515    * @param key Key whose key and value we're to remove from HTableDescriptor
516    * parameters.
517    */
518   public void remove(final String key) {
519     remove(Bytes.toBytes(key));
520   }
521 
522   /**
523    * Check if the readOnly flag of the table is set. If the readOnly flag is 
524    * set then the contents of the table can only be read from but not modified.
525    * 
526    * @return true if all columns in the table should be read only
527    */
528   public boolean isReadOnly() {
529     return isSomething(READONLY_KEY, DEFAULT_READONLY);
530   }
531 
532   /**
533    * Setting the table as read only sets all the columns in the table as read
534    * only. By default all tables are modifiable, but if the readOnly flag is 
535    * set to true then the contents of the table can only be read but not modified.
536    *  
537    * @param readOnly True if all of the columns in the table should be read
538    * only.
539    */
540   public void setReadOnly(final boolean readOnly) {
541     setValue(READONLY_KEY, readOnly? TRUE: FALSE);
542   }
543 
544   /**
545    * Check if deferred log edits are enabled on the table.  
546    * 
547    * @return true if that deferred log flush is enabled on the table
548    * 
549    * @see #setDeferredLogFlush(boolean)
550    */
551   public synchronized boolean isDeferredLogFlush() {
552     if(this.isDeferredLog == null) {
553       this.isDeferredLog =
554           isSomething(DEFERRED_LOG_FLUSH_KEY, DEFAULT_DEFERRED_LOG_FLUSH);
555     }
556     return this.isDeferredLog;
557   }
558 
559   /**
560    * This is used to defer the log edits syncing to the file system. Everytime 
561    * an edit is sent to the server it is first sync'd to the file system by the 
562    * log writer. This sync is an expensive operation and thus can be deferred so 
563    * that the edits are kept in memory for a specified period of time as represented
564    * by <code> hbase.regionserver.optionallogflushinterval </code> and not flushed
565    * for every edit.
566    * <p>
567    * NOTE:- This option might result in data loss if the region server crashes
568    * before these deferred edits in memory are flushed onto the filesystem. 
569    * </p>
570    * 
571    * @param isDeferredLogFlush
572    */
573   public void setDeferredLogFlush(final boolean isDeferredLogFlush) {
574     setValue(DEFERRED_LOG_FLUSH_KEY, isDeferredLogFlush? TRUE: FALSE);
575     this.isDeferredLog = isDeferredLogFlush;
576   }
577 
578   /**
579    * Get the name of the table as a byte array.
580    * 
581    * @return name of table 
582    */
583   public byte [] getName() {
584     return name;
585   }
586 
587   /**
588    * Get the name of the table as a String
589    * 
590    * @return name of table as a String 
591    */
592   public String getNameAsString() {
593     return this.nameAsString;
594   }
595   
596   /**
597    * This get the class associated with the region split policy which 
598    * determines when a region split should occur.  The class used by
599    * default is {@link org.apache.hadoop.hbase.regionserver.ConstantSizeRegionSplitPolicy}
600    * which split the region base on a constant {@link #getMaxFileSize()}
601    * 
602    * @return the class name of the region split policy for this table.
603    * If this returns null, the default constant size based split policy
604    * is used.
605    */
606    public String getRegionSplitPolicyClassName() {
607     return getValue(SPLIT_POLICY);
608   }
609 
610   /**
611    * Set the name of the table. 
612    * 
613    * @param name name of table 
614    */
615   public void setName(byte[] name) {
616     this.name = name;
617     this.nameAsString = Bytes.toString(this.name);
618     setMetaFlags(this.name);
619   }
620 
621   /** 
622    * Returns the maximum size upto which a region can grow to after which a region
623    * split is triggered. The region size is represented by the size of the biggest
624    * store file in that region.
625    *
626    * @return max hregion size for table, -1 if not set.
627    *
628    * @see #setMaxFileSize(long)
629    */
630   public long getMaxFileSize() {
631     byte [] value = getValue(MAX_FILESIZE_KEY);
632     if (value != null) {
633       return Long.parseLong(Bytes.toString(value));
634     }
635     return -1;
636   }
637 
638   /**
639    * Sets the maximum size upto which a region can grow to after which a region
640    * split is triggered. The region size is represented by the size of the biggest 
641    * store file in that region, i.e. If the biggest store file grows beyond the 
642    * maxFileSize, then the region split is triggered. This defaults to a value of 
643    * 256 MB.
644    * <p>
645    * This is not an absolute value and might vary. Assume that a single row exceeds 
646    * the maxFileSize then the storeFileSize will be greater than maxFileSize since
647    * a single row cannot be split across multiple regions 
648    * </p>
649    * 
650    * @param maxFileSize The maximum file size that a store file can grow to
651    * before a split is triggered.
652    */
653   public void setMaxFileSize(long maxFileSize) {
654     setValue(MAX_FILESIZE_KEY, Bytes.toBytes(Long.toString(maxFileSize)));
655   }
656 
657   /**
658    * Returns the size of the memstore after which a flush to filesystem is triggered.
659    *
660    * @return memory cache flush size for each hregion, -1 if not set.
661    *
662    * @see #setMemStoreFlushSize(long)
663    */
664   public long getMemStoreFlushSize() {
665     byte [] value = getValue(MEMSTORE_FLUSHSIZE_KEY);
666     if (value != null) {
667       return Long.parseLong(Bytes.toString(value));
668     }
669     return -1;
670   }
671 
672   /**
673    * Represents the maximum size of the memstore after which the contents of the 
674    * memstore are flushed to the filesystem. This defaults to a size of 64 MB.
675    * 
676    * @param memstoreFlushSize memory cache flush size for each hregion
677    */
678   public void setMemStoreFlushSize(long memstoreFlushSize) {
679     setValue(MEMSTORE_FLUSHSIZE_KEY,
680       Bytes.toBytes(Long.toString(memstoreFlushSize)));
681   }
682 
683   /**
684    * Adds a column family.
685    * @param family HColumnDescriptor of family to add.
686    */
687   public void addFamily(final HColumnDescriptor family) {
688     if (family.getName() == null || family.getName().length <= 0) {
689       throw new NullPointerException("Family name cannot be null or empty");
690     }
691     this.families.put(family.getName(), family);
692   }
693 
694   /**
695    * Checks to see if this table contains the given column family
696    * @param familyName Family name or column name.
697    * @return true if the table contains the specified family name
698    */
699   public boolean hasFamily(final byte [] familyName) {
700     return families.containsKey(familyName);
701   }
702 
703   /**
704    * @return Name of this table and then a map of all of the column family
705    * descriptors.
706    * @see #getNameAsString()
707    */
708   @Override
709   public String toString() {
710     StringBuilder s = new StringBuilder();
711     s.append('\'').append(Bytes.toString(name)).append('\'');
712     s.append(getValues(true));
713     for (HColumnDescriptor f : families.values()) {
714       s.append(", ").append(f);
715     }
716     return s.toString();
717   }
718 
719   /**
720    * @return Name of this table and then a map of all of the column family
721    * descriptors (with only the non-default column family attributes)
722    */
723   public String toStringCustomizedValues() {
724     StringBuilder s = new StringBuilder();
725     s.append('\'').append(Bytes.toString(name)).append('\'');
726     s.append(getValues(false));
727     for(HColumnDescriptor hcd : families.values()) {
728       s.append(", ").append(hcd.toStringCustomizedValues());
729     }
730     return s.toString();
731   }
732 
733   private StringBuilder getValues(boolean printDefaults) {
734     StringBuilder s = new StringBuilder();
735 
736     // step 1: set partitioning and pruning
737     Set<ImmutableBytesWritable> reservedKeys = new TreeSet<ImmutableBytesWritable>();
738     Set<ImmutableBytesWritable> configKeys = new TreeSet<ImmutableBytesWritable>();
739     for (ImmutableBytesWritable k : values.keySet()) {
740       if (k == null || k.get() == null) continue;
741       String key = Bytes.toString(k.get());
742       // in this section, print out reserved keywords + coprocessor info
743       if (!RESERVED_KEYWORDS.contains(k) && !key.startsWith("coprocessor$")) {
744         configKeys.add(k);        
745         continue;
746       }
747       // only print out IS_ROOT/IS_META if true
748       String value = Bytes.toString(values.get(k).get());
749       if (key.equalsIgnoreCase(IS_ROOT) || key.equalsIgnoreCase(IS_META)) {
750         // Skip. Don't bother printing out read-only values if false.
751         if (value.toLowerCase().equals(Boolean.FALSE.toString())) {
752           continue;
753         }
754       }
755 
756       // see if a reserved key is a default value. may not want to print it out
757       if (printDefaults
758           || !DEFAULT_VALUES.containsKey(key)
759           || !DEFAULT_VALUES.get(key).equalsIgnoreCase(value)) {
760         reservedKeys.add(k);
761       }
762     }
763 
764 
765 
766     // early exit optimization
767     if (reservedKeys.isEmpty() && configKeys.isEmpty()) return s;
768 
769     // step 2: printing
770     s.append(", {METHOD => 'table_att'");
771 
772     // print all reserved keys first
773     for (ImmutableBytesWritable k : reservedKeys) {
774       String key = Bytes.toString(k.get());
775       String value = Bytes.toString(values.get(k).get());
776 
777       s.append(", ");
778       s.append(key);
779       s.append(" => ");
780       s.append('\'').append(value).append('\'');
781     }
782     if (!configKeys.isEmpty()) {
783       // print all non-reserved, advanced config keys as a separate subset
784       s.append(", ");
785       s.append(HConstants.CONFIG).append(" => ");
786       s.append("{");
787       boolean printComma = false;
788       for (ImmutableBytesWritable k : configKeys) {
789         String key = Bytes.toString(k.get());
790         String value = Bytes.toString(values.get(k).get());
791         if (printComma) s.append(", ");
792         printComma = true;
793         s.append('\'').append(key).append('\'');
794         s.append(" => ");
795         s.append('\'').append(value).append('\'');
796       }
797       s.append("}");
798     }
799 
800     s.append('}'); // end METHOD
801     return s;
802   }
803                 
804   public static Map<String, String> getDefaultValues() {
805     return Collections.unmodifiableMap(DEFAULT_VALUES);
806   }
807 
808   /**
809    * Compare the contents of the descriptor with another one passed as a parameter. 
810    * Checks if the obj passed is an instance of HTableDescriptor, if yes then the
811    * contents of the descriptors are compared.
812    * 
813    * @return true if the contents of the the two descriptors exactly match
814    * 
815    * @see java.lang.Object#equals(java.lang.Object)
816    */
817   @Override
818   public boolean equals(Object obj) {
819     if (this == obj) {
820       return true;
821     }
822     if (obj == null) {
823       return false;
824     }
825     if (!(obj instanceof HTableDescriptor)) {
826       return false;
827     }
828     return compareTo((HTableDescriptor)obj) == 0;
829   }
830 
831   /**
832    * @see java.lang.Object#hashCode()
833    */
834   @Override
835   public int hashCode() {
836     int result = Bytes.hashCode(this.name);
837     result ^= Byte.valueOf(TABLE_DESCRIPTOR_VERSION).hashCode();
838     if (this.families != null && this.families.size() > 0) {
839       for (HColumnDescriptor e: this.families.values()) {
840         result ^= e.hashCode();
841       }
842     }
843     result ^= values.hashCode();
844     return result;
845   }
846 
847   // Writable
848   /**
849    * <em> INTERNAL </em> This method is a part of {@link WritableComparable} interface 
850    * and is used for de-serialization of the HTableDescriptor over RPC
851    */
852   @Override
853   public void readFields(DataInput in) throws IOException {
854     int version = in.readInt();
855     if (version < 3)
856       throw new IOException("versions < 3 are not supported (and never existed!?)");
857     // version 3+
858     name = Bytes.readByteArray(in);
859     nameAsString = Bytes.toString(this.name);
860     setRootRegion(in.readBoolean());
861     setMetaRegion(in.readBoolean());
862     values.clear();
863     int numVals = in.readInt();
864     for (int i = 0; i < numVals; i++) {
865       ImmutableBytesWritable key = new ImmutableBytesWritable();
866       ImmutableBytesWritable value = new ImmutableBytesWritable();
867       key.readFields(in);
868       value.readFields(in);
869       values.put(key, value);
870     }
871     families.clear();
872     int numFamilies = in.readInt();
873     for (int i = 0; i < numFamilies; i++) {
874       HColumnDescriptor c = new HColumnDescriptor();
875       c.readFields(in);
876       families.put(c.getName(), c);
877     }
878     if (version < 4) {
879       return;
880     }
881   }
882 
883   /**
884    * <em> INTERNAL </em> This method is a part of {@link WritableComparable} interface 
885    * and is used for serialization of the HTableDescriptor over RPC
886    */
887   @Override
888   public void write(DataOutput out) throws IOException {
889 	out.writeInt(TABLE_DESCRIPTOR_VERSION);
890     Bytes.writeByteArray(out, name);
891     out.writeBoolean(isRootRegion());
892     out.writeBoolean(isMetaRegion());
893     out.writeInt(values.size());
894     for (Map.Entry<ImmutableBytesWritable, ImmutableBytesWritable> e:
895         values.entrySet()) {
896       e.getKey().write(out);
897       e.getValue().write(out);
898     }
899     out.writeInt(families.size());
900     for(Iterator<HColumnDescriptor> it = families.values().iterator();
901         it.hasNext(); ) {
902       HColumnDescriptor family = it.next();
903       family.write(out);
904     }
905   }
906 
907   // Comparable
908 
909   /**
910    * Compares the descriptor with another descriptor which is passed as a parameter.
911    * This compares the content of the two descriptors and not the reference.
912    * 
913    * @return 0 if the contents of the descriptors are exactly matching, 
914    * 		 1 if there is a mismatch in the contents 
915    */
916   @Override
917   public int compareTo(final HTableDescriptor other) {
918     int result = Bytes.compareTo(this.name, other.name);
919     if (result == 0) {
920       result = families.size() - other.families.size();
921     }
922     if (result == 0 && families.size() != other.families.size()) {
923       result = Integer.valueOf(families.size()).compareTo(
924           Integer.valueOf(other.families.size()));
925     }
926     if (result == 0) {
927       for (Iterator<HColumnDescriptor> it = families.values().iterator(),
928           it2 = other.families.values().iterator(); it.hasNext(); ) {
929         result = it.next().compareTo(it2.next());
930         if (result != 0) {
931           break;
932         }
933       }
934     }
935     if (result == 0) {
936       // punt on comparison for ordering, just calculate difference
937       result = this.values.hashCode() - other.values.hashCode();
938       if (result < 0)
939         result = -1;
940       else if (result > 0)
941         result = 1;
942     }
943     return result;
944   }
945 
946   /**
947    * Returns an unmodifiable collection of all the {@link HColumnDescriptor} 
948    * of all the column families of the table.
949    *  
950    * @return Immutable collection of {@link HColumnDescriptor} of all the
951    * column families. 
952    */
953   public Collection<HColumnDescriptor> getFamilies() {
954     return Collections.unmodifiableCollection(this.families.values());
955   }
956 
957   /**
958    * Returns all the column family names of the current table. The map of 
959    * HTableDescriptor contains mapping of family name to HColumnDescriptors. 
960    * This returns all the keys of the family map which represents the column 
961    * family names of the table. 
962    * 
963    * @return Immutable sorted set of the keys of the families.
964    */
965   public Set<byte[]> getFamiliesKeys() {
966     return Collections.unmodifiableSet(this.families.keySet());
967   }
968 
969   /** 
970    * Returns an array all the {@link HColumnDescriptor} of the column families 
971    * of the table.
972    *  
973    * @return Array of all the HColumnDescriptors of the current table 
974    * 
975    * @see #getFamilies()
976    */
977   public HColumnDescriptor[] getColumnFamilies() {
978     return getFamilies().toArray(new HColumnDescriptor[0]);
979   }
980   
981 
982   /**
983    * Returns the HColumnDescriptor for a specific column family with name as 
984    * specified by the parameter column.
985    * 
986    * @param column Column family name 
987    * @return Column descriptor for the passed family name or the family on
988    * passed in column.
989    */
990   public HColumnDescriptor getFamily(final byte [] column) {
991     return this.families.get(column);
992   }
993   
994 
995   /**
996    * Removes the HColumnDescriptor with name specified by the parameter column 
997    * from the table descriptor
998    * 
999    * @param column Name of the column family to be removed.
1000    * @return Column descriptor for the passed family name or the family on
1001    * passed in column.
1002    */
1003   public HColumnDescriptor removeFamily(final byte [] column) {
1004     return this.families.remove(column);
1005   }
1006   
1007 
1008   /**
1009    * Add a table coprocessor to this table. The coprocessor
1010    * type must be {@link org.apache.hadoop.hbase.coprocessor.RegionObserver}
1011    * or Endpoint.
1012    * It won't check if the class can be loaded or not.
1013    * Whether a coprocessor is loadable or not will be determined when
1014    * a region is opened.
1015    * @param className Full class name.
1016    * @throws IOException
1017    */
1018   public void addCoprocessor(String className) throws IOException {
1019     addCoprocessor(className, null, Coprocessor.PRIORITY_USER, null);
1020   }
1021 
1022   
1023   /**
1024    * Add a table coprocessor to this table. The coprocessor
1025    * type must be {@link org.apache.hadoop.hbase.coprocessor.RegionObserver}
1026    * or Endpoint.
1027    * It won't check if the class can be loaded or not.
1028    * Whether a coprocessor is loadable or not will be determined when
1029    * a region is opened.
1030    * @param jarFilePath Path of the jar file. If it's null, the class will be
1031    * loaded from default classloader.
1032    * @param className Full class name.
1033    * @param priority Priority
1034    * @param kvs Arbitrary key-value parameter pairs passed into the coprocessor.
1035    * @throws IOException
1036    */
1037   public void addCoprocessor(String className, Path jarFilePath,
1038                              int priority, final Map<String, String> kvs)
1039   throws IOException {
1040     if (hasCoprocessor(className)) {
1041       throw new IOException("Coprocessor " + className + " already exists.");
1042     }
1043     // validate parameter kvs
1044     StringBuilder kvString = new StringBuilder();
1045     if (kvs != null) {
1046       for (Map.Entry<String, String> e: kvs.entrySet()) {
1047         if (!e.getKey().matches(HConstants.CP_HTD_ATTR_VALUE_PARAM_KEY_PATTERN)) {
1048           throw new IOException("Illegal parameter key = " + e.getKey());
1049         }
1050         if (!e.getValue().matches(HConstants.CP_HTD_ATTR_VALUE_PARAM_VALUE_PATTERN)) {
1051           throw new IOException("Illegal parameter (" + e.getKey() +
1052               ") value = " + e.getValue());
1053         }
1054         if (kvString.length() != 0) {
1055           kvString.append(',');
1056         }
1057         kvString.append(e.getKey());
1058         kvString.append('=');
1059         kvString.append(e.getValue());
1060       }
1061     }
1062 
1063     // generate a coprocessor key
1064     int maxCoprocessorNumber = 0;
1065     Matcher keyMatcher;
1066     for (Map.Entry<ImmutableBytesWritable, ImmutableBytesWritable> e:
1067         this.values.entrySet()) {
1068       keyMatcher =
1069           HConstants.CP_HTD_ATTR_KEY_PATTERN.matcher(
1070               Bytes.toString(e.getKey().get()));
1071       if (!keyMatcher.matches()) {
1072         continue;
1073       }
1074       maxCoprocessorNumber = Math.max(Integer.parseInt(keyMatcher.group(1)),
1075           maxCoprocessorNumber);
1076     }
1077     maxCoprocessorNumber++;
1078 
1079     String key = "coprocessor$" + Integer.toString(maxCoprocessorNumber);
1080     String value = ((jarFilePath == null)? "" : jarFilePath.toString()) +
1081         "|" + className + "|" + Integer.toString(priority) + "|" +
1082         kvString.toString();
1083     setValue(key, value);
1084   }
1085 
1086 
1087   /**
1088    * Check if the table has an attached co-processor represented by the name className
1089    *
1090    * @param className - Class name of the co-processor
1091    * @return true of the table has a co-processor className
1092    */
1093   public boolean hasCoprocessor(String className) {
1094     Matcher keyMatcher;
1095     Matcher valueMatcher;
1096     for (Map.Entry<ImmutableBytesWritable, ImmutableBytesWritable> e:
1097         this.values.entrySet()) {
1098       keyMatcher =
1099           HConstants.CP_HTD_ATTR_KEY_PATTERN.matcher(
1100               Bytes.toString(e.getKey().get()));
1101       if (!keyMatcher.matches()) {
1102         continue;
1103       }
1104       valueMatcher =
1105         HConstants.CP_HTD_ATTR_VALUE_PATTERN.matcher(
1106             Bytes.toString(e.getValue().get()));
1107       if (!valueMatcher.matches()) {
1108         continue;
1109       }
1110       // get className and compare
1111       String clazz = valueMatcher.group(2).trim(); // classname is the 2nd field
1112       if (clazz.equals(className.trim())) {
1113         return true;
1114       }
1115     }
1116     return false;
1117   }
1118 
1119   /**
1120    * Return the list of attached co-processor represented by their name className
1121    *
1122    * @return The list of co-processors classNames
1123    */
1124   public List<String> getCoprocessors() {
1125     List<String> result = new ArrayList<String>();
1126     Matcher keyMatcher;
1127     Matcher valueMatcher;
1128     for (Map.Entry<ImmutableBytesWritable, ImmutableBytesWritable> e : this.values.entrySet()) {
1129       keyMatcher = HConstants.CP_HTD_ATTR_KEY_PATTERN.matcher(Bytes.toString(e.getKey().get()));
1130       if (!keyMatcher.matches()) {
1131         continue;
1132       }
1133       valueMatcher = HConstants.CP_HTD_ATTR_VALUE_PATTERN.matcher(Bytes
1134           .toString(e.getValue().get()));
1135       if (!valueMatcher.matches()) {
1136         continue;
1137       }
1138       result.add(valueMatcher.group(2).trim()); // classname is the 2nd field
1139     }
1140     return result;
1141   }
1142 
1143   /**
1144    * Remove a coprocessor from those set on the table
1145    * @param className Class name of the co-processor
1146    */
1147   public void removeCoprocessor(String className) {
1148     ImmutableBytesWritable match = null;
1149     Matcher keyMatcher;
1150     Matcher valueMatcher;
1151     for (Map.Entry<ImmutableBytesWritable, ImmutableBytesWritable> e : this.values
1152         .entrySet()) {
1153       keyMatcher = HConstants.CP_HTD_ATTR_KEY_PATTERN.matcher(Bytes.toString(e
1154           .getKey().get()));
1155       if (!keyMatcher.matches()) {
1156         continue;
1157       }
1158       valueMatcher = HConstants.CP_HTD_ATTR_VALUE_PATTERN.matcher(Bytes
1159           .toString(e.getValue().get()));
1160       if (!valueMatcher.matches()) {
1161         continue;
1162       }
1163       // get className and compare
1164       String clazz = valueMatcher.group(2).trim(); // classname is the 2nd field
1165       // remove the CP if it is present
1166       if (clazz.equals(className.trim())) {
1167         match = e.getKey();
1168         break;
1169       }
1170     }
1171     // if we found a match, remove it
1172     if (match != null)
1173       this.values.remove(match);
1174   }
1175   
1176   /**
1177    * Returns the {@link Path} object representing the table directory under 
1178    * path rootdir 
1179    * 
1180    * @param rootdir qualified path of HBase root directory
1181    * @param tableName name of table
1182    * @return {@link Path} for table
1183    */
1184   public static Path getTableDir(Path rootdir, final byte [] tableName) {
1185     return new Path(rootdir, Bytes.toString(tableName));
1186   }
1187 
1188   /** Table descriptor for <core>-ROOT-</code> catalog table */
1189   public static final HTableDescriptor ROOT_TABLEDESC = new HTableDescriptor(
1190       HConstants.ROOT_TABLE_NAME,
1191       new HColumnDescriptor[] {
1192           new HColumnDescriptor(HConstants.CATALOG_FAMILY)
1193               // Ten is arbitrary number.  Keep versions to help debugging.
1194               .setMaxVersions(10)
1195               .setInMemory(true)
1196               .setBlocksize(8 * 1024)
1197               .setTimeToLive(HConstants.FOREVER)
1198               .setScope(HConstants.REPLICATION_SCOPE_LOCAL)
1199       });
1200 
1201   /** Table descriptor for <code>.META.</code> catalog table */
1202   public static final HTableDescriptor META_TABLEDESC = new HTableDescriptor(
1203       HConstants.META_TABLE_NAME, new HColumnDescriptor[] {
1204           new HColumnDescriptor(HConstants.CATALOG_FAMILY)
1205               // Ten is arbitrary number.  Keep versions to help debugging.
1206               .setMaxVersions(10)
1207               .setInMemory(true)
1208               .setBlocksize(8 * 1024)
1209               .setScope(HConstants.REPLICATION_SCOPE_LOCAL)
1210       });
1211 
1212   @Deprecated
1213   public void setOwner(User owner) {
1214     setOwnerString(owner != null ? owner.getShortName() : null);
1215   }
1216 
1217   // used by admin.rb:alter(table_name,*args) to update owner.
1218   @Deprecated
1219   public void setOwnerString(String ownerString) {
1220     if (ownerString != null) {
1221       setValue(OWNER_KEY, Bytes.toBytes(ownerString));
1222     } else {
1223       values.remove(OWNER_KEY);
1224     }
1225   }
1226 
1227   @Deprecated
1228   public String getOwnerString() {
1229     if (getValue(OWNER_KEY) != null) {
1230       return Bytes.toString(getValue(OWNER_KEY));
1231     }
1232     // Note that every table should have an owner (i.e. should have OWNER_KEY set).
1233     // .META. and -ROOT- should return system user as owner, not null (see
1234     // MasterFileSystem.java:bootstrap()).
1235     return null;
1236   }
1237 }