TlvDataStructure.java

package de.persosim.simulator.tlv;

import java.util.Comparator;

/**
 * This interface defines basic functionalities any TLV data object with
 * constructed encoding or any sequence of TLV data objects must provide.
 * 
 * @author slutters
 * 
 */
public interface TlvDataStructure extends Iterable<TlvDataObject> {
	
	/**
	 * Returns the TLV data object at the specified path.
	 * The TLV data object is identified using its tag field.
	 * @param path the path of the TLV data object, including the objects tag itself, not including the starting object
	 * @param index the current position within the path
	 * @return the TLV data object at the specified path, null otherwise
	 */
	public TlvDataObject getTlvDataObject(TlvPath path, int index);
	
	/**
	 * Returns the TLV data object at the specified path.
	 * The TLV data object is identified using its tag field.
	 * @param path the path of the TLV data object, including the objects tag itself, not including the starting object
	 * @return the TLV data object at the specified path, null otherwise
	 */
	public TlvDataObject getTlvDataObject(TlvPath path);
	
	/**
	 * Returns the TLV data object identified by the provided tag identifier.
	 * @param tagIdentifier 
	 * @return the TLV data object identified by the provided tag, null otherwise
	 */
	public TlvDataObject getTlvDataObject(TlvTagIdentifier tagIdentifier);
	
	/**
	 * Convenience method to allow retrieving objects with a TlvTag directly.
	 * @see #getTlvDataObject(TlvTagIdentifier)
	 * @param tlvTag the tag used for identification
	 * @return the TLV data object identified by the provided tag, null otherwise
	 */
	public TlvDataObject getTlvDataObject(TlvTag tlvTag);
	
	/**
	 * Returns whether this data structure contains a TLV data object identified by the provided tag.
	 * @param tlvTag the tag used for identification
	 * @return whether this data structure contains a TLV data object identified by the provided tag
	 */
	public boolean containsTlvDataObject(TlvTag tagField);
	
	/*--------------------------------------------------------------------------------*/
	
	/**
	 * Adds the provided object at the specified path in this data structure if possible
	 * @param path the path at which the object is to be added
	 * @param tlvDataObject the object to be added
	 */
	public void addTlvDataObject(TlvPath path, TlvDataObject tlvDataObject);
	
	/**
	 * Adds the specified object to this data structure if possible
	 * <p>
	 * NOTE: callers MUST ensure that they do not construct circular references
	 * within the object structure. Also adding of the SAME object at different
	 * places in the object structure is not advisable (though not forbidden)
	 * but may lead to unexpected behavior when adding/removing elements.
	 * 
	 * @param tlvDataObject
	 *            the object to be added
	 */
	public void addTlvDataObject(TlvDataObject... tlvDataObject);
	
	/**
	 * Removes the object at the specified path if possible.
	 * @param path the path of the object to be removed including the object itself
	 */
	public void removeTlvDataObject(TlvPath path);
	
	/**
	 * Removes the specified object from this data structure if present.
	 * @param tagIdentifier the object to be removed
	 */
	public void removeTlvDataObject(TlvTagIdentifier tagIdentifier);
	
	/**
	 * Convenience method to allow removing objects with a matching TlvTag directly.
	 * @see #removeTlvDataObject(TlvTagIdentifier)
	 * @param tlvTag the tag used for identification
	 */
	public void removeTlvDataObject(TlvTag tlvTag);
	
	/**
	 * Sort the elements within this data structure according to the provided comparator
	 * @param comparator the comparator to be used for sorting
	 */
	public void sort(Comparator<TlvDataObject> comparator);
	
	/*--------------------------------------------------------------------------------*/
	
	/**
	 * Returns the number of elements contained in this data structure.
	 * @param recursive whether sub-elements are to be included
	 * @return the number of elements contained in this data structure
	 */
	public int getNoOfElements(boolean recursive);
	
	/**
	 * Returns the number of elements contained in this data structure.
	 * @return the number of elements contained in this data structure
	 */
	public int getNoOfElements();
	
}