/*******************************************************************************
 *  Copyright 2017-2018 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.dcm30_04.utils;

import java.io.Serializable;

/**
 * This interface needs to be implemented by all classes which implements the necessary functionality for the PairedCollection.
 * 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 IPairedCollection<T1, T2> extends ICollectionIterable<T2>, Serializable
{
	/**
	 * The implementation of this method returns iterator having data elements in sorted order.
	 * @return ICollectionIterator - collection of Data Elements in sorted order.
	 */
	public ICollectionIterator<T2> sortedIterator();

	/**
	 * The implementation of this method retrieves the object of type specified at the time of instantiation of this library.
	 * @param objT1 object specifying the key of PairedCollection 
	 * @return objT2 - object specifying the value corresponding to the key in the specified collection
	 */
	public T2 get(T1 objT1);

	/**
	 * The implementation of this method add a key value pair in the paired collection
	 * @param objT1 object specifying the key of PairedCollection 
	 * @param objT2 object specifying the value corresponding to the key in the specified collection
	 */
	public void put(T1 objT1, T2 objT2);

	/**
	 * The implementation of this method checks whether the specified key is present in the collection
	 * @param objT1 object specifying the key of PairedCollection .
	 * @return boolean - shows status as success or failure.
	 */
	public boolean contains(T1 objT1);

	/**
	 * The implementation of this method retrieves the size of the collection.
	 * @return size - returns the number of elements present in the collection.
	 */
	int size();

	/**
	 * The implementation of this method removes the values associated with the given key.
	 * @param objT1 - key whose mapping value is removed.
	 * @return - previous value associated with the key or null if no mapping for this key is found.
	 */
	public T2 remove(T1 objT1);

	/**
	 * The implementation of this method gets all the keys in the collection.
	 * @return T1[] - array of keys in the collection.
	 */
	public T1[] getKeys();
}
