1 トラブルシューティング

トラブルシューティング

ここでは、Content Servicesの問題に直面したときに、問題を診断および解決するのに役立つヘルプを提供します。
ここに記載している以外のヘルプについては、以下を参照してください。

サポート依頼について、詳しい情報提供を求める場合があります。

その場合はリポジトリ管理コンソール (特に、サポートツール) を参照してください。
さまざまなインストールおよびセットアップの情報を確認したい場合は、Share 管理ツールを参照してください。

ログレベルを設定する

log4j.propertiesファイルでログレベルを設定すると、トラブルシューティング時にデバッグ情報が提供されるようになります。ログポリシーを設定するには、ログの記録先となるクラス名の先頭にlog4j.loggerを付加し、ログレベルを設定する必要があります。JMX クライアントを使用すると、ログレベルを動的に設定できます。

log4jを使用する場合は、次の点に注意してください。

ローカルのカスタマイズおよびライセンスは、Webアプリケーションの外側に置いてください。たとえば、extensionディレクトリに置きます。
$TOMCAT_HOME/shared/classes/alfresco/extension/...-log4j.properties
提供された構成ファイルは、Webアプリケーション内に保存またはインストールする必要があります。以下がその例です。
WEB-INF/classes/alfresco/extension/...-log4j.properties

dev-log4j.propertiesファイルを、製品の一部としてパッケージ化しないようにしてください。

ログの記録には、Log4J のHierarchyDynamicMBeanを使用します。

ログレベルは、クラスタには対応していません。必要に応じて、マシンごとにログレベルの変更を適用する必要があります。一部のコンソール (たとえば JManage) は、アプリケーションクラスタ内の各マシンにアクセスするための基本的な機能を備えています。

編集可能な属性は、logLevel属性を持つロガーの動的リストです。これらの属性は、OFF、FATAL、ERROR、WARN、INFO、DEBUG、またはTRACE (編集可能) への変更が可能です。
読み込まれている場合addLoggerMBeanへの影響があります

JConsole を使用してロガーを追加する手順を次に示します。

Alfresco > Log4jHierarchy > Operations > addLoggerMBean をクリックします。
右側のペインにある Name に、完全な className を入力します。
addLoggerMBean をクリックします。
Operation return value というタイトルのダイアログボックスが表示されます。成功した場合、ダイアログボックスに、入力したclassNameの前にlog4j:logger=が付加されたクラス名が表示されます。失敗した場合、ダイアログボックスにnullと表示されます。

エラーメッセージ

ここでは、インストール時のトラブルシューティングについて説明します。

ImageMagick

コンソールには次のエラーメッセージが表示されます。

ERROR [AbstractImageMagickContentTransformer]
JMagickContentTransformer not available:
ERROR [AbstractImageMagickContentTransformer]
ImageMagickContentTransformer not available:
Failed to execute command: imconvert ...

この問題が原因でサーバーで障害が発生することはありません。Content Services により、外部の文書変換エンジンがサーバーで使用できない状態であることが報告されています。不要であれば、変換の参照を削除できます。

JAVA_HOME

Java インストールで、JAVA_HOME変数が正しく設定されていることを確認してください。

FTPソケット (FTP Socket)

サーバー起動時に次のエラーメッセージが表示されます。

すでに使用されているポート

Content Services サーバー用の 8080番ポート、または FTP 統合用の 21番ポートに対して、実行中のサービスがないかを確認します。

ノードブラウザを使用する

未加工のリポジトリ構造を閲覧するためのデバッグツールとして、リポジトリ管理コンソールまたは Share 管理ツールのノードブラウザを使用します。これは、アプリケーションのカスタマイズを担当する開発者向けの機能です。

基本的な検索機能を備えた読み取り専用の機能となります。

リポジトリ管理コンソールを開きます。
Support Tools セクションで、ノードブラウザ をクリックします。ノードブラウザコンソールページが表示されます。
ストア (Store) セクションで、対象のストアを選択します。
- workspace://SpacesStore -ライブコンテンツ
- archive://SpacesStore アーカイブ済みコンテンツ (論理削除済み)
- workspace://version2Store 旧コンテンツのバージョン履歴
- user://alfrescoUserStore usr:user型のノードが格納されます。cm:person型のノードはworkspace://SpacesStoreに格納されます。
- system://systemインストールされたモジュールに関する情報
- workspace://lightWeightVersionStore
  各ストアはリポジトリの領域であり、各ストア内ではそのストアのノードが階層構造で整理されています。表示されるノードは、選択したストアのルートノードです。
