Bug 999524 - Incorrect examples of JNDI syntax
Incorrect examples of JNDI syntax
Product: JBoss Enterprise Application Platform 6
Classification: JBoss
Component: Documentation (Show other bugs)
Unspecified Unspecified
unspecified Severity urgent
: GA
: EAP 6.1.1
Assigned To: sgilda
Russell Dickenson
Depends On:
  Show dependency treegraph
Reported: 2013-08-21 09:29 EDT by Ondrej Chaloupka
Modified: 2014-09-29 14:34 EDT (History)
2 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Build: CSProcessor Builder Version 1.12 Build Name: 11863, Migration Guide-6.1-4 Build Date: 15-08-2013 13:16:01 Topic ID: 5419-308868 [Specified]
Last Closed: 2013-09-16 16:23:09 EDT
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---

Attachments (Terms of Use)

  None (edit)
Description Ondrej Chaloupka 2013-08-21 09:29:40 EDT
Title: Portable JNDI Naming Syntax


please rework whole the chapter about JNDI naming syntax.
My objections:
- the first sentence says: "There are four logical namespaces, each with its own scope. Three of the namespaces are used for portable JNDI lookups. The following table details when and how to use each namespace."
But this is not right. 
You can check linked JSR 316. The application component’s naming environment is composed of four logical namespaces. But there could be more namespaces. And in fact there are - e.g. java:jboss/ (check the https://docs.jboss.org/author/display/AS71/JNDI+Reference#JNDIReference-LocalJNDI)
The fourth namespace java:comp is portable as well (check JSR316, EE.5.2.2)

- each portable session bean global JNDI name has the following syntax :
for app: java:app/<module-name>/<bean-name>[!<fully-qualified-interface-name>]
for module: java:module/<bean-name>[!<fully-qualified-interface-name>]
(you can check the JSR 318: Enterprise JavaBeans, v.3.1, EJB.4.4.1)
 this means that the examples with ".jar" are not correct. e.g.
could be:

- it is really not true that you can use java:global name to find remote EJBs - it's described here - https://docs.jboss.org/author/display/AS71/EJB+invocations+from+a+remote+client+using+JNDI
-- you use another syntax for stateless and stateful beans (?stateful)
-- you have in fact possibilities how to do create lookup name for remote beans (with ejb: or remote:)

- the sentence "For example, a WAR and an EJB jar file in the same EAR..." should be reformulated. WAR is not packaged to jar file.
Comment 1 sgilda 2013-08-22 15:25:08 EDT

I got the information on 'Portable JNDI Syntax' from the Oracle tutorial here: http://docs.oracle.com/javaee/6/tutorial/doc/gipjf.html#girgn

It says: "Three JNDI namespaces are used for portable JNDI lookups: java:global, java:module, and java:app."

Is that information outdated? 

I assumed the 'java:jboss/' namespace is not portable. Isn't that only valid for the JBoss server?
Comment 2 sgilda 2013-08-22 16:27:36 EDT
Made updates to topic 5419, "Portable JNDI Naming Syntax", revision 499751.
Comment 3 sgilda 2013-08-22 16:41:36 EDT

I spoke with Stuart Douglas today. 

It appears that this topic title is misleading. The topic was meant to discuss EJB bindings, not namespaces. A more appropriate title would be " Portable EJB JNDI Names" but it may be too late to change the title as it impacts all the books.

I changed the introductory paragraph to the following:

There are four logical namespaces, each with its own scope, but portable EJB names only get bound to three of them. The following table details when and how to use each namespace.

I changed the java:global description:

Names in this namespace are shared by all applications deployed in an application server instance. Use names in this namespace to find EJBs external archives deployed to the same server.

As for the '.jar' in the JNDI names, they were taken from a migrated Seam application. The developer used the '.jar' to distinquish between the JAR and WAR with the same name in the EAR. I changed the '.jar' to '-jar' to be less confusing.
Comment 5 sgilda 2013-08-22 23:01:29 EDT
Changed the topic title from Portable JNDI Naming Syntax to 'Portable EJB JNDI Names' Topic 5419, rev 499807

Modified the following CSP maps:

14877 - 6.2 Migration Guide
19236 - 6.1.1 Migration Guide

Also changed:

13710 - 6.2 WebLogic Migration Guide
22175 - 6.2 WebSphere Migration Guide
Comment 7 Ondrej Chaloupka 2013-08-23 04:52:19 EDT

thanks for changes. I agree in principle with the text, but I would have one request for the change. I think that would be nicer to use "Java EE platform specification defines" then the "There are four logical namespaces".

Otherwise it seems to me fine.

I see your point about the ".jar" suffix. I didn't understand it before.

I'm just thinking that I will create a new bugzilla about migration guide as I think that it would be nice to mention the change for client remote ejb lookups. I'm not able to find such chapter around.

The second thing is that we (as QA) are supposed to put the bz as verified after the content is put on documentation-devel site.

Thank you
Comment 8 sgilda 2013-08-23 08:05:45 EDT
Agreed. Modfified the opening text to:

he Java EE 6 specification defines four logical namespaces, each with its own scope, but portable EJB names only get bound to three of them. The following table details when and how to use each namespace.

Topic 5419, 'Portable EJB JNDI Names' is now at revision 500563.

Does the section on 'Remote Invocation Changes' address the cliet remote EJB lookup changes? 


If not, when you enter the new bug, could you be specific about what you are looking for?

I understand that you need to wait for it to be staged, but we are getting down to the wire and I wanted to be sure you reviewed this before it was too late. I will move it back to ON_QA after the next docstage build.
Comment 9 Ondrej Chaloupka 2013-08-23 08:25:03 EDT
I've already found the part about the ejb remoting invocation. Sorry for mystification.

I'm fine with the text and when it will be prepared for review I'll just move it to verified.
Thank you

Note You need to log in before you can comment on or make changes to this bug.