Event Notification -----HCatalog

Overview

由于事件通知机制的引入，用户可以得到通知如果他注册的事件发生。 其中事件共有六种类型: add_database, add_table, add_partition, drop_partition, drop_table, drop_database. 当特定的事件发生，消息会被发送到消息总线上。任何用户都可以通过注册该事件去获得此消息。一旦注册，消息总线会将特定的消息发送到其所有的订阅者。

 

Topic Name：

客户如果想获得特定的消息必须订阅正确的主题。 不同事件的Topic names是不同的，并且在一些情况下是可以配置的。 所有主题的默认名字都在hive-site.xml中提前配置好的。配置文件中的关键字是 hcat.msgbus.topic.prefix，其中默认为 hcat。再剩下的文档中，我们将使用HCAT_TOPIC_PREFIX作为关键字。 例如， drop_database 将被发送到 HCAT_TOPIC_PREFIX (e.g. hcat)主题。 add_partition 消息会被发送到 HCAT_TOPIC_PREFIX.DB_NAME.TABLE_NAME (eg: hcat.default.example_table)。但是每个表中的事件的主题名称可以被用户自定义。例如， 如下hive查询为表 example_table 设置主题名称为example_table_topic_name：

 

ALTER TABLE example_table SET TBLPROPERTIES ("hcat.msgbus.topic.name" = "example_table_topic_name")

 如何接收通知：

 

为了能接收到通知，首先需要创建一个到消息总线的连接，如下：

    ConnectionFactory connFac = new ActiveMQConnectionFactory(amqurl);
    Connection conn = connFac.createConnection();
    conn.start();

然后订阅一个你感兴趣的主题。 下面的例子展示了订阅者如何先找到他感兴趣的表的主题名称，然后订阅相应事件：

    HiveMetaStoreClient msc = new HiveMetaStoreClient(hiveConf);

    String topicName = msc.getTable("mydb", "myTbl").getParameters().get(HCatConstants.HCAT_MSGBUS_TOPIC_NAME);

使用主题名称（Topic Name）去订阅一个主题， 如下：

    Session session = conn.createSession(true, Session.SESSION_TRANSACTED);
    Destination hcatTopic = session.createTopic(topicName);
    MessageConsumer consumer = session.createConsumer(hcatTopic);
    consumer.setMessageListener(this);

开始接受消息，用户需要实现一个jms的接口MessageListener，其中你需要实现一个方法叫做onMessage(Message msg)。这个方法将被调用无论什么时候一个新的相关消息到达消息总线。 这个消息将包含一个分区对象代表相应的分区，例子如下：

@Override
public void onMessage(Message msg){

  // We are interested in only add_partition events on this table.
  // So, check message type first.
  if(msg.getStringProperty(HCatConstants.HCAT_EVENT).equals(HCatConstants.HCAT_ADD_PARTITION_EVENT)){

    // Retrieve HCatEventMessage, using MessagingUtils.
    HCatEventMessage hcatMessage = MessagingUtils.getMessage(msg);

    //Get the partition-keys for all partitions added.
    List<Map<String, String>> partitionList = ((AddPartitionMessage)hcatMessage).getPartitions();
  }
}

你需要将jms的jar包添加到你的classpath中才能使这些都正常工作。另外还需要有一个jms提供者的jar包在classpath中。 HCatalog使用ActiveMQ作为他的jms提供者。 原则上讲任何jms提供者都可以被用户使用。但是我们建议ActiveMQ。他可以在如下地址获取：
http://activemq.apache.org/activemq-550-release.html

 

事件消息格式：

 

HCatlog的事件字符串（Event-string）是可插拔的，他的默认格式是JSON。 每一个事件消息仅仅传递足够定义数据库/表/分区的变动信息（added/deleted）。一个事件消费者也许会使用事件消息中定义的标示符去向HCatlog查询更进一步的信息。

下面是一个HCatlog所支持的事件的列表，和他们相应的事件格式：

