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     * @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  }