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 import java.util.EventListener; 31 32 /** 33 * Listener for data generated by a single DTrace {@link Consumer}. 34 * 35 * @author Tom Erickson 36 */ 37 public interface ConsumerListener extends EventListener { 38 /** 39 * Called whenever a DTrace probe fires (that is, once for each 40 * instance of {@link ProbeData} generated by DTrace). Identifies 41 * the probe and provides data generated by the probe's actions. To 42 * terminate the consumer in the event of unexpected data, throw a 43 * {@link ConsumerException} from this method. 44 * 45 * @throws ConsumerException if the implementation should terminate 46 * the running consumer 47 */ 48 public void dataReceived(DataEvent e) throws ConsumerException; 49 50 /** 51 * Called when traced data is dropped because of inadequate buffer 52 * space. To terminate the consumer in the event of a drop, throw 53 * a {@link ConsumerException} from this method. 54 * 55 * @throws ConsumerException if the implementation should terminate 56 * the running consumer 57 */ 58 public void dataDropped(DropEvent e) throws ConsumerException; 59 60 /** 61 * Called when an error is encountered in the native DTrace library 62 * while tracing probe data. To terminate the consumer, throw a 63 * {@link ConsumerException} from this method. 64 * 65 * @throws ConsumerException if the implementation should terminate 66 * the running consumer 67 */ 68 public void errorEncountered(ErrorEvent e) throws ConsumerException; 69 70 /** 71 * Called when the state of a target process changes. To terminate 72 * the consumer in the event of unexpected process state, throw a 73 * {@link ConsumerException} from this method. 74 * 75 * @throws ConsumerException if the implementation should terminate 76 * the running consumer 77 * @see Consumer#createProcess(String command) 78 * @see Consumer#grabProcess(int pid) 79 */ 80 public void processStateChanged(ProcessEvent e) throws ConsumerException; 81 82 /** 83 * Called once when the source {@link Consumer} is successfully 84 * started in response to {@link Consumer#go()}. 85 * 86 * @see #consumerStopped(ConsumerEvent e) 87 */ 88 public void consumerStarted(ConsumerEvent e); 89 90 /** 91 * Called once when the source {@link Consumer} is stopped, 92 * indicating that this listener should expect no further events. 93 * Called only if there was a prior call to {@link 94 * #consumerStarted(ConsumerEvent e) consumerStarted()}, that is, 95 * only if the consumer was successfully started by a call to {@link 96 * Consumer#go()}. Guaranteed to be called whether the consumer was 97 * stopped by request (via {@link Consumer#stop()}), terminated 98 * normally as a result of the DTrace {@code exit()} action or the 99 * completion of all target processes, or terminated abnormally 100 * because of an exception. It is necessary to call {@link 101 * Consumer#close()} to release any system resources still held by 102 * the stopped consumer. 103 * 104 * @see #consumerStarted(ConsumerEvent e) 105 */ 106 public void consumerStopped(ConsumerEvent e); 107 108 /** 109 * Called when the source {@link Consumer} wakes up to process its 110 * buffer of traced probe data. 111 * 112 * @see #intervalEnded(ConsumerEvent e) 113 */ 114 public void intervalBegan(ConsumerEvent e); 115 116 /** 117 * Called when the source {@link Consumer} finishes processing its 118 * buffer of traced probe data and is about to sleep until the next 119 * interval. The rate of consumption may be controlled with the 120 * {@link Option#switchrate switchrate} and {@link Option#aggrate 121 * aggrate} options (see {@link Consumer#setOption(String option, 122 * String value)}). 123 * 124 * @see #intervalBegan(ConsumerEvent e) 125 */ 126 public void intervalEnded(ConsumerEvent e); 127 } 128