package org.okip.service.logging.api;

import org.okip.service.localid.api.LocalId;

/**
Interface Log
Purpose: Represents the logging strategy used, allowing replaceable
     logging strategies. AKA: Log Handler.
*/

public interface Log
extends java.io.Serializable {

  /**
   * Method getLogName
   * Get the appication specific name.
   *
   * @return String
   *
   */
  public String getLogName();

  /**
   * Method getIdentifier
   * Get the internal identifier representing this log.
   *
   * @return LocalId
   *
   */
  public LocalId getIdentifier();

  /**
   * Method appendLog
   * Workhorse used to append to  the log.
   *
   * @param priority
   * @param message
   *
   */
  public void appendLog(final Priority priority, final String message);

  /**
   * Method readLog
   *
   * An interface to read the log. Only a low-level access to the contents is 
   * provided via this method.
   *
   * @param b             Destination array.
   * @param offset
   * @param count         # of bytes to read.
   *
   * @return int status code
   *
   * @throws Exception if any I/O or other error occurs. Semantic errors
   * include trying to read handle that cannot be read from, such as stderr,
   * stdout.
   *
   */
  public int readLog(final byte[] b, final int offset, final int count)
  throws Exception;

  /**
   * Method readLog
   * Another interface to read the log. This would return an enumeration
   * of all messages matching a certain query string. It is assumed that
   * any semantics on the format on the log will be set by
   * the application, which will also know how to parse and
   * reformat the messages for reporting or viewing purposes,
   * and handle presentation aspects as it sees fit.
   * 
   * @param  queryString Represents tag(s) to look for in the message
   *
   * @return java.util.Iterator
   * @throws Exception       if any I/O or other error occurs.
   */
  public java.util.Iterator readLog(final String queryString)
  throws Exception;

  /**
   * Method readLog
   * Yet another interface to read the log. This would return an enumeration
   * of all messages matching a certain logging level.
   *
   * @param  Priority Represents tag(s) to look for in the message
   *
   * @return java.util.Iterator
   * @throws Exception       if any I/O or other error occurs.
   *
   */
  public java.util.Iterator readLog(final Priority priority)
  throws Exception;

  /** JavaBean patterns */
  /**
   * Method setFormatSpecification
   *
   * @param format FormatSpecification.
   *
   */
  public void setFormatSpecification(final FormatSpecification format);

  /**
   * Method getFormatSpecification
   *
   * @return FormatSpecification
   *
   */
  public FormatSpecification getFormatSpecification();

}