Root List をクリックします。
ノードブラウザページには、選択したノードのプロパティ、アスペクト、子、親、関連付け、ソースの関連付け、および権限の詳細が表示されます。
必要に応じて、選択したストアを検索します。

noderef、fts-alfresco、lucene、xpath、selectnodes、cmis-strict、cmis-alfresco、db-afts、db-cmisの中から検索タイプを選択します。
指定されたフィールドに検索条件を入力します。
検索をクリックします。

Share 管理ツールでノードブラウザを使用する

Share 管理ツールに移動し、ノードブラウザをクリックします。
デフォルトでは、workspace://SpacesStoreというリポジトリストアのノードブラウザフィールドに、検索条件としてPATH:"/"が表示されます。各ストアはリポジトリの領域です。各ストア内のノードは、階層構造で整理されています。表示されるノードは、選択したストアのルートノードです。
デフォルトの検索タイプは fts-alfresco に設定されています。ほとんどの管理タスクでは、このデフォルトの検索タイプを使用できます。
詳しくは、Alfresco Full Text Search referenceを参照してください。
ノードブラウザフィールドに検索条件を入力します。
検索をクリックします。
Referenceカラムのリンクをクリックすると、詳細を閲覧できます。
ノードのプロパティ、アスペクト、子、親、関連付け、ソースの関連付け、および権限の詳細が表示されます。
別のノードを閲覧するには、「検索に戻る」をクリックします。
検索リストから次に示すタイプを1つ選択することで、別の検索構文を使用できます。

検索リストから以下のタイプを選択し、別の検索構文を使用することができます。

storeroot
noderef
xpath
fts-alfresco
cmis-strict
cmis-alfresco
db-afts
db-cmis

インストールをデバッグする

アドインを作成する、バグを修正する、またはソースコードから Content Services を変更する場合、標準的なアプリケーションサーバー上で動作するインスタンスをデバッグするのが有効です。Content Services と Eclipse を設定して、サーバーをリアルタイムで表示して、コードを 1行ずつ確認しながら問題のトラブルシューティングを行うことができます。

実行中のサーバーをデバッグするには、Content Services が動作している JVM に接続する必要があります。以下に示す手順では、JVM を設定してこの接続用のインターフェイスを公開するようにし、Eclipse を設定してその JVM に接続して制御するようにします。

JVMを設定する

サーバーに接続するためのインターフェイスを公開するように JVM を設定できます。

前提条件

次に示す前提条件を確認してから設定を開始してください。

Content Services のインスタンスが完全にインストールされ、設定され、実行されていなければなりません。以下の手順は Windows 上で Tomcat を使用していることを前提としていますが、他のシステム上の他のアプリケーションサーバーでも同様の手順となります。
IDE がインストールされていなければなりません。以下の手順では、Eclipse の設定方法について説明しています。そのため、事前に Eclipse をインストールしておく必要があります (Eclipse)。
ソースコードをダウンロードしておいてください。このプロジェクトは、開発環境の構築方法についてより詳細な手順を提供しています。
ソースコードが、インストールされているサーバーと同じバージョンであることを確認してください。

設定の開始

サーバーが起動していないことを確認します。
Tomcat インスタンスの起動に使用される JVM オプションを編集します。
たとえば、次のように設定します。
ここで、addressはお使いのシステムのポートです。
ファイルを保存して、エディタを閉じます。

Eclipseを設定する

ここでは、JVM に接続して制御するために Eclipse を設定する方法について説明します。

