package at.gv.egovernment.moa.id.auth.data;

import org.w3c.dom.Element;

/**
 * Contains an infobox token included in an <code>InfoboxReadResponse</code>.
 * Depending on whether the token is extracted from an <code>XMLContent</code> or a
 * <code>Base64Content</code> it is either returned as DOM element
 * ({@link #getXMLToken()}) or base64 encoded string ({@link #getBase64Token()}).
 * 
 * @author Harald Bratko
 */
public interface InfoboxToken {
  
  /**
   * The key of the corresponding infobox.
   * This is the value of <code>Key</code> attribute of the <code>&lt;Pair&gt;</code> child
   * element in an <code>&lt;AssocArrayData&gt;</code> content of an InfoboxReadResponse.
   * Maybe <code>null</code> if the InfoboxReadResponse conatains <code>BinaryFileData</code>.
   * 
   * 
   * @return The key identifier of the corresponding infobox.
   */
  public String getKey();
  
  /**
   * Specifies if this token is the first token (e.g in an array of tokens) included in an 
   * <code>InfoboxReadResponse</code>. If <code>true</code> this token is the token to be 
   * validated by a corresponding 
   * {@link at.gv.egovernment.moa.id.auth.validator.InfoboxValidator InfoboxValidator}.
   * If <code>false</code> this token maybe needed to validate the primary token.
   *  
   * @return <code>True</code> if this token is the first token.
   */
  public boolean isPrimary();
  
  /**
   * Returns the infobox token.
   * Maybe <code>null</code> if the token is returned by method {@link #getBase64Token()}
   * as base64 encoded string.
   * <br>
   * Note that this token is <code><i><b>not</b></i></code> validated against the 
   * application specific schema (e.g. Mandates schema in the mandates context).
   * Thus the validating application <code><i><b>has to</b></i></code> validate the token
   * against the appropriate schema.
   * 
   * @return The infobox token. If <code>null</code> the token is returned by method
   *         {@link #getBase64Token()} as base64 encoded string. 
   */
  public Element getXMLToken();
  
  /**
   * Returns the infobox token.
   * Maybe <code>null</code> if the token is returned by method {@link #getXMLToken()}
   * as a DOM element.
   * <br>
   * Note, that the base64 encoded string actually may include more than one infobox
   * elements.
   * 
   * @return The infobox token. If <code>null</code> the token is returned by method
   *         {@link #getBase64Token()} as base64 encoded string. 
   */
  public String getBase64Token();

}