We propose the following javadoc.
Shing Wai Chan
/**
* Returns the configuration name of the logical host on which the ServletContext is deployed.
*
* Servlet containers may support multiple logical hosts. This method must return the
* same name for all the servlet contexts deployed on a logical host, and the name returned
* by this method must be distinct, stable per logical host, and suitable for use in
* associating server configuration information with the logical host. The returned value
* is NOT expected or required to be equivalent to a network address or hostname of
* the logical host.
*
* @return a<code>String</code> containing the configuration name of the logical host
* on which the servlet context is deployed.
*/
public String getVirtualServerName();
On 3/6/13 8:36 AM, Rajiv Mordani wrote:
>
> On 2/26/13 8:22 PM, Ron Monzillo wrote:
>> On 2/26/13 4:55 PM, Rémy Maucherat wrote:
>>> On 02/26/2013 10:19 PM, Greg Wilkins wrote:
>>>> Remy,
>>>>
>>>> My understanding of this method is that it is on the servlet context,
>>>> thus it is available when there is no request (eg in the init method),
>>>> hence it is more than just syntax sugar over getHeader("Host").
>>> Ah yes, very good point. My mistake.
>>>>
>>>> I don't actually see a huge need for either the single valued method
>>>> or the multivalued one, as any usage of them for prepreparing URIs
>>>> etc. risks being wrong if the client uses a name mapping unknown to
>>>> the server. Ie the host header should always be used for generating
>>>> URIs in the name space of the client.
>>>>
>>>> But the single valued one may be useful for logging or selecting a DB
>>>> partition or otherwise parameterizing configuration. I can't think of
>>>> any really good reasons for the multivalued one, but then I don't see
>>>> any reason to hide this information. Containers will have a list of
>>>> virtual names aliases (or patterns?) so why not expose this in a
>>>> standard way.
>>>>
>>>> If we go with only the single valued one, then the javadoc should note
>>>> that multiple virtual host names may be configured for the context and
>>>> the method returns the preferred one (or at least the first).
>>> Yes, it's not necessary to hide the aliases, but it could also be
>>> useful to distinguish the real name. The two uses mentioned
>>> (logging, parametrization) would need it. If a collection is the
>>> returned value, the first element could be specified as the main
>>> name of the vhost, and maybe use a List ?
>>>
>>> Rémy
>>>
>> As mentioned by Shing wai, and now by Greg and Remy, one use case for
>> this method
>> is as a reference to configuration information about the logical
>> server on which the ServletContext
>> has been deployed.
>>
>> To satisfy that use case, and other similar ones such as the
>> suggested logging use case,
>> I'd like to propose a rename of the method to getVirtualServerName
>> and the following clarification
>> to its description.
>
> And for absolute clarity it will not return any host information
> (unless it is referenced in the configuration).
>
>
>>
>> Note that for these use cases, a single virtual server name would be
>> sufficient
>> and *perhaps* preferable. A multi-valued variant either by itself as
>> Remy suggested, or in addition
>> to the single valued form would also be acceptable, as long as it was
>> clear how to get the primary
>> name of the virtual server.
>>
>> /**
>> * Returns the name of the logical or virtual server on which the
>> ServletContext is deployed.
>> *
>> * Servlet containers may support multiple virtual servers. This
>> method must return the
>> * same name for all the servlet contexts deployed on a virtual
>> server, and the name returned
>> * by this method must be distinct and stable per virtual server.
>> *
>> * @return a <code>String</code> containing the name of the virtual
>> server
>> * on which the servlet context is deployed.
>> */
>> public String getVirtualServerName();
>>
>> ---
>>
>> By stable , I mean that the name should persist across system
>> restarts, and not be susceptible to
>> reassignment by other than the container administrator.
>>
>> if you would prefer a multi-valued variant, it could be defined as
>> follows
>
>
> I don't think we needa multi-valued variant at this time.
>
> - Rajiv
>
>
>>
>> /**
>> * Returns the names of the logical or virtual server on which the
>> ServletContext is deployed.
>> *
>> * Servlet containers may support multiple virtual servers. This
>> method must return the
>> * same list of names for all the servlet contexts deployed on a
>> virtual server, none of the
>> * name values in the returned list may occur in the list returned
>> for another virtual server, and
>> * the name values in all such lists must be stable.
>> *
>> * @return a List of <code>String</code> containing the names of the
>> virtual server
>> * on which the servlet context is deployed. The primary name of the
>> virtual server must
>> * always be returned as the first element in the list, and the order
>> of the names in the
>> * returned list must not vary.
>> */
>> public List<String> getVirtualServerNames();
>>
>> Ron
>