ActiveMQ与REST API实践

摘要

1. 如何搭建Active REST服务的环境

2. REST API以及相关配置参数介绍

3. ActiveMQ中optimizeAck机制介绍

 

    ActiveMQ实现了基于RESTFUL的API,允许开发者可以直接通过HTTP POST/GET方式发布消息和消费消息,这是一种基于文本(/文件)传输的协议.因为在某些特定的环境中,通过HTTP方式操作消息更加便捷,比如基于HTML5的移动终端上,通过javascript或者窗体事件来获取消息.

 

    通常，在开放互联网环境中，非核心消息/类日志系统中，我们会使用ActiveMQ REST来push(保存)/delete(消费)消息。我们可以将REST服务伪装成一个日志存储与分发系统，我们不需要额外的框架支撑，就能实现基于大数据消息的存储与分发。同时也可以在web brower中使用REST，通过轮询或者keepAlive来实现消息的实时推送。

 

    REST协议的最大特点就是更加面向互联网应用(而非企业级应用),其交互便捷, 数据可读性强.当然其局限性也很明显: 在安全上/消息ACK机制上/对事务的支持上/还有消息的异步操作上都有所欠缺(相对于openwire).无论消费者还是生产者,都需要通过URL来描述操作,这就局限了在REST协议下client端调优的情况,同时它还受限于HTTP协议(:keep-alive)以及servlet容器对异步的支持能力。

 

    每个ActiveMQ broker都集成了servlet环境(默认为jetty环境),在启动activeMQ broker的时候,默认挂载启动.org.apache.activemq.web.MessageServlet是官方已经实现的REST代理类,用来代理REST请求.实现原理也非常简单,servlet接收到请求后,内部将使用普通的JMS API + openwire协议与broker通讯.在REST协议中,AcitveMQ约定了URL格式以及参数列表,以及发布消息必须基于HTTP POST,消费消息可以基于GET/DELETE方式.

>>>http://localhost:8161/api/message/test-queue?type=queue&clientId=test1&json=true  
Hello,Restful! 

 

1. 环境准备

   AcitveMQ broker在启动的时候,会挂载启动多个web系统,其中一个web系统就是"api",你可以参看{activemq}/webapps/api中查看相应的配置.这个api系统,就是为REST协议而服务的.{activemq}/conf/activemq.xml文件,是activemq所有配置文件的入口,文件中通过配置引入jetty环境即可使用api系统.

 

    此外，因为REST底层仍然基于openwire(tcp通道)支持，且REST的特性需要贴近HTTP的“短期”/“小数据”等特性，所以我们在transportConnector中，将uri中增加soTimeout=3000，以及控制最大数据尺寸为1M。

 

    从jetty.xml中,我们可以看到所有web系统的配置信息:

 

    5.8之后,jetty环境中所有的web系统默认都是需要授权的,这就意味着,使用REST API时需要提供"name" + "password"校验信息,否则将REST请求将会被拒绝.当然,开发者可以通过注释如下参数式REST不再需要认证.

 

    此外,让ActiveMQ broker来提供REST服务似乎不是一种良好的架构设计,这将很大程度上限制了开发者对REST服务的扩展性，在很多情况下,我们需要把REST服务迁移到专门的web应用中,那么我们就不需要让jetty环境挂载启动api系统.

    接下来，我们将自己搭建ActiveMQ REST服务环境。

 