Run メニューから Open Debug ダイアログを選択します。
Remote Java Application を右クリックし、New を選択します。
Name ボックスに、”Debug Local Tomcat Alfresco” と入力します。
Project の横にある Browse をクリックし、Web Client を選択します。この選択肢がない場合は、ソースコードがサーバーのものと一致しているかを確認してください。
Connection Propertiesで、ポート番号を入力します。
Eclipse コンソールからサーバーを停止できるようにする場合は、Allow Termination of remote VM のチェックボックスをオンにします。
Applyをクリックして、設定を保存します。

アップグレードをトラブルシューティングする

ここでは、アップグレードによって発生する可能性のある問題を診断して解決するためのヒントを提供します。
サーバーを起動した直後に、alfresco.logファイルをコピーします。
alfresco.logファイルで、アップグレード中に実行された SQL ステートメントが含まれる一時ファイルの場所を確認し、これらの一時ファイルのコピーを作成します。
ログファイルと一時ファイルを Alfresco 製品のサポートチームに提出します。

ルールとアクションをトラブルシューティングする

ここでは、ルールおよびアクションを使用する際のトラブルシューティングに関するヒントを提供します。

Mac OS/Xでの型特殊化アクションの問題点**

Mac OS/X 10.8.3以降を使用している場合、Microsoft Word 文書を保存するときに型特殊化アクションが実行されません。
この問題を解決するには、alfresco-global.propertiesファイルを編集して、次の値を設定します。

クラスタリングをトラブルシューティングする

ここでは、キャッシュクラスタリングをテストする際のトラブルシューティングに関するヒントを提供します。
Linux/Unix 環境では、netstat -lnを使用することで、サーバーが正しいネットワークアダプターで正しいポートを開いているかを確認できます。telnet <hostname><port>を使用すれば、開いている各ポートがそれぞれのクラスタメンバーから到達可能かどうかを確認できます。

クラスタメンバーが NAT や IPv4 アドレスを使用している場合、強制的にサーバーが IPv6 アドレスではなく IPv4 アドレスをリッスンするようにする必要がある場合があります。そのためには、Conten Services JVM の起動オプションに次の設定を追加します。

Linux/Unix の標準的なインストールでは、次に示すスクリプトでJAVA_OPTS変数を編集する必要があります。

Windows の標準的なインストールでは、次の場所にある;-Dalfresco.homeの直前にパラメータを追加する必要があります。

その後、次に示すスクリプトを実行します。

これにより、新しいオプションでサービスが再登録されます。
クラスタリングの開始プロセスとクラスタリングの設定に使用できるオプションの詳細については、クラスタリングの設定を参照してください。

JMX ダンパーをトラブルシューティングする

ここでは、JMX ダンパーをトラブルシューティングする必要がある場合に参考になる情報を提供します。
JMX ダンパーを起動すると、ログファイルにスタックトレースが表示される場合があります。jmx-dumper.zipを開くと、web.xmlファイルに定義されているデータソース (<res-ref-name>jdbc/dataSource</res-ref-name>) の検索が始まりますが、このデータソースはalfresco.xmlファイルでは宣言されていません。
このログメッセージが表示されないようにするには、$CATALINA_BASE/conf/[enginename]/[hostname]/alfresco.xmlファイルにこのデータソースを設定します。

WebDAV をトラブルシューティングする

WebDAV の設定時に発生する可能性がある問題を診断して解決します。
Content Services では、WebDAV の2つの実装を使用します。

RFC に準拠した WebDAV：alfresco/webdav
Microsoft に準拠した WebDAV：alfresco/aos

Microsoft の WebDAV 拡張機能 (MS-DAVEXT) は、WebDAV 標準との互換性が部分的にしかないため、Windowsクライアントでは/alfresco/aosを、Linux ベースのシステムでは/alfresco/webdavを使用することを推奨します。

WebDAV 共有をマウントできない (Windows)

Content Services の読み込みが完了しているかを確認します。ログファイルに Server startup メッセージがあるかを確認します。
ホスト名ではなく IP アドレスを使用して接続を確立できるかを確認してください。
Web ブラウザでhttps://<alfresco_ip>/alfresco/aosを使用してフォルダを閲覧できるかどうかを確認します。
Windows Internet Explorer の信頼済みサイトリストに、サーバーの IP を追加します。
WebClient サービスが起動しているかを確認します。次の手順に従って確認します。
1. services.msc を起動します。
2. WebClient サービスを起動します。
  ^{注：WebClient サービスの実行に関する詳細は、}^{Enabling the WebClient service in Windows}^{を参照してください。}
