/*
 * $Log: IListener.java,v $
 * Revision 1.4  2004-09-08 14:15:11  L190409
 * removed unused imports
 *
 * Revision 1.3  2004/08/23 13:07:26  Gerrit van Brakel <gerrit.van.brakel@ibissource.org>
 * updated JavaDoc
 *
 * Revision 1.2  2004/08/03 13:09:51  Gerrit van Brakel <gerrit.van.brakel@ibissource.org>
 * moved afterMessageProcessed to IListener
 *
 * Revision 1.1  2004/07/15 07:38:22  Gerrit van Brakel <gerrit.van.brakel@ibissource.org>
 * introduction of IListener as common root for Pulling and Pushing listeners
 *
 *
 */
package nl.nn.adapterframework.core;

import nl.nn.adapterframework.configuration.ConfigurationException;

import java.util.HashMap;

/**
 * Base-interface for IPullingListener and IMessagePusher
 * 
 * @version Id
 * @author Gerrit van Brakel
 * @since 4.2
 */
public interface IListener extends INamedObject {
	public static final String version="$Id: IListener.java,v 1.4 2004-09-08 14:15:11 L190409 Exp $";

/**
 * <code>configure()</code> is called once at startup of the framework in the configure method of the owner of this listener. 
 * Purpose of this method is to reduce creating connections to databases etc. in the {@link nl.nn.adapterframework.core.IPullingListener#getRawMessage(HashMap)} method.
 * As much as possible class-instantiating should take place in the
 * <code>configure()</code> or <code>open()</code> method, to improve performance.
 */ 
public void configure() throws ConfigurationException;

/**
 * Prepares the listener for receiving messages.
 * <code>open()</code> is called once each time the listener is started.
 */
void open() throws ListenerException;

/**
 * Close all resources used for listening.
 * Called once once each time the listener is stopped.
 */
void close() throws ListenerException;

/**
 * Extracts ID-string from message obtained from {@link nl.nn.adapterframework.core.IPullingListener#getRawMessage(HashMap)}. May also extract
 * other parameters from the message and put those in the threadContext.
 * @return ID-string of message for adapter.
 */
String getIdFromRawMessage(Object rawMessage, HashMap context) throws ListenerException;

/**
 * Extracts string from message obtained from {@link nl.nn.adapterframework.core.IPullingListener#getRawMessage(HashMap)}. May also extract
 * other parameters from the message and put those in the threadContext.
 * @return input message for adapter.
 */
String getStringFromRawMessage(Object rawMessage, HashMap context) throws ListenerException;

/**
 * Called to perform actions (like committing or sending a reply) after a message has been processed by the Pipeline. 
 */
void afterMessageProcessed(PipeLineResult processResult, Object rawMessage, HashMap context) throws ListenerException;


}

/*
 * $Log: IListener.java,v $
 * Revision 1.5  2005-07-19 12:18:09  europe\L190409
 * reformat + moved some functions from pushing and pulling listeners to here
 *
 * Revision 1.4  2004/09/08 14:15:11  Gerrit van Brakel <gerrit.van.brakel@ibissource.org>
 * removed unused imports
 *
 * Revision 1.3  2004/08/23 13:07:26  Gerrit van Brakel <gerrit.van.brakel@ibissource.org>
 * updated JavaDoc
 *
 * Revision 1.2  2004/08/03 13:09:51  Gerrit van Brakel <gerrit.van.brakel@ibissource.org>
 * moved afterMessageProcessed to IListener
 *
 * Revision 1.1  2004/07/15 07:38:22  Gerrit van Brakel <gerrit.van.brakel@ibissource.org>
 * introduction of IListener as common root for Pulling and Pushing listeners
 *
 *
 */
package nl.nn.adapterframework.core;

import nl.nn.adapterframework.configuration.ConfigurationException;

import java.util.HashMap;

/**
 * Base-interface for IPullingListener and IMessagePusher
 * 
 * @author  Gerrit van Brakel
 * @since   4.2
 * @version Id
 */
public interface IListener extends INamedObject {
	public static final String version = "$RCSfile: IListener.java,v $ $Revision: 1.5 $ $Date: 2005-07-19 12:18:09 $";

	/**
	 * <code>configure()</code> is called once at startup of the framework in the configure method of the owner of this listener. 
	 * Purpose of this method is to reduce creating connections to databases etc. in the {@link nl.nn.adapterframework.core.IPullingListener#getRawMessage(HashMap)} method.
	 * As much as possible class-instantiating should take place in the
	 * <code>configure()</code> or <code>open()</code> method, to improve performance.
	 */ 
	public void configure() throws ConfigurationException;
	
	/**
	 * Prepares the listener for receiving messages.
	 * <code>open()</code> is called once each time the listener is started.
	 */
	void open() throws ListenerException;
	
	/**
	 * Close all resources used for listening.
	 * Called once once each time the listener is stopped.
	 */
	void close() throws ListenerException;
	
	/**
	 * Extracts ID-string from message obtained from {@link nl.nn.adapterframework.core.IPullingListener#getRawMessage(HashMap)}. May also extract
	 * other parameters from the message and put those in the threadContext.
	 * @return ID-string of message for adapter.
	 */
	String getIdFromRawMessage(Object rawMessage, HashMap context) throws ListenerException;
	
	/**
	 * Extracts string from message obtained from {@link nl.nn.adapterframework.core.IPullingListener#getRawMessage(HashMap)}. May also extract
	 * other parameters from the message and put those in the threadContext.
	 * @return input message for adapter.
	 */
	String getStringFromRawMessage(Object rawMessage, HashMap context) throws ListenerException;
	
	/**
	 * Called to perform actions (like committing or sending a reply) after a message has been processed by the Pipeline. 
	 */
	void afterMessageProcessed(PipeLineResult processResult, Object rawMessage, HashMap context) throws ListenerException;


}

reformat + moved some functions from pushing and pulling listeners to here