Error.java revision fb3fb4f3d76d55b64440afd0af72775dfad3bd1d
/*
* 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
* 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 2006 Sun Microsystems, Inc. All rights reserved.
* Use is subject to license terms.
*
* ident "%Z%%M% %I% %E% SMI"
*/
/**
* 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.
*/
/**
* Invalid alignment.
*/
/**
* Illegal operation.
*/
/**
* Divide-by-zero.
*/
/**
* Out of scratch space.
*/
/**
* Invalid kernel access.
*/
/**
* Invalid user access.
*/
/**
* Tuple stack overflow.
*/
/**
* Library-level fault.
*/
static {
try {
new String[] {"probeDescription",
"enabledProbeID", "CPU", "action", "offset",
"fault", "address", "defaultMessage"});
} 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 */
/** @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
{
validate();
}
private 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
{
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
{
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
{
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
{
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
{
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
{
return defaultMessage;
}
private void
throws IOException, ClassNotFoundException
{
s.defaultReadObject();
// check class invariants
try {
validate();
} catch (Exception e) {
throw new InvalidObjectException(e.getMessage());
}
}
/**
* 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()
{
}
}