DO NOT REPLY [Bug 29584] New: - JNDI documentation could be more clear

[bu...@apache.org]

DO NOT REPLY TO THIS EMAIL, BUT PLEASE POST YOUR BUG 
RELATED COMMENTS THROUGH THE WEB INTERFACE AVAILABLE AT
<http://issues.apache.org/bugzilla/show_bug.cgi?id=29584>.
ANY REPLY MADE TO THIS MESSAGE WILL NOT BE COLLECTED AND 
INSERTED IN THE BUG DATABASE.

http://issues.apache.org/bugzilla/show_bug.cgi?id=29584

JNDI documentation could be more clear

           Summary: JNDI documentation could be more clear
           Product: Tomcat 5
           Version: 5.0.25
          Platform: All
        OS/Version: All
            Status: NEW
          Severity: Normal
          Priority: Other
         Component: Unknown
        AssignedTo: tomcat-dev@jakarta.apache.org
        ReportedBy: bim2003@basistech.com


The JNDI documentation is not entirely clear as to the number of JNDI contexts 
and their relationship. I am reading the page entitled, "JNDI Resources HOW-TO".

The top of the page states that each web app receives a unique initial context. 
So far, so good.

Then, under 'Configuring JNDI Resources', the explanation talks about elements 
that live inside either <Context> or <DefaultContext> in server.xml. 

First clarification: Since <Context> elements are frequently created in 
separate files in the Catalina directory, this text should reference those 
files.

Second clarification issue: the page 'globalresources.html' explicitly states 
that <Environment/> elements in the GlobalNamingResources propagate 
automatically into each web application. To me, that implied that the other 
resources defined in GlobalNamingResources would also propagate. They don't, at 
least in the 'custom factory' case. Under 'Resource Definitions', the text says 
that you can declare the characteristics of resource-env-ref's for a web.xml in 
the GlobalNamingResources. This may be true of the standard factories, but it 
is NOT true for custom factories. Unless that's deemed to be a defect, this 
text should state, explicitly, that custom factories require a ResourceLink 
element to make them available in the per-web-application InitialContext.

Back to the JNDI howto.  

Third clarification:

The initial reference to <ResourceLink> mentions the global JNDI context 
without referencing the GlobalNamingResources link. The terminology here is not 
quite consistent with the definition of 'Global Resources' below. It would be 
clearer to include an href to GlobalNamingResources in the <ResourceLink> 
bullet, since ResourceLink is (I think) only useful for GlobalNamingResources.

Fourth clarification: Under 'Adding Custom Resource Factories', the reference 
to conf/server.xml should be more specific. It should state that you have three 
choices: <Context>, <DefaultContext>, or <GlobalNamingResources> with a 
<ResourceLink> to make it available in Context or DefaultContext. Possibly, the 
same clarification is apropos for the standard resource factories, though the 
special cases for them in the source might render it unnecessary.

---------------------------------------------------------------------
To unsubscribe, e-mail: tomcat-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: tomcat-dev-help@jakarta.apache.org