G Schema Reference: Message Catalog msgcat.dtd

This appendix provides a reference to elements of the msgcat.dtd schema, the schema behind XML you use to configure message catalog elements for log messages you can localize.

G.1 Overview of the Message Catalog Elements

Oracle CEP provides a number of message catalog elements that you use to define log messages that you can localize.

G.1.1 Element Hierarchy

The top-level Oracle CEP message catalog elements are organized into the following hierarchies, depending on message catalog type:

Example G-1 Log Message Catalog Hierarchy

message_catalog
    log_message
        messagebody
        messagedetail
        cause
        action

Example G-2 Simple Text Catalog Hierarchy

message_catalog
    message
        messagebody

G.1.2 Examples

This section provides the following message catalog examples:

Example G-3 Log Message Catalog

<?xml version="1.0"?>
<!DOCTYPE message_catalog PUBLIC "weblogic-message-catalog-dtd" 
"http://www.bea.com/servers/wls90/dtd/msgcat.dtd">
<message_catalog 
  l10n_package="programs.utils"
  i18n_package="programs.utils"
  subsystem="MYUTIL"
  version="1.0"
  baseid="600000"
  endid="600100">
  <logmessage
    messageid="600001"
    severity="warning"
    method="logNoAuthorization(String arg0, java.util.Date arg1,int arg2)">
    <messagebody>
      Could not open file, {0} on {1,date} after {2,number} attempts.
    </messagebody>
    <messagedetail>
      The configuration for this application will be defaulted to
      factory settings. Custom configuration information resides
      in file, {0}, created on {1,date}, but is not readable.
    </messagedetail>
    <cause>
      The user is not authorized to use custom configurations. Custom
     configuration information resides in file, {0}, created on
     {1,date}, but is not readable.The attempt has been logged to
     the security log.
    </cause>
    <action>
      The user needs to gain approriate authorization or learn to
      live with the default settings.
    </action>
  </logmessage>
</message_catalog>

Example G-4 Simple Text Catalog

<?xml version="1.0"?> 
<!DOCTYPE message_catalog PUBLIC "weblogic-message-catalog-dtd"
    "http://www.bea.com/servers/wls90/dtd/msgcat.dtd"> 
<message_catalog>
  l10n_package="programs.utils"
  i18n_package="programs.utils"
  subsystem="MYUTIL"
  version="1.0">
  <message messageid="FileMenuTitle">
    <messagebody>
      File
    </messagebody>
  </message>
</message_catalog>

G.2 message_catalog

This element represents the log message catalog.

G.2.1 Child Elements

The message_catalog element supports the following child elements:

G.2.2 Attributes

Table G-1 lists the attributes of the message_catalog element.

Table G-1 Attributes of the message_catalog Element

Attribute Description Data Type Required?

i18n_package

Java package containing generated Logger classes for this catalog. The classes are named after the catalog file name. For example, for a catalog using mycat.xml, a generated Logger class would be called i18n_package.mycatLogger.class.

Syntax: standard Java package syntax.

Example: i18n_package="programs.utils"

Default: weblogic.i18n

String

No.

I10n_package

A Java package containing generated LogLocalizer properties for the catalog. For example, for a catalog called mycat.xml, the following property files would be generated:

  • l10n_package.mycatLogLocalizer.properties

  • l10n_packagemycatLogLocalizerDetail.properties

Syntax: standard Java package syntax.

Example: l10n_package="programs.utils"

Default: weblogic.i18n

String

No.

subsystem

An acronym identifying the subsystem associated with this catalog. The name of the subsystem is included in the server log and is used for message isolation purposes.

Example: subsystem="MYUTIL"

String

Yes.

version

Specifies the version of the msgcat.dtd being used.

Use: Must be "1.0"

Syntax: x.y where x and y are numeric.

Example: version="1.0"

String

Yes.

baseid

Specifies the lowest message ID used in this catalog.Syntax: one to six decimal digits.Example: baseid="600000"

Valid values are:

  • 000000 for Oracle CEP server catalogs

  • 500000 for user-defined catalogs

String

No.

endid

Specifies the highest message ID used in this catalog.

Syntax: one to six decimal digits.

Example: endid="600100"

Valid values are:

  • 499999 for Oracle CEP server catalogs

  • 999999 for user-defined catalogs

String

No.

loggables

Indicates whether to generate additional methods that return loggable objects.

Example: loggable="true"

Valid values are:

  • true

  • false

Default: false

String

  

prefix

Specifies a String to be prepended to message IDs when logged. Oracle CEP server messages default to "CEP" as the prefix and may not specify a different prefix. User messages can specify any prefix. A prefixed message ID is presented in a log entry as follows:

