（二）Kafka0.8.2官方文档中文版系列-API

org.apache.kafka
    kafka-clients
    0.8.2.0

class Consumer {
  /**
   *  Create a ConsumerConnector   创建一个消费者连接器
   *
   *  @param config  at the minimum, need to specify the groupid of the consumer and the zookeeper
   *                 connection string zookeeper.connect.
　　*  参数解释：基于一个最小的配置，你只需要指定消费者组，zookeeper的连接
   */
  public static kafka.javaapi.consumer.ConsumerConnector createJavaConsumerConnector(ConsumerConfig config);
}

/**
 *  V: type of the message    消息的类型
 *  K: type of the optional key assciated with the message  与消息相关的可选的配置
 */
public interface kafka.javaapi.consumer.ConsumerConnector {
  /**
   *  Create a list of message streams of type T for each topic.
   *  为每个topic创建一个T类型的消息流列表 
　 *
   *  @param topicCountMap  a map of (topic, #streams) pair   
   *  @param decoder a decoder that converts from Message to T
   *  @return a map of (topic, list of  KafkaStream) pairs.
   *          The number of items in the list is #streams. Each stream supports
   *          an iterator over message/metadata pairs.
   */
  public  Map>>
    createMessageStreams(Map topicCountMap, Decoder keyDecoder, Decoder valueDecoder);

  /**
   *  Create a list of message streams of type T for each topic, using the default decoder.
　　*  为每个topic创建一个T类型的消息流列表，使用默认的解码器
   */
  public Mapbyte[], byte[]>>> createMessageStreams(Map topicCountMap);

  /**
   *  Create a list of message streams for topics matching a wildcard.
   *  
   *  @param topicFilter a TopicFilter that specifies which topics to
   *                    subscribe to (encapsulates a whitelist or a blacklist).
   *  @param numStreams the number of message streams to return.
   *  @param keyDecoder a decoder that decodes the message key
   *  @param valueDecoder a decoder that decodes the message itself
   *  @return a list of KafkaStream. Each stream supports an
   *          iterator over its MessageAndMetadata elements.
   */
  public  List>
    createMessageStreamsByFilter(TopicFilter topicFilter, int numStreams, Decoder keyDecoder, Decoder valueDecoder);

  /**
   *  Create a list of message streams for topics matching a wildcard, using the default decoder.
   *  为与通配符匹配的消息流创建一个消息流列表，使用默认的解码器
   */
  public Listbyte[], byte[]>> createMessageStreamsByFilter(TopicFilter topicFilter, int numStreams);

  /**
   *  Create a list of message streams for topics matching a wildcard, using the default decoder, with one stream.
   *  为与通配符匹配的消息流创建一个消息流列表，使用默认的解码器
   */
  public Listbyte[], byte[]>> createMessageStreamsByFilter(TopicFilter topicFilter);

  /**
   *  Commit the offsets of all topic/partitions connected by this connector.
   *  提交通过该连接器关联的所有的topic和分区的偏移量
   */
  public void commitOffsets();

  /**
   *  Shut down the connector 关闭连接器
   */
  public void shutdown();
}

class kafka.javaapi.consumer.SimpleConsumer {
  /**
   *  Fetch a set of messages from a topic.
   *  从一个topic拉取消息
   *
   *  @param request specifies the topic name, topic partition, starting byte offset, maximum bytes to be fetched.
   *         请求需要指定主题的名称、主题分区、起始偏移量、拉取数据的最大字节数
   *  @return a set of fetched messages 
   *         拉取回来的消息集合
   */
  public FetchResponse fetch(kafka.javaapi.FetchRequest request);

  /**
   *  Fetch metadata for a sequence of topics.
   *  获取一系列主题的元数据
   *
   *  @param request specifies the versionId, clientId, sequence of topics. 需要指定版本号、客户端ID、主题
   *  @return metadata for each topic in the request.  每个请求主题的元数据
   */
  public kafka.javaapi.TopicMetadataResponse send(kafka.javaapi.TopicMetadataRequest request);

  /**
   *  Get a list of valid offsets (up to maxSize) before the given time.
   *  在给定的时间之前，得到一个有效的偏移量列表（偏移量可以取到给定时间之前的最大值）
   *
   *  @param request a [[kafka.javaapi.OffsetRequest]] object.
   *  @return a [[kafka.javaapi.OffsetResponse]] object.
   */
  public kafka.javaapi.OffsetResponse getOffsetsBefore(OffsetRequest request);

  /**
   * Close the SimpleConsumer.   关闭SimpleConsumer
   */
  public void close();
}