JIRAのJava APIを使ってIssueをエクスポートする

#前置き
JIRAのJava APIを使う機会があり、その紹介をしたいと思います。

REST APIはドキュメントやCurlを使った例などが豊富でしたが、JavaのAPIについてはネットで探しても、
以下のJIRAの公式のチュートリアルが見つかりましたが、情報が古いため有益ではありませんでした。

• https://ecosystem.atlassian.net/wiki/display/JRJC/Tutorial

そのほかにはHttpClientを直接使ってJSONを解析している強者さんのサンプルは見つかりました。

車輪の再発明になりますが、ExcelにJIRAのIssueのサマリをエクスポートする
サンプルを作成したのでそれを紹介したいと思います。

#JIRAのJava APIの使い方の紹介。

JIRAのissueの概要をMS エクセルに出力するJavaのプログラムを例にあげています。 既に標準機能として提供されている(*)のですが、JIRAのJava APIを学びたい人の役に立つと良いです。
* JIRA 検索結果を Microsoft Excel にエクスポートする

Javaのバッチプログラムで実行すると第一引数で指定したエクセルに、タイトル、サマリ、説明を出力するようになっています。
なお、以下のGitHubに公開したコードはあくまで例なので、特にExcelを出力する個所が洗練されていません。

• https://github.com/tashxii/jira-export

##調べた順、疑問に感じた点について

以下に調べた順や疑問点等を時系列に書いていきます。結論だけほしい人は次の節を見てください。

###REST APIだけでなく、JavaでラップされたAPIがあるはずだ。
→APIはあります。以下のページの最後に書かれています。
JIRA Server,Cloud,Software Server, Service Desk Serverとどれを使えばいいのかよくわからないです。
https://developer.atlassian.com/jiradev/jira-apis

###依存ライブラリはそもそも何を使えばいいの？
視点を変えて、Mavenかgradleのどちらでもいいので動くサンプルがないかを探しました。
「pom java JIRA api」等で検索して一番近かったのが以下のページです。
これでも2.0とかなり古いです。
https://community.atlassian.com/t5/Answers-Developer-Questions/JIRA-Rest-Java-Client-libraries/qaq-p/524054

どうやら、以下のライブラリがキーワードっぽいことがわかりました。

• jira-rest-java-client-api
• jira-rest-java-client-core
• jira-rest-java-client-plugin

また、JiraRestClientFactoryというAPIがあることもわかりました。

###チュートリアルのJerseyJiraRestClientFactoryはどこにいったの？
依存ライブラリがわかったので、それをキーにpomを書きました。
「jira-rest-java-client-core maven」で調べると、バージョンが4.0が一番新しいことがわかりました。
https://mvnrepository.com/artifact/com.atlassian.jira/jira-rest-java-client-core

###どういうAPIの構造なの？
依存ライブラリは解決できたので、APIをどう使うか？を調べました。
「JiraRestClientFactory example」をキーに探します。
http://massapi.com/class/ji/JiraRestClientFactory.html
がヒットしました。

コードを見るとJiraRestClientFactory（インターフェース）がエントリーポイントになっていて、昔はJersey…という実装クラス名だったのですが、AsynchronousJiraRestClientFactoryが新しい名前になっています。

Factoryから、JiraRestClientを取得し、検索、更新などなどを行う構造になっています。

━ JiraRestClientFactory (エントリーポイント）
　　┗ AsynchronousJiraRestClientFactory (実装クラス）
　　　　┗ JiraRestClient (ファクトリからとれるClient）
　　　　　┣ IssueClient　（RestClientから取れるサブAPI群）
　　　　　┣ SearchClient
　　　　　┗ ProjectClient

JiraRestClientのJavaDocを見るとよくわかります。

• AuditRestClient getAuditRestClient()
• ComponentRestClient getComponentClient()
• IssueRestClient getIssueClient()
• MetadataRestClient getMetadataClient()
• MyPermissionsRestClient getMyPermissionsRestClient()
• ProjectRestClient getProjectClient()
• ProjectRolesRestClient getProjectRolesRestClient()
• SearchRestClient getSearchClient()
• SessionRestClient getSessionClient()
• UserRestClient getUserClient()
• VersionRestClient getVersionRestClient()

あとは、Jersey→Asynchronousに置き換えればチュートリアルと同じであることがわかりました。

###認証はどうやるの？
https://developer.atlassian.com/jiradev/jira-apis/jira-rest-apis/jira-rest-api-tutorials
このRESTのチュートリアルを見ればBasic,OAuth他があることがわかりました。
サンプルコードを見ると、以下のコードでBasic認証はできそうです。

factory.createWithBasicHttpAuthentication(jiraServerUri, yourUsername, yourPassword);

###検索はどうやってやるの？
「SearchClient JIRA example」で検索しました。とにかくexampleを付けるとよいようです。
次のページがヒットしましたが、これも古くJerseyJiraRestClientを使っていましたが参考にはなります。
http://stackoverflow.com/questions/29206524/how-to-get-all-issues-of-project-via-jira-rest-java-client

###検索するだけの簡単なサンプル
上の例から、以下のコードで検索できることがわかりました。
Promiseってなんだ？と思いましたが、claim()すると、イテレーターが返ってきます。
後は例と同じようにループすればよいだけ。

   Promise<SearchResult> searchJqlPromise = client.getSearchClient().searchJql("project = MYPURRJECT AND status in (Closed, Completed, Resolved) ORDER BY assignee, resolutiondate");

    for (Issue issue : searchJqlPromise.claim().getIssues()) {
        System.out.println(issue.getSummary());
    }

##Issueを検索するサンプルを作るための結論

###1. pom.xmlには、以下を書きます。

    <dependency>
      <groupId>com.atlassian.jira</groupId>
      <artifactId>jira-rest-java-client-core</artifactId>
      <version>4.0.0</version>
    </dependency>

    <dependency>
      <groupId>com.atlassian.jira</groupId>
      <artifactId>jira-rest-java-client-api</artifactId>
      <version>4.0.0</version>
    </dependency>

    <!-- https://mvnrepository.com/artifact/com.atlassian.fugue/fugue -->
    <dependency>
      <groupId>com.atlassian.fugue</groupId>
      <artifactId>fugue</artifactId>
      <version>2.6.1</version>
    </dependency>

    <!-- https://mvnrepository.com/artifact/org.slf4j/slf4j-log4j12 -->
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-log4j12</artifactId>
      <version>1.7.25</version>
    </dependency>

###2. JiraRestClientをBasic認証して取得します。

    JiraRestClientFactory factory = new AsynchronousJiraRestClientFactory();
    URI uri = new URI("https://your-project-name.atlassian.net");
    jiraRestClient = factory.createWithBasicHttpAuthentication(uri, userName, password);

###3. SearchClientを使ってIssueを取ります。
APIはちょっと変わっていましたが以下のコードで取れました。

    SearchRestClient searchRestClient = jiraRestClient.getSearchClient();
    final Set<String> fields = new HashSet<String>();
    String jql = "status!=done"; // Only not done issues.
    SearchResult result = searchRestClient.searchJql(jql, max, offset, fields).claim();
    Iterable<Issue> issues = result.getIssues();
    List<Issue> list = new ArrayList<Issue>();
    for (final Issue issue : issues) {
        list.add(issue);
    }

###4. IssueのAPIから必要な情報が取れます。

  issue.getKey();
  issue.getSummary();
  issue.getDescription();

以上です。

コードはこちら。

• https://github.com/tashxii/jira-export