/*******************************************************************************
 * Copyright 2014 Federal Chancellery Austria
 * MOA-ID has been developed in a cooperation between BRZ, the Federal
 * Chancellery Austria - ICT staff unit, and Graz University of Technology.
 * 
 * Licensed under the EUPL, Version 1.1 or - as soon they will be approved by
 * the European Commission - subsequent versions of the EUPL (the "Licence");
 * You may not use this work except in compliance with the Licence.
 * You may obtain a copy of the Licence at:
 * http://www.osor.eu/eupl/
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the Licence is distributed on an "AS IS" basis,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the Licence for the specific language governing permissions and
 * limitations under the Licence.
 * 
 * This product combines work with different licenses. See the "NOTICE" text
 * file for details on the various modules and licenses.
 * The "NOTICE" text file is part of the distribution. Any derivative works
 * that you distribute must include a readable copy of the "NOTICE" text file.
 ******************************************************************************/
/*
 * Copyright 2003 Federal Chancellery Austria
 * MOA-ID has been developed in a cooperation between BRZ, the Federal
 * Chancellery Austria - ICT staff unit, and Graz University of Technology.
 *
 * Licensed under the EUPL, Version 1.1 or - as soon they will be approved by
 * the European Commission - subsequent versions of the EUPL (the "Licence");
 * You may not use this work except in compliance with the Licence.
 * You may obtain a copy of the Licence at:
 * http://www.osor.eu/eupl/
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the Licence is distributed on an "AS IS" basis,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the Licence for the specific language governing permissions and
 * limitations under the Licence.
 *
 * This product combines work with different licenses. See the "NOTICE" text
 * file for details on the various modules and licenses.
 * The "NOTICE" text file is part of the distribution. Any derivative works
 * that you distribute must include a readable copy of the "NOTICE" text file.
 */


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();

}