1 /* 2 * CDDL HEADER START 3 * 4 * The contents of this file are subject to the terms of the 5 * Common Development and Distribution License (the "License"). 6 * You may not use this file except in compliance with the License. 7 * 8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9 * or http://www.opensolaris.org/os/licensing. 10 * See the License for the specific language governing permissions 11 * and limitations under the License. 12 * 13 * When distributing Covered Code, include this CDDL HEADER in each 14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15 * If applicable, add the following below this CDDL HEADER, with the 16 * fields enclosed by brackets "[]" replaced with your own identifying 17 * information: Portions Copyright [yyyy] [name of copyright owner] 18 * 19 * CDDL HEADER END 20 */ 21 22 /* 23 * Copyright 2006 Sun Microsystems, Inc. All rights reserved. 24 * Use is subject to license terms. 25 * 26 * ident "%Z%%M% %I% %E% SMI" 27 */ 28 package org.opensolaris.os.dtrace; 29 30 /** 31 * Exception thrown by a {@link ConsumerListener} to terminate a running 32 * {@link Consumer}. 33 * 34 * @author Tom Erickson 35 */ 36 public class ConsumerException extends Exception { 37 static final long serialVersionUID = -2125855097525822644L; 38 39 /** @serial */ 40 private Object notificationObject; 41 42 /** 43 * Creates a consumer exception with the given message. 44 * 45 * @see #ConsumerException(String message, Object 46 * dtraceNotificationObject) 47 */ 48 public ConsumerException(String message)49 ConsumerException(String message) 50 { 51 super(message); 52 } 53 54 /** 55 * Creates an exception thrown by a {@link ConsumerListener} 56 * implementation to terminate a running {@link Consumer}, usually 57 * in response to a drop or an error reported by the native DTrace 58 * library. Optionally includes the object reported by the native 59 * DTrace library so it can be used by an {@link ExceptionHandler} 60 * to display details about why the consumer terminated. 61 * 62 * @param message default display message explaining why the 63 * consumer was terminated. 64 * @param notification usually the object passed to a {@link 65 * ConsumerListener} from DTrace that prompted this exception. The 66 * notification could be any of the following: <ul> <li>a {@link 67 * Drop} passed to {@link ConsumerListener#dataDropped(DropEvent e) 68 * dataDropped()}</li> <li>an {@link Error} passed to {@link 69 * ConsumerListener#errorEncountered(ErrorEvent e) 70 * errorEncountered()}</li> <li>a {@link ProcessState} passed to 71 * {@link ConsumerListener#processStateChanged(ProcessEvent e) 72 * processStateChanged()}</li> </ul> or it could be a user-defined 73 * object that describes anything unexpected in {@link 74 * ConsumerListener#dataReceived(DataEvent e) dataReceived()} or 75 * that defines an arbitrary error threshold. An {@link 76 * ExceptionHandler} should be defined to handle any type of 77 * notification object set by user code. May be {@code null}. 78 * @see Consumer#go(ExceptionHandler h) 79 */ 80 public ConsumerException(String message, Object notification)81 ConsumerException(String message, Object notification) 82 { 83 super(message); 84 notificationObject = notification; 85 } 86 87 /** 88 * Gets the optional object from the {@link ConsumerListener} that 89 * communicates to the {@link ExceptionHandler} why the listener 90 * threw this exception. Usually this is the object from DTrace 91 * (such as an {@link org.opensolaris.os.dtrace.Error Error}) that 92 * prompted the exception, simply forwarded to the exception 93 * handler. 94 * 95 * @return an object that communicates to the {@link 96 * ExceptionHandler} why the {@link ConsumerListener} threw this 97 * exception, may be {@code null} 98 * @see Consumer#go(ExceptionHandler h) 99 * @see #ConsumerException(String message, 100 * Object dtraceNotificationObject) 101 */ 102 public Object getNotificationObject()103 getNotificationObject() 104 { 105 return notificationObject; 106 } 107 } 108