2.配置文件

    如果你基于activeMQ jetty环境,你可能需要查看一下{activemq}/webapps/api/WEB-INF/web.xml文件,如果你的REST server是自己搭建的,你可能需要把此web.xml文件中的核心信息copy到自己的项目中.无论如何,你都需要在servlet环境中,配置并启动"org.apache.activemq.web.MessageServlet". 其中"org.jolokia.http.AgentServlet"仅作为可选,对于自己搭建REST服务，jolokia就无须配置了。

 

    构建一个servlet系统，我们必须首先确定servlet版本，因为这将直接关系到REST的异步特性，目前比较稳定的版本组合为：servlet 2.4(2.5) + tomcat 6.x，servlet 3.0.1 + tomcat7.x，servlet 3.1 + tomcat8.x。在servlet2.x与servlet3.x中，web.xml配置有少许的差别，主要是因为它们对“异步”操作的控制方式不同，所谓异步，就是当REST请求中消费消息时，如果此时Queue/Topic中没有消息，那么此次请求是否挂起直到有消息可供消费。

 

    Tomcat配置(Tomcat 6.x+)

 

    protocol协议为“HTTP/1.1"，如果你指定了"HTTP/1.0"，那么可能无法良好的使用"keep-alive"，需要一些额外的控制，在此就不再赘言。其中connectionTimeout可以根据实际情况调整，用来控制connector释放链接前阻塞的时间，默认情况下keepAliveTimeout和connectionTimeout值一样，用来描述链接保持活性的时间。

    pom.xml(servlet-2.4)

    javax.servlet
    servlet-api
    2.4
    provided


    org.mortbay.jetty
    jetty-util
    6.1.26


    org.apache.activemq
    activemq-web
    5.8.0

	
    org.apache.activemq
    activemq-all
    5.8.0

    因为servlet2.x不支持"异步"操作，因此需要使用FauxContinuation(伪延续)来提供"阻塞" + "事件通知"特性，因此引入了"jetty-util"依赖包。

 

    web.xml(servlet-2.4)

