/*   Copyright (c) 2015 Magnet Systems, Inc.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

package com.magnet.mmx.protocol;

import java.util.Hashtable;

/**
 * @hide
 * A convenient class for the optional MMXMessage mmx headers (mmxmeta data.)
 * All headers are optional.
 */
public class MmxHeaders extends Hashtable<String, Object> {
  private static final long serialVersionUID = 9047305151889919321L;
  /**
   * A special header used by MMX SDK to specify the sender with display name.
   */
  public final static String FROM = "From";
  /**
   * A special header used by MMX SDK to specify the recipient(s) with display
   * name(s).
   */
  public final static String TO = "To";

  /**
   * A default constructor.
   */
  public MmxHeaders() {
    super();
  }
  
  /**
   * A constructor with a default capacity.
   * @param capacity The initial capacity.
   */
  public MmxHeaders(int capacity) {
    super(capacity);
  }
  
  /**
   * A convenient method to set or remove a header with any JSONifiable value.
   * This is mainly used for mmxmeta stanza.
   * @param key A key name.
   * @param value Any JSONifiable object.
   * @return
   */
  public MmxHeaders setHeader(String key, Object value) {
    if (key == null)
      throw new IllegalArgumentException("The key cannot be null");
    if (value == null)
      remove(key);
    else
      put(key, value);
    return this;
  }
  
  /**
   * Get a header JSONifiable value with default.  This method is mainly used
   * with mmxmeta stanza.
   * @param key A key name.
   * @param defVal A default value to be returned if the key does not exist.
   * @return A header value or the default value.
   */
  public Object getHeader(String key, Object defVal) {
    if (key == null)
      throw new IllegalArgumentException("The key cannot be null");
    Object value;
    if ((value = this.get(key)) == null)
      return defVal;
    else
      return value;
  }
}

@@ -1007,24 +1007,54 @@
 splay name.%0A
+   * The value must be MMXid.%0A
    */%0A  publ
@@ -1189,16 +1189,44 @@
 name(s).
+  The value must be MMXid%5B%5D.
 %0A   */%0A 
@@ -1633,32 +1633,97 @@
  mmxmeta stanza.
+  If %3Ccode%3Evalue%3C/code%3E is null,%0A   * the header will be removed.
 %0A   * @param key
@@ -1775,16 +1775,25 @@
 e object
+, or null
 .%0A   * @
@@ -2578,10 +2578,580 @@
 ue;%0A  %7D%0A
+  %0A  /**%0A   * Set the TO header with the MMX ID's of recipients.  It is equivalent to%0A   * %7B@link #setHeader(String, Object)%7D with %7B@link #TO%7D.%0A   * @param xids The recipients' MMX ID's, or null%0A   * @return%0A   */%0A  public MmxHeaders setTo(MMXid%5B%5D xids) %7B%0A    return setHeader(TO, xids);%0A  %7D%0A  %0A  /**%0A   * Set the FROM header with the MMX ID of the sender.  It is equivalent to%0A   * %7B@link #setHeader(String, Object)%7D with %7B@link #FROM%7D.%0A   * @param xid The sender MMX ID.%0A   * @return%0A   */%0A  public MmxHeaders setFrom(MMXid xid) %7B%0A    return setHeader(FROM, xid);%0A  %7D%0A
 %7D%0A

Add type-safe methods to set the From and To headers.