/* *******************************************************************
 * Copyright (c) 1999-2001 Xerox Corporation, 
 *               2002 Palo Alto Research Center, Incorporated (PARC).
 * All rights reserved. 
 * This program and the accompanying materials are made available 
 * under the terms of the Common Public License v1.0 
 * which accompanies this distribution and is available at 
 * http://www.eclipse.org/legal/cpl-v10.html 
 *  
 * Contributors: 
 *     Xerox/PARC     initial implementation 
 * ******************************************************************/

package org.aspectj.bridge;

import java.util.List;

/**
 * Hold and query a collection of messages.
 */
public interface IMessageHolder
	extends IMessageHandler { // XXX do not extend - mix instead
    // XXX go to LT EQ GT GE LE rather than simple orGreater
	/** value for orGreater parameter */
	public static final boolean ORGREATER = true;

	/** value for orGreater parameter */
	public static final boolean EQUAL = false;

	/** 
	 * Tell whether this holder has any message of this kind 
	 * (optionally or greater).
	 * @param kind the IMessage.Kind to check for - accept any if null
	 * @param orGreater if true, also any greater than the target kind
	 *         as determined by IMessage.Kind.COMPARATOR 
	 * @return true if this holder has any message of this kind,
	 *           or if orGreater and any message has a greater kind,
	 *           as determined by IMessage.Kind.COMPARATOR
	 */
	boolean hasAnyMessage(IMessage.Kind kind, boolean orGreater);

	/**
	 * Count the messages currently held by this holder.
	 * Pass null to get all kinds.
	 * @param kind the IMessage.Kind expected, or null for all messages
	 * @param orGreater if true, also any greater than the target kind
	 *         as determined by IMessage.Kind.COMPARATOR 
	 * @return number of IMessage held (now) by this holder
	 */
	int numMessages(IMessage.Kind kind, boolean orGreater);

	/**
	 * Get all messages or those of a specific kind.
	 * Pass null to get all kinds.
	 * @param kind the IMessage.Kind expected, or null for all messages
     * @param orGreater if true, also get any greater than the target kind
     *         as determined by IMessage.Kind.COMPARATOR 
	 * @return IMessage[] of messages of the right kind, or IMessage.NONE
	 */
	IMessage[] getMessages(IMessage.Kind kind, boolean orGreater);
    
    /** @return unmodifiable List view of underlying collection of IMessage  */
    List getUnmodifiableListView();
    
    /**
     * Clear any messages.
     * @throws UnsupportedOperationException if message list is read-only
     */
    void clearMessages() throws UnsupportedOperationException;
}
