/*
    * Copyright (c) 2003-2008 by Cosylab d. d.
    *
    * This file is part of Java-Common.
    *
    * Java-Common is free software: you can redistribute it and/or modify
    * it under the terms of the GNU General Public License as published by
    * the Free Software Foundation, either version 3 of the License, or
    * (at your option) any later version.
   *
   * Java-Common is distributed in the hope that it will be useful,
   * but WITHOUT ANY WARRANTY; without even the implied warranty of
   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   * GNU General Public License for more details.
   *
   * You should have received a copy of the GNU General Public License
   * along with Java-Common.  If not, see <http://www.gnu.org/licenses/>.
   */
  
  package com.cosylab.util;
  
  import java.util.HashMap;
  import java.util.Map;
  
  import javax.swing.Action;
  
  
  /**
   * This is the basic checked exceptions for the Java projects. In addition to
   * normal Java checked exceptions it provides information about the computer
   * where the exception has occured, as well as instance information about the
   * object, throwing the exception. It also contains hooks for integration with
   * other Java or framework serviecs, in the  form of JavaHelp ID string and
   * list of available Swing actions.  Several important parameters that are
   * determined at construction time, such as message, instance that is throwing
   * the exception and the possible exception cause (if the exceptions are
   * chained). Other parameters (such as helpID and actions) can be set after
   * construction with their respective property setter methods. Most of the
   * parameters are automatically set in the constructors of
   * <code>CommonException</code>. If the derived exception wishes to override
   * the parameters (such as thread, username, host etc), it may reset them in
   * the derived constructor.
   */
  public class CommonException extends Exception implements CommonThrowable
  {
  	protected static String host = null;
  	protected Thread thread = null;
  	protected Object instance = null;
  	protected HashMap values = new HashMap();
  	protected long timestamp = 0;
  	protected String helpID = null;
  	protected Action[] actions = null;
  	protected String username = null;
  
  	/** DOCUMENT ME! */
  	public String caughtIn = null;
  
  	/**
  	 * Create a new instance of <code>CommonException</code>. This constructor
  	 * should normally not be used since it carries no additional exception
  	 * data.
  	 */
  	protected CommonException()
  	{
  		super();
  		initialize();
  	}
  
  	/**
  	 * Create an instance of <code>CommonException</code> with a with a
  	 * specified message string. The construction is delegated to
  	 * <code>super</code>.
  	 *
  	 * @param instance identifier of the instance throwing this exception
  	 * @param s message to be printed together with the exception type     when
  	 *        the <code>toString()</code> is called.
  	 *
  	 * @throws NullPointerException DOCUMENT ME!
  	 */
  	public CommonException(Object instance, String s)
  	{
  		super(s);
  
  		if (instance == null) {
  			throw new NullPointerException("instance");
  		}
  
  		this.instance = instance;
  
  		/* must call initialize after the construction completes */
  		initialize();
  	}
  
  	/**
  	 * Create an instance of <code>CommonException</code> by specifying both
  	 * the string message and a <code>Throwable</code> object that represents
  	 * the nested exception.
  	 *
  	 * @param instance identifier of the instance throwing this exception
 	 * @param message a string message passed to <code>super</code>
 	 * @param t an instance of <code>Throwable</code> that caused this to be
 	 *        thrown, can be <code>null</code>
 	 *
 	 * @throws NullPointerException DOCUMENT ME!
 	 */
 	public CommonException(Object instance, String message, Throwable t)
 	{
 		super(message);
 
 		if (instance == null) {
 			throw new NullPointerException("instance");
 		}
 
 		this.instance = instance;
 
 		if (t != null) {
 			initCause(t);
 		}
 
 		/* must call initialize after the construction completes */
 		initialize();
 	}
 
 	/**
 	 * Call this method if the exception is caught. Provides additional
 	 * debugging info.
 	 *
 	 * @param target Object in which this exception was caught
 	 * @param method method name without parenthesis of prefixed class name
 	 */
 	public void caughtIn(Object target, String method)
 	{
 		assert (target != null);
 		assert (method != null);
 
 		if (target instanceof Class) {
 			caughtIn = ((Class)target).getName() + "::" + method;
 		} else {
 			caughtIn = target.getClass().getName() + "::" + method;
 		}
 	}
 
 	/**
 	 * Returns the string description of where the exception has been caught or
 	 * <code>null</code> if it has not been caught.
 	 *
 	 * @return String "className::method" of where exception has been caught
 	 */
 	public String getCaughtIn()
 	{
 		return caughtIn;
 	}
 
 	/**
 	 * Return the host this exception was generated on, if the JVM has access
 	 * to such data.
 	 *
 	 * @return host name
 	 */
 	public String getHost()
 	{
 		return host;
 	}
 
 	/**
 	 * Return the parent exception that caused this exception to be thrown.
 	 *
 	 * @return parent exception
 	 */
 	public Throwable getParent()
 	{
 		return getCause();
 	}
 
 	/**
 	 * Returns the thread of execution in which the constructor of this
 	 * exception was invoked. It is presupposed that exception is thrown in
 	 * the same thread in which it was instantiated.
 	 *
 	 * @return thread in which this exception was instantiated
 	 */
 	public Thread getThread()
 	{
 		return thread;
 	}
 
 	/**
 	 * Returns the timestamp of the instantiation of this exception. Value is
 	 * in the format returned by Java <code>System.currentTimeMillis()</code>.
 	 *
 	 * @return exception creation timestamp
 	 */
 	public long getTimestamp()
 	{
 		return timestamp;
 	}
 
 	/**
 	 * Returns a hashmap that can hold any key-value pairs that contain
 	 * internal state of the system or specifically the <code>Object</code>
 	 * instance raising this exception. Such data may help in debugging.
 	 * 
 	 * <p>
 	 * <b>Note!</b> Try to store serialized vaues not to introduce memory
 	 * leaks.
 	 * </p>
 	 *
 	 * @return additional data
 	 */
 	public Map getValues()
 	{
 		return values;
 	}
 
 	/**
 	 * Initializes the exception by filling in the host, timestamp, username,
 	 * thread information. Subclasses should override this method (but still
 	 * call it from the overridden version) to provide specialized
 	 * initialization.
 	 */
 	protected void initialize()
 	{
 		if (host == null) {
 			try {
 				host = java.net.InetAddress.getLocalHost().getHostName();
 			} catch (Exception ex) {
 				host = "N/A";
 			}
 		}
 
 		timestamp = System.currentTimeMillis();
 		thread = Thread.currentThread();
 
 		if (username == null) {
 			username = System.getProperty("user.name");
 		}
 	}
 
 	/**
 	 * A shortcut to <code>getValues().put(Object key, Object value)</code>.
 	 * Convenience method. Also converts value to string, not to produce
 	 * memory leak.
 	 *
 	 * @param key key under which the value will be stored in the hashtable
 	 * @param value value for the key, should have <code>toString()</code>
 	 *        overriden to allow for a more informative display
 	 */
 	public void putValue(String key, Object value)
 	{
 		getValues().put(key, String.valueOf(value));
 	}
 
 	/**
 	 * @see com.cosylab.util.CommonThrowable#getActions()
 	 */
 	public Action[] getActions()
 	{
 		return actions;
 	}
 
 	/**
 	 * @see com.cosylab.util.CommonThrowable#getHelpID()
 	 */
 	public String getHelpID()
 	{
 		return helpID;
 	}
 
 	/**
 	 * @see com.cosylab.util.CommonThrowable#getInstance()
 	 */
 	public Object getInstance()
 	{
 		return instance;
 	}
 
 	/**
 	 * @see com.cosylab.util.CommonThrowable#getUsername()
 	 */
 	public String getUsername()
 	{
 		return username;
 	}
 
 	/**
 	 * @see com.cosylab.util.CommonThrowable#getValue(String)
 	 */
 	public Object getValue(String key)
 	{
 		return values.get(key);
 	}
 
 	/**
 	 * Sets the actions returned by this exception. Such actions will  be
 	 * displayed in the GUI when the exception is caught and handled.
 	 *
 	 * @param actions actions to display
 	 */
 	public void setActions(Action[] actions)
 	{
 		assert (actions != null);
 		this.actions = actions;
 	}
 
 	/**
 	 * Sets the JavaHelp id under which the help for this specific  exception
 	 * instance may be looked up. This can be set for exceptions that happen
 	 * more frequently (such as some improper configuration etc) to enable the
 	 * users to get step-by-step help.
 	 *
 	 * @param helpID the JavaHelp identification
 	 */
 	public void setHelpID(String helpID)
 	{
 		this.helpID = helpID;
 	}
 }
 
 /* __oOo__ */