プロジェクト構成 の記事で、コンポーネントが .html・.wod・任意の .api・任意の .md を持つ .wo フォルダであることを見ました。この記事では その .api ファイルを取り上げます。.api はコンポーネントの一部なので、これは Component Editor の予習にもなります。

.api ファイルは、コンポーネントの 公開バインディング（そのインターフェース）を宣言します。つまり 「これが受け付けるバインディングで、これは必須、これは真偽値を期待する」 ということを表します。必ずしも 必要ではありませんが、あると各種ツールがそれを活用します。WOD エディターはコンポーネントのバインディングに 対して オートコンプリートとバリデーション を提供し、Component Editor はそのコンポーネントが何を期待して いるかを把握できます。

.api ファイルの中身

小さな XML ファイルです。API エディターを使えばフォームとして編集できるので、XML を手で触る必要はありません。 実際に書き出されるのは次のような内容です。

<?xml version="1.0" encoding="UTF-8"?>
<tbdefinitions>
    <tb class="MyComponent.java" tbcomponentcontent="false">
        <binding name="editingContext"/>
        <binding defaults="Boolean" name="allowHiding"/>
        <validation message="'editingContext' is a required binding.">
            <unbound name="editingContext"/>
        </validation>
    </tb>
</tbdefinitions>

• <tb class="…"> – この API が属するコンポーネント
• tbcomponentcontent – コンポーネントが他のコンテンツを ラップ できるかどうか（HTML のコンテナのように）
• <binding name="…"> – 公開バインディングごとに 1 つ。defaults="…" はその Value Set を記録します
• <validation> / <unbound> – 必須 バインディングの表し方

エディターの構成

Component Content

上部のチェックボックスで tbcomponentcontent を設定します。コンポーネントが親から渡されたコンテンツを ラップする場合にオンにします。

バインディング一覧

コンポーネントの公開バインディングの一覧です。必須 のバインディングは 太字 で表示されます。 Add / Remove で追加・削除します。

バインディングの詳細

バインディングを選択すると、右側のパネルに次の項目が表示されます。

Value Set の選択肢

Value Set は、そのバインディングが何を期待するかをエディターに伝えるもので、.wod エディターが オートコンプリートできるようにします。

知っておくと便利なこと

• .api は 任意 です — なくてもコンポーネントは動作します。宣言された、オートコンプリートと バリデーションの効くインターフェースをコンポーネントに与えるために追加します。他のコンポーネントから 再利用されるものには付けることをおすすめします。
• Required はバインディングの属性ではなく、<unbound> エントリを含む独立した <validation> ブロック です。これが一覧でバインディングを太字にし、指定が漏れているときに .wod で警告する仕組みです。
• バインディング名はコンポーネントの Java アクセサメソッドと揃えましょう — .html・.wod・.api・.java がすべて同じ名前で会話できるようになります。

関連記事

• Component Editor — .api が属する .wo バンドル (次の記事)
• プロジェクト構成 — .wo の構造

In the Project Layout post we saw a component is a .wo folder holding .html, .wod, an optional .api, and an optional .md. This post is about that .api file — and it’s really a warm-up for the Component Editor, because the .api is part of a component.

An .api file declares a component’s public bindings — its interface. It says “these are the bindings I accept, this one is required, this one expects a boolean.” You don’t strictly need it, but when it’s there the tooling uses it: the WOD editor offers autocomplete and validation for the component’s bindings, and the Component Editor knows what the component expects.

What a .api file looks like

It’s a small XML file. The API Editor lets you edit it as a form so you never touch the XML by hand, but here is what it writes:

<?xml version="1.0" encoding="UTF-8"?>
<tbdefinitions>
    <tb class="MyComponent.java" tbcomponentcontent="false">
        <binding name="editingContext"/>
        <binding defaults="Boolean" name="allowHiding"/>
        <validation message="'editingContext' is a required binding.">
            <unbound name="editingContext"/>
        </validation>
    </tb>
</tbdefinitions>

• <tb class="…"> – the component this API belongs to
• tbcomponentcontent – whether the component can wrap other content (like an HTML container)
• <binding name="…"> – one per public binding; defaults="…" records its Value Set
• <validation> / <unbound> – how a required binding is expressed

Editor Layout

Component Content

A checkbox at the top sets tbcomponentcontent. Turn it on when the component wraps content passed in by its parent.

Bindings List

The list of the component’s public bindings. Required bindings are shown in bold. Use Add / Remove to manage them.

Binding Details

Select a binding and the right panel shows:

Value Set options

The Value Set tells the editor what a binding expects, so the .wod editor can autocomplete it:

Good to know

