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