SSL を使用していない場合は、Windows と Microsoft Office の接続構成を確認します。
^{注：レジストリエディタでの基本認証レベルキーの設定の詳細については、Microsoft を参照してください。}
サーバーに接続できるが、ログイン情報の認証ができない場合は、同じユーザー名とパスワードでAlfresco Shareにログインできるかを確認します。

Ubuntu クライアントで WebDAV を使用してファイルまたはフォルダを移動すると、メタデータが失われ、新しいノード参照が作成される

WebDAV でファイルやフォルダを移動すると、Ubuntu によって新しいnodeRefが作成されるという既知の問題があります。これは、Ubuntu が MOVE メソッドではなく PUT メソッドと DELETE メソッドを使用するために発生します。その結果、ファイルやフォルダのnodeRefが変更され、関連するメタデータが失われます。この問題は、Ubuntu のすべてのバージョンに共通しますが、Windowsクライアントを使用するときは発生しません。

編集者の権限では WebDAV と Cyberduck バージョン 4.4+を使用してコンテンツを編集できない

WebDAV を Cyberduck 4.4以降と一緒に使用すると、アクセス許可が不十分でコンテンツを編集できないという既知の問題があります。この問題を回避するには、4.4よりも前のバージョンの Cyberduck を使用するか、ファイル作成を可能にするアクセス許可をユーザーに割り当てます。

Microsoft Windows Vista または Microsoft Windows 7 で WebDav リソースを操作する際にレスポンスが遅い

WebDav フォルダを開く、WebDav フォルダにファイルをコピーする (または WebDav フォルダからファイルをコピーする) 、または WebDav フォルダ上のフォルダを別のフォルダに変更するとき、パフォーマンスが低下する場合があるという既知の問題があります。この問題は、WebClient が WebDAV コマンドを発行する際に、Web プロキシサーバーをチェックすることが原因で発生します。自動プロキシ検出を有効にして、クライアントと WebDAV リソースの間にプロキシサーバーが存在しない環境では、WebClient は自動プロキシ検出がタイムアウトするまで待機します。自動プロキシ検出がタイムアウトになるまで待機することが、コマンドの完了に時間がかかる原因となっています。

OpenLDAP に関するヒント

ここでは、OpenLDAP の使用に関するヒントを提供します。

注意すべき点

注意すべき点がいくつかあります。
返される結果の最大件数がデフォルトの 500から増加されました (ページングされた結果にも適用される)。制限については、OpenLDAP のマニュアルを参照してください。500人以上のユーザーまたはグループがいる場合、問題が生じます。
ダイジェスト認証は、ユーザーIDをマップ元とし、対応する識別名をマップ先とするように設定されています。サンプルデータを参照してください。
パスワードは平文です (どのような認証メカニズムでも使用できます)。パスワードは、MD5 ダイジェストが機能するように、正しい、ハッシュ化された形式になっている場合があります。

以下は、ユーザーとグループの組織単位と、ユーザーとグループの例を定義した、非常にシンプルな LDIF ファイルの例です。

Active Directory に関するヒント

LDAP 同期で Active Directory を使用する場合のヒントを以下に示します。

Active Directory 内で、LDAP バインドに使用しているアカウントに特別な権限を付与することが必要な場合があります (ldap.synchronization.java.naming.security.principalで設定)。このアカウントに権限を付与するには、Active Directory Users and Computersを開き、ドメインを右クリックし、Delegate Control..を選択します。Next をクリックしてから、LDAP バインドに使用しているユーザーを選択して Next をクリックします。必要とする権限は次の画面 (Read all inetOrgPerson information) にあります。
ldap.authentication.java.naming.provider.urlのサンプル URL は、SSL を使用していません。本番システムでは、SSL を推奨します。ポートを 389 (以下、非 SSL) から SSL 用の 636に切り替える必要があります。
大抵の場合、非ユーザーアカウントや無効なアカウントは除外するのが有効です。ldap-adサブシステムタイプのデフォルトのユーザークエリでは、userAccountControl属性のビットフィールドをチェックすることにより、このようなアカウントを除外しています。以下がその例です。