• The .api is optional — a component works without one. You add it to give the component a declared, autocompleting, validated interface. Recommended for anything reused by other components.
• Required is not an attribute on the binding — it’s a separate <validation> block with an <unbound> entry. That’s what turns the binding bold in the list and what warns you in the .wod when it’s missing.
• Match binding names to the component’s Java accessor methods — it keeps the .html, .wod, .api and .java all speaking the same names.

Related

• The Component Editor — the .wo bundle the .api belongs to (next post)
• Project Layout — the .wo anatomy

これは もう一方の マイグレーション — データベースの構造 をモデルに合わせて保つためのものです。EO マイグレーション（データ）エディタと混同しやすいので、まずは 1 行で違いを整理します。

エンティティを変更して ハッシュがオレンジ色になったら、スキーママイグレーションでデータベースを追従させます。

Generate Migration

Entity Editor のツールバーで Generate Migration を押すと、次のダイアログが表示されます。

• Package – 生成されるクラスの配置先（デフォルトはモデルの …migrations パッケージ）
• Migration Number – このマイグレーションの連番（後述の 採番 を参照）
• Entities to include – このマイグレーションが対象とするエンティティにチェックを入れます（デフォルトは Select all）
• Preview – 実際に書き出される Java。オプションを変更するとその場で更新されます

オプション

• Model Dependencies – このマイグレーションが他のモデルのマイグレーションに依存することを宣言し、モデルをまたいだ順序を正しく保ちます
• New Automatic – すべてのカラムを書き下す代わりに、現在のモデルバージョンからスキーマを導出する 自動 マイグレーションを生成します
• Transformation – 変換フックを含めます（構造変更に伴ってデータを整形するため）
• Run Migration – SQL データを読み込むエリア（各データベースのコールバック有り）

生成される内容

スキーママイグレーションは実際の Java クラス です。名前はモデルのプレフィックス + マイグレーション番号（例：TBTag0）で、TBEnterpriseMigrationDatabase.Migration を継承します。1 つのマイグレーションクラスが、チェックしたすべてのエンティティをカバーします。処理は 3 つのパス に分かれています。

public class TBTag0 extends TBEnterpriseMigrationDatabase.Migration {

    @Override
    public void upgrade(TBEnterpriseEditingContext ec, TBEnterpriseMigrationDatabase database) {
        var table = database.newTableByEntity(TBTagStore.clazz.entity());
        table.newStringColumn("name_en", 255, NOT_NULL);
        table.newBooleanColumn("locked", NOT_NULL);
        // … one table per entity, each with its columns
    }

    @Override
    public void foreignKeyUpgrade(TBEnterpriseEditingContext ec, TBEnterpriseMigrationDatabase database) {
        var table = database.existingTableByEntity(TBTagConnection.clazz.entity());
        table.addForeignKey("idTag", TBTagStore.clazz.entity(), "id");
    }

    @Override
    public void indexUpgrade(TBEnterpriseEditingContext ec, TBEnterpriseMigrationDatabase database) {
        safeAddIndex(database, TBTagStore.clazz.entity(), _TBTagStore.NAME_EN_KEY);
    }
}

• upgrade – テーブルとそのカラムを作成します（newStringColumn・newIntegerColumn・newBooleanColumn … に NOT_NULL / ALLOWS_NULL を指定）
• foreignKeyUpgrade – 外部キーを追加します
• indexUpgrade – インデックスを追加します（およびデータベース固有のチューニング）

なぜ 3 パスなのか？ 外部キーは、すべてのテーブルが存在した 後 に追加されます — まだ作成されていないテーブルを外部キーで参照することはできないからです。そこで、まずすべてのテーブルとカラムを作成し（upgrade）、次にそれらを結ぶキーを追加し（foreignKeyUpgrade）、最後にインデックスを追加します。

採番

EO マイグレーションと同様に、番号は恒久的で順序を持つ履歴 です。TBTag0 はマイグレーション 0 で、そのモデルへの次の構造変更は 新しい クラス TBTag1、その次は TBTag2、というように続きます。すでにどこかで実行済みのマイグレーションは決して編集せず、次の番号を追加します。フレームワークは各データベースがどの番号まで進んでいるかを記録し、まだ適用していないものだけを実行します。

EO マイグレーション（Migration Editor で編集する .xml ファイル）とは異なり、スキーママイグレーションは 素の Java です。生成後は通常の Java エディタで開いて手動で調整できます。

関連記事

• Entity Editor — Generate Migration がある場所
• EO Migration Editor — データ のマイグレーション、もう一方の種類
• プロジェクト構成

This is the other migration — the one that keeps the database structure in step with your model. It is easy to confuse with the EO Migration (data) editor, so the one-line difference first:

When you change an entity and its hash turns orange, a schema migration is how you bring the database along.

Generate Migration

