/*******************************************************************************
 * 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 java.security.PublicKey;
import java.util.List;

import org.w3c.dom.Element;

/**
 * Parameters for validating an infobox.
 * 
 * This interface is used by MOA-ID to provide parameters to an
 * {link at.gv.egovernment.moa.id.auth.validator.InfoboxValidator
 * InfoboxValidator}.
 * 
 * @author Harald Bratko
 */
public interface InfoboxValidatorParams {
  
  /**
   * Returns a list of {@link at.gv.egovernment.moa.id.auth.data.InfoboxToken InfoboxToken}
   * objects. The first token in this list is the one to be validated. Each further token
   * maybe needed to validate this first token.
   * 
   * @return A list of {@link at.gv.egovernment.moa.id.auth.data.InfoboxToken InfoboxToken}
   * objects.
   */
  public List getInfoboxTokenList();
  
  /**
   * Returns the ID of the trust profile to be used for validating 
   * certificates. Maybe ignored by a validator, if no certificates 
   * has to be validated.
   * 
   * @return The ID of a trust profile.
   */
  public String getTrustProfileID();
  
  /**
   * Returns schema location URIs that may be needed by the
   * validator to parse infobox tokens.
   * Each entry in the list is a {@link Schema} specifying the location
   * of an XML schema. 
   *  
   * @return A list of {@link Schema} objects each of them specifying the
   *         location of an XML schema.
   */
  public List getSchemaLocations();
  
  /**
   * Returns the URL of the BKU.
   * Maybe needed by a validator.
   *  
   * @return The url of the BKU.
   */
  public String getBkuURL();
  
  /**
   * Returns the target parameter.
   * <code>null</code> in the case of a business service.
   * 
   * @return The target parameter.
   */
  public String getTarget();
  
  /**
   * Returns the register and number in the register parameter.
   * <code>null</code> in the case of not a business service.
   * 
   * @return The register and number in the register parameter.
   */
  public String getDomainIdentifier();
  
  /**
   * Returns <code>true</code> if the application is a business
   * service, otherwise <code>false</code>. This may be useful
   * for the validating application.
   * 
   * @return <code>True</code> if the application is a business
   * service, otherwise <code>false</code>
   */
  public boolean getBusinessApplication();
  
  /**
   * Returns the family name from the identity link. 
   * Maybe needed by a validator.
   * 
   * @return The family name from the identity link.
   */
  public String getFamilyName();
  
  /**
   * Returns the given name from the identity link. 
   * Maybe needed by a validator.
   * 
   * @return The given name from the identity link.
   */
  public String getGivenName();
  
  /**
   * The date of birth from the identity link.
   * The method returns the value of the <pr:DateOfBirth>
   * element from the identity link.
   * Maybe needed by a validator.
   * 
   * @return The date of birth from the identity link.
   */
  public String getDateOfBirth();
  
  /**
   * Returns he identification value from the identity
   * link. This may be the <code>Stammzahl</code>
   * in the case of a public application or the
   * <code>wbPK</code> in the case of a business
   * application. This parameter is only returned
   * if specified within the config file.
   * 
   * @return The identification value from the identity link.
   */
  public String getIdentificationValue();
  
  /**
   * Returns the type of the identification value 
   * from the identity link. This may be 
   * especially of interest for business
   * applications.
   * 
   * @return The type of the identification value 
   * from the identity link.
   */
  public String getIdentificationType();
  
  /**
   * Returns the public keys from the identity link.
   * Maybe needed by the application.
   * 
   * @return PublicKey[] The public keys from the
   *                     identity link.
   */
  public PublicKey[] getPublicKeys();
  
  /**
   * Returns the identity link. 
   * A validator may need other data from the identity link, than
   * family name, given name, date of birth and identification value.
   * The identity link element is only returned if specified within the 
   * config file.
   * 
   * @return The identity link.
   */
  public Element getIdentityLink();
  
  /**
   * Indicates whether source pins (<code>Stammzahl</code>en) should be hidden or not.
   * If an online application lying behind MOA-ID is not allowed to get source pins 
   * (<code>Stammzahl</code>en), any source pins within <code>SAML attributes</code>
   * returned by the validator must suppressed:<br>
   * If the parameter <code>getHideStammzahl</code> is <code>true</code>, then the validator 
   * <b>MUST</b> hide (replace by an empty string) any source pin (<code>Stammzahl</code>)
   * that may be included in a <code>SAML attribute</code> returned by the validator.
   * 
   * @return <code>true</code> if source pins (<code>Stammzahl</code>en) must be hidden,
   *         otherwise <code>false</code>.
   */
  public boolean getHideStammzahl();
  
  /**
   * Returns application specific parameters.
   * Each child element of this element contains
   * a validating application specific parameter. The  
   * element is passed as specified within the config 
   * file and its up to the implementing class to
   * parse and interprete its children. 
   * 
   * @return Application specific parameters.
   */
  public Element getApplicationSpecificParams();
  
}