StartTLS を使用して SMTP 着信 Eメールをトラブルシューティングする

着信 Eメールに対して StartTLS を有効にするには、Java に SSL を設定する必要があります。

この問題が発生しているかどうかを確認するには、log4j.propertiesファイルでorg.subethamailクラスに対し、DEBUGログを有効にします。

また、デバッグモードで受信用メールサーバーのログを効率的に記録できるようにするには、送信者情報、受信者情報、件名、拒否/承諾の理由などのメール情報の追跡を可能にするlog4jオプションが必要となります。そのためには、次のように、class org.subethamail.smtp.server.ConnectionHandlerに対してDEBUGログを有効にします。

自己署名証明書を作成する方法の一例を以下に示します。ただし、これは JVM ベンダーによって異なる場合があるので、詳細については JVM のマニュアルを参照してください。

適切なキーと証明書を作成します。
Tomcat 設定の任意の場所 (たとえば/etc/tomcat5/tomcat7.conf) に、次の設定を追加します。

より多くの送信 TCP 接続を処理する

Windows クライアントで Web サービス API を使用していて、クライアントアプリケーションでjava.net.BindException: Address already in use: connectのようなエラーが頻発する場合は、クライアントのオペレーティングシステムのパラメータを調整して、より多くの送信TCP接続を処理できるようにする必要があります。

Registry を開きます。
次に示すレジストリエントリに移動します。
Windowsクライアントマシンのレジストリを入力します。
次に示すレジストリエントリを追加します。
- TcpTimedWaitDelay
  この DWORD を、30の値で追加します。
- MaxUserPort
  この DWORD を、32768の値で追加します。
これらのレジストリエントリの詳細については、Windows のマニュアルを参照してください。

IMAP をトラブルシューティングする

ここでは、IMAP の問題のトラブルシューティングについて説明します。

IMAPの規模の限界

5,000個以上のフォルダやメールボックスフォルダをマウントしている場合、お使いのIMAPクライアントによっては、最初の5,000個のフォルダしか表示されない場合があります。
この状況を回避するには、マウントするフォルダの数を制限する必要があります。

例：

フォルダ構造がきわめて大きいものであることがわかっている場合は、社内のルートスペースからマウントしないでください。特定のサイトを選択して、マウントするフォルダの数を減らしてください。
特にリポジトリが大規模なものである場合は、添付ファイルを別のフォルダ (imap.attachments.mode=SEPARATE) に展開しないでください。imap.attachments.modeを指定する際には次のいずれかの設定を選択してください。
- imap.attachments.mode=COMMON: すべての Eメールのすべての添付ファイルを1つのフォルダに展開します。
- imap.attachments.mode=SAME：添付ファイルを元のメッセージと同じフォルダに展開します。

IMAP サーバーのエラーメッセージ

このエラーメッセージは、バインド用に入力したIPアドレスまたはホスト名に関するものです。この問題を解決するには、次の確認を行ってください。

imap.server.hostの設定に対して正しい IP アドレスまたはホスト名を入力しているかを確認します。
使用するポートがブロックされていないかを確認します。デフォルトで使用するポートは143です。
そのIPアドレスまたはホスト名がファイアウォールにブロックされていないかを確認します。
コマンドラインツールのNetstatを使用して、ネットワーク接続を確認します。

imap.server.host として localhost を使用しないでください。この値を使用している場合は、外部 IP インターフェイスの IP アドレス (または対応する DNS アドレス) に変更してください。Unix で 0.0.0.0 を指定すると、すべての IP インターフェイスで指定されているポートを待ち受けるようになります。

データベーススキーマの問題をトラブルシューティングする

スキーマ比較ツール(Schema Difference Tool)では、データベーススキーマの問題を特定し、トラブルシューティングする方法を提供します。特定のバージョンアップグレードやカスタムインストールを行った際に、データベーススキーマの問題が発生することがあります。
スキーマ比較ツールは、リポジトリのデータベーススキーマのトラブルシューティングや調査に使用できます。このツールには、主に 2つの機能があります。

