コンポーネント

J2G は、基本となる Eclipse IDE UI エクステンションの3種類の実行可能なユーティリティーで構成されています。"コンフィグレーター" コンポーネント、3種類の主要コンポーネント、各々の関連機能を、次のように順序よく実行しなければいけません。

必要条件

J2G ツール・セットは、少なくとも、以下のアプリケーションのバージョンを必要とします。
(これらは、J2G の動作確認が取れているバージョンです)

• Sun JDK 5.0 以上 (J2SE 1.5)
• Eclipse SDK 3.3M7 ( JDT Core Plug-in が付属していること )
• Apache Geronimo 1.1.1 以上
• JBoss 3.2 以上、もしくは、J2EE 1.2 以上で書き下ろされたアプリケーション

環境変数

J2G の各ツールでは、次の環境変数が正しい場所に設定されていなければいけません:

• JAVA_HOME (JDK の場所)
• ECLIPSE_HOME (Eclipse SDK の場所)
• WORKSPACE (一時領域となる eclipse ワークスペースの場所)

コンフィグレーター

このコンポーネントを実行するには、bin へ移動し、j2g-configure を実行してください。

user@lappy-486:~/j2g$ cd bin
user@lappy-486:~/j2g/bin$ ./j2g-configure.sh

Copying J2G plugins to /home/user/.m2/repository/eclipse/eclipse/plugins/ ...

`../plugins/org.apache.geronimo.j2g.common_1.0.0-SNAPSHOT.jar' ->
`/home/user/.m2/repository/eclipse/eclipse/plugins/org.apache.geronimo.j2g.common_1.0.0-SNAPSHOT.jar'
`../plugins/org.apache.geronimo.j2g.descriptors_1.0.0-SNAPSHOT.jar' ->
`/home/user/.m2/repository/eclipse/eclipse/plugins/org.apache.geronimo.j2g.descriptors_1.0.0-SNAPSHOT.jar'
`../plugins/org.apache.geronimo.j2g.jasper_1.0.0-SNAPSHOT.jar' ->
`/home/user/.m2/repository/eclipse/eclipse/plugins/org.apache.geronimo.j2g.jasper_1.0.0-SNAPSHOT.jar'
`../plugins/org.apache.geronimo.j2g.resources_1.0.0-SNAPSHOT.jar' ->
`/home/user/.m2/repository/eclipse/eclipse/plugins/org.apache.geronimo.j2g.resources_1.0.0-SNAPSHOT.jar'
`../plugins/org.apache.geronimo.j2g.sources_1.0.0-SNAPSHOT.jar' ->
/home/user/.m2/repository/eclipse/eclipse/plugins/org.apache.geronimo.j2g.sources_1.0.0-SNAPSHOT.jar'
`../plugins/org.apache.geronimo.j2g.util_1.0.0-SNAPSHOT.jar' ->
`/home/user/.m2/repository/eclipse/eclipse/plugins/org.apache.geronimo.j2g.util_1.0.0-SNAPSHOT.jar'
`../properties/org.apache.geronimo.j2g.descriptors.ejb/persistence_differences.properties' ->
`/home/user/.m2/repository/eclipse/eclipse/plugins/org.apache.geronimo.j2g.descriptors.ejb/persistence_differences.properties'
`../properties/org.apache.geronimo.j2g.descriptors.ejb.annotation/annotation_differences.properties' ->
/home/user/.m2/repository/eclipse/eclipse/plugins/org.apache.geronimo.j2g.descriptors.ejb.annotation/annotation_differences.properties'
`../properties/org.apache.geronimo.j2g.sources.dependence/default_jars.properties' ->
`/home/user/.m2/repository/eclipse/eclipse/plugins/org.apache.geronimo.j2g.sources.dependence/default_jars.properties'
`../properties/org.apache.geronimo.j2g.sources.dependence/class_analogies.properties' ->
`/home/user/.m2/repository/eclipse/eclipse/plugins/org.apache.geronimo.j2g.sources.dependence/class_analogies.properties'
`../properties/org.apache.geronimo.j2g.sources.dependence/compatible_sources.properties' ->
`/home/user/.m2/repository/eclipse/eclipse/plugins/org.apache.geronimo.j2g.sources.dependence/compatible_sources.properties'
`../properties/org.apache.geronimo.j2g.sources.environment/beans-types.properties' ->
`/home/user/.m2/repository/eclipse/eclipse/plugins/org.apache.geronimo.j2g.sources.environment/beans-types.properties'
`../properties/org.apache.geronimo.j2g.sources.environment/beans-interfaces.properties' ->
`/home/user/.m2/repository/eclipse/eclipse/plugins/org.apache.geronimo.j2g.sources.environment/beans-interfaces.properties'
`../properties/org.apache.geronimo.j2g.sources.environment/beans-references.properties' ->
`/home/user/.m2/repository/eclipse/eclipse/plugins/org.apache.geronimo.j2g.sources.environment/beans-references.properties'
`../compatibility/org.apache.geronimo.j2g.sources.dependence.compatibility/DigestCallback.java' ->
`/home/user/.m2/repository/eclipse/eclipse/plugins/org.apache.geronimo.j2g.sources.dependence.compatibility/DigestCallback.java'
`../compatibility/org.apache.geronimo.j2g.sources.dependence.compatibility/GeronimoLoginModule.java' ->
`/home/user/.m2/repository/eclipse/eclipse/plugins/org.apache.geronimo.j2g.sources.dependence.compatibility/GeronimoLoginModule.java'
`../compatibility/org.apache.geronimo.j2g.sources.dependence.compatibility/PasswordHasher.java' ->
`/home/user/.m2/repository/eclipse/eclipse/plugins/org.apache.geronimo.j2g.sources.dependence.compatibility/PasswordHasher.java'
`../compatibility/org.apache.geronimo.j2g.sources.dependence.compatibility/Nobody.java' ->
`/home/user/.m2/repository/eclipse/eclipse/plugins/org.apache.geronimo.j2g.sources.dependence.compatibility/Nobody.java'
`../compatibility/org.apache.geronimo.j2g.sources.dependence.compatibility/GeronimoSimpleGroup.java' ->
`/home/user/.m2/repository/eclipse/eclipse/plugins/org.apache.geronimo.j2g.sources.dependence.compatibility/GeronimoSimpleGroup.java'
`../compatibility/org.apache.geronimo.j2g.sources.dependence.compatibility/Anybody.java' ->
`/home/user/.m2/repository/eclipse/eclipse/plugins/org.apache.geronimo.j2g.sources.dependence.compatibility/Anybody.java'

