2013年9月13日 星期五

RESTful API 文件產生器 Enunciate 輕鬆上手



接續上一篇"Restful JSON API 文件產生器整理",我最後選了Enunciate來當做Restful 的文件產生器,在使用上也實很簡單,只要在Maven 專案裡面增加以下的Depency

 
<dependency>
 <groupid>org.codehaus.enunciate</groupid>
 <artifactid>enunciate-jboss-rt</artifactid>
 <version>1.27</version>
</dependency>

 

(註:因為我的rest framework 是用jboss 的resteasy 所以選擇enunciate-jboss-rt,如果你是用其他的套件可以參考文件enuciate maven plugin)

然後在Maven Plugin 的地方加入


org.codehaus.enunciate
 maven-enunciate-jboss-plugin
    1.27
 
  true
  ${basedir}/src/main/resources/enunciate.xml
  enunciate
 
 
  
   install
    
     docs
    
   
   
    ${project.parent.basedir}/myproject-doc/docs
   
  
 

 

接下來只要每次run mvn install 就會自動產生文件在指定的位置,如我上面所指定的${project.parent.basedir}/myproject-doc/docs

產生的畫面如下圖所示:






有興趣的人還可以去客製化改ccs,而且Enunciate 這個plugin 最厲害的是還可以針對你的Restful API產生好幾種語言的Client,包含java php ruby



2013年9月2日 星期一

[筆記]在設計MQ時到底何時該用哪種Exchange Type




在討論MQ何時應該使用哪一種Exchange Type前,讓我們先來看看到底有多少種Exchange type可以選擇,因為每一種Exchange type都有適合的情境。



在設計與使用MQ的時候,有哪些需要注意的準則呢?以下內容節錄自 Best Practices for Maximizing Scalability and Cost Effectiveness of Queue-Based Messaging Solutions on Windows Azure

Queue-Based Messaging Fundamentals

A typical messaging solution that exchanges data between its distributed components using message queues includes publishers depositing messages into queues and one or more subscribers intended to receive these messages. In most cases, the subscribers, sometimes referred to as queue listeners, are implemented as single- or multi-threaded processes, either continuously running or initiated on demand as per a scheduling pattern.

At a higher level, there are two primary dispatch mechanisms used to enable a queue listener to receive messages stored on a queue:

    Polling (pull-based model): A listener monitors a queue by checking the queue at regular intervals for new messages. When the queue is empty, the listener continues polling the queue, periodically backing off by entering a sleep state.

    Triggering (push-based model): A listener subscribes to an event that is triggered (either by the publisher itself or by a queue service manager) whenever a message arrives on a queue. The listener in turn can initiate message processing thus not having to poll the queue in order to determine whether or not any new work is available.

所以在選擇Exchange Type 前要先思考,我們要的是Polling 還是 Triggering?

It is also worth mentioning that there are different flavors of both mechanisms. For instance, polling can be blocking and non-blocking. Blocking keeps a request on hold until a new message appears on a queue (or timeout is encountered) whereas a non-blocking request completes immediately if there is nothing on a queue. With a triggering model, a notification can be pushed to the queue listeners either for every new message, only when the very first message arrives to an empty queue or when queue depth reaches a certain level.

那到底最常用的有哪幾種?

Message Bus 






圖片來源:Message Bus



Command Message






圖片來源:Command Message



Message Route


圖片來源:Message Route



Dynamic Router


2013年9月1日 星期日

Restful JSON API 文件產生器整理

寫程式最痛苦的就是寫文件,更痛苦的就一旦程式或介面有修改,也要立即找到相對應的文件修改,也就是這樣才會有文件產生器的誕生,對於一般Java 程式最方變得當然是使用java doc 來產生文件。

但是只要是一談到跨系統跨語言的整合就沒有這麼簡單了,舉例來說 Web service,常見的Web Service 有兩種,一種是XML based 的 SOAP 本身就有一套嚴謹的文件產生規則,所以問題到不大,但是另一種 RESTful Service  就不是這樣了,因為它通常使用JSON的格式在交換訊息,而JSON又是一種很隨性鬆散的結構,這時候如果沒有專門為了 RESTful API的文件產生器那就會很痛苦了....

為了減輕這方面的痛苦,所以特別去找了目前市面上專門為了Java Solution的RESTful service 文件產生器。

不過絕大部分都是針對springmvc 去設計的.....

SpringDoclet


SpringDoclet is a Javadoc doclet that generates documentation on Spring Framwork artifacts in a project. The detection of Spring artifacts is based on the presence of Spring annotations on Java classes and methods.

RESTdoclet


IG Group’s RESTdoclet  is a Maven Doclet plugin for generating REST service documentation from Spring 3 REST implemented services. (必須使用 Spring 3 REST annotations)

Wsdoc


WsDoc is a documentation generator for Spring MVC REST services. Multi modules/war and unified report.

Swagger


Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services.e overarching goal of Swagger is to enable client and documentation systems to update at the same pace as the server. The documentation of methods, parameters and models are tightly integrated into the server code, allowing APIs to always stay in sync. With Swagger, deploying managing, and using powerful APIs has never been easier. swagger-springmvc

JsonDoc


JSONDoc  has a set of completely MVC framework agnostic annotations


雖然知道使用Spring mvc 在java solution 佔大宗,但難道不是使用Spring mvc 開發就不行嘛!? 我想用Jersey 或是 resteasy呢?

後來我找到了Enunciate 它支援標準JAX-WS和 JAX-RS的 annotation,所以不一定要綁定在Spring mvc上 (不過他也有支援),不過他產生的介面算是裡面比較醜的...Orz..

Enunciate


Enunciate is an engine for dramatically enhancing your Java Web service API. (@javax.ws.rs.Path) It’s simple. You develop your Web service API using standard Java technologies and attach Enunciate to your build process. Suddenly, your Web service API is boasting some pretty impressive features:
- Full HTML documentation of your services, scraped from your JavaDocs.
- Client-side libraries (e.g. Java, .NET, iPhone, Ruby, Flex, AJAX, GWT, etc.) for developers who want to interface with your API.
- Interface Definition Documents (e.g. WSDL, XML-Schema, etc.)