ALPS チュートリアル

ALPSのチュートリアルは2部構成になっています：

1. 基本チュートリアル（このページ）
   • 実践的なハンズオン形式で、ALPSの基本的な使い方を学びます
   • ツールの使用方法から始めて、段階的にALPSの機能を理解していきます
   • ALPSを使い始めるための最初のステップとして最適です
2. 応用チュートリアル
   • ALPSの理論的な基盤と設計パターンについて学びます
   • REST/HTTPアプリケーションの状態遷移システムとしての本質を理解します
   • より深い理解を得たい方や、大規模なアプリケーション設計に携わる方向けです

まずはこの基本チュートリアルから始めることをお勧めします。

始める

このチュートリアルでは、ブラウザベースのALPSエディタを使用します：

1. ALPS Editor を開きます
2. 左側のエディターペインに表示されているデモコードを全て削除します

注：ローカル環境でASDアプリケーションを使用することもできますが、このチュートリアルではオンラインエディタの使用を推奨しています。

最初のステップ：空のファイルを用意する

ALPSドキュメントを作成するための最初のステップとして、基本となる空のファイルを用意します。これは、すべてのALPSドキュメントの出発点となる最小限の構造を持つファイルです。

ALPSドキュメントは、XMLまたはJSON形式で記述できます。それぞれの形式には対応するスキーマ（XMLはXSD、JSONはJson-Schema）があり、これを参照することでドキュメントの構造が正しく、ALPS仕様に沿っているかをチェックできます。どちらの形式を使っても機能的な違いはないので、チームの好みや普段使っているツールに合わせて選んでください。

XMLの場合：

<?xml version="1.0" encoding="UTF-8"?>
<alps
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://alps-io.github.io/schemas/alps.xsd">
</alps>

JSONの場合：

{
    "$schema": "https://alps-io.github.io/schemas/alps.json",
    "alps": {
        "descriptor": [
        ]
    }
}

意味をIDとして登録する

ALPSではアプリケーションが扱う特定の語句をIDとして定義します。最初にdateCreated（作成日付）という語句を加えてみましょう。

XMLの場合：

<?xml version="1.0" encoding="UTF-8"?>
<alps
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://alps-io.github.io/schemas/alps.xsd">
+    <descriptor id="dateCreated"/>
</alps>

JSONの場合：

{
    "$schema": "https://alps-io.github.io/schemas/alps.json",
    "alps": {
        "descriptor": [
+            {"id": "dateCreated"}
        ]
    }
}

語句を説明する

titleやdocで説明を加えられます。

XMLの場合：

<?xml version="1.0" encoding="UTF-8"?>
<alps
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="https://alps-io.github.io/schemas/alps.xsd">
-    <descriptor id="dateCreated"/>
+   <descriptor id="dateCreated" title="作成日付">
+      <doc format="text">ISO8601フォーマットで記事の作成日付を表します</doc>
+   </descriptor>
</alps>

JSONの場合：

{
    "$schema": "https://alps-io.github.io/schemas/alps.json",
    "alps": {
        "descriptor": [
-            {"id": "dateCreated"}
+            {"id": "dateCreated", "title": "作成日付", "doc": {"format": "text", "value": "ISO8601フォーマットで記事の作成日付を表します"}}
        ]
    }
}

titleは見出しのような簡潔な表現、docはより長いテキストでの説明です。

この意味に紐づけられたIDをセマンティックディスクリプタ（意味的記述子）といいます。dateCreatedは「作成日付」という意味を紐づけたセマンティックディスクリプタです。このような意味や概念の定義をオントロジーといいます。

ボキャブラリ

ALPSの重要な役割の１つはアプリケーションの語句の辞書になることです。利用者が同じ意味を指し示すときは同じ語句を使い、表現の揺れを防いだり、利用者が違った認識を持つことを防止します。

情報は情報を含む

セマンティックディスクリプタはセマンティックディスクリプタを含むことがあります。

例えば、BlogPosting（ブログ記事）はarticleBody（本文）とdateCreated（作成日付）を含みます。descriptorの中にdescriptorを記述することで情報の階層を表します。このような情報の構成や配置がタクソノミーです。

XMLの場合：

<alps
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://alps-io.github.io/schemas/alps.xsd">
    
    <!-- Ontology -->
    <descriptor id="id" title="id"/>
    <descriptor id="articleBody" title="本文"/>
    <descriptor id="dateCreated" title="作成日付"/>

    <!-- Taxonomy -->
    <descriptor id="BlogPosting" title="記事" >
        <descriptor href="#id"/>
        <descriptor href="#dateCreated"/>
        <descriptor href="#articleBody"/>
    </descriptor>
    <descriptor id="Blog" title="記事リスト">
        <descriptor href="#BlogPosting"/>
    </descriptor>
</alps>

JSONの場合：

{
    "$schema": "https://alps-io.github.io/schemas/alps.json",
    "alps": {
        "descriptor": [
            {"id": "id", "title": "id"},
            {"id": "articleBody", "title": "本文"},
            {"id": "dateCreated", "title": "作成日付"},
            {"id": "BlogPosting", "title": "記事", "descriptor": [
                {"href": "#id"},
                {"href": "#dateCreated"},
                {"href": "#articleBody"}
            ]},
            {"id": "Blog", "title": "記事リスト", "descriptor": [
                {"href": "#BlogPosting"}
            ]}
        ]
    }
}

