WABI BLAST の詳細

URI POST /blast (検索ジョブの登録

BLAST検索のジョブ をキューに投入して、 Request ID を返します。
BLAST検索 の検索条件や結果通知方法などを HTTPパラメーター で指定します。

項目 説明
HTTP メソッド POST
URI /blast
HTTP パラメーター querySequence multi FASTA 形式の検索配列データ
例:
>my query sequence 1
CACCCTCTCTTCACTGGAAAGGACACCATGAGCACGGAAAGCATGATCCAGGACGTGGAA
GCTGGCCGAGGAGGCGCTCCCCAGGAAGACAGCAGGGCCCCAGGGCTCCAGGCGGTGCTG
GTTCCTCAGCCTCTTCTCCTTCCTGCTCGTGGCAGGCGCCGCCAC
※配列数を増やしても並列度は上がりません。
ジョブ管理エンジンによる負荷分散も考慮すると、
Web API として利用するならば配列数は少なめにすることを推奨します。
datasets データセット (例: "ddbjall")
database データベース (例: "hum", "hum pri")
program BLAST プログラム (例: "blastn")
parameters その他のオプション指定 (例: "-v 100 -b 100 -e 10 -F F -W 11")
format 応答データの形式 (例: "text", "json")
result 結果通知方法 (例: "www", "mail")
address メールアドレス
処理内容 BLAST検索 のジョブをキューに投入する。
HTTP レスポンス 成功した場合 Request ID を含むジョブ情報
失敗した場合 HTTP ステータス 4xx

処理の流れ

  1. 入力値を検証します。
    入力値エラーが見つかった場合は、処理を中断して HTTP ステータス 400 Bad Request を返します。
  2. BLAST検索 のジョブをキューに投入します。
  3. キューに投入されたジョブの情報を、 format で指定された形式にして、返します。
    ただし、利用不可能な format 値だった場合は HTTP ステータス 404 Not Found を返します。

  • 開発者向けの情報
    1. Springフレームワーク がリクエスト情報を request/BlastRequest にバインドします。
    2. Springフレームワーク がコントローラーの post(@ModelAttribute BlastRequest request, BindingResult errors) アクションを呼び出します。
      その際に errors は、リクエスト情報をバインドした際のエラー情報を格納しています。
    3. job/JobInfo がリクエスト ID を発行します。既存のリクエスト ID と重複した場合は発行処理を再帰的にやり直すため、必ず一意な値を発行します。
      job/JobInfo は続けて、作業ディレクトリーを作成します。
      #リクエスト情報を JSON形式 の文字列として、作業ディレクトリーの user_request.json ファイルに保存します。
      #検索配列を、作業ディレクトリーの query_sequence.fasta ファイルに保存します。
    4. 入力値を検証します。
      入力値エラーが見つかった場合は、処理を中断して HTTP ステータス 400 Bad Request を返します。
      入力値エラーが存在する場合は、アクションが BadRequestException 例外を投げます。
      Springフレームワーク が、ハンドラー handlerException(BadRequestException e) が呼び出します。
      ハンドラーは、対応する HTTP ステータスを返します。
    5. 入力値より、 BLAST計算 を行なう BASH スクリプトを作成して、作業ディレクトリーの wabi_blast.sh ファイルに保存します。
    6. コントローラーが JobName を構築します。
      JobName は、 "wabi_blast_" + program + "_w3wabi" という書式です。
      例: "wabi_blast_blastn_w3wabi"
    7. BLAST検索 のジョブをキューに投入します。
      job/JobInfo は、前述の BASH スクリプトを qsub コマンドを使って UGE にサブミットします。
      サブミットする際には、構築した JobName を用います。
      job/JobInfo は、ジョブがサブミットされた時に採番される JobID を返します。
    8. JobID を、作業ディレクトリーの uge_job_id.txt ファイルに保存します。
    9. ジョブ情報を、作業ディレクトリーの job_info.json ファイルに保存します。
    10. キューに投入されたジョブの情報を、 format で指定された形式にして、返します。
      ただし、利用不可能な format 値だった場合は HTTP ステータス 404 Not Found を返します。

入力値の検証内容

  1. datasets (省略可能)
    1. 未定義の値が指定された場合、入力値エラーです。
      ※現在、未使用。 database との整合性チェックは行なっていません。
  2. database
    1. 必須チェック
    2. データベース名を空白区切りで並べた値以外は、入力値エラーです。データベース名は英字または "_" のみです。
      例: "hum" や "hum pri" など。
  3. program
    1. 必須チェック
    2. 未定義の値が指定された場合、入力値エラーです。
  4. format
    1. 必須チェック
    2. 未定義の値が指定された場合、入力値エラーです。
  5. parameters (省略可能)
    1. オプション指定とその設定値を空白区切りで並べた値以外は、入力値エラーです。
    2. 指定可能なオプション以外は、入力値エラーです。指定可能なオプションは、 program 値に応じて次の通りです。
      • program 値が "megablast" の場合:
        ADEFGHIJLMNPRSTUVWXYZbefglmnpqrstvyz 以外のオプション指定を含む場合は、入力値エラーです。
        例: "-A" は正常値ですが、 "-B" は入力値エラー。
      • program 値がそれ以外の場合:
        ABCDEFGIJKLMPQSTUVWXYZbefglmnqrstvwyz 以外のオプション指定を含む場合は、入力値エラーです。
        例: "-B" は正常値ですが、 "-H" は入力値エラー。
    3. オプションの設定値は整数値または、英数字およびカンマ区切り英数字です。
      例: "-1" 、 "foo,bar" など。
  6. result
    1. 必須チェック
    2. 未定義の値が指定された場合、入力値エラーです。
  7. address
    1. result 値が "mail" の場合は必須チェック
    2. メールアドレスの形式以外は、入力値エラーです。

応答データの内容

  • 正常終了した場合
    • HTTP ステータスが 200 等の「成功」を示す値です。
    • requestId に「リクエストID」が対応付けられた情報を返します。
    • その他、 current-time (現在時刻) やリクエスト情報を含むことがありますが、書式は随時更新いたします。
      実行の成否判定のためには HTTP ステータスを利用してください。
  • 異常終了した場合
    • HTTP ステータスが 400 等の「クライアントエラー」を示す値です。
    • 応答データの中からキー error-messages で取得できるエラーメッセージ情報には、入力値エラーとなったパラメーター名の情報等が含まれます。
    • その他、リクエスト情報やエラーの原因などの情報を含むことがありますが、書式は随時更新いたします。
      実行の成否判定のためには HTTP ステータスを利用してください。

入出力データの例

  • 入力値の例
    HTTP パラメーター 入力値
    address ""
    database "hum"
    datasets "ddbjall"
    format "json"
    parameters " -v 100 -b 100 -e 10 -F F -W 11"
    program "blastn"
    querySequence >my query sequence 1
    CACCCTCTCTTCACTGGAAAGGACACCATGAGCACGGAAAGCATGATCCAGGACGTGGAA
    GCTGGCCGAGGAGGCGCTCCCCAGGAAGACAGCAGGGCCCCAGGGCTCCAGGCGGTGCTG
    GTTCCTCAGCCTCTTCTCCTTCCTGCTCGTGGCAGGCGCCGCCAC
    result "www"
  • 正常終了した場合の応答データ例 
    HTTP ステータス 200
 1{
 2        "requestId": "wabi_blast_1111-1111-1111-11-111-111111",
 3        "program": "blastn",
 4        "datasets": "ddbjall",
 5        "database": "hum",
 6        "parameters": " -v 100 -b 100 -e 10 -F F -W 11 ",
 7        "current-time": "2013-01-01 12:34:56",
 8        "start-time": "",
 9        "current-state": "" 
10}

    HTTP ステータス 200
 1<?xml version="1.0" ?>
 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 3<result>
 4  <requestId>wabi_blast_1111-1111-1111-11-111-111111</requestId>
 5  <program>blastn</program>
 6  <datasets>ddbjall</datasets>
 7  <database>hum</database>
 8  <parameters> -v 100 -b 100 -e 10 -F F -W 11 </parameters>
 9  <current-time>2013-01-01 12:34:56</current-time>
10  <start-time></start-time>
11  <current-state></current-state>
12</result>
  • 入力値エラーの場合の応答データ例 
    HTTP ステータス 400
 1{
 2    "status": "illegal-arguments",
 3    "message": "Illegal arguments.",
 4    "format": null,
 5    "program": "blastn",
 6    "datasets": "ddbjall",
 7    "database": "hum",
 8    "parameters": null,
 9    "querySequence": ">my query sequence 1\nCACCCTCTCTTCACTGGAAAGGACACCATGAGCACGGAAAGCATGATCCAGGACGTGGAA\nGCTGGCCGAGGAGGCGCTCCCCAGGAAGACAGCAGGGCCCCAGGGCTCCAGGCGGTGCTG\nGTTCCTCAGCCTCTTCTCCTTCCTGCTCGTGGCAGGCGCCGCCAC\n",
10    "result": "",
11    "address": null,
12    "current-time": "2013-01-01 12:34:56",
13    "error-messages": [
14        "Required: (result)" 
15    ],
16    "error-message": "BAD_REQUEST (null)" 
17}

利用例

Java で SpringFramework の RESTクライアント を使う場合:

 1import java.util.LinkedHashMap;
 2import org.springframework.util.LinkedMultiValueMap;
 3import org.springframework.util.MultiValueMap;
 4import org.springframework.web.client.RestTemplate;
 5import org.springframework.web.client.HttpClientErrorException;
 6import net.arnx.jsonic.JSON;
 7
 8/*
 9 * (中略)
10 */
11
12        MultiValueMap<String, String> parts = new LinkedMultiValueMap<String, String>();
13        parts.add("address", "");
14        parts.add("database", "hum");
15        parts.add("datasets", "ddbjall");
16        parts.add("format", "json");
17        parts.add("parameters", " -v 100 -b 100 -e 10 -F F -W 11");
18        parts.add("program", "blastn");
19        parts.add("querySequence", ">my query sequence 1\nCACCCTCTCTTCACTGGAAAGGACACCATGAGCACGGAAAGCATGATCCAGGACGTGGAA\nGCTGGCCGAGGAGGCGCTCCCCAGGAAGACAGCAGGGCCCCAGGGCTCCAGGCGGTGCTG\nGTTCCTCAGCCTCTTCTCCTTCCTGCTCGTGGCAGGCGCCGCCAC\n");
20        parts.add("result", "www");
21        try {
22            RestTemplate rest = new RestTemplate();
23            String response = rest.postForObject("http://ddbj.nig.ac.jp/wabi/blast/", parts, String.class);
24            /*
25----  response の例 (ここから)  --------------------------------
26{
27    "requestId": "wabi_blast_1111-1111-1111-11-111-111111",
28    "program": "blastn",
29    "datasets": "ddbjall",
30    "database": "hum",
31    "parameters": " -v 100 -b 100 -e 10 -F F -W 11",
32    "current-time": "2013-01-01 12:34:56",
33    "start-time": "",
34    "current-state": "" 
35}
36----  response の例 (ここまで)  --------------------------------
37             */
38            LinkedHashMap<String, String> result = JSON.decode(response, LinkedHashMap.class);
39            String requestId = result.get("requestId");
40            /*
41             * ジョブの投入に成功した場合は Request ID を覚えておく。
42             */
43        } catch (HttpClientErrorException e) {
44            /*
45             * 入力値エラー等。
46             */
47        }

URI GET /blast/{Request-ID}?info=status (検索ジョブの状態確認)

指定された Request ID の ジョブの現在の状態 を返します。

項目 説明
HTTP メソッド GET
URI "/blast/" + Request ID + HTTP パラメーター
(例: "/blast/wabi_blast_1111-1111-1111-11-111-111111?info=status")
HTTP パラメーター info (デフォルト値 = "status") ジョブ情報の種類 (例: "status", "result")
format (デフォルト値 = "text") 応答データの形式 (例: "text", "json")

処理の流れ

  1. 入力値を検証します。
    入力値エラーが見つかった場合は、処理を中断して HTTP ステータス 400 Bad Request を返します。
  2. 指定された Request ID に対するジョブ情報を取得して、 現在の状態 情報を取得します。
    検索結果の保存期間を過ぎている場合など、ジョブ情報が見つからなかった場合には、 HTTP ステータス 404 を返します。
  3. 取得した 現在の状態 情報を format で指定された形式に整形して返します。
    ただし、利用不可能な format 値だった場合は HTTP ステータス 404 Not Found を返します。

  • 開発者向けの情報
    1. Springフレームワーク がリクエスト情報を request/BlastGetRequest にバインドします。
      format 値が未指定の場合、デフォルト値で代替します。
    2. Springフレームワーク がコントローラーの get(@PathVariable("id") String requestId, @ModelAttribute BlastGetRequest request, BindingResult errors, HttpServletRequest req) アクションを呼び出します。
      その際に errors は、リクエスト情報をバインドした際のエラー情報を格納しています。
    3. 入力値を検証します。
      入力値エラーが見つかった場合は、処理を中断して HTTP ステータス 400 Bad Request を返します。
      入力値エラーが存在する場合は、アクションが BadRequestException 例外を投げます。
      Springフレームワーク が、ハンドラー handlerException(BadRequestException e) が呼び出します。
      ハンドラーは、対応する HTTP ステータスを返します。
    4. 入力値 info の値に応じて場合分けします。
    5. 指定された Request ID に対するジョブ情報を取得して、 現在の状態 情報を取得します。
      検索結果の保存期間を過ぎている場合など、ジョブ情報が見つからなかった場合には、 HTTP ステータス 404 を返します。
      job/JobInfo は、指定された Request ID に対応する作業ディレクトリーに保存されている筈の uge_job_id.txt ファイルから JobID を読み取ります。
      次に job/JobInfo は qstat , qacct 等のコマンドの出力結果から UGE ジョブの現在の状態を判定します。
      その際 JobID が取得できていなかった場合には例外を投げてコントローラーに処理を戻して、 HTTP ステータス 400 Bad Request を返します。
      リクエスト元IPアドレス が DDBJ内部 以外の場合には、 qsub のシステム情報を除去して返します。
    6. 取得した 現在の状態 情報を format で指定された形式に整形して返します。
      ただし、利用不可能な format 値だった場合は HTTP ステータス 404 Not Found を返します。

入力値の検証内容

  1. requestId
    1. 必須チェック
    2. 英数字、 "-" 、 "_" 以外を含む場合、入力値エラーです。
    3. 実在する Request ID 以外の場合、入力値エラーです。
      一定日数を超えた検索結果は破棄されていますが、その場合も入力値エラーとして扱われます。
  2. format
    1. 必須チェック
    2. 未定義の値の場合、入力値エラーです。
  3. imageId
    1. 何も指定しないこと。
  4. info
    1. "status" を指定すること。

応答データの内容

  • 正常終了した場合
    • HTTP ステータスが 200 等の「成功」を示す値です。
    • status に「現在の状態」が対応付けられた情報を返します。
    • その他、 current-time (現在時刻) やリクエスト情報を含みますが、書式は随時更新いたします。
      実行の成否判定のためには HTTP ステータスを利用してください。
  • 異常終了した場合
    • HTTP ステータスが 400 等の「クライアントエラー」を示す値です。
    • 応答データの中からキー error-messages で取得できるエラーメッセージ情報には、入力値エラーとなったパラメーター名の情報等が含まれます。
    • その他、リクエスト情報やエラーの原因などの情報を含みますが、書式は随時更新いたします。
      実行の成否判定のためには HTTP ステータスを利用してください。

入出力データの例

  • 入力値の例
    HTTP パラメーター 入力値
    format "json"
    result "www"
    info "status"
  • 正常終了した場合の応答データ例 
    HTTP ステータス 200
1request-ID: wabi_blast_1111-1111-1111-11-111-111111
2status: finished
3current-time: 2013-01-01 12:34:56
4system-info:
5stdout

    HTTP ステータス 200
1{
2        "request-ID": "wabi_blast_1111-1111-1111-11-111-111111",
3        "status": "finished",
4        "current-time": "2013-01-01 12:34:56",
5        "system-info": "\nstdout" 
6}

    HTTP ステータス 200
1<?xml version="1.0" ?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3<result>
4  <request-ID>wabi_blast_1111-1111-1111-11-111-111111</request-ID>
5  <status>finished</status>
6  <current-time>2013-01-01 12:34:56</current-time>
7  <system-info>stdout</system-info>
8</result>
  • 入力値エラーの場合の応答データ例 
    HTTP ステータス 400
 1{
 2        "status": "illegal-arguments",
 3        "message": "Illegal arguments.",
 4        "requestId": "wabi_blast_1111-1111-1111-11-111-111111",
 5        "format": "json",
 6        "imageId": null,
 7        "info": "status",
 8        "current-time": "2013-01-01 12:34:56",
 9        "error-messages": [
10                "No such data: (requestId)" 
11        ],
12        "error-message": "BAD_REQUEST (null)" 
13}

利用例

Java で SpringFramework の RESTクライアント を使う場合:

 1import java.util.LinkedHashMap;
 2import org.springframework.util.LinkedMultiValueMap;
 3import org.springframework.util.MultiValueMap;
 4import org.springframework.web.client.RestTemplate;
 5import org.springframework.web.client.HttpClientErrorException;
 6import net.arnx.jsonic.JSON;
 7
 8/*
 9 * (中略)
10 */
11
12        /*
13         * 覚えておいた Request ID を使って GET する。
14         */
15        String requestId = "wabi_blast_1111-1111-1111-11-111-111111";
16        MultiValueMap<String, String> parts = new LinkedMultiValueMap<String, String>();
17        parts.add("info", "status");
18        parts.add("format", "json");
19        try {
20            RestTemplate rest = new RestTemplate();
21            String response = rest.getForObject("http://ddbj.nig.ac.jp/wabi/blast/" + requestId, String.class, parts);
22            /*
23----  response の例 (ここから)  --------------------------------
24{
25    "request-ID": "wabi_blast_1111-1111-1111-11-111-111111",
26    "status": "finished",
27    "current-time": "2013-01-01 12:34:56",
28    "system-info": "stdout" 
29}
30----  response の例 (ここまで)  --------------------------------
31             */
32            LinkedHashMap<String, String> result = JSON.decode(response, LinkedHashMap.class);
33            String status = result.get("status");
34            /*
35             * ジョブの状態は status の値。 例: "waiting", "running", "finished" 
36             */
37        } catch (HttpClientErrorException e) {
38            /*
39             * 入力値エラー等。
40             */
41        }

URI GET /blast/{Request-ID}?info=request (検索条件の確認)

指定された Request ID の検索条件を返します。

項目 説明
HTTP メソッド GET
URI "/blast/" + Request ID + "?info=request" + HTTP パラメーター
(例: "/blast/wabi_blast_1111-1111-1111-11-111-111111?info=request")
HTTP パラメーター format (デフォルト値 = "text") 応答データの形式 (例: "text", "json")

処理の流れ

  1. 入力値を検証します。
    入力値エラーが見つかった場合は、処理を中断して HTTP ステータス 400 Bad Request を返します。
  2. 指定された Request ID に対するジョブ情報を取得して、 検索条件 情報を取得します。
    検索結果の保存期間を過ぎている場合など、ジョブ情報が見つからなかった場合には、 HTTP ステータス 404 を返します。
  3. 取得した 検索条件 情報を format で指定された形式に整形して返します。
    ただし、利用不可能な format 値だった場合は HTTP ステータス 404 Not Found を返します。

  • 開発者向けの情報
    1. Springフレームワーク がリクエスト情報を request/BlastGetRequest にバインドします。
      format 値が未指定の場合、デフォルト値で代替します。
    2. Springフレームワーク がコントローラーの get(@PathVariable("id") String requestId, @ModelAttribute BlastGetRequest request, BindingResult errors, HttpServletRequest req) アクションを呼び出します。
      その際に errors は、リクエスト情報をバインドした際のエラー情報を格納しています。
    3. 入力値を検証します。
      入力値エラーが見つかった場合は、処理を中断して HTTP ステータス 400 Bad Request を返します。
      入力値エラーが存在する場合は、アクションが BadRequestException 例外を投げます。
      Springフレームワーク が、ハンドラー handlerException(BadRequestException e) が呼び出します。
      ハンドラーは、対応する HTTP ステータスを返します。
    4. 入力値 info の値に応じて場合分けします。
    5. 指定された Request ID に対するジョブ情報を取得して、 検索条件 情報を取得します。
      検索結果の保存期間を過ぎている場合など、ジョブ情報が見つからなかった場合には、 HTTP ステータス 404 を返します。
      job/JobInfo は、指定された Request ID に対応する作業ディレクトリーに user_request.json ファイルが存在するか調べます。
      検索条件ファイルが見つからなかった場合は HTTP エラーを返します。
    6. 取得した 検索条件 情報を format で指定された形式に整形して返します。
      ただし、利用不可能な format 値だった場合は HTTP ステータス 404 Not Found を返します。

入力値の検証内容

  1. requestId
    1. 必須チェック
    2. 英数字、 "-" 、 "_" 以外を含む場合、入力値エラーです。
    3. 実在する Request ID 以外の場合、入力値エラーです。
      一定日数を超えた検索結果は破棄されていますが、その場合も入力値エラーとして扱われます。
  2. 応答データの形式 format
    1. 必須チェック
    2. 未定義の値の場合、入力値エラーです。
  3. imageId
    1. 何も指定しないこと。
  4. info
    1. "request" を指定すること。

応答データの内容

  • 正常終了した場合
    • HTTP ステータスが 200 等の「成功」を示す値です。
    • BLAST検索ジョブを投入した際の各パラメーター情報です。
    • 実行の成否判定のためには HTTP ステータスを利用してください。
  • 異常終了した場合
    • HTTP ステータスが 400 等の「クライアントエラー」を示す値です。
    • 応答データの中からキー error-messages で取得できるエラーメッセージ情報には、入力値エラーとなったパラメーター名の情報等が含まれます。
    • 実行の成否判定のためには HTTP ステータスを利用してください。

入出力データの例

  • 入力値の例
    HTTP パラメーター 入力値
    format "requestfile"
    info "request"
  • 正常終了した場合の応答データ例 
    HTTP ステータス 200
 1{
 2        "address": "",
 3        "database": "hum",
 4        "datasets": "ddbjall",
 5        "format": "text",
 6        "parameters": " -v 100 -b 100 -e 10 -F F -W 11 ",
 7        "program": "blastn",
 8        "querySequence": ">my query sequence 1\nCACCCTCTCTTCACTGGAAAGGACACCATGAGCACGGAAAGCATGATCCAGGACGTGGAA\nGCTGGCCGAGGAGGCGCTCCCCAGGAAGACAGCAGGGCCCCAGGGCTCCAGGCGGTGCTG\nGTTCCTCAGCCTCTTCTCCTTCCTGCTCGTGGCAGGCGCCGCCAC\n",
 9        "result": "www" 
10}
  • 入力値エラーの場合の応答データ例 
    HTTP ステータス 404
 1{
 2        "Message": "Unexpected error ( Results of your request id have been NOT FOUND.)",
 3        "requestId": "wabi_blast_1111-1111-1111-11-111-111111",
 4        "format": "text",
 5        "imageId": null,
 6        "info": "result",
 7        "current-time": "2013-01-01 12:34:56",
 8        "error-messages": [
 9                "No such data: (requestId)" 
10        ],
11        "error-message": "NOT_FOUND (null)" 
12}

利用例

Java で SpringFramework の RESTクライアント を使う場合:

 1import java.util.LinkedHashMap;
 2import org.springframework.util.LinkedMultiValueMap;
 3import org.springframework.util.MultiValueMap;
 4import org.springframework.web.client.RestTemplate;
 5import org.springframework.web.client.HttpClientErrorException;
 6import net.arnx.jsonic.JSON;
 7
 8/*
 9 * (中略)
10 */
11
12        /*
13         * 覚えておいた Request ID を使って GET する。
14         */
15        String requestId = "wabi_blast_1111-1111-1111-11-111-111111";
16        MultiValueMap<String, String> parts = new LinkedMultiValueMap<String, String>();
17        parts.add("info", "request");
18        parts.add("format", "json");
19        try {
20            RestTemplate rest = new RestTemplate();
21            String response = rest.getForObject("http://ddbj.nig.ac.jp/wabi/blast/" + requestId, String.class, parts);
22            /*
23----  response の例 (ここから)  --------------------------------
24{
25    "address": "",
26    "database": "hum",
27    "datasets": "ddbjall",
28    "format": "json",
29    "parameters": " -v 100 -b 100 -e 10 -F F -W 11",
30    "program": "blastn",
31    "querySequence": ">my query sequence 1\nCACCCTCTCTTCACTGGAAAGGACACCATGAGCACGGAAAGCATGATCCAGGACGTGGAA\nGCTGGCCGAGGAGGCGCTCCCCAGGAAGACAGCAGGGCCCCAGGGCTCCAGGCGGTGCTG\nGTTCCTCAGCCTCTTCTCCTTCCTGCTCGTGGCAGGCGCCGCCAC\n      ",
32    "result": "www" 
33}
34----  response の例 (ここまで)  --------------------------------
35             */
36            LinkedHashMap<String, String> request = JSON.decode(response, LinkedHashMap.class);
37            /*
38             * ---- request の例 (ここから)  -------------------
39             * request["address"] == "" 
40             * request["database"] == "hum" 
41             * request["datasets"] == "ddbjall" 
42             * request["format"] == "json" 
43             * request["parameters"] == " -v 100 -b 100 -e 10 -F F -W 11" 
44             * request["program"] == "blastn" 
45             * request["querySequence"] == ">my query sequence 1\nCACCCTCTCTTCACTGGAAAGGACACCATGAGCACGGAAAGCATGATCCAGGACGTGGAA\nGCTGGCCGAGGAGGCGCTCCCCAGGAAGACAGCAGGGCCCCAGGGCTCCAGGCGGTGCTG\nGTTCCTCAGCCTCTTCTCCTTCCTGCTCGTGGCAGGCGCCGCCAC\n" 
46             * request["result"] == "www" 
47             * ---- request の例 (ここまで)  -------------------
48             */
49        } catch (HttpClientErrorException e) {
50            /*
51             * 入力値エラー等。
52             */
53        }

URI GET /blast/{Request-ID}?info=result (検索結果の閲覧)

指定された Request ID の検索結果を返します。

項目 説明
HTTP メソッド GET
URI "/blast/" + Request ID + "?info=result" + HTTP パラメーター
(例: "/blast/wabi_blast_1111-1111-1111-11-111-111111?info=result")
HTTP パラメーター format (デフォルト値 = "text") 応答データの形式 (例: "text", "json")

処理の流れ

  1. 入力値を検証します。
    入力値エラーが見つかった場合は、処理を中断して HTTP ステータス 400 Bad Request を返します。
  2. 指定された Request ID に対するジョブ情報を取得して、 検索結果 情報を取得します。
    検索結果の保存期間を過ぎていてジョブ情報が見つからなかった場合や検索処理が完了していなくて検索結果情報を取得できなかった場合、には、 HTTP ステータス 400, 404 等を返します。
  3. 取得した 検索結果 情報を format で指定された形式に整形して返します。
    ただし、利用不可能な format 値だった場合は HTTP ステータス 404 Not Found を返します。

  • 開発者向けの情報
    1. Springフレームワーク がリクエスト情報を request/BlastGetRequest にバインドします。
      format 値が未指定の場合、デフォルト値で代替します。
    2. Springフレームワーク がコントローラーの get(@PathVariable("id") String requestId, @ModelAttribute BlastGetRequest request, BindingResult errors, HttpServletRequest req) アクションを呼び出します。
      その際に errors は、リクエスト情報をバインドした際のエラー情報を格納しています。
    3. 入力値を検証します。
      入力値エラーが見つかった場合は、処理を中断して HTTP ステータス 400 Bad Request を返します。
      入力値エラーが存在する場合は、アクションが BadRequestException 例外を投げます。
      Springフレームワーク が、ハンドラー handlerException(BadRequestException e) が呼び出します。
      ハンドラーは、対応する HTTP ステータスを返します。
    4. 入力値 info の値に応じて場合分けします。
    5. 指定された Request ID に対するジョブ情報を取得して、 検索結果 情報を取得します。
      検索結果の保存期間を過ぎていてジョブ情報が見つからなかった場合や検索処理が完了していなくて検索結果情報を取得できなかった場合、には、 HTTP ステータス 400, 404 等を返します。
      job/JobInfo は、指定された Request ID に対応する作業ディレクトリーに blast_result.txt ファイルが存在するか調べます。
      BLAST 結果ファイルが見つからなかった場合は HTTP エラーを返します。
    6. 取得した 検索結果 情報を format で指定された形式に整形して返します。
      ただし、利用不可能な format 値だった場合は HTTP ステータス 404 Not Found を返します。

入力値の検証内容

  1. requestId
    1. 必須チェック
    2. 英数字、 "-" 、 "_" 以外を含む場合、入力値エラーです。
    3. 実在する Request ID 以外の場合、入力値エラーです。
      一定日数を超えた検索結果は破棄されていますが、その場合も入力値エラーとして扱われます。
  2. 応答データの形式 format
    1. 必須チェック
    2. 未定義の値の場合、入力値エラーです。
  3. imageId
    1. 何も指定しないこと。
  4. info
    1. "result" を指定すること。

応答データの内容

  • 正常終了した場合
    • HTTP ステータスが 200 等の「成功」を示す値です。
    • BLAST 検索が出力した結果ファイルの内容を返します。
    • 実行の成否判定のためには HTTP ステータスを利用してください。
  • 異常終了した場合
    • HTTP ステータスが 400 等の「クライアントエラー」を示す値です。
    • 応答データの中からキー error-messages で取得できるエラーメッセージ情報には、入力値エラーとなったパラメーター名の情報等が含まれます。
    • 実行の成否判定のためには HTTP ステータスを利用してください。

入出力データの例

  • 入力値の例
    HTTP パラメーター 入力値
    format "bigfile"
    info "result"
  • 正常終了した場合の応答データ例 
    HTTP ステータス 200
 1BLASTN 2.2.25 [Feb-01-2011]
 2
 3Reference: Altschul, Stephen F., Thomas L. Madden, Alejandro A. Schaffer,
 4Jinghui Zhang, Zheng Zhang, Webb Miller, and David J. Lipman (1997),
 5"Gapped BLAST and PSI-BLAST: a new generation of protein database search
 6programs",  Nucleic Acids Res. 25:3389-3402.
 7
 8Query= AB000095|AB000095.1 Homo sapiens mRNA for hepatocyte growth
 9factor activator inhibitor, complete cds.
10         (1740 letters)
11
12Database: hum
13           572,091 sequences; 5,019,832,159 total letters
14
15Searching..................................................done
16
17                                                                 Score    E
18Sequences producing significant alignments:                      (bits) Value
19
20AB000095|AB000095.1 Homo sapiens mRNA for hepatocyte growth fact...  3449   0.0
21BC018702|BC018702.1 Homo sapiens serine peptidase inhibitor, Kun...  3435   0.0
22BC004140|BC004140.1 Homo sapiens serine peptidase inhibitor, Kun...  3190   0.0
23BT007425|BT007425.1 Homo sapiens serine protease inhibitor, Kuni...  3053   0.0
24AY358969|AY358969.1 Homo sapiens clone DNA35880 HAI-1 (UNQ223) m...  2145   0.0
25AY296715|AY296715.1 Homo sapiens hepatocyte growth factor activa...  1984   0.0

    (後略)
  • 入力値エラーの場合の応答データ例 
    HTTP ステータス 400
 1{
 2        "Message": "Error ( Results of your request id have been NOT FOUND, or still running.)",
 3        "requestId": "wabi_blast_1111-1111-1111-11-111-111111",
 4        "format": "text",
 5        "imageId": null,
 6        "info": "result",
 7        "current-time": "2013-01-01 12:34:56",
 8        "error-messages": [
 9                "No such data: (requestId)" 
10        ],
11        "error-message": "NOT_FOUND (null)" 
12}

利用例

Java で SpringFramework の RESTクライアント を使う場合:

 1import java.util.LinkedHashMap;
 2import org.springframework.util.LinkedMultiValueMap;
 3import org.springframework.util.MultiValueMap;
 4import org.springframework.web.client.RestTemplate;
 5import org.springframework.web.client.HttpClientErrorException;
 6import net.arnx.jsonic.JSON;
 7
 8/*
 9 * (中略)
10 */
11
12        /*
13         * 覚えておいた Request ID を使って GET する。
14         */
15        String requestId = "wabi_blast_1111-1111-1111-11-111-111111";
16        MultiValueMap<String, String> parts = new LinkedMultiValueMap<String, String>();
17        parts.add("info", "result");
18        parts.add("format", "bigfile");
19        try {
20            RestTemplate rest = new RestTemplate();
21            String response = rest.getForObject("http://ddbj.nig.ac.jp/wabi/blast/" + requestId, String.class, parts);
22            /*
23----  response の例 (ここから)  --------------------------------
24BLASTN 2.2.25 [Feb-01-2011]
25
26Reference: Altschul, Stephen F., Thomas L. Madden, Alejandro A. Schaffer,
27Jinghui Zhang, Zheng Zhang, Webb Miller, and David J. Lipman (1997),
28"Gapped BLAST and PSI-BLAST: a new generation of protein database search
29programs",  Nucleic Acids Res. 25:3389-3402.
30
31Query= AB000095|AB000095.1 Homo sapiens mRNA for hepatocyte growth
32factor activator inhibitor, complete cds.
33         (1740 letters)
34
35Database: hum
36           572,091 sequences; 5,019,832,159 total letters
37
38Searching..................................................done
39
40                                                                 Score    E
41Sequences producing significant alignments:                      (bits) Value
42
43AB000095|AB000095.1 Homo sapiens mRNA for hepatocyte growth fact...  3449   0.0
44BC018702|BC018702.1 Homo sapiens serine peptidase inhibitor, Kun...  3435   0.0
45BC004140|BC004140.1 Homo sapiens serine peptidase inhibitor, Kun...  3190   0.0
46BT007425|BT007425.1 Homo sapiens serine protease inhibitor, Kuni...  3053   0.0
47AY358969|AY358969.1 Homo sapiens clone DNA35880 HAI-1 (UNQ223) m...  2145   0.0
48AY296715|AY296715.1 Homo sapiens hepatocyte growth factor activa...  1984   0.0
49----  response の例 (後略)  ------------------------------------
50             */
51        } catch (HttpClientErrorException e) {
52            /*
53             * 入力値エラー等。
54             */
55        }

URI GET /blast/{Request-ID}?imageId={Image-ID} (検索処理によって出力された画像データの取得)

指定された RequestID の検索処理が出力した画像データを返します。

項目 説明
HTTP メソッド GET
URI "/blast/" + RequestID + "?imageId=" + 画像ID + HTTP パラメーター
(例: "/blast/wabi_blast_1111-1111-1111-11-111-111111?imageId=1")
HTTP パラメーター format (デフォルト値 = "text") 応答データの形式 (例: "imagefile")

処理の流れ

  1. 入力値を検証します。
    入力値エラーが見つかった場合は、処理を中断して HTTP ステータス 400 Bad Request を返します。
  2. 指定された RequestID に対するジョブ情報を取得して、 BLAST 検索処理が出力した画像データ を取得します。
    検索結果の保存期間を過ぎていてジョブ情報が見つからなかった場合や検索処理が完了していなくて検索結果情報を取得できなかった場合、には、 HTTP ステータス 400, 404 等を返します。
  3. 取得した BLAST 検索処理が出力した画像データ 情報を format で指定された形式で返します。
    ただし、利用不可能な format 値だった場合は HTTP ステータス 404 Not Found を返します。

  • 開発者向けの情報
    1. Springフレームワーク がリクエスト情報を request/BlastGetRequest にバインドします。
      format 値が未指定の場合、デフォルト値で代替します。
    2. Springフレームワーク がコントローラーの get(@PathVariable("id") String requestId, @ModelAttribute BlastGetRequest request, BindingResult errors, HttpServletRequest req) アクションを呼び出します。
      その際に errors は、リクエスト情報をバインドした際のエラー情報を格納しています。
    3. 入力値を検証します。
      入力値エラーが見つかった場合は、処理を中断して HTTP ステータス 400 Bad Request を返します。
      入力値エラーが存在する場合は、アクションが BadRequestException 例外を投げます。
      Springフレームワーク が、ハンドラー handlerException(BadRequestException e) が呼び出します。
      ハンドラーは、対応する HTTP ステータスを返します。
    4. 入力値 info の値に応じて場合分けします。
    5. 指定された RequestID に対するジョブ情報を取得して、 BLAST 検索処理が出力した画像データ を取得します。
      検索結果の保存期間を過ぎていてジョブ情報が見つからなかった場合や検索処理が完了していなくて検索結果情報を取得できなかった場合、には、 HTTP ステータス 400, 404 等を返します。
      job/JobInfo は、指定された RequestID に対応する作業ディレクトリーに「RequestID + "_" + imageId + ".png" 」という名前の画像ファイルが存在するか調べます。
      BLAST 結果の画像ファイルが見つからなかった場合は HTTP エラーを返します。
    6. 取得した BLAST 検索処理が出力した画像データ 情報を format で指定された形式で返します。
      ただし、利用不可能な format 値だった場合は HTTP ステータス 404 Not Found を返します。

入力値の検証内容

  1. requestId
    1. 必須チェック
    2. 英数字、 "-" 、 "_" 以外を含む場合、入力値エラーです。
    3. 実在する requestId 以外の場合、入力値エラーです。
      一定日数を超えた検索結果は破棄されていますが、その場合も入力値エラーとして扱われます。
  2. 応答データの形式 format
    1. "imagefile" 以外の場合は、入力値エラーです。
  3. imageId
    1. 数字以外の場合は、入力値エラーです。
  4. info
    1. 未定義の値を指定した場合は、入力値エラーです。

応答データの内容

  • 正常終了した場合
    • HTTP ステータスが 200 等の「成功」を示す値です。
    • BLAST 検索処理が出力した画像データを返します。
    • 実行の成否判定のためには HTTP ステータスを利用してください。
  • 異常終了した場合
    • HTTP ステータスが 400 等の「クライアントエラー」を示す値です。
    • 応答データの中からキー error-messages で取得できるエラーメッセージ情報には、入力値エラーとなったパラメーター名の情報等が含まれます。
    • 実行の成否判定のためには HTTP ステータスを利用してください。

入出力データの例

  • 入力値の例
    HTTP パラメーター 入力値
    imageId "1"
    format "imagefile"
    info ""
  • 正常終了した場合の応答データ例 
    HTTP ステータス 200
(画像データ)
  • 入力値エラーの場合の応答データ例 
    HTTP ステータス 404
 1{
 2        "Message": "Error ( Blast image file of your request id have been NOT FOUND, or still running.)",
 3        "requestId": "wabi_blast_1111-1111-1111-11-111-111111",
 4        "format": "text",
 5        "imageId": null,
 6        "info": "result",
 7        "current-time": "2013-01-01 12:34:56",
 8        "error-messages": [
 9                "No such data: (requestId)" 
10        ],
11        "error-message": "NOT_FOUND (null)" 
12}

利用例

Java で HttpURLConnection を使う場合:

 1import java.io.BufferedInputStream;
 2import java.io.File;
 3import java.io.FileOutputStream;
 4import java.net.URL;
 5import java.net.HttpURLConnection;
 6
 7/*
 8 * (中略)
 9 */
10
11        /*
12         * この例では取得した画像をファイルに保存する。
13         */
14        File outputFile = ....;
15
16        /*
17         * 覚えておいた Request ID を使って GET する。
18         */
19        String requestId = "wabi_blast_1111-1111-1111-11-111-111111";
20        URL url = new URL("http://ddbj.nig.ac.jp/wabi/blast/" + requestId + "?imageId=" + imageId);
21        HttpURLConnection http = (HttpURLConnection)url.openConnection();
22        http.setRequestMethod("GET");
23        http.connect();
24        int responseCode = http.getResponseCode();
25        if (200<=responseCode && responseCode<=299) {
26            BufferedInputStream inputStream = new BufferedInputStream(http.getInputStream());
27            outputFile.createNewFile();
28            FileOutputStream outputStream new FileOutputStream(outputFile);
29            for (int data = inputStream.read(); -1!=(data = inputStream.read());) {
30                outputStream.write(data);
31            }
32            inputStream.close();
33            outputStream.close();
34        } else if (400<=responseCode && responseCode<=499) {
35            /*
36             * 入力値エラー等。
37             */
38        } else {
39            /*
40             * その他
41             */
42        }

Java で SpringFramework の RESTクライアント を使う場合:
※既知の問題のため、 RESTクライアント によっては画像データの変換に失敗します。

 1import java.awt.image.BufferedImage;
 2import java.io.File;
 3import java.util.List;
 4import java.util.LinkedHashMap;
 5import javax.imageio.ImageIO;
 6import org.springframework.http.converter.BufferedImageHttpMessageConverter;
 7import org.springframework.util.LinkedMultiValueMap;
 8import org.springframework.util.MultiValueMap;
 9import org.springframework.web.client.RestTemplate;
10import org.springframework.web.client.HttpClientErrorException;
11
12/*
13 * (中略)
14 */
15
16        /*
17         * この例では取得した画像をファイルに保存する。
18         */
19        File outputFile = ....;
20
21        /*
22         * 覚えておいた Request ID を使って GET する。
23         */
24        String requestId = "wabi_blast_1111-1111-1111-11-111-111111";
25        MultiValueMap<String, String> parts = new LinkedMultiValueMap<String, String>();
26        parts.add("imageId", "1");
27        parts.add("format", "imagefile");
28        try {
29            RestTemplate rest = new RestTemplate();
30            List converters = rest.getMessageConverters();
31            converters.add(new BufferedImageHttpMessageConverter());
32            rest.setMessageConverters(converters);
33            BufferedImage response = rest.getForObject("http://ddbj.nig.ac.jp/wabi/blast/" + requestId, BufferedImage.class, parts);
34            ImageIO.write(response, "PNG", outputFile);
35        } catch (HttpClientErrorException e) {
36            /*
37             * 入力値エラー等。
38             */
39        }

URI GET /blast/help/{Help-Command} (ヘルプ情報の閲覧)

WABI BLAST のヘルプ情報を返します。

項目 説明
HTTP メソッド GET
URI "/blast/help/" + Help-Command + HTTP パラメーター
(例: "/blast/help/list_program?format=json")
HTTP パラメーター format (デフォルト値 = "text") 応答データの形式 (例: "text", "json")
program BLAST プログラム (例: "blastn")

Help-Command

Help-Command 等 その他の HTTPパラメーター 参照できるヘルプ情報
list_datasets パラメーター データセット の定義値の一覧
list_database パラメーター データベース の定義値の一覧
list_program パラメーター BLASTプログラム の定義値の一覧
list_parameters program = パラメーター BLASTプログラム を指定 パラメーター BLASTプログラムのオプション指定 の定義値の一覧
list_format パラメーター 応答データの形式 の定義値の一覧
list_result パラメーター 結果取得方法 の定義値の一覧
list_info パラメーター 参照するジョブ情報の種類 の定義値の一覧

応答データの内容

  • 正常終了した場合
    • 指定されたヘルプ情報を返します。
  • 異常終了した場合
    • 指定可能な Help-Command 等の情報を返します。

入出力データの例

  • 入力値の例
    Help-Command 等 入力値
    Help-Command "list_result"
    format "json"
  • 正常終了した場合の応答データ例 
    1{
2    "result": [
3        "www",
4        "mail" 
5    ]
6}
  • 異常終了の場合の応答データ例 
     1{
 2    "help_commands": [
 3        "list_datasets",
 4        "list_database",
 5        "list_program",
 6        "list_parameters",
 7        "list_format",
 8        "list_result",
 9        "list_info" 
10    ],
11    "format": [
12        "text",
13        "json",
14        "xml" 
15    ]
16}

利用例

Java で SpringFramework の RESTクライアント を使う場合:

 1import java.util.LinkedHashMap;
 2import org.springframework.util.LinkedMultiValueMap;
 3import org.springframework.util.MultiValueMap;
 4import org.springframework.web.client.RestTemplate;
 5import org.springframework.web.client.HttpClientErrorException;
 6import net.arnx.jsonic.JSON;
 7
 8/*
 9 * (中略)
10 */
11
12            MultiValueMap<String, String> parts = new LinkedMultiValueMap<String, String>();
13            parts.add("format", "json");
14            RestTemplate rest = new RestTemplate();
15            String response = rest.getForObject("http://ddbj.nig.ac.jp/wabi/blast/help/list_result", String.class, parts);
16            /*
17----  response の例 (ここから)  --------------------------------
18{
19    "result": [
20        "www",
21        "mail" 
22    ]
23}
24----  response の例 (ここまで)  --------------------------------
25             */
26            LinkedHashMap<String, Object> result = JSON.decode(response, LinkedHashMap.class);
27            String result0 = (List<String>)result.get(0);
28            /*
29             * 例:
30             * result.size() == 2
31             * result0 == "www" 
32             */

URI GET /blast/{Request-ID}?info=result_stdout (検索処理の標準出力の閲覧)

※ これは、開発関係者のみが利用可能なアクション

指定された Request ID の検索処理が標準出力に出力した内容を返します。
具体的には、 qsub コマンドでキューに投入したジョブが標準出力に出力した内容を返します。

項目 説明
HTTP メソッド GET
URI "/blast/" + Request ID + "?info=result_stdout" + HTTP パラメーター
(例: "/blast/wabi_blast_1111-1111-1111-11-111-111111?info=result_stdout")
HTTP パラメーター format (デフォルト値 = "text") 応答データの形式 (例: "text", "json")

処理の流れ

  1. 入力値を検証します。
    入力値エラーが見つかった場合は、処理を中断して HTTP ステータス 400 Bad Request を返します。
  2. 指定された Request ID に対するジョブ情報を取得して、 検索結果 情報を取得します。
    検索結果の保存期間を過ぎていてジョブ情報が見つからなかった場合や検索処理が完了していなくて検索処理の標準出力を取得できなかった場合には、 HTTP ステータス 400, 404 等を返します。
  3. 取得した標準出力情報を format で指定された形式に整形して返します。
    ただし、利用不可能な format 値だった場合は HTTP ステータス 404 Not Found を返します。

  • 開発者向けの情報
    1. Springフレームワーク がリクエスト情報を request/BlastGetRequest にバインドします。
      format 値が未指定の場合、デフォルト値で代替します。
    2. Springフレームワーク がコントローラーの get(@PathVariable("id") String requestId, @ModelAttribute BlastGetRequest request, BindingResult errors, HttpServletRequest req) アクションを呼び出します。
      その際に errors は、リクエスト情報をバインドした際のエラー情報を格納しています。
    3. 入力値を検証します。
      入力値エラーが見つかった場合は、処理を中断して HTTP ステータス 400 Bad Request を返します。
      入力値エラーが存在する場合は、アクションが BadRequestException 例外を投げます。
      Springフレームワーク が、ハンドラー handlerException(BadRequestException e) が呼び出します。
      ハンドラーは、対応する HTTP ステータスを返します。
    4. 入力値 info の値に応じて場合分けします。
    5. qsub コマンドの標準出力にはシステム情報が含まれることがあるので、セキュリティ対策の観点から リクエスト元IPアドレス が DDBJ以外 の場合には、何もせずに HTTP エラーを返します。
    6. 指定された Request ID に対するジョブ情報を取得して、 検索結果 情報を取得します。
      検索結果の保存期間を過ぎていてジョブ情報が見つからなかった場合や検索処理が完了していなくて検索処理の標準出力を取得できなかった場合には、 HTTP ステータス 400, 404 等を返します。
      job/JobInfo は、指定された Request ID に対応する作業ディレクトリーに blast_result.txt ファイルが存在するか調べます。
      BLAST 結果ファイルが見つからなかった場合は HTTP エラーを返します。
    7. 取得した標準出力情報を format で指定された形式に整形して返します。
      ただし、利用不可能な format 値だった場合は HTTP ステータス 404 Not Found を返します。

入力値の検証内容

  1. requestId
    1. 必須チェック
    2. 英数字、 "-" 、 "_" 以外を含む場合、入力値エラーです。
    3. 実在する Request ID 以外の場合、入力値エラーです。
      一定日数を超えた検索結果は破棄されていますが、その場合も入力値エラーとして扱われます。
  2. 応答データの形式 format
    1. 必須チェック
    2. 未定義の値の場合、入力値エラーです。
  3. imageId
    1. 何も指定しないこと。
  4. info
    1. "result_stdout" を指定すること。

応答データの内容

  • 正常終了した場合
    • HTTP ステータスが 200 等の「成功」を示す値です。
    • 検索ジョブが出力した標準出力の内容を返します。
    • 実行の成否判定のためには HTTP ステータスを利用してください。
  • 異常終了した場合
    • HTTP ステータスが 400 等の「クライアントエラー」を示す値です。
    • 実行の成否判定のためには HTTP ステータスを利用してください。

入出力データの例

  • 入力値の例
    HTTP パラメーター 入力値
    format "json"
    info "result_stdout"

利用例

Java で SpringFramework の RESTクライアント を使う場合:

 1import java.util.LinkedHashMap;
 2import org.springframework.util.LinkedMultiValueMap;
 3import org.springframework.util.MultiValueMap;
 4import org.springframework.web.client.RestTemplate;
 5import org.springframework.web.client.HttpClientErrorException;
 6import net.arnx.jsonic.JSON;
 7
 8/*
 9 * (中略)
10 */
11
12        /*
13         * 覚えておいた Request ID を使って GET する。
14         */
15        String requestId = "wabi_blast_1111-1111-1111-11-111-111111";
16        MultiValueMap<String, String> parts = new LinkedMultiValueMap<String, String>();
17        parts.add("info", "result_stdout");
18        parts.add("format", "text");
19        try {
20            RestTemplate rest = new RestTemplate();
21            String response = rest.getForObject("http://ddbj.nig.ac.jp/wabi/blast/" + requestId, String.class, parts);
22        } catch (HttpClientErrorException e) {
23            /*
24             * 入力値エラー等。
25             */
26        }

URI GET /blast/{Request-ID}?info=result_stderr (検索処理の標準エラー出力の閲覧)

※ これは、開発関係者のみが利用可能なアクション

指定された Request ID の検索処理が標準エラー出力に出力した内容を返します。
具体的には、 qsub コマンドでキューに投入したジョブが標準エラー出力に出力した内容を返します。

項目 説明
HTTP メソッド GET
URI "/blast/" + Request ID + "?info=result_stderr" + HTTP パラメーター
(例: "/blast/wabi_blast_1111-1111-1111-11-111-111111?info=result_stderr")
HTTP パラメーター format (デフォルト値 = "text") 応答データの形式 (例: "text", "json")

処理の流れ

  1. 入力値を検証します。
    入力値エラーが見つかった場合は、処理を中断して HTTP ステータス 400 Bad Request を返します。
  2. 指定された Request ID に対するジョブ情報を取得して、 検索結果 情報を取得します。
    検索結果の保存期間を過ぎていてジョブ情報が見つからなかった場合や検索処理が完了していなくて検索処理の標準エラー出力を取得できなかった場合には、 HTTP ステータス 400, 404 等を返します。
  3. 取得した標準エラー出力情報を format で指定された形式に整形して返します。
    ただし、利用不可能な format 値だった場合は HTTP ステータス 404 Not Found を返します。

  • 開発者向けの情報
    1. Springフレームワーク がリクエスト情報を request/BlastGetRequest にバインドします。
      format 値が未指定の場合、デフォルト値で代替します。
    2. Springフレームワーク がコントローラーの get(@PathVariable("id") String requestId, @ModelAttribute BlastGetRequest request, BindingResult errors, HttpServletRequest req) アクションを呼び出します。
      その際に errors は、リクエスト情報をバインドした際のエラー情報を格納しています。
    3. 入力値を検証します。
      入力値エラーが見つかった場合は、処理を中断して HTTP ステータス 400 Bad Request を返します。
      入力値エラーが存在する場合は、アクションが BadRequestException 例外を投げます。
      Springフレームワーク が、ハンドラー handlerException(BadRequestException e) が呼び出します。
      ハンドラーは、対応する HTTP ステータスを返します。
    4. 入力値 info の値に応じて場合分けします。
    5. qsub コマンドの標準エラー出力にはシステム情報が含まれることがあるので、セキュリティ対策の観点から リクエスト元IPアドレス が DDBJ以外 の場合には、何もせずに HTTP エラーを返します。
    6. 指定された Request ID に対するジョブ情報を取得して、 検索結果 情報を取得します。
      検索結果の保存期間を過ぎていてジョブ情報が見つからなかった場合や検索処理が完了していなくて検索処理の標準エラー出力を取得できなかった場合には、 HTTP ステータス 400, 404 等を返します。
      job/JobInfo は、指定された Request ID に対応する作業ディレクトリーに blast_result.txt ファイルが存在するか調べます。
      BLAST 結果ファイルが見つからなかった場合は HTTP エラーを返します。
    7. 取得した標準エラー出力情報を format で指定された形式に整形して返します。
      ただし、利用不可能な format 値だった場合は HTTP ステータス 404 Not Found を返します。

入力値の検証内容

  1. requestId
    1. 必須チェック
    2. 英数字、 "-" 、 "_" 以外を含む場合、入力値エラーです。
    3. 実在する Request ID 以外の場合、入力値エラーです。
      一定日数を超えた検索結果は破棄されていますが、その場合も入力値エラーとして扱われます。
  2. 応答データの形式 format
    1. 必須チェック
    2. 未定義の値の場合、入力値エラーです。
  3. imageId
    1. 何も指定しないこと。
  4. info
    1. "result_stderr" を指定すること。

応答データの内容

  • 正常終了した場合
    • HTTP ステータスが 200 等の「成功」を示す値です。
    • 検索ジョブが出力した標準エラー出力の内容を返します。
    • 実行の成否判定のためには HTTP ステータスを利用してください。
  • 異常終了した場合
    • HTTP ステータスが 400 等の「クライアントエラー」を示す値です。
    • 実行の成否判定のためには HTTP ステータスを利用してください。

入出力データの例

  • 入力値の例
    HTTP パラメーター 入力値
    format "json"
    info "result_stderr"

利用例

Java で SpringFramework の RESTクライアント を使う場合:

 1import java.util.LinkedHashMap;
 2import org.springframework.util.LinkedMultiValueMap;
 3import org.springframework.util.MultiValueMap;
 4import org.springframework.web.client.RestTemplate;
 5import org.springframework.web.client.HttpClientErrorException;
 6import net.arnx.jsonic.JSON;
 7
 8/*
 9 * (中略)
10 */
11
12        /*
13         * 覚えておいた Request ID を使って GET する。
14         */
15        String requestId = "wabi_blast_1111-1111-1111-11-111-111111";
16        MultiValueMap<String, String> parts = new LinkedMultiValueMap<String, String>();
17        parts.add("info", "result_stderr");
18        parts.add("format", "text");
19        try {
20            RestTemplate rest = new RestTemplate();
21            String response = rest.getForObject("http://ddbj.nig.ac.jp/wabi/blast/" + requestId, String.class, parts);
22        } catch (HttpClientErrorException e) {
23            /*
24             * 入力値エラー等。
25             */
26        }

URI GET /blast (環境情報の確認)

※ これは、開発関係者のみが利用可能なアクション

環境情報を返します。
具体的には、環境変数の設定状況を返します。

項目 説明
HTTP メソッド GET
URI "/blast/?info=result_stderr" + HTTP パラメーター
(例: "/blast?info=env")
HTTP パラメーター format (デフォルト値 = "text") 応答データの形式 (例: "text", "json")
info (デフォルト値 = "env") 参照する環境情報の種類 (例: "env")

処理の流れ

  1. Springフレームワーク がリクエスト情報を request/BlastGetenvRequest にバインドします。
    format 値が未指定の場合、デフォルト値で代替します。
    info 値が未指定の場合、デフォルト値で代替します。
  2. Springフレームワーク がコントローラーの getenv(@ModelAttribute BlastGetenvRequest request, BindingResult errors, HttpServletRequest req) アクションを呼び出します。
    その際に errors は、リクエスト情報をバインドした際のエラー情報を格納しています。
  3. このアクションはセキュリティに関わるシステム情報を出力できるので、 リクエスト元IPアドレス が DDBJ以外 の場合には、何もせずに HTTPエラー を返します。
  4. 入力値を検証します。
    入力値エラーが見つかった場合は、処理を中断して HTTP ステータス 400 Bad Request を返します。
    入力値エラーが存在する場合は、アクションが BadRequestException 例外を投げます。
    Springフレームワーク が、ハンドラー handlerException(BadRequestException e) が呼び出します。
    ハンドラーは、対応する HTTP ステータスを返します。
  5. 現在の環境情報を取得します。
  6. 具体的には、次のコマンドをシェルで実行して環境変数の設定内容を取得します。 
    env | sort
  7. 取得した環境情報を format で指定された形式に整形して返します。
    ただし、利用不可能な format 値だった場合は HTTP ステータス 404 Not Found を返します。

入力値の検証内容

  1. 応答データの形式 format (省略可能)
    1. 未定義の値の場合、入力値エラーです。
  2. info (省略可能)
    1. "env" を指定すること。

応答データの内容

  • 正常終了した場合
    • HTTP ステータスが 200 等の「成功」を示す値です。
    • 環境情報の内容を返します。
    • 実行の成否判定のためには HTTP ステータスを利用してください。
  • 異常終了した場合
    • HTTP ステータスが 400 等の「クライアントエラー」を示す値です。
    • 実行の成否判定のためには HTTP ステータスを利用してください。

入出力データの例

  • 入力値の例
    HTTP パラメーター 入力値
    format "test"
    info "env"
ページの先頭へ戻る