Press Generate Migration in the Entity Editor toolbar and you get this dialog:

• Package – where the generated class goes (defaults to your model’s …migrations package)
• Migration Number – the sequence number for this migration (see Numbering below)
• Entities to include – tick the entities this migration should cover (Select all by default)
• Preview – the exact Java that will be written, updated live as you change the options

Options

• Model Dependencies – declare that this migration depends on other models’ migrations, so cross-model order is correct
• New Automatic – generate an automatic migration that derives the schema from the current model version, instead of spelling out every column
• Transformation – include a transformation hook (for reshaping data as part of the structural change)
• Run Migration – apply data sql loading to the migration that should run for data import

What gets generated

A schema migration is a real Java class — the model’s prefix and the migration number (e.g. TBTag0) — that extends TBEnterpriseMigrationDatabase.Migration. One migration class covers all the entities you ticked. It does its work in three passes:

public class TBTag0 extends TBEnterpriseMigrationDatabase.Migration {

    @Override
    public void upgrade(TBEnterpriseEditingContext ec, TBEnterpriseMigrationDatabase database) {
        var table = database.newTableByEntity(TBTagStore.clazz.entity());
        table.newStringColumn("name_en", 255, NOT_NULL);
        table.newBooleanColumn("locked", NOT_NULL);
        // … one table per entity, each with its columns
    }

    @Override
    public void foreignKeyUpgrade(TBEnterpriseEditingContext ec, TBEnterpriseMigrationDatabase database) {
        var table = database.existingTableByEntity(TBTagConnection.clazz.entity());
        table.addForeignKey("idTag", TBTagStore.clazz.entity(), "id");
    }

    @Override
    public void indexUpgrade(TBEnterpriseEditingContext ec, TBEnterpriseMigrationDatabase database) {
        safeAddIndex(database, TBTagStore.clazz.entity(), _TBTagStore.NAME_EN_KEY);
    }
}

• upgrade – creates the tables and their columns (newStringColumn, newIntegerColumn, newBooleanColumn, … with NOT_NULL / ALLOWS_NULL)
• foreignKeyUpgrade – adds the foreign keys
• indexUpgrade – adds the indexes (and any database-specific tuning)

Why three passes? Foreign keys are added after every table exists — you can’t point a foreign key at a table that hasn’t been created yet. So all tables and columns go in first (upgrade), then the keys that link them (foreignKeyUpgrade), then the indexes.

Numbering

Like EO migrations, the number is a permanent, ordered history. TBTag0 is migration 0; the next structural change to that model is a new class TBTag1, then TBTag2, and so on. You never edit a migration that has already run somewhere — you add the next number. The framework tracks which number a database is on and applies only the ones it hasn’t seen.

Unlike an EO migration (an .xml file you edit in the Migration Editor), a schema migration is plain Java — once generated you can open and hand-tune it in the normal Java editor.

Related

• The Entity Editor — where Generate Migration lives
• The EO Migration Editor — the data migration, the other kind
• Project Layout

TreasureBoat には名前に「マイグレーション」と付くものが 2 つ あり、混同しがちです。 まずはこの 2 つを区別しておきましょう。この記事で扱うのは 2 つ目だけです。

つまり、スキーママイグレーションはデータベースの 形 を変え、EO マイグレーションはそこにデータを入れます（あるいはデータを変更・削除します）。このエディタは後者、すなわち Project Layout の記事で見た EOMigration/ や EOTestMigration/ の中にある .xml ファイルを扱うものです。

EO マイグレーションとは

EO マイグレーションとは、アプリケーションの起動時 に実行され、Enterprise Object を作成・更新・削除する小さな .xml ファイルです。アプリに存在していてほしいシードデータ — CMS ページ、ロール、ポリシー、ナビゲーションバー、スケジュールジョブなど — を用意します。

• ファイルは EOMigration/（全環境）または EOTestMigration/（開発・テスト専用）に置かれます。
• 番号付き（1001_…、0101_…）で、順番どおり に実行されます。
• 一度リリースしたマイグレーションは 変更不可 です — 古いファイルは決して編集せず、変更は 新しい 番号のファイルに入れます。（番号は恒久的で順序を持った履歴です。）

File Settings

各ファイルは 1 つの操作ブロック であり、エディタ上部で設定します。

• Root Type – ファイル全体の操作：Create、Update、Delete、または SaveChanges
• Target – 適用する環境。例：dev,common,deploy
• Condition – 冪等性のためのガード：条件が真のときだけブロックが実行されます。典型的には !hasEoForKey('TBPolicy.<uuid>') — 「まだ存在しない場合だけ作成する」 という意味です。これにより、起動のたびにマイグレーションが実行されてもデータが重複しないようになっています。
• Version – (任意) マイグレーションが対象とするモデルバージョン
• Face – (任意) 特定のフェイスに限定します。例：{FaceId1},{FaceId2}
• LockingEO – (任意) マイグレーション実行中にロックするストアドプロパティ