XML ファイル形式のスキーマダンプを作成する。
データベーススキーマを検証する。

旧バージョンの Content Services でも、スキーマダンプは作成されていました。しかし、スキーマ比較ツールが導入されるまでは、スキーマの妥当性を判断するには、ファイルを手作業で調べ、Unix の diff コマンドなどの簡単なテキストツールでスキーマを比較するしかありませんでした。スキーマ比較ツールでは、一定量の比較を自動で行ってくれるため、これらの比較に要する労力を大幅に削減できます。
サーバー起動時にデータベーススキーマに何らかの変更 (新規インストールなど) が加えられた場合、スキーマ比較ツールは、上述のスキーマダンプと検証の両方を行います。ダンプと検証は、アップグレード前 (つまりスキーマの変更前) とアップグレード後の両方で行われます。

使用する用語の定義

このセクションの残りの部分では、次に示す用語が使用されます。

データベースオブジェクト
スキーマ、シーケンス、テーブル、カラム、インデックス、プライマリキー、または外部キー。
参照スキーマ
ベンダー固有の RDBMS における、あるスキーマバージョンに対するリポジトリスキーマの確定的な表現です。参照スキーマは、特定のバージョンのリポジトリをインストールしたり、リポジトリを特定のバージョンにアップグレードしたりした後に、データベースに存在すべきものを表したモデルです。参照スキーマは、スキーマダンプと同じ XML 形式で表示されます。たとえば、リポジトリスキーマのバージョン 5025の MySQL に対して参照スキーマを作成できます。
ターゲットスキーマ
参照スキーマに照らし合わせて比較・検証されるデータベーススキーマです。たとえば、リポジトリを最初からインストールする場合、新しく作成されたスキーマは、適切な参照スキーマと比較されるターゲットスキーマとなります。

スキーマダンプを実行する

スキーマダンプは、データベーススキーマを XML で表現したものです。

スキーマダンプが実行されるケースは2つあります。

起動時に参照データベーススキーマと実際のデータベーススキーマの間に差異が見つかることにより、自動的にダンプがトリガーされるケース。
JMX クライアントを使用して手動でダンプがトリガーされるケース。

それぞれのシナリオについて、以下のセクションで説明します。

自動ダンプ