A backup of your configuration file has been written to /home/user/.m2/repository/eclipse/eclipse/configuration/config.bak

Configuration complete.
user@lappy-486:~/j2g/bin$

これは、./plugins、./properties 、および、./compatibility の本体を ECLIPSE_HOME/plugins へ自動コピーするだけでなく、ECLIPSE_HOME/configuration/config.ini も変更します(もしくは、必要に応じて、作成します)。

ソース解析ツールの概略

このツールは、コマンドライン引数として渡されたディレクトリーにおいて、ソースコード (.java および .jsp ファイル) を再帰的に解析します。これを実行している間、Geronimo と同等な要素に対応している、あらゆる JBoss クラスや依存関係の要素を置換します。同じものがなかった場合、置換するクラスを手作業で作成するか、JBoss クラスに依存しているコードの部分を書き換えることによって、解決しなければならないこの課題をユーザーに警告します。

ディスクリプター変換ツールの概略

このツールは、JBoss 固有のデプロイメント・ディスクリプターや J2EE 標準のデプロイメント・ディスクリプターを、(必要に応じて) Geronimo の同等な要素へ変換します。

リソース変換ツールの概略

このツールは、Java メッセージング・サービス (JMS) キュー、JMS トピック、Java データベース接続 (JDBC) データソース、といった JBoss 固有のリソースを Geronimo の同等な要素へ変換します。

ソース解析ツール

説明

ソース解析ツールから、最初にスタートしてください。移行プロセス中に変更の必要なソースや固有ファイルをスキャンします。これらのファイルには、Java クラス (.java ファイル)、JSP (.jsp ファイル) だけでなく、引数 -jspext を指定した JSP ファイルの拡張をオーバーライドしたファイル (例: .html ファイル用の -jspext html) も含まれます。