知っておくと便利: 1 ファイルにつき操作ブロックは 1 つ にしてください。1 つのファイルを 複数のブロックに分けると確実には実行されません — 別の番号のファイルに分けましょう。

EO リスト（左）

設定の下には、操作の対象となる Enterprise Object の一覧が表示されます。各行が 1 つのオブジェクトで、Entity (identifier) の形式で表示されます。例：TBPolicy (show.navigation)。リスト上部の小さなツールバーで行の追加・削除・並べ替えができます。

Properties / XML Preview（右）

行を選択すると、右側に 2 つのタブが表示されます。

• Properties – オブジェクトを編集します：
  • Entity – EO のエンティティ種別（例：TBKVDataStorage）
  • _qualifier – このオブジェクトを 識別する キー。Create では Condition のチェックに使われる識別子であり、Update/Delete では変更対象の既存オブジェクトを 見つける ためのキーです。
  • Attribute / Value テーブル – 設定するフィールドの値
• XML Preview – ディスクに書き込まれる実際の XML。保存する前に一度目を通しておくとよいでしょう。

4 つの操作

関連

• Entity Editor — その Generate Migration ボタン（もう一方の スキーマ マイグレーション）
• Project Layout — EOMigration/ と EOTestMigration/ の場所
• スキーママイグレーション — スキーママイグレーションファイルの編集 (次の記事)

TreasureBoat has two things with “migration” in the name, and they are easy to mix up. Let’s separate them first, because this post is only about the second:

So: schema migrations change the shape of the database; EO migrations put data in it (or change/remove data). This editor is for the second kind — the .xml files under EOMigration/ and EOTestMigration/ you saw in the Project Layout post.

What an EO migration is

An EO migration is a small .xml file that runs at application boot and creates, updates or deletes Enterprise Objects — the seed data your app needs to exist: CMS pages, roles, policies, navigation bars, scheduled jobs, and so on.

• Files live in EOMigration/ (all environments) or EOTestMigration/ (dev/test only).
• They are numbered (1001_…, 0101_…) and run in order.
• Once a migration has shipped it is immutable — you never edit an old file; a new change goes in a new numbered file. (The numbers are a permanent, ordered history.)

File Settings

Each file is one operation block, configured at the top of the editor:

• Root Type – the operation for the whole file: Create, Update, Delete, or SaveChanges
• Target – which environments it applies to, e.g. dev,common,deploy
• Condition – an idempotency guard: the block only runs if the condition is true. Typically !hasEoForKey('TBPolicy.<uuid>') — “only create this if it isn’t already there.” This is what makes it safe for the migration to run on every boot without duplicating data.
• Version – (optional) a model version the migration targets
• Face – (optional) limit the migration to specific faces, e.g. {FaceId1},{FaceId2}
• LockingEO – (optional) a stored property to lock on while the migration runs

Good to know: keep one operation block per file. Splitting a file into several blocks does not execute reliably — make a separate numbered file instead.

The EO list (left)

Below the settings is the list of Enterprise Objects the operation acts on — each row is one object, shown as Entity (identifier), for example TBPolicy (show.navigation). The small toolbar above the list adds, removes and reorders rows.

Properties / XML Preview (right)

Select a row and the right side gives you two tabs:

• Properties – edit the object:
  • Entity – the EO entity type (e.g. TBKVDataStorage)
  • _qualifier – the key that identifies this object. For Create it’s the identity used by the Condition check; for Update/Delete it’s how the migration finds the existing object to change.
  • Attribute / Value table – the field values to set
• XML Preview – the exact XML that will be written to disk. Always worth a glance before saving.

The four operations

Related

• The Entity Editor — and its Generate Migration button (the schema migration, the other kind)
• Project Layout — where EOMigration/ and EOTestMigration/ live
• The Schema Migrations — editing the Schema migration files (next post)

プロジェクト構成 の記事では、resources フォルダに .eomodeld（EO モデル）が入っていることを見ました。この記事では、それを 編集するためのエディタを取り上げます。

EOModel は TreasureBoat のオブジェクト・リレーショナルマッピングです。エンティティ （テーブル）、その属性（カラム）、そしてそれらの間のリレーションシップ（結合）を、Java コード内のアノテーションではなく、宣言的にデータとして記述します。.eomodeld を開くと、 プラグインは生の plist ファイルではなく、ビジュアルな エンティティエディタ を提供します。

EOModel とは

.eomodeld は単一のファイルではなく、NeXTSTEP 形式の plist ファイルをまとめた バンドル（フォルダ）です。

