/**
 * 
 */
package at.gv.egiz.pdfas.api;

import java.util.List;

import at.gv.egiz.pdfas.api.analyze.AnalyzeParameters;
import at.gv.egiz.pdfas.api.analyze.AnalyzeResult;
import at.gv.egiz.pdfas.api.commons.SignatureProfile;
import at.gv.egiz.pdfas.api.exceptions.PdfAsException;
import at.gv.egiz.pdfas.api.sign.SignParameters;
import at.gv.egiz.pdfas.api.sign.SignResult;
import at.gv.egiz.pdfas.api.verify.VerifyAfterAnalysisParameters;
import at.gv.egiz.pdfas.api.verify.VerifyParameters;
import at.gv.egiz.pdfas.api.verify.VerifyResult;
import at.gv.egiz.pdfas.api.verify.VerifyResults;

/**
 * The PDF-AS API main interface.
 * 
 * <p>
 * Create an Object implementing this interface using the proper factory.
 * </p>
 * 
 * @author wprinz
 */
public interface PdfAs
{

  /**
   * Signs a PDF document using PDF-AS.
   * 
   * @param signParameters
   *          The sign parameters.
   * @return Returns the signed document plus additional information.
   * @throws PdfAsException
   *           Thrown, if an error occurs.
   * 
   * @see SignParameters
   * @see SignResult
   */
  public SignResult sign(SignParameters signParameters) throws PdfAsException;

  /**
   * Verifies a document with (potentially multiple) PDF-AS signatures.
   * 
   * @param verifyParameters
   *          The verify parameters.
   * @return Returns the verification results.
   * @throws PdfAsException
   *           Thrown, if an error occurs.
   * 
   * @see VerifyParameters
   * @see VerifyResults
   * @see VerifyResult
   */
  public VerifyResults verify(VerifyParameters verifyParameters) throws PdfAsException;

  /**
   * Analyzes a document for signatures and returns a verify-able list of such.
   * 
   * @param analyzeParameters
   *          The analyzation parameters.
   * @return Returns a list of verify-able signatures that were found in the
   *         document.
   * @throws PdfAsException
   *           Thrown on error.
   * 
   * @see AnalyzeParameters
   * @see AnalyzeResult
   * @see {@link #verify(AnalyzeResult)}
   */
  public AnalyzeResult analyze(AnalyzeParameters analyzeParameters) throws PdfAsException;

  /**
   * Verifies a list of signatures that have been analyzed previously.
   * 
   * @param verifyAfterAnalysisParameters The parameters.
   * 
   * @return Returns the verification results.
   * @throws PdfAsException
   *           Thrown on error.
   * 
   * @see AnalyzeResult
   * @see VerifyAfterAnalysisParameters
   * @see VerifyResults
   * @see VerifyResult
   * @see {@link #analyze(AnalyzeParameters)}
   */
  public VerifyResults verify(VerifyAfterAnalysisParameters verifyAfterAnalysisParameters) throws PdfAsException;

  /**
   * Reloads the configuration from the work directory.
   * 
   * @throws PdfAsException
   *           Thrown, if an error occurs.
   */
  public void reloadConfig() throws PdfAsException;

  /**
   * Returns the list of information objects about the profiles available in the
   * configuration.
   * 
   * <p>
   * Note: Currently the profile information consists of the profile Id and the
   * MOA Key Id only.
   * </p>
   * <p>
   * Note: In near future the profile management will be moved out of the config
   * file into an API class representation of the profiles which may render this
   * (and related) methods obsolete.
   * </p>
   * 
   * @return Returns the list of {@link SignatureProfile} objects with
   *         information about the profiles available in the configuration.
   * @throws PdfAsException
   *           Thrown on error.
   * 
   * @see SignatureProfile
   */
  public List getProfileInformation() throws PdfAsException;
}