1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 */ 18 19 package org.apache.hadoop.chukwa.datacollection.adaptor; 20 21 22 import org.apache.hadoop.chukwa.datacollection.ChunkReceiver; 23 import org.apache.hadoop.chukwa.datacollection.agent.AdaptorManager; 24 25 /** 26 * An adaptor is a component that runs within the Local Agent, producing chunks 27 * of monitoring data. 28 * 29 * An adaptor can, but need not, have an associated thread. If an adaptor lacks 30 * a thread, it needs to arrange some mechanism to periodically get control and 31 * send reports such as a callback somewhere. 32 * 33 * Adaptors must be able to stop and resume without losing data, using a byte 34 * offset in the stream. 35 * 36 * If an adaptor crashes at byte offset n, and is restarted at byte offset k, 37 * with k < n, it is allowed to send different values for bytes k through n the 38 * second time around. However, the stream must still be parseable, assuming 39 * that bytes 0-k come from the first run,and bytes k - n come from the second. 40 * 41 * Note that Adaptor implements neither equals() nor hashCode(). It is never 42 * safe to compare two adaptors with equals(). It is safe to use adaptors 43 * as hash table keys, though two distinct Adaptors will appear as two distinct 44 * keys. This is the desired behavior, since it means that messages intended 45 * for one Adaptor will never be received by another, even across Adaptor 46 * restarts. 47 */ 48 public interface Adaptor { 49 /** 50 * Start this adaptor 51 * 52 * @param type the application type, who is starting this adaptor 53 * @param status the status string to use for configuration. 54 * @param offset the stream offset of the first byte sent by this adaptor 55 * @throws AdaptorException 56 */ 57 public void start(String adaptorID, String type, long offset, 58 ChunkReceiver dest) throws AdaptorException; 59 60 /** 61 * Return the adaptor's state Should not include class name or byte 62 * offset, which are written by caller. The datatype should, however, 63 * be written by this method. 64 * 65 * @return the adaptor state as a string 66 */ 67 public String getCurrentStatus(); 68 69 public String getType(); 70 71 /** 72 * Parse args, return stream name. Do not start running. 73 * 74 * Return the stream name, given params. 75 * The stream name is the part of the Adaptor status that's used to 76 * determine uniqueness. 77 * 78 * @return Stream name as a string, null if params are malformed 79 */ 80 public String parseArgs(String datatype, String params, AdaptorManager c); 81 82 83 84 /** 85 * Signals this adaptor to come to an orderly stop. The adaptor ought to push 86 * out all the data it can before exiting depending of the shutdown policy 87 * 88 * @return the logical offset at which the adaptor was when the method return 89 * @throws AdaptorException 90 */ 91 public long shutdown(AdaptorShutdownPolicy shutdownPolicy) throws AdaptorException; 92 93 /** 94 * Signals this adaptor to come to an orderly stop. The adaptor ought to push 95 * out all the data it can before exiting. 96 * 97 * This method is synchronous up to 60 seconds 98 * 99 * @return the logical offset at which the adaptor stops 100 * @throws AdaptorException 101 */ 102 // @Deprecated 103 // public long shutdown() throws AdaptorException; 104 105 106 /** 107 * Signals this adaptor to come to an abrupt stop, as quickly as it can. The 108 * use case here is "Whups, I didn't mean to start that adaptor tailing a 109 * gigabyte file, stop it now". 110 * 111 * Adaptors might need to do something nontrivial here, e.g., in the case in 112 * which they have registered periodic timer interrupts, or use a shared 113 * worker thread from which they need to disengage. 114 * 115 * This method is synchronous: In other words, after shutdown() returns, no 116 * new data should be written. 117 * 118 * @throws AdaptorException 119 */ 120 // @Deprecated 121 // public void hardStop() throws AdaptorException; 122 123 }