/*
 * Copyright (C) The Apache Software Foundation. All rights reserved.
 *
 * This software is published under the terms of the Apache Software
 * License version 1.1, a copy of which has been included with this
 * distribution in the LICENSE.txt file.  */

package org.apache.log4j;

import org.apache.log4j.spi.LoggingEvent;
import org.apache.log4j.spi.LoggerRepository;

/**
  Defines the required interface for all Receiver objects.
  
  <p>Just as Appenders send logging events outside of the log4j
  environment (to files, to smtp, to sockets, etc), Receivers bring
  logging events inside the log4j environment.
  
  <p>This is to primarily support the sending of logging events from 
  one process to another, the best example being SocketAppender.
  SocketAppender "appends" the logging event to a socket, configured
  for a specific host and port number.  On the receiving side of
  the socket can be a SocketReceiver object.  The SocketReceiver 
  object receives the logging event, and the "posts" it to the log4j 
  environment (LoggerRepository) to be handled by the configured
  appenders, etc.  The various settings in this environment
  (Logger levels, Appender filters & thresholds) are applied to the
  received logging event.
  
  <p>Receivers can also be used to "import" log messages from other
  loggin packages into the log4j environment.
*/
public interface Receiver {
  
  /**
    Gets the name of the receiver. */
  public String getName();
  
  /**
    Sets the name of the receiver. */
  public void setName(String _name);
      
  /**
    Gets the logger repository for this receiver. If not
    explicity set, returns the value of 
    LogManager.getLoggerRepository(). */
  public LoggerRepository getLoggerRepository();

  /**
    Sets the logger repository used by this reciever. This
    repository will be used to retrieve the Logger object
    matching the received LoggingEvent objects and used to post
    the event. */
  public void setLoggerRepository(LoggerRepository _repository);
  
  /**
    Starts the receiver, and starts receiving events. */
  public void startReceiving();
  
  /**
    Stops the receiver, and stops receiving events. */
  public void stopReceiving();
  
  /**
    Posts the logging event to a logger in the set logger
    repository. */
  public void doPost(LoggingEvent event);

}