アーキテクチャとコード構造

このページでは、Fess のアーキテクチャ、コード構造、 主要なコンポーネントについて説明します。 Fess の内部構造を理解することで、効率的に開発を進めることができます。

全体アーキテクチャ

Fess は、以下の主要なコンポーネントで構成されています：

┌─────────────────────────────────────────────────┐
│          ユーザーインターフェース                │
│  ┌──────────────┐      ┌──────────────┐        │
│  │  検索画面     │      │   管理画面    │        │
│  │  (JSP/HTML)   │      │   (JSP/HTML)  │        │
│  └──────────────┘      └──────────────┘        │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│              Web アプリケーション層               │
│  ┌──────────────────────────────────────────┐  │
│  │           LastaFlute                       │  │
│  │  ┌────────┐  ┌─────────┐  ┌──────────┐  │  │
│  │  │ Action │  │  Form   │  │  Service │  │  │
│  │  └────────┘  └─────────┘  └──────────┘  │  │
│  └──────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│              ビジネスロジック層                   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │ Crawler  │  │  Job     │  │  Helper  │    │
│  └──────────┘  └──────────┘  └──────────┘    │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│              データアクセス層                     │
│  ┌──────────────────────────────────────────┐  │
│  │          DBFlute / OpenSearch             │  │
│  │  ┌────────┐  ┌─────────┐  ┌──────────┐  │  │
│  │  │Behavior│  │ Entity  │  │  Query   │  │  │
│  │  └────────┘  └─────────┘  └──────────┘  │  │
│  └──────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│               データストア                        │
│              OpenSearch 3.5.0                   │
└─────────────────────────────────────────────────┘

レイヤーの説明

ユーザーインターフェース層

ユーザーが直接操作する画面です。 JSP と HTML、JavaScript で実装されています。

• 検索画面: エンドユーザー向けの検索インターフェース

• 管理画面: システム管理者向けの設定・管理インターフェース

Web アプリケーション層

LastaFlute フレームワークを使用した Web アプリケーション層です。

• Action: HTTP リクエストを処理し、ビジネスロジックを呼び出す

• Form: リクエストパラメータの受け取りとバリデーション

• Service: ビジネスロジックの実装

ビジネスロジック層

Fess の主要な機能を実装する層です。

• Crawler: Web サイトやファイルシステムからデータを収集

• Job: スケジュール実行されるタスク

• Helper: アプリケーション全体で使用されるヘルパークラス

データアクセス層

DBFlute を使用した OpenSearch へのアクセス層です。

• Behavior: データ操作のインターフェース

• Entity: データの実体

• Query: 検索クエリの構築

データストア層

検索エンジンとして OpenSearch 3.5.0 を使用します。

プロジェクト構造

ディレクトリ構造

fess/
├── src/
│   ├── main/
│   │   ├── java/org/codelibs/fess/
│   │   │   ├── app/              # Web アプリケーション
│   │   │   │   ├── web/          # 検索画面
│   │   │   │   │   ├── admin/    # 管理画面
│   │   │   │   │   │   ├── ...Action.java
│   │   │   │   │   │   └── ...Form.java
│   │   │   │   │   └── ...Action.java
│   │   │   │   └── service/      # サービス層
│   │   │   ├── crawler/          # クローラー
│   │   │   │   ├── helper/       # クローラーヘルパー
│   │   │   │   ├── processor/    # クロール処理
│   │   │   │   ├── service/      # クローラーサービス
│   │   │   │   └── transformer/  # データ変換
│   │   │   ├── opensearch/       # OpenSearch 関連
│   │   │   │   ├── client/       # OpenSearch クライアント
│   │   │   │   ├── config/       # 設定管理
│   │   │   │   ├── log/          # ログ管理
│   │   │   │   ├── query/        # クエリビルダー
│   │   │   │   └── user/         # ユーザー管理
│   │   │   ├── helper/           # ヘルパークラス
│   │   │   │   ├── ...Helper.java
│   │   │   ├── job/              # ジョブ
│   │   │   │   ├── ...Job.java
│   │   │   ├── util/             # ユーティリティ
│   │   │   ├── entity/           # エンティティ（自動生成）
│   │   │   ├── mylasta/          # LastaFlute 設定
│   │   │   │   ├── action/       # Action 基底クラス
│   │   │   │   ├── direction/    # アプリケーション設定
│   │   │   │   └── mail/         # メール設定
│   │   │   ├── Constants.java    # 定数定義
│   │   │   └── FessBoot.java     # 起動クラス
│   │   ├── resources/
│   │   │   ├── fess_config.properties  # 設定ファイル
│   │   │   ├── fess_config.xml         # LastaDi コンポーネント設定
│   │   │   ├── fess_message_ja.properties  # メッセージ（日本語）
│   │   │   ├── fess_message_en.properties  # メッセージ（英語）
│   │   │   └── ...
│   │   └── webapp/
│   │       ├── WEB-INF/
│   │       │   ├── view/          # JSP ファイル
│   │       │   │   ├── admin/     # 管理画面 JSP
│   │       │   │   └── ...
│   │       │   └── web.xml
│   │       ├── css/               # CSS ファイル
│   │       ├── js/                # JavaScript ファイル
│   │       └── images/            # 画像ファイル
│   └── test/
│       └── java/org/codelibs/fess/
│           ├── ...Test.java       # テストクラス
│           └── it/                # 統合テスト
├── pom.xml                        # Maven 設定
├── dbflute_fess/                  # DBFlute 設定
│   ├── dfprop/                    # DBFlute プロパティ
│   └── freegen/                   # FreeGen 設定
└── README.md