これらにファイルに対して、当該ツールは以下の内容をチェックします:

• Geronimo の非互換 API の使用 (例. JBoss 内部 API)。
• J2EE ネーミング規則の違反。

ツールは Geronimo 非互換 API 使用のチェック時に、JBoss クラスは Geronimo 互換クラスへ自動的に置換されます。

今後は JBoss に依存できなくなるので、上記の一覧にない参照があれば手作業で修正しなければいけません。処理する JSP ファイルには問題の識別に限界があるのと、自動修正が現在サポートされていないことに、注意しておくことが重要です。

ツールが J2EE ネーミングの検証時に、コンポーネント (クラス、または、JSP) が変換されるアプリケーションの部分にない名前のオブジェクトを参照しているケースを検知します (例: データソース、JMS、Eメール・プロバイダーのリファレンス)。単純なケースの場合、コンポーネントがダイレクト、フル・パスつきの外部リソースを要求し、かつ、環境リファレンスがないと、ツールは、コンポーネントのデプロイメント・ディスクリプターに対してリソース・リファレンスを追加することによって自動的にこの問題を修正しようと試み、追加されたリファレンスの名前のダイレクト・パスに置換します。

ソース解析ツールでソースファイルが自動変換されると、変換元のバージョンは .j2g エクステンションに保存され、情報レベルのメッセージが出力されます。その他のケースでは、問題を手作業で修正する必要があるときに、ツールは警告メッセージを簡単に出力します。

追加クラスの指定

JBoss 固有クラスに対する追加のドロップ・イン置換は、 正式なリレーションシップを含む <ECLIPSE_HOME>/plugins/org.apache.geronimo.j2g.sources.dependence/class_analogies.properties だけでなく、クラス名を含む <ECLIPSE_HOME>/plugins/org.apache.geronimo.j2g.sources.dependence/compatible_sources.properties を変更することによって、ユーザー定義可能です。これらの置換クラスに対応するソースコードは、正式な含有に対応する <ECLIPSE_HOME>/plugins/org.apache.geronimo.j2g.sources.dependence.compatibility ディレクトリーに配置しなければなりません。

Geronimo の JAR ファイルにすでに存在するクラスは、class-analogies.properties ファイルに追加することが可能です。これらのクラスは、互換ディレクトリーに配置する必要はありませんが、依存関係については、変換元のアプリケーションにある関連ファイルに追加しなければいけません。

以下に示すのは、class_analogies.properties ファイルの初期設定例です。

#
#  Licensed to the Apache Software Foundation (ASF) under one or more
#  contributor license agreements.  See the NOTICE file distributed with
#  this work for additional information regarding copyright ownership.
#  The ASF licenses this file to You under the Apache License, Version 2.0
#  (the "License"); you may not use this file except in compliance with
#  the License.  You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
#  Unless required by applicable law or agreed to in writing, software
#  distributed under the License is distributed on an "AS IS" BASIS,
#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#  See the License for the specific language governing permissions and
#  limitations under the License.
#
###########################################################################################################
# Jboss classes and it's analogies.
###########################################################################################################
org.jboss.security.SimplePrincipal = org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal
org.jboss.security.auth.spi.DigestCallback = org.apache.geronimo.j2g.sources.dependence.compatibility.DigestCallback
org.jboss.security.Nobody = org.apache.geronimo.j2g.sources.dependence.compatibility.Nobody
org.jboss.security.Anybody = org.apache.geronimo.j2g.sources.dependence.compatibility.Anybody
org.jboss.security.auth.spi.UsernamePasswordLoginModule = org.apache.geronimo.j2g.sources.dependence.compatibility.GeronimoLoginModule
org.jboss.security.SimpleGroup = org.apache.geronimo.j2g.sources.dependence.compatibility.GeronimoSimpleGroup

以下に示すのは、compatible_sources.properties ファイルの初期設定例です。

