/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License (the "License").
 * You may not use this file except in compliance with the License.
 *
 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
 * or http://www.opensolaris.org/os/licensing.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
 * If applicable, add the following below this CDDL HEADER, with the
 * fields enclosed by brackets "[]" replaced with your own identifying
 * information: Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 */

/*
 * Copyright 2007 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 *
 * ident	"%Z%%M%	%I%	%E% SMI"
 */
package org.opensolaris.os.dtrace;

import java.util.*;
import java.io.*;
import java.beans.*;

/**
 * An error encountered in the native DTrace library while tracing probe
 * data.  Each of the fault name constants beginning with {@code
 * DTRACEFLT_} identifies a specific fault with a name that is
 * guaranteed not to change across API versions.
 * <p>
 * Immutable.  Supports persistence using {@link java.beans.XMLEncoder}.
 *
 * @see ConsumerListener#errorEncountered(ErrorEvent e)
 *
 * @author Tom Erickson
 */
public final class Error implements Serializable {
    static final long serialVersionUID = 5069931629562700614L;

    /**
     * Invalid address.
     */
    public static final String DTRACEFLT_BADADDR = "DTRACEFLT_BADADDR";
    /**
     * Invalid alignment.
     */
    public static final String DTRACEFLT_BADALIGN = "DTRACEFLT_BADALIGN";
    /**
     * Illegal operation.
     */
    public static final String DTRACEFLT_ILLOP = "DTRACEFLT_ILLOP";
    /**
     * Divide-by-zero.
     */
    public static final String DTRACEFLT_DIVZERO = "DTRACEFLT_DIVZERO";
    /**
     * Out of scratch space.
     */
    public static final String DTRACEFLT_NOSCRATCH = "DTRACEFLT_NOSCRATCH";
    /**
     * Invalid kernel access.
     */
    public static final String DTRACEFLT_KPRIV = "DTRACEFLT_KPRIV";
    /**
     * Invalid user access.
     */
    public static final String DTRACEFLT_UPRIV = "DTRACEFLT_UPRIV";
    /**
     * Tuple stack overflow.
     */
    public static final String DTRACEFLT_TUPOFLOW = "DTRACEFLT_TUPOFLOW";
    /**
     * Library-level fault.
     */
    public static final String DTRACEFLT_LIBRARY = "DTRACEFLT_LIBRARY";

    static {
	try {
	    BeanInfo info = Introspector.getBeanInfo(Error.class);
	    PersistenceDelegate persistenceDelegate =
		    new DefaultPersistenceDelegate(
		    new String[] {"probeDescription",
		    "enabledProbeID", "CPU", "action", "offset",
		    "fault", "address", "defaultMessage"});
	    BeanDescriptor d = info.getBeanDescriptor();
	    d.setValue("persistenceDelegate", persistenceDelegate);
	} catch (IntrospectionException e) {
	    e.printStackTrace();
	}
    }

    /** @serial */
    private final ProbeDescription probeDescription;
    /** @serial */
    private final int epid;
    /** @serial */
    private final int cpu;
    /** @serial */
    private final int action;
    /** @serial */
    private final int offset;
    /** @serial */
    private final String fault;
    /** @serial */
    private final long address;
    /** @serial */
    private final String defaultMessage;

    /**
     * Creates a DTrace error with the given properties.  Supports XML
     * persistence.
     *
     * @param pdesc probe description that identifies the error-inducing
     * probe among all the probes on the system
     * @param enabledProbeID identifies the error-inducing probe among
     * all probes enabled by the same {@link Consumer}
     * @param errorCPU non-negative ID of the CPU where the error was
     * encountered, or a negative number if the CPU is unknown
     * @param errorAction integer that identifies the error-inducing
     * action as the nth action (starting at one) in the error-inducing
     * probe, or zero if the error is in the predicate rather than in an
     * action
     * @param errorOffset error offset in compiled DTrace Intermediate
     * Format (DIF), or a negative number if the offset is not available
     * @param faultName name of the specific fault, or {@code null}
     * if the fault is unknown to the Java DTrace API
     * @param faultAddress address of fault, or -1 if address is not
     * applicable to the specific fault
     * @param errorMessage default message from the native DTrace
     * library preconstructed from the properties of this error
     * @throws NullPointerException if the given probe description or
     * default message is {@code null}
     */
    public
    Error(ProbeDescription pdesc, int enabledProbeID, int errorCPU,
	    int errorAction, int errorOffset, String faultName,
	    long faultAddress, String errorMessage)
    {
	probeDescription = pdesc;
	epid = enabledProbeID;
	cpu = errorCPU;
	action = errorAction;
	offset = errorOffset;
	fault = faultName;
	address = faultAddress;
	defaultMessage = errorMessage;
	validate();
    }