1. Creation of Database:

Event type-string: "CREATE_DATABASE"
Topic Name: HCAT_TOPIC_PREFIX
Example JSON Format:

{
  "timestamp" : 1360272556,
  "eventType" : "CREATE_DATABASE",
  "server"    : "hcatserver.mydomain.net",
  "servicePrincipal" : "hcat/hcatserver@MYDOMAIN.NET",
  "db"        : "mydb"
}

2. Dropping a Database:

Event type-string: "DROP_DATABASE"
Topic Name: HCAT_TOPIC_PREFIX
Example JSON Format:

{
  "timestamp" : 1360272556,
  "eventType" : "DROP_DATABASE",
  "server"    : "hcatserver.mydomain.net",
  "servicePrincipal" : "hcat/hcatserver@MYDOMAIN.NET",
  "db"        : "mydb"
}

 

3. Creation of a Table:

Event type-string: "CREATE_TABLE"
Topic Name: HCAT_TOPIC_PREFIX.DB_NAME
Example JSON Format:

{
  "timestamp" : 1360272556,
  "eventType" : "CREATE_TABLE",
  "server"    : "hcatserver.mydomain.net",
  "servicePrincipal" : "hcat/hcatserver@MYDOMAIN.NET",
  "db"        : "mydb",
  "table"     : "mytbl" 
}

 

4. Dropping a Table:

Event type-string: "DROP_TABLE"
Topic Name: HCAT_TOPIC_PREFIX.DB_NAME
Example JSON Format:

{
  "timestamp" : 1360272556,
  "eventType" : "DROP_TABLE",
  "server"    : "hcatserver.mydomain.net",
  "servicePrincipal" : "hcat/hcatserver@MYDOMAIN.NET",
  "db"        : "mydb",
  "table"     : "mytbl" 
}

5. Adding (an atomic set of) partitions:

Event type-string: "ADD_PARTITION"
Topic Name: HCAT_TOPIC_PREFIX.DB_NAME.TABLE_NAME (default) but is user configurable
Example JSON Format:

{
  "timestamp" : 1360272556,
  "eventType" : "ADD_PARTITION",
  "server"    : "hcatserver.mydomain.net",
  "servicePrincipal" : "hcat/hcatserver@MYDOMAIN.NET",
  "db"        : "mydb",
  "table"     : "mytbl",
  "partitions": [
                   { "partKey1" : "partVal1A", "partKey2" : "partVal2A" },
                   { "partKey1" : "partVal1B", "partKey2" : "partVal2B" },
                   { "partKey1" : "partVal1C", "partKey2" : "partVal2C" }
                ]
}

 

6. Dropping (a set of) partitions:

Event type-string: "DROP_PARTITION"
Topic Name: HCAT_TOPIC_PREFIX.DB_NAME.TABLE_NAME (default) but is user configurable
Example JSON Format:

{
  "timestamp" : 1360272556,
  "eventType" : "DROP_PARTITION",
  "server"    : "hcatserver.mydomain.net",
  "servicePrincipal" : "hcat/hcatserver@MYDOMAIN.NET",
  "db"        : "mydb",
  "table"     : "mytbl",
  "partitions": [
                   { "partKey1" : "partVal1A", "partKey2" : "partVal2A" },
                   { "partKey1" : "partVal1B", "partKey2" : "partVal2B" },
                   { "partKey1" : "partVal1C", "partKey2" : "partVal2C" }
                ]
}

所有的JMS消息都作为TextMessage实例被发送。除了消息体本身，每个消息都还携带3 个字符串属性， 使用如下的keys：

1. HCatConstants.HCAT_EVENT: The event-type string (E.g. "CREATE_TABLE", "ADD_PARTITIONS", etc.)
2. HCatConstants.HCAT_MESSAGE_VERSION: The version-string for the messages (E.g. "0.1", etc.)
3. HCatConstants.HCAT_FORMAT: An identifier for the message format (E.g. "json", by default.)