This project has retired. For details please refer to its Attic page.
Adaptor xref
View Javadoc

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 }