test-web

    
    
    
    
        org.apache.activemq.connectionFactory
        activeMQConnectionFactory
    
    
    
        org.apache.activemq.brokerURL
        
        tcp://127.0.0.1:51616
    
    
    
        org.apache.activemq.connectionFactory.prefetch
        1
    
    
    
        org.apache.activemq.connectionFactory.optimizeAck
        true
    
    
    
        org.apache.activemq.selectorName
        
        selector
    
    
        OrdersQueueServlet
        org.apache.activemq.web.MessageServlet
        1
        
        
            destination
            orderQueue?consumer.prefetchSize=10
        
        
        
            topic
            false
        
        
        
        
        
            maximumReadTimeout
            10000
        
        
        
            replyTimeout
            10000
        
        
        
            defaultContentType
            text/plain; charset=utf-8
        
    

    
        OrdersQueueServlet
        /rest/order/*
    
    
        continuationFilter
        org.eclipse.jetty.continuation.ContinuationFilter
        
            faux
            true
        
    
    
        continuationFilter
        /rest/*
    

    在web.xml中，我们需要引入continuationFitler，这个Fitler主要用来构建"continuation"实例，此filter将与MessageServlet的内部实现互相协调，通过"轮询"(Filter中) +"阻塞" + "事件通知"(continuation中)，来实现伪异步。具体相关的jetty continuation原理设计请参见其他文档。

    配置文件中标记为"Required"部分是必须要按照规则配置的，"optional"部分为可选的。

 

 

    pom.xml(servlet 3.x)

    javax.servlet
    javax.servlet-api
    3.0.1
    provided


    org.apache.activemq
    activemq-web
    5.8.0

	
    org.apache.activemq
    activemq-all
    5.8.0

    servlet 3.x已经支持了异步，因此我们无需jetty-util的依赖包。

 

    web.xml(servlet 3.x)

?xml version="1.0" encoding="utf-8"?>

test-web
    
    
        OrdersQueueServlet
        org.apache.activemq.web.MessageServlet
        1
        true
        

    

    
        OrdersQueueServlet
        /queue/order/*
    

    此文件和servlet 2.4几乎一样，只是在中增加了 表示使用"异步"，此外在servlet 3.x中，也无需配置continuationFitler。

 

    此处需要特别声明一下，因为tomcat容器的Thread模型的限制，在servlet2.4中“异步”操作仅仅是一种“模拟的”(Faux),其内部机制仍然是基于当前线程阻塞(wait)而实现，因此servlet2.4中使用NIO + 长连接的方式，tomcat仍然无法支撑过多的request。在servlet3.x之后，tomcat 7.x之后，才能配合实现相对完善的NIO/AIO + 长连接方案，tomcat可以在支撑较大请求(包括连接数)的情况下，仍然能够保证性能(内存消耗，吞吐能力)上相对平稳

 

 

3. MessageServlet原理与使用注意事项

 

    [###]在上述web.xml中，其中包含"brokerUrl"/"optimizeAck"/"prefetch"/"selectorName"主要四个参数。

    "brokerUrl"部分需要明确配置brokerUrl参数，这个值和我们常用的openwire协议中的 brokerUrl一样，也允许在brokerUrl中使用查询字符串等用于调优，不过这个brokerUrl需要是一个openwire协议中合法的transport通道(AcitveMQ broker中可以有任意多个openwire transportConnector)，比如"tcp://""failover://"等。MessageServlet将根据"brokerUrl"的值构建ConnectionFactory。

 

    "optimizeAck"表明consumer是否使 用"optimizeAck"选项来优化消息ACK策略，它用来描述"消息确认"的时机，如果此值为true，将采取"延迟ACK"，否则将会"立即ACK"。如果开启，client端将会使用"延迟 + 批量ACK"策略来确认消息，它可以有效的提高消息消费的效率，但有可能会接收到重复的消息，具体原理请参考其他文档。在MessageServlet中，消息的确认方式为“AUTO_ACKNOWLEDGE”，可以有效的在ActiveMQ "optimizeAcknowledge"机制中运行(简析：AUTO_ACK + optimizeAck + prefetchSize > 1 最终构成“批量延迟ACK”优化机制，这是一种高效的消息消费调优策略)。[optimizeACK机制]

 

    "prefetch"用来描 述消费者"预获取"消息的条数(批量消息)，默认值为"1"，此参数值即为prefetchSize。如果broker端有足够多的消息，那么Consumer客户端将会在每次"optimizeAck"确认之后，client端可以一次性获取(或者由broker推送)多条消 息并缓存，总缓存的消息量(未消费 + 已消费但未ACK)控制在prefetchSize之内，这是一个优化消费者的参数，通常和"optimizeAck"协同；如果我们的应用中，REST 客户端1) Queue/Topic通道中消息的数量少 2) REST调用频率都比较低 3) 同一个Queue中Consumer个数较少时，我们需要将optimizeAck=false，或者将 prefetchSize设置为1，场景例如：(获取"推荐商品"消息，"即时通讯"消息);这两个参数非常重要，同时REST API中没有提供ACK的接口(url),所以希望开发者慎重考虑这两个参数。"prefetch"参数值将会对所有Connection有效，如果开发者在destinationOptions中没有指定额外的"prefetchSize"选项，那么将会使用此"prefetch"参数作为默认值。

 

    [###]selectorName为可选参数，默认值为"selector",selector在 ActiveMQ中，称为"消息选择器"；我们可以在REST Url中通过传递"selector=type%3D1"(备注:urlEncode之前为"type=1")，此后将会根据此selector值来构建 Consumer实例，那么此Consumer将会接收到符合selector条件的消息，具体请参考其他文档；不过此处需要注意，对于每个 clientId，只会创建一个Consumer实例，一旦创建，selector值将不会被修改，即使此后使用REST URL传递不同的selector值也不会生效；这个实现和ActiveMQ在openwire协议下一样，如果需要更新selector，需要重建consumer，在REST API中，重建consumer的API就是"unsubscribe"。

    上面的内容，就是ActiveMQ 消息者优化策略的核心原理，如果您还没有明白，我只能"跪"下了!!!

 

    在配置中，还有几个相对简单的配置信息，这些配置信息通常和url查询字符串有很大关系，它们决定了REST API的URL风格。

    destination表示"消息目的地"，无论是发送消息还是接受消息，必须指定destination才能与broker交互。此外，我们可以在destination中添加"destinationOptions"，比如在示例中添加了"customer.prefetchSize=1"表示通过此destination创建的所有的consumer都使用prefetchSize=1。你可以参考更多的文档，来使用"destinationOptions"调优等。不过此后仍然可以在REST URL中使用"&destination=orderQueue"来指定destination，不过我们强烈建议不要使用这种方式，通常情况下，我们会为每个destination单独配置成一个servlet。

 

    destinationOptions也可以通过指定，不过此值只会在REST URL中指定了"&destination=orderQueue"查询字符串时才会有效。如果你在web.xml中配置了"destination"参数，那就需要把相应options追加其后即可，而无需再次配置"destinationOptions"参数。

 

    maxinumReadTimeout表示REST请求阻塞的最长时间，REST URL可以通过查询字符串"&readTimeout=1000"来指定当前请求阻塞时间，不过不能指定比"maxunumReadTimeout"更大的值.设置此值的时候必须要注意，它最好不要大于tomcat中connector链接的keepAlive时间。

 

    replyTimeout，在请求应答(request-reply)模式中，等待"reply"的最大时间。通过REST 发送消息时，可以指定消息是否为"sync"(同步)模式，如果URL中"sync=true",此时消息发送之后即等待消费者"reply",如果等待replyTimeout之后，仍然没有得到应答，那么此消息将意味着发送失败(REST客户端将会得到一个501错误)，在sync=true下，内部使用了camel组件来实现了这种机制。如果没有指定sync，那么消息将会立即发送给broker，也不会涉及到replyTimeout的问题。

 

    [###] REST API列表

    消费消息

        URL:  /queue/order?clientId=client-001&readTimeout=1000&type=json   

        HTTP METHOD:  GET,DELETE

    发送消息

        URL:  /queue/order?clientId=client-00&JMSDeliveryMode=persistent1 或者
                  /queue/order?clientId=client-001&sync=true&replyTimeout=1000   

        HTTP METHOD: POST
                 Header
                 body:消息内容

    取消消费(关闭consumer)

        URL: /queue/order?clientId=client-001&action=unsubscribe   

        HTTP METHOD: POST

 

    提醒，所有的REST URL中都必须携带clientId参数，无论如何，调用者都需要采取一定的手段，不能让clientId总是变化。这和MessageServlet的内部实现有关，它为了提升性能以及避免对broker造成太多的资源浪费，将会根据clientId来缓存(存入Map)一个"webClient"实例,每个webClient实例中都会持有"JMS Session"/"Consumer"/"producer";因此过多的webClient实例会带来一些风险。当REST调用异常时,比如tomcat server返回501内部错误，我们应该"unsubscribe"相应的clientId，这会触发MessageServlet从缓存中移除相应的webClient实例(包括关闭consumer和producer等)。

    "发送消息"URL中，可以指定"JMSDeliveryMode=persistent"表示消息的传输模式(持久化与否)，不过当sync=true时，"JMSDeliveryMode"参数将不会有效。

 

4. 使用REST API

    我们可以使用浏览器，或者任何http客户端，都可以访问这写REST API，在MessageServlet中，支持"POST"/"DELETE"/"GET"三种合法的请求方法(request method),其中"DELETE"/"GET"用于消费消息，"POST"用于发布消息和关闭Consumer链接。如下，我们通过apache httpclient来模拟REST API调用过程以及简单的异常处理。HttpClientUtil.java样例：

 

public class HttpClientUtil {

    private static final CloseableHttpClient httpClient;
    public static final String CHARSET = "UTF-8";

    static {
        RequestConfig config = RequestConfig.custom()
                .setConnectTimeout(60000)
                .setSocketTimeout(-1)
                .build();
        httpClient = HttpClientBuilder.create()
                .setDefaultRequestConfig(config)
                .build();
        /**
        keepAliveClient = HttpClientBuilder.create()
                .setKeepAliveStrategy(DefaultConnectionKeepAliveStrategy.INSTANCE)
                .setConnectionReuseStrategy(DefaultConnectionReuseStrategy.INSTANCE)
                .build();
         **/
    }

    public static String restGet(String url,Map params) {
        if (StringUtils.isBlank(url)) {
            return null;
        }
        try {
            HttpGet httpget = new HttpGet(url);
            if (params != null && !params.isEmpty()) {
                List pairs = new ArrayList(params.size());
                for (Map.Entry entry : params.entrySet()) {
                    String value = entry.getValue();
                    if (value != null) {
                        pairs.add(new BasicNameValuePair(entry.getKey(), value));
                    }
                }
                url += "?" + EntityUtils.toString(new UrlEncodedFormEntity(pairs,CHARSET));
            }
            CloseableHttpResponse response = httpClient.execute(httpget); //block here
            int statusCode = response.getStatusLine().getStatusCode();
            // >= 400
            if(statusCode >= HttpStatus.SC_BAD_REQUEST || statusCode < HttpStatus.SC_OK) {
                httpget.abort();
                response.close();
                throw new RuntimeException("HttpClient,error status code :" + statusCode);
            }
            HttpEntity entity = response.getEntity();
            String result = null;
            if (entity != null) {
                result = EntityUtils.toString(entity, "utf-8");
            }
            //will close inputStream.
            EntityUtils.consume(entity);
            response.close();
            return result;
        } catch (Exception e) {
            e.printStackTrace();
        }
        return null;
    }

    public static String restPost(String url, Map params) {
        if (StringUtils.isBlank(url)) {
            return null;
        }
        try {
            HttpPost httpPost = new HttpPost(url);
            if (params != null && !params.isEmpty()) {
                List pairs = new ArrayList(params.size());
                for (Map.Entry entry : params.entrySet()) {
                    String value = entry.getValue();
                    if (value != null) {
                        pairs.add(new BasicNameValuePair(entry.getKey(), value));
                    }
                }
                httpPost.setEntity(new UrlEncodedFormEntity(pairs, CHARSET));//Utf-8
            }

            CloseableHttpResponse response = httpClient.execute(httpPost);
            int statusCode = response.getStatusLine().getStatusCode();
            if (statusCode != 200) {
                httpPost.abort();
                response.close();
                throw new RuntimeException("HttpClient,error status code :" + statusCode);
            }
            HttpEntity entity = response.getEntity();
            String result = null;
            if (entity != null) {
                result = EntityUtils.toString(entity, CHARSET);
            }
            EntityUtils.consume(entity);
            response.close();
            return result;
        } catch (Exception e) {
            e.printStackTrace();
        }
        return null;
    }
}

  

   REST测试客户端代码，RestClient.java

 

