エンティティー・パフォーマンス・インスツルメンテーション・エージェント

Java Development Kit (JDK) バージョン 1.5 以降を使用している場合、 WebSphere® eXtreme Scale インスツルメンテーション・エージェントを使用可能にすることで、 フィールド・アクセス・エンティティーのパフォーマンスを向上させることができます。

JDK バージョン 1.5 以降での eXtreme Scale エージェントの使用可能化

以下の構文で Java コマンド行オプションを使用して ObjectGrid エージェントを使用可能化することができます。
-javaagent:jarpath[=options]
jarpath 値は、eXtreme Scale エージェント・クラスおよびサポート・クラスが入っている eXtreme Scale ランタイムの Java アーカイブ (JAR) ファイル (objectgrid.jarwsobjectgrid.jarogclient.jarwsogclient.jar、および ogagent.jar ファイルなど) へのパスです。通常、スタンドアロン Java プログラム、または WebSphere Application Server を稼働していない Java Platform, Enterprise Edition 環境では、objectgrid.jar ファイルまたは ogclient.jar ファイルを使用します。 WebSphere Application Server または複数クラス・ローダー環境では、Java コマンド行エージェント・オプションで ogagent.jar ファイルを使用する必要があります。 追加情報を指定するには、クラスパスに ogagent.config ファイルを指定するか、エージェント・オプションを使用します。

eXtreme Scale エージェント・オプション

config
構成ファイル名をオーバーライドします。
include
構成ファイルの最初の部分である変換ドメイン定義を指定またはオーバーライドします。
exclude
@Exclude 定義を指定またはオーバーライドします。
fieldAccessEntity
@FieldAccessEntity 定義を指定またはオーバーライドします。
trace
トレース・レベルを指定します。レベルには ALL、CONFIG、FINE、 FINER、FINEST、SEVERE、WARNING、INFO、および OFF があります。
trace.file
トレース・ファイルのロケーションを指定します。
各オプションを区切るために、区切り文字としてセミコロン (;) を使用します。コンマ ( ,) は、オプション内の各エレメントの区切り文字として使用します。以下の例は、Java プログラムの eXtreme Scale エージェント・オプションを示します。
-javaagent:objectgridRoot/lib/objectgrid.jar=config=myConfigFile;
include=includedPackage;exclude=excludedPackage;
fieldAccessEntity=package1,package2

ogagent.config ファイル

ogagent.config ファイルは、指定された eXtreme Scale エージェント構成ファイル名です。ファイル名がクラスパス内にある場合、eXtreme Scale エージェントはそのファイルを検索し、解析します。eXtreme Scale エージェントの構成オプションを使用して、指定されたファイル名をオーバーライドすることができます。 以下の例は、構成ファイルの指定方法を示しています。
-javaagent:objectgridRoot/lib/objectgrid.jar=config=myOverrideConfigFile
eXtreme Scale エージェント構成ファイルには、以下の部分があります。
  • 変換ドメイン: 変換ドメイン部分は、構成ファイルの最初にあります。変換ドメインは、クラス変換プロセスに組み込まれているパッケージおよびクラスのリストです。この変換ドメインには、フィールド・アクセス・エンティティー・クラスであるすべてのクラス、およびそれらのフィールド・アクセス・エンティティー・クラスを参照するその他のクラスが組み込まれる必要があります。フィールド・アクセス・エンティティー・クラス、およびそれらのフィールド・アクセス・エンティティー・クラスを参照するその他のクラスによって、変換ドメインは構成されます。フィールド・アクセス・エンティティー・クラスを @FieldAccessEntity 部分に指定する場合は、この部分にフィールド・アクセス・エンティティー・クラスを組み込む必要はありません。変換ドメインは、完全なものである必要があります。そうでないと、FieldAccessEntityNotInstrumentedException 例外が発生する場合があります。
  • @Exclude: @Exclude トークンは、このトークンの後にリストされるパッケージおよびクラスが、変換ドメインから除外されることを示します。
  • @FieldAccessEntity: @FieldAccessEntity トークンは、このトークンの後にリストされるパッケージおよびクラスが、フィールド・アクセス・エンティティー・パッケージおよびクラスであることを示します。@FieldAccessEntity トークンの後に行がない場合は、「@FieldAccessEntity が指定されていない」ことと同じになります。eXtreme Scale エージェントは、定義済みのフィールド・アクセス・エンティティー・パッケージおよびクラスはないものと判断します。 @FieldAccessEntity トークンの後に行が存在する場合、それらの行は、ユーザー指定のフィールド・アクセス・エンティティー・パッケージおよびクラスを表します。 例えば、「フィールド・アクセス・エンティティー・ドメイン」などです。 フィールド・アクセス・エンティティー・ドメインは、変換ドメインのサブドメインです。フィールド・アクセス・エンティティー・ドメインにリストされているパッケージおよびクラスは、それらが変換ドメインにリストされていない場合でも変換ドメインの一部です。変換から除外されているパッケージおよびクラスをリストする @Exclude トークンは、フィールド・アクセス・エンティティー・ドメインにはまったく影響しません。 @FieldAccessEntity トークンが指定されている場合、すべてのフィールド・アクセス・エンティティーが、このフィールド・アクセス・エンティティー・ドメインに入っている必要があります。そうでないと、FieldAccessEntityNotInstrumentedException 例外が発生する場合があります。

