2.4.3 Naming rules for the Portable Global JNDI names

The Portable Global JNDI name includes the standard application name, standard module name, and Enterprise Bean name. Java EE defines the naming rules and characters that can be used for these names.

This subsection describes the naming rules for the standard application name, standard module name, and Enterprise Bean name used in the Portable Global JNDI name, and the characters that can be used.

Organization of this subsection
(1) Naming rules for the standard application name
(2) Naming rules for the standard module name
(3) Naming rules for the Enterprise Bean name
(4) Operations when the standard application name or standard module name are duplicated

(1) Naming rules for the standard application name

The following table describes the rules for setting up the standard application name.

Table 2-11 Naming rules for the standard application name

Preconditions for the applicationStandard application name
J2EE application (EAR file)application.xml exists.The <application-name> tag exists.The value exists.Value of the <application-name> tag #1
The value is null #2.Default standard application name #3
The <application-name> tag does not exist.--
application.xml does not exist.----
WAR application
(WAR file)
A value is specified in the -name option of the cjimportwar commandValue of the -name option of the cjimportwar command #1
No value is specified in the -name option of the cjimportwar commandDefault standard application name #3
Legend:
--: Not applicable.
#1
The space characters before and after the value (single-byte spaces, tabs, and linefeeds) are removed. The space characters between the words are not removed.
#2
Indicates a zero length string. A value consisting of only a space character is also determined to be null.
#3
The default standard application name differs depending on the J2EE application format. The following table describes the naming rules for the default standard application name.

Table 2-12 Naming rules for the default standard application name

Precondition for applicationsDefault standard application name
J2EE application
(EAR file)
Archive formatString obtained by removing the extension from the name of the EAR file.
However, the extension is not removed if a period "." exists only at the beginning of the file name.
Exploded archive format
  • If application.xml exists
    J2EE application name (value of the <display-name> tag).
  • If application.xml does not exist
    Name of the application directory.
WAR application
(WAR file)
Archive formatString obtained by removing the extension from the name of the WAR file.
However, the extension is not removed if a period "." exists only at the beginning of the file name.
Exploded archive formatWAR directory name.

The values that can be specified in the standard application name are as follows:

Standard application name specified in the <application-name> tag
The standard application name is registered if the name contains single-byte alphanumeric characters (0 to 9, A to Z, and a to z) and the following special characters:
Space ( ), exclamation mark (!), double quotation mark ("), hash mark (#), dollar sign ($), percent sign (%), ampersand (&), single quotation mark ('), barren (() ()), asterisk (*), plus sign (+), comma (,), hyphen (-), period (.), colon (:), semicolon (;), less-than sign (<), equal sign (=), greater-than sign (>), question mark (?), at mark (@), square brackets ([) (]), backslash (\), caret (^), underscore (_), grave accent mark (`), curly brackets ({) (}), vertical bar (|), and tilde (~)
However, the following names are not registered:
  • Names that begin or end with a period (.)
  • Names containing a period (.) only
  • Names with a string length of 256 characters or more
  • Names matching with env
Standard application name specified in the <display-name> tag
The standard application name (value of the <display-name> tag) is registered if the name contains single-byte alphanumeric characters (0 to 9, A to Z, and a to z), plus (+), hyphen (-), period (.), underscore (_), and caret (^).
However, the following names are not registered:
  • Names that begin or end with a period (.)
  • Names containing a period (.) only
  • Names with a string length of less than 1 character
  • Names with a string length of 256 characters or more
  • Names matching with env
Examples of names that are not registered
foo/bar, .foo, .foobar., env

In the case of names for which the standard application name cannot be registered, KDJE47710-W is output when the application starts and the start processing of the application continues. However, the Portable Global JNDI names are not registered for all the objects included in that application, so the Portable Global JNDI names cannot be used for lookup. To look up with the Portable Global JNDI names, as and when required, change the name of the DD or EAR file, or the name of the application directory according to the naming rules.

(2) Naming rules for the standard module name

The following table describes the rules for setting up the standard module name.

Table 2-13 Naming rules for the standard module name

Preconditions for the moduleStandard module name
EJB-JAR module (EJB-JAR file)ejb-jar.xml existsThe <module-name> tag exists.The value exists.Value of the <module-name> tag #1
The value is null #2.Default standard module name #3
The <module-name> tag does not exist.--
ejb-jar.xml does not exist----
Web module (WAR file)web.xml existsThe <module-name> tag exists.The value exists.Value of the <module-name> tag #1
The value is null #2.Default standard module name #3
The <module-name> tag does not exist.--
web.xml does not exist----
Resource adapter module (RAR file)

--

Default standard module name #3
Legend:
--: Not applicable.
#1
The space characters before and after the value (single-byte spaces, tabs, and linefeeds) are removed. The space characters between the words are not removed.
#2
Indicates a zero length string. A value consisting of only a space character is also determined to be null.
#3
The default standard module name differs depending on the module and J2EE application format. The following table describes the naming rules for the default standard module name.

Table 2-14 Naming rules for the default standard module name

ModuleJ2EE application formatDefault standard module name
EJB-JAR module (EJB-JAR file)Archive formatString obtained when you remove the extension from the relative path from the root directory of the application package up to the EJB-JAR file.
However, the extension is not removed if a period "." exists only at the beginning of the EJB-JAR file name.
If the path delimiter is \, the character is converted to /.
Exploded archive format
  • If application.xml exists
    The path specified in the <module>/<ejb> tag of application.xml.
  • If application.xml does not exist
    String obtained when you remove the last _jar from the relative path from the application directory up to the EJB-JAR directory.
    If the path delimiter is \, the character is converted to /.
Web module (WAR file)Archive formatString obtained when you remove the extension from the relative path from the root directory of the application package up to the WAR file.
However, the extension is not removed if a period "." exists only at the beginning of the WAR file name.
If the path delimiter is \, the character is converted to /.
Exploded archive format
  • If application.xml exists
    The path specified in the <module>/<web>/<web-uri> tag of application.xml.
  • If application.xml does not exist
    String obtained when you remove the last _war from the relative path from the application directory up to the WAR directory.
    If the path delimiter is \, the character is converted to /.
Resource adapter moduleArchive formatString obtained when you remove the extension from the relative path from the root directory of the application package up to the RAR file.
However, the extension is not removed if a period "." exists only at the beginning of the RAR file name.
If the path delimiter is \, the character is converted to /.

Note that the standard module name (value of the <module-name> tag) is registered if the name contains single-byte alphanumeric characters (0 to 9, A to Z, and a to z) and the following special characters:

Space ( ), exclamation mark (!), double quotation mark ("), hash mark (#), dollar sign ($), percent sign (%), ampersand (&), single quotation mark ('), barren (() ()), asterisk (*), plus sign (+), comma (,), hyphen (-), period (.), forward slash as a delimiter (/), colon (:), semicolon (;), less-than sign (<), equal sign (=), greater-than sign (>), question mark (?), at mark (@), square brackets ([) (]), backslash (\), caret (^), underscore (_), grave accent mark (`), curly brackets ({) (}), vertical bar (|), and tilde (~)

However, the following names are not registered:

Examples of names that are not registered
/foo, /foobar/, /, foo//bar, bar., .foobar., foo/.bar, AppName, AppName/foo, env/foo/bar

In the case of names for which the standard module name cannot be registered, KDJE47711-W is output for each module when the application starts and the start processing of the application continues. However, the Portable Global JNDI names are not registered for all the objects included in that module, so the Portable Global JNDI names cannot be used for lookup. To look up with the Portable Global JNDI names, as and when required, change the name of the DD or the name of the application directory according to the naming rules.

(3) Naming rules for the Enterprise Bean name

A name is registered as the Enterprise Bean name if the name contains single-byte alphanumeric characters (0 to 9, A to Z, and a to z) and the following special characters:

Space ( ), exclamation mark (!), double quotation mark ("), hash mark (#), dollar sign ($), percent sign (%), ampersand (&), single quotation mark ('), barren (() ()), asterisk (*), plus sign (+), comma (,), hyphen (-), period (.), colon (:), semicolon (;), less-than sign (<), equal sign (=), greater-than sign (>), question mark (?), at mark (@), square brackets ([) (]), backslash (\), caret (^), underscore (_), grave accent mark (`), curly brackets ({) (}), vertical bar (|), and tilde (~)

However, the following names are not registered:

Examples of names that are not registered
.foo, .foobar., ModuleName, env

In the case of names for which the Enterprise Bean name cannot be registered, KDJE47712-W is output for each Enterprise Bean when the application starts and the start processing of the application continues. However, the registration to the Portable Global JNDI names is not performed for all the objects included in that Enterprise Bean. Note that the names for which the Enterprise Bean name cannot be registered cannot be looked up with the Portable Global JNDI names, but all the other application functionality operate as before.

Furthermore, the specifiable string length is checked for each Enterprise Bean interface (home interface or business interface) as well. For example, if the following string length is 256 characters or more, KDJE47713-W is output for each interface, and the name is not registered in the Portable Global JNDI name with the format specifying that interface name.

Length-of-Enterprise-Bean-name + length-of-interface-class-name# + 1

# Fully-qualified class name containing the package name

Note that in EJB 3.1, if the interface is omitted, the Enterprise Bean class name is applicable instead of the interface class name.

(4) Operations when the standard application name or standard module name are duplicated

With Application Server, if the same standard application name is already registered for a name space when an application starts, KDJE47720-W is output, and the name is not registered for the name space. Similarly, if the same standard module name is already registered for a name space in the same application, the following message is output and the name is not registered for the name space. However, the start processing of the application continues.

Note that the modules are registered in the following order with Application Server:

  1. Resource adapter
  2. EJB-JAR
  3. Web application

If the registered object and name match in the hierarchy demarcated with forward slashes (/), even if the name does not exactly match the registered standard application name or standard module name, the name might be determined to be a duplicate. The examples are as follows:

Example 1
If the applications are started in the following order, the standard application name is determined to be duplicated:
  1. An application with the standard application name foo/bar is started
  2. An application with the standard application name foo is started
Example 2
If the applications are started in the following order, the standard application name is determined to be duplicated:
  1. An application with the standard application name foo and the standard module name bar is started
  2. An application with the standard application name foo/bar is started