#
#  Licensed to the Apache Software Foundation (ASF) under one or more
#  contributor license agreements.  See the NOTICE file distributed with
#  this work for additional information regarding copyright ownership.
#  The ASF licenses this file to You under the Apache License, Version 2.0
#  (the "License"); you may not use this file except in compliance with
#  the License.  You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
#  Unless required by applicable law or agreed to in writing, software
#  distributed under the License is distributed on an "AS IS" BASIS,
#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#  See the License for the specific language governing permissions and
#  limitations under the License.
#
######################################################################
# List of compatibility sources
######################################################################
org.apache.geronimo.j2g.sources.dependence.compatibility.DigestCallback
org.apache.geronimo.j2g.sources.dependence.compatibility.Nobody
org.apache.geronimo.j2g.sources.dependence.compatibility.Anybody
org.apache.geronimo.j2g.sources.dependence.compatibility.GeronimoLoginModule
org.apache.geronimo.j2g.sources.dependence.compatibility.GeronimoSimpleGroup
org.apache.geronimo.j2g.sources.dependence.compatibility.PasswordHasher

ソース解析ツールの実行 - Eclipse GUI

Eclipse IDE GUI にてこのコンポーネントを実行するには、左パネルがまずナビゲーター・ビューになければいけません。

ナビゲーター・ビューに入ると、右クリックして、コンテキスト・メニューから J2G Migration を選択することが可能です。

J2G Migration サブ・メニューに入り、"1. Source Identification Tool (jsrc2g)" を選択し、後は表示されているプロンプトに従ってください。

出力内容は Eclipse IDE の下部にある Console ウィンドウの中に表示されます。

ソース解析ツールの実行 - コマンドライン

このコンポーネントを実行するには、j2g の bin ディレクトリーから次のコマンドを実行してください。<APPLICATION> は変換するアプリケーションのパスを表し、<GERONIMO_HOME> は Geronimo 2.0のパスを表しています。

*nix

./jsrc2g.sh -src <APPLICATION>/src -web <APPLICATION>/web -geronimo <GERONIMO_HOME>

Windows

jsrc2g.bat -src <APPLICATION>\src -web <APPLICATION>\web -geronimo <GERONIMO_HOME>

注意: 変換対象に複数のソースを指定したい時は、次のように、単に , （カンマ）で区切ってください。

jsrc2g.cmd -src <APPLICATION>/src,<APPLICATION>/src2,...<APPLICATION>/srcn -web <APPLICATION>/web -geronimo <GERONIMO_HOME>

ツールの実行後(システムの速度やアプリケーションの複雑度次第では、数秒程度かかるかもしれません)、コンソール出力に、警告やエラーがすべて表示されます。これらのメッセージは、ユーザーに合うように解釈され、目に見える形で修正されなければいけません。変更を完了すると、ソース解析ツールは、修正の確認を再度実行することが可能です。

ディスクリプター変換ツール

説明

ディスクリプター変換ツールは、次のデプロイメント・ディスクリプターを検索して、自動変換を試みます。その結果、それらは Geronimo で使用されます:

注意: Geronimo は OpenEJB を使用し、専用のディスクリプター (openejb-jar.xml) を必要とします。jboss.xml が与えられない一部のインスタンスが若干あるかもしれません。これらのケースでは、openejb-jar.xml は、J2G に指定されたソース・パスの一番上のレベルのディレクトリー上に作成されます。

アノテーション (EJB 3.0 用)

標準の EJB アノテーションは、Geronimo と JBoss の両方でサポートされています。しかしながら、アノテーションの一部に提供されている属性の中には、差異があります。
以下に示すのは、指定アノテーションの中に発生するかもしれない、提供されているすべての標準属性の違いの一覧です。

今後は JBoss に依存できなくなるので、上記の一覧にない参照があれば手作業で修正しなければいけません。

追加アノテーションの指定

JBoss 固有のアノテーション属性に対する追加のドロップ・イン置換は、 正式なリレーションシップを含む <ECLIPSE_HOME>/plugins/org.apache.geronimo.j2g.descriptors.ejb.annotation/annotation_differences.properties を変更することによって、ユーザー定義可能です。というのも、これらのマッピングの本来の形は1対1ではなく、<annotation>=<attribute> という従来の書式の中でプロパティーを書式化することができません。その代わりに、正式な書式化は次のようになります:

標準の EJB アノテーションの場合

<property> :: <annotation>=<mapping>

<annotation> は 標準の EJB アノテーションです。

Geronimo 互換のリレーションシップに対する標準的な JBoss 固有属性の場合

<mapping> :: <j_attribute>--><g_attribute>

<j_attribute> は JBoss がサポートしている属性、<g_attribute> は Geronimo がサポートしている属性です。

最後に、単一アノテーションに対して複数属性のマッピングを必要とする場合

<mapping> :: <j_attribute>--><g_attribute>,<mapping>

<j_attribute> は JBoss がサポートしている属性、<g_attribute> は Geronimo がサポートしている属性です。

以下に示すのは、annotation_differences.properties ファイルの初期設定例です。

#
#  Licensed to the Apache Software Foundation (ASF) under one or more
#  contributor license agreements.  See the NOTICE file distributed with
#  this work for additional information regarding copyright ownership.
#  The ASF licenses this file to You under the Apache License, Version 2.0
#  (the "License"); you may not use this file except in compliance with
#  the License.  You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
#  Unless required by applicable law or agreed to in writing, software
#  distributed under the License is distributed on an "AS IS" BASIS,
#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#  See the License for the specific language governing permissions and
#  limitations under the License.
#
###########################################################################
# Jboss classes and it's analogies.
###########################################################################
Resource = mappedName-->name
EJB = mappedName-->name
MessageDriven = mappedName-->name
Stateful = mappedName-->name
Stateless = mappedName-->name

OpenEJB

ツールが Geronimo と非互換の EJB リファレンスの使用をチェックすると、これらの JBoss EJB リファレンスは Geronimo 互換の OpenEJB リファレンスに自動的に置換されます。ここにあるのは、(EJB 3.0 で使用される) persistence.xml の中でで変更するために示されている差異です。したがって、構成は密接に結び合っています。

今後は JBoss に依存できなくなるので、上記の一覧にない参照があれば手作業で修正しなければいけません。

persistence.xml に対する追加 OpenEJB アノテーションの指定

JBoss 固有のアノテーション属性に対する追加のドロップ・イン置換は、正式なリレーションシップを含む <ECLIPSE_HOME>/plugins/org.apache.geronimo.j2g.descriptors.ejb/persistence_differences.properties を変更することによって、ユーザー定義可能です。

以下に示すのは、persistence_differences.properties ファイルの初期設定例です。

#
#  Licensed to the Apache Software Foundation (ASF) under one or more
#  contributor license agreements.  See the NOTICE file distributed with
#  this work for additional information regarding copyright ownership.
#  The ASF licenses this file to You under the Apache License, Version 2.0
#  (the "License"); you may not use this file except in compliance with
#  the License.  You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
#  Unless required by applicable law or agreed to in writing, software
#  distributed under the License is distributed on an "AS IS" BASIS,
#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#  See the License for the specific language governing permissions and
#  limitations under the License.
#
###########################################################################
# Jboss persistence.xml property names and its analogies.
###########################################################################
hibernate.connection.url = openjpa.ConnectionURL
hibernate.connection.driver_class = openjpa.ConnectionDriverName
hibernate.connection.password = openjpa.ConnectionPassword
hibernate.connection.username = openjpa.ConnectionUserName
hibernate.hbm2ddl.auto = suggestion:openjpa.jdbc.SynchronizeMappings

X が Y に対する代わりであるかもしれないことをユーザーにしっかり提示するためには (これは直接解釈されないため、条件つきです)、プロパティーは <Y> = suggestion:<X> として書くことも可能です。

ディスクリプター変換ツールの実行 - Eclipse GUI

Eclipse IDE GUI にてこのコンポーネントを実行するには、左パネルがまずナビゲーター・ビューになければいけません。

ナビゲーター・ビューに入ると、右クリックして、コンテキスト・メニューから J2G Migration を選択することが可能です。

J2G Migration サブ・メニューに入り、"2. Descriptors Conversion Tool (jdes2g)", を選択し、後は表示されているプロンプトに従ってください。
出力内容は Eclipse IDE の下部にある Console ウィンドウの中に表示されます。

