Bug 47769 - documentation on web.xml resource-ref does'nt state optional
Summary: documentation on web.xml resource-ref does'nt state optional
Status: RESOLVED FIXED
Alias: None
Product: Tomcat 6
Classification: Unclassified
Component: Documentation (show other bugs)
Version: unspecified
Hardware: PC Windows XP
: P2 normal (vote)
Target Milestone: default
Assignee: Tomcat Developers Mailing List
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2009-08-31 04:49 UTC by Martin Gainty
Modified: 2009-12-14 10:14 UTC (History)
0 users



Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Martin Gainty 2009-08-31 04:49:13 UTC
<snip> from users@tomcat.apache.org
 There has to be some use of that resource-ref element. All the Tomcat
> examples and tutorials instruct you to create this element. Someone
> really badly wants you to use it, yet it seemingly has not function
> whatsoever. Something just doesn't add up, or maybe it's just me...
 
It's not just you. I've also been wondering why you should need it when
obviously you don't as your <Resource> works without a <resource-ref>.

<commentary>
if web.xml <resource-ref> and <resource-env-ref> tags are optional 
could the documentation be updated to say web.xml <resource-ref> and <resource-env-ref> tags are 'optional'

<Existing Documentation considerations>
change tomcat-docs/config/context.html#Resource Definitions
You can declare the characteristics of the resource to be returned for JNDI lookups of <resource-ref> and <resource-env-ref> elements in the web application deployment descriptor. You MUST also define the needed resource parameters as attributes of the Resource element, to configure the object factory to be used (if not known to Tomcat already), and the properties used to configure that object factory.

change Documentation to:
Optionally you can declare the characteristics of the resource to be returned for JNDI lookups of <resource-ref> and <resource-env-ref> elements in the web application deployment descriptor. Be advised that both <resource-ref> and <resource-env-ref> tags are OPTIONAL tags within web.xml
You MUST define the needed resource parameters as attributes of the Resource element, to configure the object factory to be used (if not known to Tomcat already), and the properties used to configure that object factory.
The ApplicationContext.xml <Resource> tag within <Context> is mandatory for the resource to be recognised.

....
The valid attributes for a <Resource> element are as follows:
...

Thanks,
Martin-
For example, you can create a resource definition like this:

Thanks 
Martin
Comment 1 Mark Thomas 2009-12-14 10:14:07 UTC
I took a look at this and it works as follows:

- if there is enough info in web.xml to create the resource, that is all that is required
- if more info is needed to create the resource, then that must be provided via a Context element
- any resource defined via a context element need not be defined in web.xml

It is a good idea to list all the resources in web.xml to document the JNDI resource expectations of the web app.

I have updated the docs in trunk, 6.0.x and 5.5.x to try and make this clearer.