<[prefix-]id>

Where prefix is this attribute and id is the six-digit message ID associated with a specific message.

For example, if prefix is "XYZ", then message 987654 would be shown in a log entry as <XYZ-987654>. If prefix is not defined, then the log entry would be <987654>.

Syntax: any String (should be limited to five characters).

Example: prefix="CEP"

Valid values are:

  • "CEP" for Oracle CEP server catalogs.

  • null for user-defined catalogs

String

No.

description

An optional attribute that serves to document the catalog content.

Example: description="Contains messages logged by the foobar application"

String

No.

G.2.3 Example

The following example shows how to use the message_catalog element in log message catalog file:

<?xml version="1.0"?>
<!DOCTYPE message_catalog PUBLIC "weblogic-message-catalog-dtd" 
"http://www.bea.com/servers/wls90/dtd/msgcat.dtd">
<message_catalog 
  l10n_package="programs.utils"
  i18n_package="programs.utils"
  subsystem="MYUTIL"
  version="1.0"
  baseid="600000"
  endid="600100">
  <logmessage
    messageid="600001"
    severity="warning"
    method="logNoAuthorization(String arg0, java.util.Date arg1,int arg2)">
    <messagebody>
      Could not open file, {0} on {1,date} after {2,number} attempts.
    </messagebody>
    <messagedetail>
      The configuration for this application will be defaulted to
      factory settings. Custom configuration information resides
      in file, {0}, created on {1,date}, but is not readable.
    </messagedetail>
    <cause>
      The user is not authorized to use custom configurations. Custom
     configuration information resides in file, {0}, created on
     {1,date}, but is not readable.The attempt has been logged to
     the security log.
    </cause>
    <action>
      The user needs to gain approriate authorization or learn to
      live with the default settings.
    </action>
  </logmessage>
</message_catalog>

G.3 logmessage

Use this element to define a formal log message.

G.3.1 Child Elements

The logmessage component configuration element supports the following child elements:

G.3.2 Attributes

Table G-2 lists the attributes of the logmessage component configuration element.

Table G-2 Attributes of the logmessage Element

Attribute Description Data Type Required?

messageid

Unique identifier for this log message. Uniqueness should extend across all catalogs. Value must be in range defined by baseid and endid attributes.

Use: Value must be in the range defined by the baseid and endid attributes defined in the message_catalog element.

Syntax: one to six decimal digits.

Example: messageid="600001"

String

Yes.

datelastchanged

Date/time stamp used for managing modifications to this message. The date is supplied by utilities that run on the catalogs.

Use: The date is supplied by utilities that run on the catalogs.

Syntax: Long.toString(new Date().getTime());

String

No.

severity

Indicates the severity of the log message. User-defined catalogs may only use debug, info, warning, and error.

Valid values:

  • error

  • warning

  • info

  • debug

Example: severity="warning"

String

Yes.

method

Method signature for logging this message.

The syntax is the standard Java method signature, without the qualifiers, semicolon, and extensions. Argument types can be any Java primitive or class. Classes must be fully qualified if not in java.lang. Classes must also conform to java.text.MessageFormat conventions. In general, class arguments should have a useful toString() method.

Arguments can be any valid name, but should follow the convention of argn where n is 0 through 9. There can be no more than 10 arguments. For each argn there should be at least one corresponding placeholder in the text elements Section G.3.1, "Child Elements" describes. Placeholders are of the form {n}, {n,number} or {n,date}.

String

Yes.

methodtype

Specifies type of method to generate. Methods can be:

  • Logger methods format the message body into the default locale and log the results.

  • Getter methods return the message body prefixed by the subsystem and messageid, as follows: [susbsystem:msgid]text.

Valid values are:

  • logger

  • getter

Default: logger.

String

No.

stacktrace

Indicates whether to generate a stack trace for Throwable arguments. When the value is true, a trace is generated.

Valid values are:

  • true

  • false

Default: true.

String

No.

retired

Indicates whether message is retired. A retired message is one that was used in a previous release but is now obsolete and not used in the current version. Retired messages are not represented in any generated classes or resource bundles.

Valid values are:

  • true

  • false

Default: false.

String

No.

G.3.3 Example

The following example shows how to use the logmessage element in log message catalog file:

<?xml version="1.0"?>
<!DOCTYPE message_catalog PUBLIC "weblogic-message-catalog-dtd" 
"http://www.bea.com/servers/wls90/dtd/msgcat.dtd">
<message_catalog 
  l10n_package="programs.utils"
  i18n_package="programs.utils"
  subsystem="MYUTIL"
  version="1.0"
  baseid="600000"
  endid="600100">
  <logmessage
    messageid="600001"
    severity="warning"
    method="logNoAuthorization(String arg0, java.util.Date arg1,int arg2)">
    <messagebody>
      Could not open file, {0} on {1,date} after {2,number} attempts.
    </messagebody>
    <messagedetail>
      The configuration for this application will be defaulted to
      factory settings. Custom configuration information resides
      in file, {0}, created on {1,date}, but is not readable.
    </messagedetail>
    <cause>
      The user is not authorized to use custom configurations. Custom
     configuration information resides in file, {0}, created on
     {1,date}, but is not readable.The attempt has been logged to
     the security log.
    </cause>
    <action>
      The user needs to gain approriate authorization or learn to
      live with the default settings.
    </action>
  </logmessage>
</message_catalog>

G.4 message

Use this element to define an informal log message.

G.4.1 Child Elements

The message element supports the following child elements:

G.4.2 Attributes

Table G-3 lists the attributes of the message element.

Table G-3 Attributes of the message Element

Attribute Description Data Type Required?

messageid

Unique identifier for this log message in alpha-numeric string format. Uniqueness is required only within the context of this catalog.

String

Yes.

datelastchanged

Date/time stamp used for managing modifications to this message. The date is supplied by utilities that run on the catalogs.

Use: The date is supplied by utilities that run on the catalogs.

Syntax: Long.toString(new Date().getTime());

String

No.

method

Method signature for formatting this message.

The syntax is a standard Java method signature, less return type, qualifiers, semicolon, and extensions. The return type is always String. Argument types can be any Java primitive or class. Classes must be fully qualified if not in java.lang. Classes must also conform to java.text.MessageFormat conventions. In general, class arguments should have a useful toString() method, and the corresponding MessageFormat placeholders must be strings; they must be of the form {n}. Argument names can be any valid name. There can be no more than 10 arguments.

For each argument there must be at least one corresponding placeholder in the messagebody element. Placeholders are of the form {n}, {n,number} or {n,date}.

Example: method="getNoAuthorization(String filename, java.util.Date creDate)"

This example would result in a method in the TextFormatter class as follows:

public String getNoAuthorization(String filename, java.util.Date creDate)

String

No.

retired

Indicates whether message is retired. A retired message is one that was used in a previous release but is now obsolete and not used in the current version. Retired messages are not represented in any generated classes or resource bundles.

Valid values are:

  • true

  • false

Default: false.

String

No.

G.4.3 Example

The following example shows how to use the message element in log message catalog file:

<?xml version="1.0"?> 
<!DOCTYPE message_catalog PUBLIC "weblogic-message-catalog-dtd"
    "http://www.bea.com/servers/wls90/dtd/msgcat.dtd"> 
<message_catalog>
  l10n_package="programs.utils"
  i18n_package="programs.utils"
  subsystem="MYUTIL"
  version="1.0">
  <message messageid="FileMenuTitle">
    <messagebody>
      File
    </messagebody>
  </message>
</message_catalog>

G.5 messagebody

Use this element to define a short description for this message.

The messagebody element can contain a 0 to 10 placeholder as {n}, to be replaced by the appropriate argument when the log message is localized.

The message body must include placeholders for all arguments listed in the corresponding method attribute, unless the last argument is throwable or a subclass.

Be careful when using single quotes, because these are specially parsed by java.text.MessageFormat. If it is appropriate to quote a message argument, use double quotes (Section G.5.3, "Example" shows). If a message has one or more placeholders, in order for a single quote to appear correctly (for example, as an apostrophe), it must be followed by a second single quote.

Syntax: a String

G.5.1 Child Elements

The messagebody element has no child elements.

G.5.2 Attributes

The messagebody element has no attributes.

G.5.3 Example

The following example shows how to use the messagebody element in log message catalog file:

<?xml version="1.0"?>
<!DOCTYPE message_catalog PUBLIC "weblogic-message-catalog-dtd" 
"http://www.bea.com/servers/wls90/dtd/msgcat.dtd">
<message_catalog 
  l10n_package="programs.utils"
  i18n_package="programs.utils"
  subsystem="MYUTIL"
  version="1.0"
  baseid="600000"
  endid="600100">
  <logmessage
    messageid="600001"
    severity="warning"
    method="logNoAuthorization(String arg0, java.util.Date arg1,int arg2)">
    <messagebody>
      Could not open file, "{0}" on {1,date} after {2,number} attempts.
    </messagebody>
    <messagedetail>
      The configuration for this application will be defaulted to
      factory settings. Custom configuration information resides
      in file, {0}, created on {1,date}, but is not readable.
    </messagedetail>
    <cause>
      The user is not authorized to use custom configurations. Custom
     configuration information resides in file, {0}, created on
     {1,date}, but is not readable.The attempt has been logged to
     the security log.
    </cause>
    <action>
      The user needs to gain approriate authorization or learn to
      live with the default settings.
    </action>
  </logmessage>