ディスクリプター変換ツールの実行 - コマンド・ライン

ディスクリプター変換ツールを実行するには、j2g の bin ディレクトリーから次のコマンドを実行してください。繰り返しになりますが、<APPLICATION> は変換するアプリケーションのパスを表します。

*nix

./jdesc2g.sh <APPLICATION>

Windows

jdesc2g.bat <APPLICATION>

このツールの出力に示されている警告は、自動的に変換できなかった未サポートの要素のみをレポートしているため、手作業で解決および変換しなければなりません。この処理は、変換されるアプリケーションの構造に大きく依存するため、本文書の範囲を越えてしまいます。

リソース変換ツール

説明

リソース変換ツールは、JBoss 固有のリソースを Geronimo の同等な要素へ変換します。次にあげる種類のリソースを対象に処理します:

• JDBC 接続プールを定義している JBoss/JCA データソース・ディスクリプター (*-ds.xml ファイル)。データソースはデータベースの種類に依存するため、ツールは次のよく知られているデータベース向けの移行を自動的に実行します
  • DB2
  • Derby
  • Hypersonic
  • Informix
  • Microsoft SQL
  • MySQL
  • Oracle
  • PostgreSQL
  • それ以外のデータソースの定義は手作業で移行する必要があります。定義が未知のパラメータを含んでいる場合、ツールは警告メッセージを添えてこのことを知らせます。

• JBoss MBean ディスクリプター (*-service.xml ファイル)。次のリソースの定義のみが移行されます。
  • javax.mail.Session
  • javax.jms.QueueConnectionFactory
  • javax.jms.TopicConnectionFactory
  • javax.transaction.TransactionManager

• JASS ログイン・モジュール構成を提供している JBoss セキュリティー・ポリシー・ディスクリプター (login-config.xml)。ツールは次の JBoss ログイン・モジュール向けにロールやポリシーだけでなくユーザーやグループを移行します。
  • org.jboss.security.auth.spi.IdentityLoginModule
  • org.jboss.security.auth.spi.UsersRolesLoginModule
  • org.jboss.security.auth.spi.LdapLoginModule
  • org.jboss.security.auth.spi.DatabaseServerLoginModule

リソース変換ツールの実行 - Eclipse GUI

Eclipse IDE GUI にてこのコンポーネントを実行するには、左パネルがまずナビゲーター・ビューになければいけません。

ナビゲーター・ビューに入ると、右クリックして、コンテキスト・メニューから J2G Migration を選択することが可能です。

J2G Migration サブ・メニューに入り、"3. Resource Migration Tool (jres2g)", を選択し、後は表示されているプロンプトに従ってください。
出力内容は Eclipse IDE の下部にある Console ウィンドウの中に表示されます。

リソース変換ツールの実行 - コマンド・ライン

ディスクリプター変換ツールを実行するには、j2g の bin ディレクトリーから次のコマンドを実行してください。繰り返しになりますが、<APPLICATION> は変換するアプリケーションのパスを表します。

*nix

./jres2g.sh <APPLICATION>

Windows

jres2g.bat <APPLICATION>

ツールは、移行対象の各リソースの名前だけでなく、ファイル名や行番号を添えた情報、エラー、警告のメッセージを出力します。エラーなしでリソースの移行が完了した場合、ツールは成功のメッセージを出力し、同じフォルダーに移行されたりソースをオリジナル・リソースとして生成します。

他のツールと同様に、エラーや警告のメッセージについては、変換処理を完了させるために、手作業で修正する必要があります。繰り返しになりますが、それは大きなアプリケーション固有の内容であり、本文書の範囲を越えています。

完了

上記のツールをすべて実行し、エラーや警告がなければ、変換されたアプリケーションは Geronimo 用にビルドされるかもしれません。また、このことは極端にアプリケーション固有であったり、特定の状況ごとに十分適応させる必要がある、といった重要なことです。

正常にビルドされた後、アプリケーションは、問題なく Geronimo 2.0 の実行インスタンスの中でデプロイすることが可能ですが、それはデプロイメント時に表示される解決すべきエラーがない場合であって、アプリケーションはリビルドさせる必要があります。