• index.eomodeld – モデルのメタデータ（接続情報、命名規則）
• エンティティごとの .plist – そのエンティティの属性・リレーションシップ・フェッチ仕様

これらの plist を手で編集する必要はありません。そのためのエディタです。

エディタの構成

エディタには 2 つのパネルがあります。左側の ツリー と、右側の プロパティパネル です。

エンティティツリー（左）

ツリーにはモデル全体の構造が表示されます。

• Model – .eomodeld バンドル（ルート）
  • Entity – モデル内の各エンティティ
    • Attributes – カラム
    • Relationships – 他のエンティティへの結合
    • Fetch Specifications – あらかじめ定義された名前付きクエリ
    • Indexes – データベースのインデックス

ノードを右クリックすると、エンティティ・属性・リレーションシップ・フェッチ仕様・インデックスの 追加や削除、エンティティの サブクラス 作成ができます。

また、必要に応じて次のファイルも作成できます。

• Create REST Controller…
• Create Sangria Rules…
• Create Sangria Delegate…

プロパティパネル（右）

任意のノードを選択すると、右側のパネルにそのプロパティが表示され、編集できます — 属性の カラムや型、リレーションシップの参照先や削除ルールなどです。

ツールバー

押さえておきたいプロパティ

エンティティ

ベーシック・パネル

アドバンスト・パネル

ローカライズ・パネル

属性

知っておくと便利: isClassProperty が付いた属性だけが Java のアクセサを持ちます。 テーブルには存在するがクラスプロパティではないカラム（たとえば生の外部キーカラム）は、 モデルには残りますが、EO のメソッドとしては現れません。

プロトタイプとは? プロトタイプは、カラムのデータベース型・Java の値型・幅をまとめた 名前付きテンプレートです。それぞれを手で設定する代わりに、プロトタイプ（uuid、 varchar255、date など）を選ぶと、属性がそれらをすべて引き継ぎます。覚えておきたい 落とし穴が 1 つあります。uuid プロトタイプはカラム名を既定で uuid にするため、 uuid の主キーや外部キーでは columnName = id を明示的に設定しなければなりません。 さもないと、生成される SQL が “column uuid does not exist” で失敗します。

ベーシック・パネル

アドバンスト・パネル

ドキュメント・パネル

リレーションシップ

ベーシック・パネル

アドバンスト・パネル

エンティティハッシュ

ツールバーには、選択中のエンティティの小さな ハッシュ が表示されます。これはエンティティの 構造 — 属性・リレーションシップ・型 — の指紋です。その色は、最後に保存したマイグレーション 以降に構造が変わったかどうかを示します。

• グレー – 保存済みのハッシュと一致（構造変更なし）
• オレンジ – 保存済みのハッシュと相違（構造が変わった — 新しいマイグレーションがおそらく必要）
• ブルー – 新規、保存済みのハッシュがまだない

ハッシュをクリックするとクリップボードにコピーされます。

知っておくと便利: ハッシュは、データベースをモデルと同期させておくためのリマインダー です。オレンジ になったら、それが Generate Migration を押す合図です。

モデルからコードへ — Generate EO

Generate EO は、Template Path で設定した Velocity テンプレートを使って、モデルを Java に変換します。これが プロジェクト構成 の記事で 触れた generated/ フォルダを埋めるものです。各エンティティごとに、KVC のアクセサと リレーションシップを持つ アンダースコア始まりのベースクラス（_MyEntity.java）が 書き出されます。これらは編集しないでください — 再生成すると上書きされます。あなたの ビジネスロジックは、java フォルダにある、対応する MyEntity.java サブクラスに書きます。 このクラスは生成されたベースクラスを継承します。

つまり、日々の流れはこうです。

1. ツリーでエンティティを編集する。
2. ハッシュが オレンジ になるのを確認する。
3. Generate Migration でデータベースを追従させる。
4. Generate EO で Java クラスを追従させる。
5. Save。

関連

• プロジェクト構成 — .eomodeld が置かれている場所
• Migration Editor — このエディタが生成するマイグレーションファイルの編集 (次の記事)

In the Project Layout post we saw the resources folder holds an .eomodeld — the EO Model. This post is about the editor you use to work with it.

An EOModel is TreasureBoat’s object-relational mapping: it describes your entities (tables), their attributes (columns), and the relationships (joins) between them — declaratively, as data, not as annotations in your Java code. Open an .eomodeld and the plugin gives you a visual Entity Editor instead of raw plist files.

What an EOModel is

An .eomodeld is not a single file — it is a bundle (a folder) of plist files in NeXTSTEP format:

• index.eomodeld – the model metadata (connection info, naming conventions)
• one .plist per entity – that entity’s attributes, relationships and fetch specs