サーバーの起動時にデータベーススキーマの変更が検出されると、スキーマダンプが自動で実行されます。
スキーマダンプは、RDBMSスキーマをXMLで表現したものです。これらのスキーマダンプは XSD: (http://www.alfresco.org/repo/db-schema/db-schema.xsd)に準拠する必要があります。XSD ファイルはリポジトリに含まれています。

データベーススキーマに変更があった場合、リポジトリサーバー起動時にスキーマダンプが自動的に実行されます。ログには、ダンプが実行されたかどうかが記録され、次のようなエントリが存在します。

アップグレード後のファイルについても、同様のエントリが存在します。

JMX を利用してダンプをトリガーする

スキーマダンプは、JMX クライアントを使用して手動でトリガーすることもできます。

自動ダンプのほか、JMX インターフェイスを使用して手動でダンプを呼び出すこともできます。

JMX カテゴリの Alfresco > DatabaseInformation > SchemaExport には、2つの処理が含まれています。

java.util.List dumpSchemaToXML()
java.util.List dumpSchemaToXML(String prefixList)

1つ目の処理はパラメータを取らず、呼び出されると、alf_とact_の各プレフィックスについて1つずつ、3つのダンプファイルを作成します。このプレフィックスは、そのプレフィックスで始まる名前のテーブルとシーケンスのみがダンプに含まれることを意味しています。特定のテーブルに属するインデックスなどの関連アイテムは、名前に関係なくダンプされます。

2つ目の処理は、Stringという1つのパラメータを取ります。このパラメータはダンプするプレフィックスのコンマ区切りの一覧となります。たとえば、この処理がalf_acl_, alf_node_というパラメータで呼び出された場合、2つのファイル (各プレフィックスにつき1つずつ) が作成されます。1つ目のファイルにダンプされるテーブルには、alf_acl_change_setとalf_acl_memberが含まれます。2つ目のファイルにダンプされるテーブルには、alf_node_aspectsとalf_node_assocが含まれます。指定されたプレフィックスが付いていないalf_localeまたはalf_permissionは、いずれのファイルにも含まれません。
いずれの処理が呼び出された場合も、ログにはダンプされたファイルの場所が示され、さらにパス名のListが返されます。JConsole では、これらのリストをコピー/貼り付けしやすいように表示します。

スキーマ検証を実行する

スキーマダンプのスキーマ検証には、リポジトリの起動中にスキーマが変更された場合に実行されるケースと、JMXを使用して手動でトリガーされるケースがあります。
スキーマの検証は、差分比較と検証により実行されます。

差分比較

差分比較では、既知の「理想的な」参照スキーマのダンプと問題があると考えられるターゲットスキーマのダンプに対してdiffという Unix ツールを使用して得られる情報と同様の情報が生成されます。
しかし、このツールは任意のテキストではなく、2つのデータベーススキーマの比較を行うように設計されているため、出力は差分の種類に特化した内容となります。

報告できる差分の種類：

参照スキーマとターゲットスキーマの両方に同じデータベースオブジェクトが表示されているが、そのプロパティが異なる場合。たとえば、両方のスキーマに同じインデックスが表示されているが、その名前が異なっている場合がこれに該当します。
参照スキーマに表示されているデータベースオブジェクトに対応するオブジェクトがターゲットデータベースで見つからない場合。
ターゲットスキーマに表示されているデータベースオブジェクトに対応するオブジェクトが参照データベースで見つからない場合。

スキーマ比較ツールが従来の diff ツールよりも優れている点は、スキーマ比較ツールを使用した差分比較では、ダンプに表示される完全一致のテキストによってインデックスが認識されないということです。スキーマ比較ツールでは、インデックスがどのテーブルに属しているか、どのカラムにどのような順序でインデックスが付けられているかに基づき、インデックスが特定されます。

インデックスが期待される名前を持ち、正しいテーブルに属していても、間違ったカラムを持っているか、または正しいカラムが間違った順序で並んでいると、差分が報告されます。逆に、正しい順序で並んだ正しいカラムを持つインデックスが正しいテーブルにあったとしても、そのインデックス名が間違っていれば、その旨が報告されます。

名前は、比較の際に無視することもできますし (インデックス名を自動生成している場合など) 、比較の対象とすることもできます。参照スキーマファイルを作成するタスクの一環として、このような動作をDbValidatorオブジェクトを使用して指定する必要があります。この点については、以下のセクションで説明します。

たとえば、参照スキーマに次のようなインデックスが定義されているとします。

インデックス	`permission_id`
親テーブル	`alf_access_control_entry`
列 (カラム)	`permission_id`, `authority_id`, `allowed`, `applies`

このインデックスは、参照スキーマファイルで次のように指定されています (簡潔にするために一部省略)。

この参照スキーマに対してターゲットスキーマのインデックスが比較されると、最初に一致候補の一覧が作成されます。ターゲットスキーマに一致するインデックスが複数の存在する場合は、冗長なデータベースオブジェクトに関する警告が発行されます。
一致候補は、オブジェクトの種類に基づいて生成されます。

インデックスの場合：

親テーブルが同じでインデックス名が同じであれば、同じインデックスとみなします。
名前が異なっていても、親テーブルが同じで、インデックス付けされているカラムが同じで、これらのカラムが同じ順序で並んでいれば、同じインデックスとみなします。

1つ目の一致ケースを採用し、上記の例で定義されているpermission_idインデックスを使用した場合、ターゲットデータベースのpermission_idインデックスが持つallowedとappliesというカラムが期待する順序とは逆の順序で並んでいる場合、ログファイルにより検証の問題が通知されます。

レポートファイルの内容は、次のようなものになります。

各行は、特定のデータベースプロパティに関する問題を示しています。このレポートファイルでは、.alf_access_control_entry.permission_id.columnNames[2]というパスにあるプロパティがappliesという値を持ちますが、参照スキーマによれば、この値はallowedのはずであることが示されています。パスの先頭のピリオドは無視できます (たとえばOracleの場合、先頭のピリオドの前にスキーマ名が存在します)。次にalf_access_control_entryというテーブル名があり、そのテーブル内のインデックス名 (permission_id) があり、ゼロから始まるインデックスのリストプロパティがあります。3つ目のアイテム (インデックス2、すなわちcolumnNames[2]) が問題のあるプロパティです。
同様に、次の行では、コラム名一覧の次のアイテムであるcolumnNames[3]の値がallowedになっていますが、期待値はappliesであることが示されています。

検証

スキーマ比較ツールでは、単純な差分比較による検証に加え、スキーマ参照XMLファイルを使用して検証を行うことができます。

検証では、2つのプロパティ値を比べて差異の有無を確認するよりも、複雑なルールを適用できます。検証は、DbValidatorオブジェクトによって実行されます。参照スキーマの各データベースオブジェクトには、DbValidatorオブジェクトのチェーンが関連付けられています。各オブジェクトが順番に実行され、ターゲットスキーマの対応するオブジェクトに基づいて検証エラーを作成する機会が与えられます。

インデックスに特定の名前が付けられていない場合は、RDBMSにより、作成時に名前が自動生成されます。つまり、参照スキーマは、ターゲットデータベースのインデックスが持つことになる正確な名前を指定することはできません。そのため、バリデータを使用しなければ、スキーマの差分が報告されることになります。

このようなインデックスには、NameValidatorを指定できます。

この例は、スキーマ参照ファイル (Schema-Reference-ALF.xml) からの抜粋で、元の参照スキーマではインデックスの名前はSQL120116153558430となっていますが、名前が正規表現であるSQL[0-9]+に一致していれば、適切な親テーブルとカラム名 (およびカラム順序) を持つインデックスは有効であることを示しています。

このバリデータを起動すると、インデックスの name プロパティが指定された正規表現に一致するかどうかが確認されます。これに加えて、このバリデータは、設定されている場合、インデックスの name プロパティを検証対象とすることを報告します。
これにより、スキーマ比較ツールは name プロパティに差分ロジックを適用しなくなります。DbValidatorがどのプロパティに対しても単独で検証を行わないようにすることで、差分ロジックに加え、このバリデータによる検証を適用することができます。逆に、バリデータがデータベースオブジェクト全体に対して検証を行うようにすることも可能で、その場合、オブジェクトのどの部分に対しても差分ロジックが適用されなくなります。

特定のサポートされていないアップグレードパスにより、スキーマに予期しない変化が生じた場合、それが必ずしも問題であるとは限りませんが、差分を明確にすることにより、その差分が問題かどうか、そして修正が必要かどうかを判断できるようにすることが重要です。スキーマ比較ツールを実行すると、ログファイルに以下の内容が記録される場合があります。

ACTデータベースオブジェクトは期待したものと同じですが、ターゲットスキーマとALF (alf_ prefixedデータベースオブジェクト) 参照スキーマとの間に差異があります。このファイルを確認してみると、自動生成されるはずのインデックスが、明示的な名前で作成されていることがわかります。

つまり、エラーレポートによると、参照スキーマで定義されている、ALF_ACCESS_CONTROL_ENTRYテーブルに属するSQL120131142718040という名前のインデックスは、SQLというプレフィックスと1桁以上の数字の文字列で命名されることが期待されています。

自動生成される名前の問題に類似した問題として、データベースオブジェクトが自動作成されるケースがあります。一部のデータベースは、スキーマ宣言に明示的に準拠するのではなく、即席でインデックスを作成します。これらのインデックスがスキーマ比較ツールを実行する時点で存在しているかどうかは不明です。このようなエラーが発生しないようにするには、IgnoreObjectValidatorを使用します。このバリデータは、関連するデータベースオブジェクトの検証に対応しますが、実際の検証は行いません。

自動検証のほか、JMX インターフェイスを使用して手動で検証を起動することもできます。

JMX カテゴリの Alfresco > DatabaseInformation > SchemaValidator には、1つの処理が含まれています。

この処理はパラメータを取らず、何も返しません。しかし、処理が起動されると、検証が実行され、その結果がログに表示されます。

この例では、ターゲットスキーマに問題は見つかりませんでした。