主要パッケージの詳細

app パッケージ

Web アプリケーション層のコードです。

app.web パッケージ

検索画面とエンドユーザー向け機能を実装します。

主要なクラス:

• SearchAction.java: 検索処理

• LoginAction.java: ログイン処理

例:

@Execute
public HtmlResponse index(SearchForm form) {
    // 検索処理の実装
    return asHtml(path_IndexJsp);
}

app.web.admin パッケージ

管理画面の機能を実装します。

主要なクラス:

• AdminWebconfigAction.java: Web クロール設定

• AdminSchedulerAction.java: スケジューラー管理

• AdminUserAction.java: ユーザー管理

命名規則:

• Admin プレフィックス: Admin 用 Action

• Action サフィックス: Action クラス

• Form サフィックス: Form クラス

app.service パッケージ

ビジネスロジックを実装するサービス層です。

主要なクラス:

• SearchLogService.java: 検索ログサービス

• UserService.java: ユーザー管理サービス

• ScheduledJobService.java: ジョブ管理サービス

例:

public class ScheduledJobService {
    @Resource
    private ScheduledJobBhv scheduledJobBhv;

    // ジョブの CRUD 操作の実装
}

crawler パッケージ

データ収集機能を実装します。

crawler パッケージ（fess-crawler ライブラリ）

クローラーの基盤機能は fess-crawler ライブラリで実装されています。

主要なクラス（fess-crawler）:

• CrawlerClient.java: クローラークライアントのインターフェース

• HcHttpClient.java: Web サイトのクロール（HTTP クライアント）

• FileSystemClient.java: ファイルシステムのクロール

• ExtractorFactory.java: エクストラクターのファクトリ

• TikaExtractor.java: Apache Tika を使用した抽出

• Transformer.java: 変換処理のインターフェース

crawler パッケージ（fess 本体）

Fess 固有のクローラー拡張を実装します。

主要なクラス:

• FessStandardTransformer.java: 標準的な変換処理

• FessXpathTransformer.java: XPath を使用した変換処理

opensearch パッケージ

OpenSearch との連携を実装します。

opensearch.client パッケージ

OpenSearch クライアントの実装です。

主要なクラス:

• SearchEngineClient.java: 検索エンジンクライアント

opensearch.query パッケージ

検索クエリの構築を実装します。

主要なクラス:

• QueryCommand.java: クエリコマンド

• QueryProcessor.java: クエリ処理

helper パッケージ

アプリケーション全体で使用されるヘルパークラスです。

主要なクラス:

• SystemHelper.java: システム全体のヘルパー

• QueryHelper.java: クエリ構築のヘルパー

• CrawlingConfigHelper.java: クロール設定のヘルパー

• SearchLogHelper.java: 検索ログのヘルパー

• UserInfoHelper.java: ユーザー情報のヘルパー

• ViewHelper.java: ビュー関連のヘルパー

例:

public class SystemHelper {
    @PostConstruct
    public void init() {
        // システム初期化処理
    }
}

job パッケージ

スケジュール実行されるジョブを実装します。

主要なクラス:

• CrawlJob.java: クロールジョブ

• SuggestJob.java: サジェストジョブ

• ScriptExecutorJob.java: スクリプト実行ジョブ

例:

public class CrawlJob extends ExecJob {
    @Override
    public String execute() {
        // クロール処理の実装
    }
}