    private final void
    validate()
    {
	if (probeDescription == null) {
	    throw new NullPointerException(
		    "enabled probe description is null");
	}
	if (defaultMessage == null) {
	    throw new NullPointerException("default message is null");
	}
    }

    /**
     * Gets the probe description that identifies the error-inducing
     * probe among all the probes on the system.
     *
     * @return non-null probe description
     */
    public ProbeDescription
    getProbeDescription()
    {
	return probeDescription;
    }

    /**
     * Gets the enabled probe ID.  The "epid" is different from {@link
     * ProbeDescription#getID()} because it identifies a probe among all
     * the probes enabled by a {@link Consumer}, rather than among all
     * the probes on the system.
     *
     * @return the enabled probe ID
     */
    public int
    getEnabledProbeID()
    {
	return epid;
    }

    /**
     * Gets the CPU that encountered the error.
     *
     * @return non-negative CPU ID, or a negative number if the CPU is
     * unknown
     */
    public int
    getCPU()
    {
	return cpu;
    }

    /**
     * Gets the error-inducing action as the <i>nth</i> action (starting
     * at one) in the error-inducing probe, or zero if the error is in
     * the predicate rather than in an action.  Note that some actions
     * in a D program consist of multiple actions internally within the
     * DTrace library.
     *
     * @return zero if the error is in the probe predicate, otherwise
     * the <i>nth</i> action (<i>n</i> starting at one) from the start
     * of the probe that induced the error
     */
    public int
    getAction()
    {
	return action;
    }

    /**
     * Gets the error offset in compiled DTrace Intermediate Format
     * (DIF), or a negative number if the offset is not available.
     *
     * @return the error offset in compiled DTrace Intermediate Format
     * (DIF), or a negative number if the offset is not available
     */
    public int
    getOffset()
    {
	return offset;
    }

    /**
     * Gets the name identifying the specific fault.  The names are
     * guaranteed not to change across API versions as long as the fault
     * cases they identify still exist.
     *
     * @return name of the specific fault or {@code null} if the
     * fault is unknown to the Java DTrace API
     */
    public String
    getFault()
    {
	return fault;
    }

    /**
     * Gets the address of the fault, if any.
     *
     * @return address of fault, or -1 if address is not applicable to
     * the specific fault (the fault is not one of {@link
     * #DTRACEFLT_BADADDR} or {@link #DTRACEFLT_BADALIGN})
     */
    public long
    getAddress()
    {
	return address;
    }

    /**
     * Gets the default message from the native DTrace library
     * preconstructed from the properties of this error.
     *
     * @return non-null preconstructed message
     */
    public String
    getDefaultMessage()
    {
	return defaultMessage;
    }

    private void
    readObject(ObjectInputStream s)
            throws IOException, ClassNotFoundException
    {
	s.defaultReadObject();
	// check class invariants
	try {
	    validate();
	} catch (Exception e) {
	    InvalidObjectException x = new InvalidObjectException(
		    e.getMessage());
	    x.initCause(e);
	    throw x;
	}
    }

    /**
     * Gets a string representation of this error useful for logging and
     * not intended for display.  The exact details of the
     * representation are unspecified and subject to change, but the
     * following format may be regarded as typical:
     * <pre><code>
     * class-name[property1 = value1, property2 = value2]
     * </code></pre>
     */
    public String
    toString()
    {
	StringBuilder buf = new StringBuilder();
	buf.append(Error.class.getName());
	buf.append("[probeDescription = ");
	buf.append(probeDescription);
	buf.append(", epid = ");
	buf.append(epid);
	buf.append(", cpu = ");
	buf.append(cpu);
	buf.append(", action = ");
	buf.append(action);
	buf.append(", offset = ");
	buf.append(offset);
	buf.append(", fault = ");
	buf.append(fault);
	buf.append(", address = ");
	buf.append(address);
	buf.append(", defaultMessage = ");
	buf.append(defaultMessage);
	buf.append(']');
	return buf.toString();
    }
}