You never have to edit those plists by hand. That is what the editor is for.

Editor Layout

The editor has two panels: the tree on the left and the property panel on the right.

Entity Tree (left)

The tree shows the whole model structure:

• Model – the .eomodeld bundle (root)
  • Entity – each entity in the model
    • Attributes – the columns
    • Relationships – the joins to other entities
    • Fetch Specifications – predefined, named queries
    • Indexes – database indexes

Right-click a node to add or delete entities, attributes, relationships, fetch specs and indexes, or to create a subclass of an entity.

Also you can create following files when needed:

• Create REST Controller…
• Create Sangria Rules…
• Create Sangria Delegate…

Property Panel (right)

Select any node and the right panel shows its properties for editing — the attribute’s column and type, the relationship’s destination and delete rule, and so on.

Toolbar

The properties that matter

Entity

Basic Panel

Advanced Panel

Localization Panel

Attribute

Good to know: only attributes marked isClassProperty get a Java accessor. A column that exists in the table but is not a class property (a raw foreign-key column, for example) stays in the model but never shows up as a method on your EO.

What is a prototype? A prototype is a named template that bundles a column’s database type, Java value type and width together. Instead of setting each of those by hand, you pick a prototype (uuid, varchar255, date, …) and the attribute inherits all of it. One gotcha worth remembering: the uuid prototype defaults the column name to uuid, so for a uuid primary or foreign key you must set columnName = id explicitly — otherwise the generated SQL fails with “column uuid does not exist”.

Basic Panel

Advanced Panel

Documentation Panel

Relationship

Basic Panel

Advanced Panel

The Entity Hash

The toolbar shows a small hash for the selected entity. It is a fingerprint of the entity’s structure — its attributes, relationships and types. Its colour tells you whether the structure has changed since the last saved migration:

• Gray – matches the saved hash (no structural change)
• Orange – differs from the saved hash (structure changed — you probably need a new migration)
• Blue – new, no saved hash yet

Click the hash to copy it to the clipboard.

Good to know: the hash is your reminder to keep the database in step with the model. When it turns orange, that is the cue to press Generate Migration.

From model to code — Generate EO

Generate EO turns the model into Java, using the Velocity templates set by Template Path. This is what fills the generated/ folder from the Project Layout post: for each entity it writes an underscore base class (_MyEntity.java) with the KVC accessors and relationships. You never edit those — regenerating overwrites them. Your business logic goes in the matching MyEntity.java subclass under java, which extends the generated base.

So the everyday loop is:

1. Edit the entity in the tree.
2. Watch the hash go orange.
3. Generate Migration to bring the database along.
4. Generate EO to bring the Java classes along.
5. Save.

Related

• Project Layout — where the .eomodeld lives
• The Migration Editor — editing the migration files this editor generates (next post)

まずはフレームワークプロジェクトの構成を見ていきましょう。
この例では tb-pro-rule-engine を使います。

概要

• .idea – IntelliJ がセットアップや設定を管理するためのフォルダです
• docs – .sangria ルールのバックアップファイルが保存される、任意のフォルダです
• Documents – こちらもドキュメント用の、任意のフォルダです
• src – 実際のプロジェクトフォルダです（開発・コンパイル）
• target – src フォルダをコンパイルした結果が入るフォルダです（デプロイ用）。ビルド時にはバンドルの Info.plist もここに生成されます（実行ファイル名・プリンシパルクラス・バージョンといった、バンドルメタデータの唯一の正となる情報源です）。そのため Info.plist は src には見当たりません。
• .treasureboat – プロジェクトの情報（アプリケーションかフレームワークか）を持つファイルです。旧来の（変換された）プロジェクトがバンドル識別に使っていた Eclipse の build.properties を置き換えるものです。
• pom.xml – ビルドファイル（Maven）です。依存関係、TreasureBoat フレームワークのバージョン、ビルドプロファイルを記述します。
• pom.xml.versionsBackup – versions:set（リリースバージョンの更新など）を実行したときに Maven が作成するバックアップです。削除して構いません。
• {プロジェクト名}.iml – IntelliJ がプロジェクト情報を管理するために使うファイルです

プロジェクト構成

src フォルダの中には、test と main の 2 つがあります。

test

test フォルダにはプロジェクトのユニットテストが入ります。
TreasureBoat は JUnit 5 によるユニットテストに対応しています。

• java – ユニットテストの Java ソースコードが入ります
• resources – プロジェクトのリソース（画像や設定ファイルなど）が入ります

main

main フォルダにはプロジェクトのソースコードが入ります。

