/*******************************************************************************
 *  Copyright 2017 Centre for Development of Advanced Computing(C-DAC), Pune
 *  
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *  
 *    http://www.apache.org/licenses/LICENSE-2.0
 *  
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *******************************************************************************/
package cdac.medinfo.sdk.hl7282.utils;

import cdac.medinfo.sdk.hl7282.commoninterface.ICollectionIterable;
import cdac.medinfo.sdk.hl7282.commoninterface.ISingleCollection;


/**
 * This interface is a parameterized interface which specifies the contract
 * for the MultiValuedPairedCollection.  This template is generic so that any key value pairs 
 * can be used. The only condition for the object to be used as a key is to 
 * override hashCode() method to provide value based hashCode generation
 * so that all the objects containing same values should generate same hashCode.
 * @param <T1> - object to be used as a key in PairedCollection
 * @param <T2> - object to be used as a value in PairedCollection
 */
public interface IMultiValuedPairedCollection<T1, T2>  extends ICollectionIterable<T2>
{
	/**
	 * Return the object of type specified at the time of instantiation of this library.
	 * @param objT1 object specifying the key of MultiValuedPairedCollection 
	 * @return objT2 - object specifying the value corresponding to the key in
	 * the specified collection
	 */
	public ISingleCollection<T2> get(T1 objT1);

	/**
	 * Added key and value in the paired collection
	 * @param objT1 object specifying the key of MultiValuedPairedCollection 
	 * @param objT2 object specifying the value corresponding to the key in
	 * the specified collection
	 */
	public void put(T1 objT1, T2 objT2);

	/**
	 * Added key and collection of values repsective to that key in the paired collection
	 * @param objT1 object specifying the key of MultiValuedPairedCollection 
	 * @param objT2 object specifying the value corresponding to the key in
	 * the specified collection
	 */
	public void put(T1 objT1, ISingleCollection<T2> objT2);

	/**
	 * Implementation of this method provides a mechanism to remove a key value pair from collection
	 * @param objT1 This parameter specifies the key whose corresponding value to remove
	 * 
	 */
	public void remove(T1 objT1);
	
	/**
	 * Implementation of this method provides a mechanism to remove a specified value present for specified
	 * key and removes key to if no values present for that key. 
	 * @param objT1 This parameter specifies the key whose corresponding value to remove
	 * @param objT2 object specifying the value corresponding to the key in
	 * the specified collection
	 */
	public void remove(T1 objT1,T2 objT2);
	
	/**
	 * Check whether the specified key is present in the collection
	 * @param objT1 object specifying the key of PairedCollection
	 * @return boolean - true if key is present
	 */
	public boolean contains(T1 objT1);
	
	/**
	 * Retrieves All values present in the collection
	 * @return ISingleCollection<T2> list of T2 type values
	 */
	public ISingleCollection<T2> getAllValues();
}
