package at.gv.egiz.pdfas.api.commons;

import at.gv.egiz.pdfas.api.PdfAs;
import at.gv.egiz.pdfas.api.sign.SignParameters;

/**
 * A dynamic signature profile. It is used to define a signature profile like the ones from pdf-as/config.properties at runtime.
 * After creation via {@link PdfAs} you can set properties via {@link #setPropertyRaw(String, String)} 
 * or {@link #setFieldValue(String, String)}.<br>
 * You have to call {@link #apply()} to use the profile. The identifying name (e.g. for {@link SignParameters#setSignatureProfileId(String)}
 * can be obtained via {@link #getName()}.<br>
 * Depending on the {@link DynamicSignatureLifetimeEnum} the profile can be alive and usable till you {@link #dispose()} it manually. 
 * 
 * @author exthex
 *
 */
public interface DynamicSignatureProfile {

   /**
    * Get the name of the dynamic signature profile. Equals the <b>SignatureProfileId</b>
    * @return
    */
   public abstract String getName();   

   /**
    * Set a field value for the profile. Use {@link #setPropertyRaw(String, String)} for setting any property.<br>
    * For example to set <code>sig_obj.MEIN_DYN_SIGNATURBLOCK.value.SIG_META</code> just use <code>SIG_META</code> as fieldName. 
    * @param fieldName the name of the field
    * @param value the value to set
    */
   public abstract void setFieldValue(String fieldName, String value);

   /**
    * Get a field value from the profile. See {@link #setFieldValue(String, String)}
    * @param fieldName
    * @return
    */
   public abstract String getFieldValue(String fieldName);
   
   /**
    * Set any property for the signature profile. 
    * Uses the same keys as the property file without the "prefix" for the profile.
    * For example to set <code>sig_obj.MEIN_DYN_SIGNATURBLOCK.key.SIG_META</code> use <code>key.SIG_META</code>
    * @param key property key
    * @param val property value
    */
   public void setPropertyRaw(String key, String val);

   /**
    * Get any property from the signature profile. See {@link #setPropertyRaw(String, String)} for details.
    * @param key
    * @return
    */
   public String getPropertyRaw(String key);      

   /**
    * Apply the signature profile. Call this after all properties are set and you want to use the profile. It is then added
    * to the globally available signature profiles. Depending on the lifetime model {@link DynamicSignatureLifetimeEnum} you
    * have to {@link #dispose()} it manually when not needed anymore.
    */
   public abstract void apply();

   /**
    * Disposes the signature profile from the global store. Call this for {@link DynamicSignatureLifetimeEnum#MANUAL} only. 
    */
   public abstract void dispose();
  
}