• generated – 自動生成されたコード（生成されたクラスなど）が入ります
• java – プロジェクトの Java ソースコードが入ります
• resources – プロジェクトのリソース（画像や設定ファイルなど）が入ります
• webapp – プロジェクトのコンポーネント（HTML / XML / JS など）が入ります
• webserver-resources – Web サーバー用のリソース（静的ファイルなど）が入ります

generated

ここには自動生成されたコード（生成されたクラスなど）が入ります。
TreasureBoat では、生成コードはフレームワークによって自動生成されるものであり、ユーザーが手で編集するものではありません。
これらのファイルは Entity Editor の EOGenerator によって生成されます。

各エンティティごとに、KVC のアクセサやリレーションシップを持つ アンダースコア始まりのベースクラス（例：_MyEntity.java）がここに生成されます。これらは絶対に編集しないでください — 再生成のたびに上書きされてしまいます。あなたのビジネスロジックは、java フォルダにある、対応する アンダースコアなしのサブクラス（MyEntity.java）に書きます。このクラスは生成されたベースクラスを継承しています。この分割のおかげで、自分のコードを失うことなくモデルを再生成できます。

java

ここにはプロジェクトのすべてのソースコードが入ります。

resources

アプリケーションが必要とするすべてのリソースを置くフォルダです。

ローカライズファイル

• Chinese_Taiwan.lproj – 中国語（台湾）のローカライズファイル
• Dutch.lproj – オランダ語のローカライズファイル
• English.lproj – 英語のローカライズファイル
• French.lproj – フランス語のローカライズファイル
• German.lproj – ドイツ語のローカライズファイル
• Italian.lproj – イタリア語のローカライズファイル
• Japanese.lproj – 日本語のローカライズファイル
• Portuguese_Brazil.lproj – ポルトガル語（ブラジル）のローカライズファイル
• Spanish.lproj – スペイン語のローカライズファイル

EO マイグレーションファイル

• EOMigration – 起動時にデータを読み込むための EO マイグレーションファイル
• EOTestMigration – マイグレーションファイルを開発するための、EO マイグレーションのテスト用ファイル

ナビゲーション

• Navigationbar – ナビゲーションバーの設定

モデル

• tb_pro_rule_engine_model.eomodeld – EO モデル

Sangria

• d2w.sangria – Sangria のルールファイル（NeXTSTEP plist 形式）です。ルールの条件（LHS）=> プロパティ値（RHS）を記述し、ルールベースの UI を制御します。概要で触れた docs フォルダには、このファイルのタイムスタンプ付きバックアップが保存されます。

プロパティ

• Properties.properties – プロパティファイル

webapp

ここにはプロジェクトのすべてのコンポーネント（HTML / XML / JS など）が入ります。

各コンポーネントは .wo フォルダ です。これは、1 つのコンポーネントを構成する各ファイルをまとめた小さなバンドルです。

• .html – テンプレート。動的なプレースホルダとして <treasureboat>（または <tb:...>）タグを使います
• .wod – (任意) それらのタグを KVC キーパス経由で Java コードに結びつけるバインディング
• .api – (任意) Component Editor 向けに、コンポーネントのバインディングを宣言します
• .md – (任意) コンポーネントのドキュメント

このフォルダ内の構成は自由です。好きなようにコンポーネントをグループ分けできます。

古い実装の名残で NonLocalized.lproj フォルダが残っている場合がありますが、現在はもう必要ありません。
TreasureBoat は多言語コンポーネントには対応していません。
ローカライズには localizer クラスを使ってください。

webserver-resources

ここには Web サーバー用のリソース、つまりアプリケーションを介さずに Web サーバーが直接配信する静的ファイル（CSS・JS・画像・フォントなど）が入ります。

これらを参照するには、所有するフレームワーク名と webserver-resources 内のパスを指定した static:// URL を使います。例：

static://tb-core-skin-keen:assets/css/style.bundle.css

フレームワーク名が URL の一部になっているため、1 つのバンドルが、それに依存するすべてのアプリにアセットを配信できます。これが、スキンが CDN を使わずに CSS / JS をすべてのアプリへ届ける仕組みです。

アプリケーション と フレームワーク

概要に出てきた .treasureboat ファイルには、プロジェクトが アプリケーション なのか フレームワーク なのかが記録されています。両者は、いま見てきた構成 — generated・java・resources・webapp・webserver-resources を含む src/main — を まったく同じように 共有しています。違うのは、バンドルが 何であるか、そしてどう動くかです。

この例の tb-pro-rule-engine はフレームワークで、アプリケーションが依存するルールエンジンのモデルとコンポーネントを提供します。アプリケーションはこれ（と他の多くのフレームワーク）に依存し、その上に独自の画面・データ・デプロイ設定を追加します。

So let’s take a first look at a framework project layout.
In this example we use tb-pro-rule-engine.

Overview