</message_catalog>

G.6 messagedetail

Use this element to define a detailed description of the event. This element may contain any argument place holders.

Syntax: a String

G.6.1 Child Elements

The messagedetail element supports has no child elements.

G.6.2 Attributes

The messagedetail element has no attributes.

G.6.3 Example

The following example shows how to use the messagedetail element in log message catalog file:

<?xml version="1.0"?>
<!DOCTYPE message_catalog PUBLIC "weblogic-message-catalog-dtd" 
"http://www.bea.com/servers/wls90/dtd/msgcat.dtd">
<message_catalog 
  l10n_package="programs.utils"
  i18n_package="programs.utils"
  subsystem="MYUTIL"
  version="1.0"
  baseid="600000"
  endid="600100">
  <logmessage
    messageid="600001"
    severity="warning"
    method="logNoAuthorization(String arg0, java.util.Date arg1,int arg2)">
    <messagebody>
      Could not open file, {0} on {1,date} after {2,number} attempts.
    </messagebody>
    <messagedetail>
      The configuration for this application will be defaulted to
      factory settings. Custom configuration information resides
      in file, {0}, created on {1,date}, but is not readable.
    </messagedetail>
    <cause>
      The user is not authorized to use custom configurations. Custom
     configuration information resides in file, {0}, created on
     {1,date}, but is not readable.The attempt has been logged to
     the security log.
    </cause>
    <action>
      The user needs to gain approriate authorization or learn to
      live with the default settings.
    </action>
  </logmessage>
</message_catalog>

G.7 cause

Use this element to define the root cause of the problem. This element can contain any argument place holders.

Syntax: a String.

G.7.1 Child Elements

The cause element supports has no child elements.

G.7.2 Attributes

The cause element has no attributes.

G.7.3 Example

The following example shows how to use the cause element in log message catalog file:

<?xml version="1.0"?>
<!DOCTYPE message_catalog PUBLIC "weblogic-message-catalog-dtd" 
"http://www.bea.com/servers/wls90/dtd/msgcat.dtd">
<message_catalog 
  l10n_package="programs.utils"
  i18n_package="programs.utils"
  subsystem="MYUTIL"
  version="1.0"
  baseid="600000"
  endid="600100">
  <logmessage
    messageid="600001"
    severity="warning"
    method="logNoAuthorization(String arg0, java.util.Date arg1,int arg2)">
    <messagebody>
      Could not open file, {0} on {1,date} after {2,number} attempts.
    </messagebody>
    <messagedetail>
      The configuration for this application will be defaulted to
      factory settings. Custom configuration information resides
      in file, {0}, created on {1,date}, but is not readable.
    </messagedetail>
    <cause>
      The user is not authorized to use custom configurations. Custom
     configuration information resides in file, {0}, created on
     {1,date}, but is not readable.The attempt has been logged to
     the security log.
    </cause>
    <action>
      The user needs to gain approriate authorization or learn to
      live with the default settings.
    </action>
  </logmessage>
</message_catalog>

G.8 action

Use this element to define the recommended resolution. This element can contain any argument place holders.

Syntax: a String.

G.8.1 Child Elements

The action element supports has no child elements.

G.8.2 Attributes

The action element has no attributes.

G.8.3 Example

The following example shows how to use the action element in log message catalog file:

<?xml version="1.0"?>
<!DOCTYPE message_catalog PUBLIC "weblogic-message-catalog-dtd" 
"http://www.bea.com/servers/wls90/dtd/msgcat.dtd">
<message_catalog 
  l10n_package="programs.utils"
  i18n_package="programs.utils"
  subsystem="MYUTIL"
  version="1.0"
  baseid="600000"
  endid="600100">
  <logmessage
    messageid="600001"
    severity="warning"
    method="logNoAuthorization(String arg0, java.util.Date arg1,int arg2)">
    <messagebody>
      Could not open file, {0} on {1,date} after {2,number} attempts.
    </messagebody>
    <messagedetail>
      The configuration for this application will be defaulted to
      factory settings. Custom configuration information resides
      in file, {0}, created on {1,date}, but is not readable.
    </messagedetail>
    <cause>
      The user is not authorized to use custom configurations. Custom
     configuration information resides in file, {0}, created on
     {1,date}, but is not readable.The attempt has been logged to
     the security log.
    </cause>
    <action>
      The user needs to gain approriate authorization or learn to
      live with the default settings.
    </action>
  </logmessage>
</message_catalog>