2N/A/*
2N/A * CDDL HEADER START
2N/A *
2N/A * The contents of this file are subject to the terms of the
2N/A * Common Development and Distribution License (the "License").
2N/A * You may not use this file except in compliance with the License.
2N/A *
2N/A * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
2N/A * or http://www.opensolaris.org/os/licensing.
2N/A * See the License for the specific language governing permissions
2N/A * and limitations under the License.
2N/A *
2N/A * When distributing Covered Code, include this CDDL HEADER in each
2N/A * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
2N/A * If applicable, add the following below this CDDL HEADER, with the
2N/A * fields enclosed by brackets "[]" replaced with your own identifying
2N/A * information: Portions Copyright [yyyy] [name of copyright owner]
2N/A *
2N/A * CDDL HEADER END
2N/A */
2N/A
2N/A/*
2N/A * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
2N/A * Use is subject to license terms.
2N/A *
2N/A * ident "%Z%%M% %I% %E% SMI"
2N/A */
2N/Apackage org.opensolaris.os.dtrace;
2N/A
2N/A/**
2N/A * Exception thrown by a {@link ConsumerListener} to terminate a running
2N/A * {@link Consumer}.
2N/A *
2N/A * @author Tom Erickson
2N/A */
2N/Apublic class ConsumerException extends Exception {
2N/A static final long serialVersionUID = -2125855097525822644L;
2N/A
2N/A /** @serial */
2N/A private Object notificationObject;
2N/A
2N/A /**
2N/A * Creates a consumer exception with the given message.
2N/A *
2N/A * @see #ConsumerException(String message, Object
2N/A * dtraceNotificationObject)
2N/A */
2N/A public
2N/A ConsumerException(String message)
2N/A {
2N/A super(message);
2N/A }
2N/A
2N/A /**
2N/A * Creates an exception thrown by a {@link ConsumerListener}
2N/A * implementation to terminate a running {@link Consumer}, usually
2N/A * in response to a drop or an error reported by the native DTrace
2N/A * library. Optionally includes the object reported by the native
2N/A * DTrace library so it can be used by an {@link ExceptionHandler}
2N/A * to display details about why the consumer terminated.
2N/A *
2N/A * @param message default display message explaining why the
2N/A * consumer was terminated.
2N/A * @param notification usually the object passed to a {@link
2N/A * ConsumerListener} from DTrace that prompted this exception. The
2N/A * notification could be any of the following: <ul> <li>a {@link
2N/A * Drop} passed to {@link ConsumerListener#dataDropped(DropEvent e)
2N/A * dataDropped()}</li> <li>an {@link Error} passed to {@link
2N/A * ConsumerListener#errorEncountered(ErrorEvent e)
2N/A * errorEncountered()}</li> <li>a {@link ProcessState} passed to
2N/A * {@link ConsumerListener#processStateChanged(ProcessEvent e)
2N/A * processStateChanged()}</li> </ul> or it could be a user-defined
2N/A * object that describes anything unexpected in {@link
2N/A * ConsumerListener#dataReceived(DataEvent e) dataReceived()} or
2N/A * that defines an arbitrary error threshold. An {@link
2N/A * ExceptionHandler} should be defined to handle any type of
2N/A * notification object set by user code. May be {@code null}.
2N/A * @see Consumer#go(ExceptionHandler h)
2N/A */
2N/A public
2N/A ConsumerException(String message, Object notification)
2N/A {
2N/A super(message);
2N/A notificationObject = notification;
2N/A }
2N/A
2N/A /**
2N/A * Gets the optional object from the {@link ConsumerListener} that
2N/A * communicates to the {@link ExceptionHandler} why the listener
2N/A * threw this exception. Usually this is the object from DTrace
2N/A * (such as an {@link org.opensolaris.os.dtrace.Error Error}) that
2N/A * prompted the exception, simply forwarded to the exception
2N/A * handler.
2N/A *
2N/A * @return an object that communicates to the {@link
2N/A * ExceptionHandler} why the {@link ConsumerListener} threw this
2N/A * exception, may be {@code null}
2N/A * @see Consumer#go(ExceptionHandler h)
2N/A * @see #ConsumerException(String message,
2N/A * Object dtraceNotificationObject)
2N/A */
2N/A public Object
2N/A getNotificationObject()
2N/A {
2N/A return notificationObject;
2N/A }
2N/A}