• .idea - A folder is the IntelliJ maintenance folder for all the setup and configuration
• docs - A folder is an optional folder where .sangria rule backup files get saved
• Documents – Also, here is an optional folder for your Documentation
• src – This is the real project folder (development/compile)
• target – The target folder is the compiled version of the src folder (deploy). The build also generates the bundle’s Info.plist in here (the single source of truth for bundle metadata — executable name, principal class, version), which is why you won’t find Info.plist in src.
• .treasureboat - This file has information about the project (Application or Framework). It replaces the legacy Eclipse build.properties that older, converted projects used for bundle identification.
• pom.xml – The build file (Maven): dependencies, the TreasureBoat framework versions, and the build profiles.
• pom.xml.versionsBackup – A backup Maven writes when you run versions:set (e.g. bumping the release version). Safe to delete.
• {Project Name}.iml – A file that is used by IntelliJ for tracking project information

Project Layout

Inside the src folder you will find the following: test and main

test

The test folder contains the unit tests for the project.
TreasureBoat supports JUnit 5 unit testing.

• java – This folder contains the Java source code for the unit tests.
• resources – This folder contains the resources for the project (e.g., images, configuration files, etc.)

main

The main folder contains the source code for the project.

• generated – This folder contains the generated code for the project (e.g., generated classes, etc.)
• java – This folder contains the Java source code for the project.
• resources – This folder contains the resources for the project (e.g., images, configuration files, etc.)
• webapp – This folder contains the Components (HTML/XML/JS …) for the project.
• webserver-resources – This folder contains the web server resources for the project (e.g., static files, etc.)

generated

Here you can find the generated code for the project (e.g., generated classes, etc.)
In TreasureBoat, the generated code is automatically generated by the framework and is not meant to be modified by the user.
Those files get generated by the Entity Editor EOGenerator.

Each entity produces an underscore-prefixed base class here (e.g. _MyEntity.java) that holds the KVC accessors and relationships. Never edit these — regenerating overwrites them. Your business logic goes in the matching non-underscore subclass (MyEntity.java) under java, which extends the generated base. This split lets you re-generate the model without losing your code.

java

Here you can find all your Source Code for the project.

resources

This is the folder for all the resources that are needed by the application.

Localization Files

• Chinese_Taiwan.lproj – Chinese Localization File
• Dutch.lproj – Dutch Localization File
• English.lproj – English Localization File
• French.lproj – French Localization File
• German.lproj – German Localization File
• Italian.lproj – Italian Localization File
• Japanese.lproj – Japanese Localization File
• Portuguese_Brazil.lproj – Brazil Portuguese Localization File
• Spanish.lproj – Spanish Localization File

EO Migration Files

• EOMigration – The EO Migration Files for loading data at boot time
• EOTestMigration – The EO Migration Test file for developing Migration Files

Navigation

• Navigationbar - The Navigation-bar configuration

Model

• tb_pro_rule_engine_model.eomodeld – The EO Model

Sangria

• d2w.sangria – The Sangria rule file (NeXTSTEP plist format): rule conditions (LHS) => property values (RHS) that drive the rule-based UI. The docs folder mentioned in the Overview keeps timestamped backups of this file.

Properties

• Properties.properties – The Properties file

webapp

Here you can find all your Components for the project (e.g., HTML/XML/JS …)

Each component is a .wo folder — a small bundle that groups the parts of one component together:

• .html – the template, using <treasureboat> (or <tb:...>) tags as dynamic placeholders
• .wod – (optional) the bindings that wire those tags to your Java code through KVC keypaths
• .api – (optional) declares the component’s bindings for the Component Editor
• .md – (optional) documentation for the component

The folder structure inside this folder is free — group components however you like.

From older implementations there is still a NonLocalized.lproj folder, but it is not necessary anymore.
TreasureBoat is not supporting Multilanguage Components.
For Localization you should use the localizer classes.

webserver-resources

Here you can find all your web server resources for the project — static files (CSS, JS, images, fonts) that the web server serves directly, not through the application.

Reference them with a static:// URL that names the owning framework and the path inside webserver-resources, for example:

static://tb-core-skin-keen:assets/css/style.bundle.css

Because the framework name is part of the URL, one bundle can serve its assets to every app that depends on it — this is how a skin ships its CSS/JS to all apps without needing a CDN.

Application vs Framework

The .treasureboat file in the Overview records whether a project is an Application or a Framework. Both share the exact same layout you just saw — src/main with generated, java, resources, webapp, and webserver-resources. What differs is what the bundle is and how it runs:

Our example, tb-pro-rule-engine, is a framework: it ships a rule-engine model and components that applications depend on. An application depends on it (and many other frameworks) and adds its own screens, data, and deployment configuration on top.