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 adaptorID cutomized application ID 53 * @param type the application type, who is starting this adaptor 54 * @param offset the stream offset of the first byte sent by this adaptor 55 * @param dest receiver of the chunk 56 * @throws AdaptorException 57 */ 58 public void start(String adaptorID, String type, long offset, 59 ChunkReceiver dest) throws AdaptorException; 60 61 /** 62 * Return the adaptor's state Should not include class name or byte 63 * offset, which are written by caller. The datatype should, however, 64 * be written by this method. 65 * 66 * @return the adaptor state as a string 67 */ 68 public String getCurrentStatus(); 69 70 public String getType(); 71 72 /** 73 * Parse args, return stream name. Do not start running. 74 * 75 * Return the stream name, given params. 76 * The stream name is the part of the Adaptor status that's used to 77 * determine uniqueness. 78 * @param datatype 79 * @param params 80 * @param c 81 * 82 * @return Stream name as a string, null if params are malformed 83 */ 84 public String parseArgs(String datatype, String params, AdaptorManager c); 85 86 87 88 /** 89 * Signals this adaptor to come to an orderly stop. The adaptor ought to push 90 * out all the data it can before exiting depending of the shutdown policy 91 * @param shutdownPolicy 92 * 93 * @return the logical offset at which the adaptor was when the method return 94 * @throws AdaptorException 95 */ 96 public long shutdown(AdaptorShutdownPolicy shutdownPolicy) throws AdaptorException; 97 98 /** 99 * Signals this adaptor to come to an orderly stop. The adaptor ought to push 100 * out all the data it can before exiting. 101 * 102 * This method is synchronous up to 60 seconds 103 * 104 * @return the logical offset at which the adaptor stops 105 * @throws AdaptorException 106 */ 107 // @Deprecated 108 // public long shutdown() throws AdaptorException; 109 110 111 /** 112 * Signals this adaptor to come to an abrupt stop, as quickly as it can. The 113 * use case here is "Whups, I didn't mean to start that adaptor tailing a 114 * gigabyte file, stop it now". 115 * 116 * Adaptors might need to do something nontrivial here, e.g., in the case in 117 * which they have registered periodic timer interrupts, or use a shared 118 * worker thread from which they need to disengage. 119 * 120 * This method is synchronous: In other words, after shutdown() returns, no 121 * new data should be written. 122 * 123 * @throws AdaptorException 124 */ 125 // @Deprecated 126 // public void hardStop() throws AdaptorException; 127 128 }