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 * @param adaptorID Adaptor ID 52 * 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 Chunk receiving destination 56 * @throws AdaptorException if adaptor can not be started 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 Data type 79 * @param params Adaptor parameters 80 * @param c Adaptor Manager 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 * Signals this adaptor to come to an orderly stop. The adaptor ought to push 88 * out all the data it can before exiting depending of the shutdown policy 89 * @param shutdownPolicy is defined as forcefully or gracefully 90 * 91 * @return the logical offset at which the adaptor was when the method return 92 * @throws AdaptorException Exception on shutdown 93 */ 94 public long shutdown(AdaptorShutdownPolicy shutdownPolicy) throws AdaptorException; 95 96 }