/*
* 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"
*/
/**
* Exception thrown by a {@link ConsumerListener} to terminate a running
* {@link Consumer}.
*
* @author Tom Erickson
*/
/** @serial */
/**
* Creates a consumer exception with the given message.
*
* @see #ConsumerException(String message, Object
* dtraceNotificationObject)
*/
public
{
super(message);
}
/**
* Creates an exception thrown by a {@link ConsumerListener}
* implementation to terminate a running {@link Consumer}, usually
* in response to a drop or an error reported by the native DTrace
* library. Optionally includes the object reported by the native
* DTrace library so it can be used by an {@link ExceptionHandler}
* to display details about why the consumer terminated.
*
* @param message default display message explaining why the
* consumer was terminated.
* @param notification usually the object passed to a {@link
* ConsumerListener} from DTrace that prompted this exception. The
* notification could be any of the following: <ul> <li>a {@link
* Drop} passed to {@link ConsumerListener#dataDropped(DropEvent e)
* dataDropped()}</li> <li>an {@link Error} passed to {@link
* ConsumerListener#errorEncountered(ErrorEvent e)
* errorEncountered()}</li> <li>a {@link ProcessState} passed to
* {@link ConsumerListener#processStateChanged(ProcessEvent e)
* processStateChanged()}</li> </ul> or it could be a user-defined
* object that describes anything unexpected in {@link
* ConsumerListener#dataReceived(DataEvent e) dataReceived()} or
* that defines an arbitrary error threshold. An {@link
* ExceptionHandler} should be defined to handle any type of
* notification object set by user code. May be {@code null}.
* @see Consumer#go(ExceptionHandler h)
*/
public
{
super(message);
}
/**
* Gets the optional object from the {@link ConsumerListener} that
* communicates to the {@link ExceptionHandler} why the listener
* threw this exception. Usually this is the object from DTrace
* (such as an {@link org.opensolaris.os.dtrace.Error Error}) that
* prompted the exception, simply forwarded to the exception
* handler.
*
* @return an object that communicates to the {@link
* ExceptionHandler} why the {@link ConsumerListener} threw this
* exception, may be {@code null}
* @see Consumer#go(ExceptionHandler h)
* @see #ConsumerException(String message,
* Object dtraceNotificationObject)
*/
public Object
{
return notificationObject;
}
}