エージェント構成ファイル (ogagent.config) の例

################################
# The # indicates comment line
################################
# This is an ObjectGrid agent config file (the designated file name is ogagent.config) that can be found and parsed by the ObjectGrid agent
# if it is in classpath.
# If the file name is "ogagent.config" and in classpath, Java program runs with -javaagent:objectgridRoot/ogagent.jar will have
# ObjectGrid agent enabled.
# If the file name is not "ogagent.config" but in classpath, you can specify the file name in config option of ObjectGrid agent
#     -javaagent:objectgridRoot/lib/objectgrid.jar=config=myOverrideConfigFile
# See comments below for more info regarding instrumentation setting override.

# The first part of the configuration is the list of packages and classes that should be included in transformation domain.
# The includes (packages/classes, construct the instrumentation doamin) should be in the beginning of the file.
com.testpackage
com.testClass

# Transformation domain: The above lines are packages/classes that construct the transformation domain.
# The system will process classes with name starting with above packages/classes for transformation.
#
# @Exclude token : Exclude from transformation domain.
# The @Exclude token indicates packages/classes after that line should be excluded from transformation domain.
# It is used when user want to exclude some packages/classes from above specified included packages
#
# @FieldAccessEntity token: Field-access Entity domain.
# The @FieldAccessEntity token indicates packages/classes after that line are field-access Entity packages/classes.
# If there is no lilne after the @FieldAccessEntity token, it is equivalent to "No @FieldAccessEntity specified".
# The runtime will consider the user does not specify any field-access Entity packages/classes.
# The "field-acces Entity domain" is a sub-domain of transformation domain.
#
# Packages/classes listed in the "field-access Entity domain" will always be part of transformation domain,
# even they are not listed in transformation domain.
# The @Exclude, which lists packages/classes excluded from transformation, has no impact on the "field-acces Entity domain".
# Note: When @FieldAccessEntity is specified, all field-access entities must be in this field-acces Entity domain,
#       otherwise, FieldAccessEntityNotInstrumentedException may occur.
#
# The default ObjectGrid agent config file name is ogagent.config
# The runtime will look for this file as a resource in classpath and process it.
# Users can override this designated ObjectGrid agent config file name via config option of agent.
#
# e.g.
#	javaagent:objectgridRoot/lib/objectgrid.jar=config=myOverrideConfigFile
#
# The instrumentation definition, including transformation domain, @Exclude, and  @FieldAccessEntity can be overriden individually
# by corresponding designated agent options.
# Designated agent options include:
#    include              -> used to override instrumentation domain definition that is the first part of the config file
#    exclude              -> used to override @Exclude definition
#    fieldAccessEntity    -> used to override @FieldAccessEntity definition
#
# Each agent option should be separated by ";"
# Within the agent option, the package or class should be seperated by ","
#
# The following is an example that does not override the config file name:
#    -javaagent:objectgridRoot/lib/objectgrid.jar=include=includedPackage;exclude=excludedPackage;fieldAccessEntity=package1,package2
#
################################

@Exclude
com.excludedPackage
com.excludedClass

@FieldAccessEntity

パフォーマンスの考慮

パフォーマンスを向上させるために、変換ドメインおよびフィールド・アクセス・エンティティー・ドメインを指定します。