Standard Evidence Interface

/*
 * Copyright 2005-2006,2011 Curam Software Ltd.
 * All rights reserved.
 * 
 * This software is the confidential and proprietary information
 * of Curam Software, Ltd. ("Confidential Information").  You 
 * shall not disclose such Confidential Information and shall use
 * it only in accordance with the terms of the license agreement 
 * you entered into with Curam Software.
 */
package curam.core.sl.infrastructure.impl;

import curam.core.sl.infrastructure.entity.struct
  .AttributedDateDetails;
import curam.core.sl.infrastructure.struct.EIEvidenceKey;
import curam.core.sl.infrastructure.struct.EIEvidenceKeyList;
import 
  curam.core.sl.infrastructure.struct.EIFieldsForListDisplayDtls;
import curam.core.sl.infrastructure.struct.ValidateMode;
import curam.core.struct.CaseKey;
import curam.util.exception.AppException;
import curam.util.exception.InformationalException;
import curam.util.type.Date;

/**
 * This interface is a key component of the Curam
 * Evidence Solution. Implementations hoping to manage evidence
 * via the Evidence Solution must ensure that the 
 * evidence entities contained within the solution implement the 
 * Evidence Interface. By doing this, the evidence is utilizing 
 * the Evidence Controller pattern whereby a lot of the common 
 * business functions for maintaining evidence are contained 
 * within the out-of-the-box evidence infrastructure.
 * 
 * This interface is the super interface that will be 
 * extended by other evidence interfaces that wish to provide 
 * custom functionality for that type of evidence. The methods 
 * defined on this evidence are common to any interface that 
 * extends it.
 */
public interface StandardEvidenceInterface {

  // ____________________________________________________________
  /**
   * Method for calculating case attribution dates. The 
   * calculation of evidence attribution is an integral part of a
   * evidence solution as it determines the period of 
   * time for which a piece of evidence is effective. The 
   * implementation of this function will contain the logic that 
   * derives the appropriate effective period for the evidence of
   * a particular type.
   * 
   * @param caseKey
   *          Contains a case identifier
   * @param evKey
   *          Contains the evidenceID / evidenceType pairing of 
   *          the evidence to be attributed
   * 
   * @return Case attribution details
   */
  AttributedDateDetails calcAttributionDatesForCase(
    CaseKey caseKey, EIEvidenceKey evKey) 
      throws AppException, InformationalException;

  // ____________________________________________________________
  /**
   * Retrieves a summary of evidence details which are used to 
   * populate the 'Details' column on the following evidence 
   * pages:
   *
   *  - All evidence workspace pages
   *  - Apply changes page
   *  - Apply user changes page
   *  - Approve page
   *  - Reject page
   * 
   * @param key
   *          Contains an evidenceID / evidenceType pairing
   * 
   * @return A summary of the evidence details to be displayed
   */
  EIFieldsForListDisplayDtls getDetailsForListDisplay(
    EIEvidenceKey key) 
      throws AppException, InformationalException;

  // ____________________________________________________________
  /**
   * Method to get the business end date for this evidence 
   * record.
   * 
   * @param key
   *          Contains an evidenceID / evidenceType pairing
   * 
   * @return The end date for this evidence
   */
  Date getEndDate(EIEvidenceKey evKey) throws AppException,
    InformationalException;

  // ____________________________________________________________
  /**
   * Method to get the business start date for this evidence 
   * record.
   * 
   * @param key
   *          Contains an evidenceID / evidenceType pairing
   * 
   * @return The start date for this evidence
   */
  Date getStartDate(EIEvidenceKey evKey) throws AppException,
    InformationalException;

  // ____________________________________________________________
  /**
   * Method for inserting case evidence.
   * 
   * @param dtls
   *          Custom evidence details to be inserted
   * @param parentKey
   *          Contains the evidence type of the evidence being 
   *          inserted
   * 
   * @return Contains the evidenceID / evidenceType of the 
   *         evidence inserted
   */
  EIEvidenceKey insertEvidence(
    Object dtls, EIEvidenceKey parentKey)
      throws AppException, InformationalException;

  // ____________________________________________________________
  /**
   * Method for inserting case evidence on modification. An 
   * insert on modification takes place when the record being 
   * modified is 'Active'.
   * 
   * @param dtls
   *          Evidence details to be inserted
   * @param origKey
   *          Contains the evidenceID / evidenceType pairing of  
   *          the evidence being modified
   * @param parentKey
   *          Contains the evidence type of the evidence to be 
   *          inserted
   * 
   * @return Contains the evidenceID / evidenceType of the 
   *         evidence inserted
   */
  EIEvidenceKey insertEvidenceOnModify(Object dtls, 
    EIEvidenceKey origKey, EIEvidenceKey parentKey) 
      throws AppException, InformationalException;

 // ____________________________________________________________
  /**
   * Method for modifying case evidence. This function is called
   * when 'In Edit' evidence is being modified in place.
   * 
   * @param key
   *          Contains the evidenceID / evidenceType pairing of
   *          the evidence to be modified
   * @param dtls
   *          Modified evidence details
   */
  void modifyEvidence(EIEvidenceKey key, Object dtls) 
    throws AppException, InformationalException;

  // ____________________________________________________________
  /**
   * Method for retrieving all child evidence for a specified 
   * parent
   * 
   * @param key
   *          Contains a parent evidenceID / evidenceType pairing
   * 
   * @return List of all child evidence (evidenceID / 
   *         evidenceType pairings) for the specified parent
   */
  EIEvidenceKeyList readAllByParentID(EIEvidenceKey key) 
    throws AppException, InformationalException;

  // ____________________________________________________________
  /**
   * Method for reading case evidence.
   * 
   * @param key
   *          Contains the evidenceID / evidenceType pairing of 
   *          the evidence to be read
   * 
   * @return Custom evidence details
   */
  Object readEvidence(EIEvidenceKey key) 
    throws AppException, InformationalException;

 // ____________________________________________________________
  /**
   * Method for retrieving the list of evidence to be used in
   * the validation procedure. This is based on the evidenceID /
   * evidenceType pairing passed into this function.
   *
   * If the input evidence key was that of parent evidence, then 
   * this function should return the parent and its associated 
   * 'Active' and 'In Edit' child evidence records, if they 
   * exist.
   * 
   * @param evKey
   *          Contains the evidenceID / evidenceType pairing of 
   *          the evidence being "acted upon".
   * 
   * @return List of evidenceID / evidenceType pairings to be 
   *         used in the validation procedure
   */
  EIEvidenceKeyList selectForValidation(EIEvidenceKey evKey)
    throws AppException, InformationalException;

  // ____________________________________________________________
  /**
   * Method for validating evidences based on the validate mode 
   * setting.
   * 
   * @param evKey
   *          The evidenceID / evidenceType pairing of the 
   *          evidence being "acted upon"
   * @param evKeyList
   *          The evidence hierarchy structure for the evKey 
   *          parameter. If the evKey identified the parent 
   *          evidence, the evKeyList may contain this parent and
   *          its relevant children for validation purposes
   * 
   * @param mode
   *          The validation mode (insert, modify, 
   *          validateChanges,applyChanges)
   */
  void validate(EIEvidenceKey evKey, EIEvidenceKeyList evKeyList,
    ValidateMode mode) 
      throws AppException, InformationalException;
}