#を使って他のdescriptorを参照する事ができます。これをインラインリンクと呼び１つのdescriptorを複数の箇所から参照する事ができます。

情報の閲覧と操作

Webのページは情報だけでなく他のページへのリンクやアクションのフォームを含み、関連する情報の閲覧や操作ができます。以下の３種類の操作が出来ます。

safe

関連する情報の閲覧。HTMLで言うとAタグ、HTTPではGETです。リソースの状態を変更しない安全な遷移です。ユーザーが何を見ているかというアプリケーション状態が変化します。つまり閲覧しているURLが変わります。

idempotent

リソース状態を変更します。冪等性（べきとうせい）があり、何度繰り返しても同じ結果になります。ファイルの上書きをイメージしてください。何度実行しても結果は変わりません。

unsafe

idempotentと同じようにリソース状態は変更しますが冪等性がありません。ファイルの追記をイメージしてください。繰り返し実行しただけ結果が異なってきます。

HTTPメソッドとの対応

safeはGET、idempotentはPUTまたはDELETE、unsafeはPOSTとそれぞれのHTTPのメソッドに対応します。

リンク

typeで操作の種類、rtで遷移先を指定してリンクを作成します。 この例はBlogを閲覧するリンクです。

XMLの場合：

<descriptor type="safe" id="goBlog" rt="#Blog" title="ブログ記事リストを見る" />

JSONの場合：

{"type": "safe", "id": "goBlog", "rt": "#Blog", "title": "ブログ記事リストを見る"}

この例はブログ記事からブログ記事リストに戻る操作を追加しています。

XMLの場合：

<descriptor id="BlogPosting" title="記事">
    <descriptor href="#id"/>
    <descriptor href="#dateCreated"/>
    <descriptor href="#articleBody"/>
    <descriptor href="#goBlog" />
</descriptor>

JSONの場合：

{"id": "BlogPosting", "title": "記事", "descriptor": [
    {"href": "#id"},
    {"href": "#dateCreated"},
    {"href": "#articleBody"},
    {"href": "#goBlog"}
]}

遷移や操作に必要なdescriptorはdescriptorに含めます。

XMLの場合：

<descriptor id="goBlogPosting" type="safe" rt="#BlogPosting" title="記事を見る">
    <!-- 記事を見るにはIDが必要 -->
    <descriptor href="#id"/>
</descriptor>

JSONの場合：

{"id": "goBlogPosting", "type": "safe", "rt": "#BlogPosting", "title": "記事を見る", "descriptor": [
   {"href": "#id"}
]}

ブログ記事リストとブログ記事双方のリンクを追加してみましょう。

XMLの場合：

<alps
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://alps-io.github.io/schemas/alps.xsd">
    
    <!-- Ontology -->
    <descriptor id="id" title="id"/>
    <descriptor id="articleBody" title="本文"/>
    <descriptor id="dateCreated" title="作成日付"/>

    <!-- Taxonomy -->
    <descriptor id="BlogPosting" title="記事" >
        <descriptor href="#id"/>
        <descriptor href="#dateCreated"/>
        <descriptor href="#articleBody"/>
        <descriptor href="#goBlog" />
    </descriptor>
    <descriptor id="Blog" title="記事リスト">
        <descriptor href="#BlogPosting"/>
        <descriptor href="#goBlogPosting" />
    </descriptor>

    <!-- Choreography -->
    <descriptor type="safe" id="goBlog" rt="#Blog" title="記事リストを見る" />
    <descriptor type="safe" id="goBlogPosting" rt="#BlogPosting" title="記事を見る">
        <descriptor href="#id"/>
    </descriptor>
</alps>

JSONの場合：

{
    "$schema": "https://alps-io.github.io/schemas/alps.json",
    "alps": {
        "descriptor": [
            {"id": "id", "title": "id"},
            {"id": "articleBody", "title": "本文"},
            {"id": "dateCreated", "title": "作成日付"},
            {"id": "BlogPosting", "title": "記事", "descriptor": [
                {"href": "#id"},
                {"href": "#dateCreated"},
                {"href": "#articleBody"},
                {"href": "#goBlog"}
            ]},
            {"id": "Blog", "title": "記事リスト", "descriptor": [
                {"href": "#BlogPosting"},
                {"href": "#goBlogPosting"}
            ]},
            {"type": "safe", "id": "goBlog", "rt": "#Blog", "title": "記事リストを見る"},
            {"type": "safe", "id": "goBlogPosting", "rt": "#BlogPosting", "title": "記事を見る", "descriptor": [
               {"href": "#id"}
            ]}
        ]
    }
}

アプリケーション状態遷移図

記事リスト、記事、双方からリンクされた状態遷移図が表示されます。四角のボックスのはユーザーがどこを見ているかというアプリケーション状態、つまり閲覧中のWebページです。矢印は情報の閲覧や変更などの操作を表します。HTMLでのAタグやFORMタグの遷移に該当します。ボックスや矢印をクリックすると詳しい情報が見られます。確認してみましょう。

Webサイトの情報が相互にリンクされているように、ASDドキュメントページも相互にリンクされています。アプリケーション状態遷移図はサイトの情報設計を俯瞰することができ、情報の意味や構造、接続といった情報設計の詳細にリンクしています。