public class RestClient {
    private static String baseUrl = "http://localhost:8080/rest/order";
    //any client must have one clientId
    // but the best is that they should be different.
    private static String clientId = "restful";

	/**
	 * @param args
	 */
	public static void main(String[] args) throws Exception{
        String selfId = clientId + "_" + RandomStringUtils.random(6,true,true);
        for(int i=0; i< 5; i++){
            postMessage(selfId,"Hello,rest activeMQ.." + i);
        }
        System.out.println("post message end..");
        consume(selfId);
        Thread.sleep(3000);
        consume(selfId);
        System.out.println("end!!");
    }

    public static void consume(String selfId){

        while(true){
            try{
                Map params = new HashMap();
                params.put("clientId",selfId);
                params.put("readTimeout","10000");//max blocking time as MS.
                String response = HttpClientUtil.restGet(baseUrl,params);
                System.out.println(response);
                if(StringUtils.isBlank(response)){
                    Thread.sleep(3000);
                }
            }catch (InterruptedException e){
                break;
            } catch (Exception e){
                unSubscribe(selfId);
            }
        }
    }

    protected  static void unSubscribe(String selfId){
        try{
            Map params = new HashMap();
            params.put("clientId",selfId);
            params.put("action", "unsubscribe");
            HttpClientUtil.restPost(baseUrl, params);
        } catch (Exception e){
            e.printStackTrace();
        }
    }

    public static void postMessage(String selfId,String body){
        try{
            Map params = new HashMap();
            params.put("clientId",selfId);
            //sync or async
            // if "sync",after sending out a message,it should be blocking util the message is consumed.
            //params.put("sync","true");
            params.put("body",body);
            HttpClientUtil.restPost(baseUrl,params);
        } catch (Exception e){
            e.printStackTrace();
        }
    }

}

    如果按照，上述的配置，测试代码应该可以顺利通过！！

    Active web项目中，还提供了便于Ajax调用调用的REST方案(Servlet + javascript)，如果读者能够清楚上述讲解的内容，我相信你自己已经可以搭建和配置响应的环境了。