entity パッケージ

OpenSearch のドキュメントに対応するエンティティクラスです。 このパッケージは DBFlute によって自動生成されます。

主要なクラス:

• SearchLog.java: 検索ログ

• ClickLog.java: クリックログ

• FavoriteLog.java: お気に入りログ

• User.java: ユーザー情報

• Role.java: ロール情報

注釈

entity パッケージのコードは自動生成されるため、 直接編集しないでください。 スキーマを変更して再生成することで更新します。

mylasta パッケージ

LastaFlute の設定とカスタマイズを行います。

mylasta.action パッケージ

Action の基底クラスを定義します。

• FessUserBean.java: ユーザー情報

• FessHtmlPath.java: HTML パス定義

mylasta.direction パッケージ

アプリケーション全体の設定を行います。

• FessConfig.java: 設定の読み込み

• FessFwAssistantDirector.java: フレームワーク設定

デザインパターンと実装パターン

Fess では、以下のようなデザインパターンが使用されています。

MVC パターン

LastaFlute による MVC パターンで実装されています。

• Model: Service、Entity

• View: JSP

• Controller: Action

例：

// Controller (Action)
public class SearchAction extends FessSearchAction {
    @Resource
    protected SearchHelper searchHelper;

    @Execute
    public HtmlResponse index(SearchForm form) {
        return search(form);
    }
}

DI パターン

LastaFlute の DI コンテナを使用します。

public class SearchService {
    @Resource
    private SearchEngineClient searchEngineClient;

    @Resource
    private UserInfoHelper userInfoHelper;
}

Factory パターン

各種コンポーネントの生成に使用されます。

public class ExtractorFactory {
    public Extractor getExtractor(String key) {
        // キーに応じた Extractor を取得
    }
}

Strategy パターン

クローラーやトランスフォーマーで使用されます。

public interface Transformer {
    ResultData transform(ResponseData responseData);
}

public class HtmlTransformer implements Transformer {
    // HTML 用の変換処理
}

設定管理

Fess の設定は複数のファイルで管理されています。

fess_config.properties

アプリケーションの主要な設定を定義します。

# OpenSearch 接続設定
search_engine.http.url=http://localhost:9201

# クロール設定
crawler.document.max.site.length=100
crawler.document.cache.enabled=true

fess_config.xml

LastaDi コンポーネント設定ファイルです。

<component name="systemProperties" class="org.codelibs.core.misc.DynamicProperties">
    <arg>
        org.codelibs.fess.util.ResourceUtil.getConfPath("system.properties")
    </arg>
</component>

fess_message_*.properties

多言語対応のメッセージファイルです。

• fess_message_ja.properties: 日本語

• fess_message_en.properties: 英語

データフロー

検索フロー

1. ユーザーが検索画面で検索
   ↓
2. SearchAction が検索リクエストを受信
   ↓
3. SearchService がビジネスロジックを実行
   ↓
4. SearchEngineClient が OpenSearch に検索クエリを送信
   ↓
5. OpenSearch が検索結果を返却
   ↓
6. SearchService が結果を整形
   ↓
7. SearchAction が JSP に結果を渡して表示

クロールフロー

1. CrawlJob がスケジュール実行される
   ↓
2. CrawlingConfigHelper がクロール設定を取得
   ↓
3. CrawlerClient が対象サイトにアクセス
   ↓
4. Extractor がコンテンツからテキストを抽出
   ↓
5. Transformer がデータを検索用の形式に変換
   ↓
6. SearchEngineClient が OpenSearch にドキュメントを登録

拡張ポイント

Fess は、以下のポイントで拡張できます。

カスタムクローラーの追加

CrawlerClient インターフェースを実装して、独自のデータソースに対応できます。

カスタムトランスフォーマーの追加

Transformer を実装して、独自のデータ変換処理を追加できます。

カスタムエクストラクターの追加

Extractor を実装して、独自のコンテンツ抽出処理を追加できます。

カスタムプラグインの追加

管理画面のプラグイン管理機能を使用して、独自のプラグインを追加できます。

参考資料

フレームワーク

• LastaFlute リファレンス

• DBFlute ドキュメント

技術ドキュメント

• OpenSearch API リファレンス

• Apache Tika

次のステップ

アーキテクチャを理解したら、以下のドキュメントを参照してください：

• 開発ワークフロー - 実際の開発フロー

• ビルドとテスト - ビルドとテスト

• コントリビューションガイド - プルリクエストの作成