com.bea.wlw.netui.tags.databinding.bundle
Class DeclareBundle

java.lang.Object
  javax.servlet.jsp.tagext.TagSupport
      javax.servlet.jsp.tagext.BodyTagSupport
          com.bea.wlw.netui.tags.AbstractBaseTag
              com.bea.wlw.netui.tags.databinding.bundle.DeclareBundle

All Implemented Interfaces:

HtmlConstants, Serializable, javax.servlet.jsp.tagext.BodyTag, javax.servlet.jsp.tagext.IterationTag, javax.servlet.jsp.tagext.JspTag, javax.servlet.jsp.tagext.Tag

public class DeclareBundle
extends AbstractBaseTag

A tag used to declare a ResourceBundle that can be used inside of the declaring page as a source for displaying internationalized messages. The declared resource bundle is accessible using the bundle databinding context. The required name attribute specifies the identifier via which to refer to the ResourceBundle in an expression. For example:

 <netui-data:declareBundle name="someMessages" bundlePath="com/foobar/resources/WebAppMessages"/>
 

This tag declares a bundle that is referenced in a data binding expression as {bundle.someMessages}.

The bundle that is referenced depends on the java.util.Locale specified. The resource bundle properties files that are accessed are located in the package com/foobar/resources with the root properties file name of WebAppMessages. The naming conventions for properties can be found in Sun's Java documentation at ResourceBundle.getBundle(String, Locale, ClassLoader) . These files must be located in a classpath that is available to the web application. Often, they are stored in WEB-INF/classes. If the properties file contains a key called helloWorld, then the expression {bundle.someMessages.helloWorld} would look-up the message matching the Locale specified on the tag. Bundle binding expressions can be used in any data bindable <netui...> tag attribute.

It is possible to have keys that contain multiple words separated by spaces, commas, or periods. If this is the case, then you must use slightly different syntax to reference those keys in your data binding statement. The following list illustrates three ways to access the key My helloWorld from the someMessages property file:

• <netui:label value="{bundle.someMessages['My helloWorld']}"/>
• <netui:label value='{bundle.someMessages["My helloWorld"]}'/>
• <netui:label value="{bundle.someMessages[\"My helloWorld\"]}"/>
  

WebLogic Workshop automatically generates the last example listed above when you set the label control in the property editor to bundle.someMessages["My helloWorld"]. In all three cases, you WebLogic Workshop can successfully retrieve the multi-word key.

Note: the name default is a bundle identifier that is reserved for use by the DeclareBundle tag. If this value is used for the name attribute on a DeclareBundle tag, an error will be reported in the page. The default bundle is reserved for use when accessing internationalized messages from the "current" Struts module's default properties file.

This tag provides a high level of customizability for rendering internationalized messages. Specifically, the Locale for which to look-up messages can be specified on the DeclareBundle tag. By default, the Locale for the current request is used, but this Locale can be overridden by setting the language, country, and variant tag attributes as necessary. See Locale for more information on the possible values for these attributes.

The Locale can be overridden by setting these attributes in three combinations:

• country, language, variant
• country, language
• country

Any other combinations will throw an exception.

Attribute Descriptions
Attribute	Required	Runtime Expression Evaluation	Data Bindable
bundlePath	No	No	No
	The path to a package in classpath that contains a set of ResourceBundle properties files. This can be a slash or dot delimited classpath. Valid values might be: com/foobar/resources/WebAppProperties com.foobar.resources.WebAppProperties These are treated as equivalent values. The ResourceBundle class will handle appending the .properties file type and locale information as necessary. For details about the .properties file naming conventions, see ResourceBundle.getBundle(String, Locale, ClassLoader). These files must be available in classpath for the webapp in order to be successfully located.
country	No	No	Yes
	The two-letter uppercase ISO-3166 country / region code for the Locale from which to look-up resource bundle messages. This value is used to further specify the name of the .properties file from which message keys will be read.
language	No	No	Yes
	The two-letter lowercase ISO-639 language code for the Locale from which to look-up resource bundle messages. This value is used to further specify the name of the .properties file from which message keys will be read.
name	No	No	No
	The name inside of the bundle databinding context under which the properties in this bundle are available. The identifier default is an illegal value for this attribute and is reserved for use by this tag.
variant	No	No	Yes
	A vendor / browser specific code for further parameterizign the Locale from which to look-up resource bundle messages.

See Also:

java.util.ResourceBundle, java.util.Locale, Serialized Form

Beadoc.tagdescription:

This tag declares a java.util.ResourceBundle as a source for displaying internationalized messages. The declared resource bundle is accessible using the {bundle...} data binding context. The required name attribute specifies the identifier used to refer to the ResourceBundle in an expression. For example:

    <netui-data:declareBundle name="someMessages" bundlePath="com/foobar/resources/WebAppMessages"/>

This tag declares a bundle that is referenced in a data binding expression as {bundle.someMessages}.

The bundle that is referenced depends on the java.util.Locale specified. The resource bundle properties files that are accessed are located in the package com/foobar/resources with the root properties file name of WebAppMessages. The naming conventions for properties can be found in Sun's Java documentation at ResourceBundle.getBundle(String, Locale, ClassLoader) . These files must be located in a classpath that is available to the web application. Often, they are stored in WEB-INF/classes. If the properties file contains a key called helloWorld, then the expression {bundle.someMessages.helloWorld} would look-up the message matching the Locale specified on the tag. Bundle binding expressions can be used in any data bindable <netui...> tag attribute.

It is possible to have keys that contain multiple words separated by spaces, commas, or periods. If this is the case, then you must use slightly different syntax to reference those keys in your data binding statement. The following list illustrates three ways to access the key My helloWorld from the someMessages property file:

• <netui:label value="{bundle.someMessages['My helloWorld']}"/>
• <netui:label value='{bundle.someMessages["My helloWorld"]}'/>
• <netui:label value="{bundle.someMessages[\"My helloWorld\"]}"/>
  

WebLogic Workshop automatically generates the last example listed above when you set the label control in the property editor to bundle.someMessages["My helloWorld"]. In all three cases, you WebLogic Workshop can successfully retrieve the multi-word key.

Note: the name default is a bundle identifier that is reserved for use by the <netui-data:declareBundle> tag. If this value is used for the name attribute on a <netui-data:declareBundle> tag, an error will be reported in the page. The default bundle is reserved for use when accessing internationalized messages from the "current" Struts module's default properties file.

This tag provides a high level of customizability for rendering internationalized messages. Specifically, the Locale for which to look-up messages can be specified on the <netui-data:declareBundle> tag. By default, the Locale for the current request is used, but this Locale can be overridden by setting the language, country, and variant tag attributes as necessary. See java.util.Locale for more information on the possible values for these attributes.

The Locale can be overridden by setting these attributes in three combinations:

• country, language, variant
• country, language
• country

Any other combinations will throw an exception.

The <netui-data:declareBundle> tag and the Struts <i18n:getMessage> tags have the following differences. The <netui-data:declareBundle> tag lets you customize the use of a particular resource bundle with attributes to set the country, language, and variant explicitly, but it does not write a message out to the JSP page. Writing out a message from this bundle is done inside of any of the other tags using the {bundle...} data binding context.

    <netui:label value="{bundle.messages.messageKey}"/>

The Struts <i18n:getMessage> tag is used to access a bundle and write the message out. It is roughly equivalent to doing the following:

    <netui-data:declareBundle bundlePath="com/foobar/resources/messages"
        name="messages"/>
     <netui:label value="{bundle.messages.messageKey"/>

An advantage of using the {bundle...} data binding context, is that it lets you write into the <span>...</span> that the <netui:label> creates, or into a <neuti:checkBox> name, etc. just like using a regular String.

Field Summary

Fields inherited from class com.bea.wlw.netui.tags.AbstractBaseTag

ATTR_GENERAL, ATTR_GENERAL_EXPRESSION, ATTR_JAVASCRIPT, ATTR_STYLE, JAVASCRIPT_STATUS, NETUI_UNIQUE_CNT

Fields inherited from class javax.servlet.jsp.tagext.BodyTagSupport

bodyContent

Fields inherited from class javax.servlet.jsp.tagext.TagSupport

id, pageContext

Fields inherited from interface com.bea.wlw.netui.tags.html.HtmlConstants

ACCEPT, ACCESSKEY, ACTION, ALIGN, ALINK, ALT, ANCHOR, BACKGROUND, BASE, BGCOLOR, BODY, BORDER, BR, CAPTION, CELLPADDING, CELLSPACING, CHAR, CHAROFF, CHARSET, CHECKED, CLASS, COLS, COORDS, DIR, DISABLED, DIV, ENCTYPE, FOR, FORM, FORM_GET, FORM_POST, FRAME, HEIGHT, HREF, HREFLANG, HSPACE, HTML, ID, IMAGE, INPUT, INPUT_BUTTON, INPUT_CHECKBOX, INPUT_FILE, INPUT_HIDDEN, INPUT_IMAGE, INPUT_PASSWORD, INPUT_RADIO, INPUT_RESET, INPUT_SUBMIT, INPUT_TEXT, ISMAP, LABEL, LANG, LINK, LONGDESC, MAXLENGTH, METHOD, NAME, ONBLUR, ONCHANGE, ONCLICK, ONDBLCLICK, ONFOCUS, ONKEYDOWN, ONKEYPRESS, ONKEYUP, ONLOAD, ONMOUSEDOWN, ONMOUSEMOVE, ONMOUSEOUT, ONMOUSEOVER, ONMOUSEUP, ONRESET, ONSELECT, ONSUBMIT, ONUNLOAD, OPTION, READONLY, REL, REV, ROWS, RULES, SELECT, SHAPE, SIZE, SPAN, SRC, STYLE, SUMMARY, TABINDEX, TABLE, TARGET, TD, TEXT, TEXTAREA, TITLE, TR, TYPE, USEMAP, VALIGN, VALUE, VLINK, VSPACE, WIDTH

Fields inherited from interface javax.servlet.jsp.tagext.BodyTag

EVAL_BODY_BUFFERED, EVAL_BODY_TAG

Fields inherited from interface javax.servlet.jsp.tagext.IterationTag

EVAL_BODY_AGAIN

Fields inherited from interface javax.servlet.jsp.tagext.Tag

EVAL_BODY_INCLUDE, EVAL_PAGE, SKIP_BODY, SKIP_PAGE

Constructor Summary

DeclareBundle()

Method Summary

int	doEndTag() Register a ResourceBundle that is available for the scope of this page.
int	doStartTag() Start the JSP rendering lifecycle for this tag; it skips its body.
String	getBundlePath() Get the path to the resource bundle's properties files.
String	getCountry() Get the country to use when looking-up resource bundle messages.
String	getLanguage() Get the language to use when looking-up resource bundle messages.
String	getName() Get the name via which this bundles messages can be accessed using the bundle databinding context.
String	getTagName() Get the name of this tag.
String	getVariant() Get the variant to use when looking-up resource bundle messages.
protected void	localRelease() Reset all of the fields of this tag.
void	setBundlePath(String bundlePath) Set the path to the resource bundle's properties files.
void	setCountry(String country) Set the country to use when looking-up resource bundle messages.
void	setLanguage(String language) Set the language to use when looking-up resource bundle messages.
void	setName(String name) Set the name via which this bundle can be accessed using the bundle databinding context.
void	setVariant(String variant) Set the vendor / browser specific code that further parameterizes the .properties file messages will be read from.

Methods inherited from class com.bea.wlw.netui.tags.AbstractBaseTag

addTagIdMapping, containsExpression, evaluateAttributeToString, evaluateExpression, filter, filter, formatErrorString, formatString, getAttribute, getErrorsReport, getExpressionEvaluator, getJavaScriptUtils, getNearestForm, getNextId, getQualifiedBundleName, getScriptReporter, getUserLocale, hasErrors, isExpression, prepForRendering, registerAttribute, registerError, registerTagError, release, removeAttribute, renderAttribute, renderAttributes, reportErrors, rewriteName, setPageContext, updateExpression, write

Methods inherited from class javax.servlet.jsp.tagext.BodyTagSupport

doAfterBody, doInitBody, getBodyContent, getPreviousOut, setBodyContent

Methods inherited from class javax.servlet.jsp.tagext.TagSupport

findAncestorWithClass, getId, getParent, getValue, getValues, removeValue, setId, setParent, setValue

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface javax.servlet.jsp.tagext.Tag

getParent, setParent

Constructor Detail

DeclareBundle

public DeclareBundle()

Method Detail

getTagName

public String getTagName()

Get the name of this tag. This is used to identify the type of this tag for reporting tag errors.

Specified by:

getTagName in class AbstractBaseTag

Returns:

a constant String representing the name of this tag.

setLanguage

public void setLanguage(String language)

Set the language to use when looking-up resource bundle messages. This value is used to further specify the name of the .properties file message keys will be read from.

Parameters:

language - the two-letter lowercase ISO-639 code for a language.

Beadoc.attributedescription:

The two-letter lowercase ISO-639 language code for the Locale from which to look-up resource bundle messages. This value is used to further specify the name of the .properties file from which message keys will be read.

Beadoc.attributesyntaxvalue:

string_language

Beadoc.databindable:

true

getLanguage

public String getLanguage()

Get the language to use when looking-up resource bundle messages.

Returns:

the language code

setCountry

public void setCountry(String country)

Set the country to use when looking-up resource bundle messages. This value is used to further specify the name of the .properties file message keys will be read from.

Parameters:

country - the two-letter uppercase ISO-3166 code for a country

Beadoc.attributedescription:

The two-letter uppercase ISO-3166 country / region code for the Locale from which to look-up resource bundle messages. This value is used to further specify the name of the .properties file from which message keys will be read.

Beadoc.attributesyntaxvalue:

string_country

Beadoc.databindable:

true

getCountry

public String getCountry()

Get the country to use when looking-up resource bundle messages.

Returns:

the country code

setVariant

public void setVariant(String variant)

Set the vendor / browser specific code that further parameterizes the .properties file messages will be read from.

Parameters:

variant - the variant

Beadoc.attributedescription:

A vendor / browser specific code for further parameterizign the Locale from which to look-up resource bundle messages.

Beadoc.attributesyntaxvalue:

string_variant

Beadoc.databindable:

true

getVariant

public String getVariant()

Get the variant to use when looking-up resource bundle messages.

Returns:

the variant

setName

public void setName(String name)

Set the name via which this bundle can be accessed using the bundle databinding context. The identifier default is an illegal value for this attribute and is reserved for use by this tag.

Parameters:

name - the name of the bundle

Beadoc.attributedescription:

The name inside of the {bundle...} databinding context under which the properties in this bundle are available. The identifier default is an illegal value for this attribute and is reserved for use by this tag.

Beadoc.attributesyntaxvalue:

string_name

Beadoc.databindable:

false

getName

public String getName()

Get the name via which this bundles messages can be accessed using the bundle databinding context.

Returns:

String the name of the bundle

setBundlePath

public void setBundlePath(String bundlePath)

Set the path to the resource bundle's properties files. This can be a slash or dot delimited classpath. Valid values might be:

• com/foobar/resources/WebAppProperties
• com.foobar.resources.WebAppProperties

These are treated as equivalent values. The ResourceBundle class will handle appending the .properties file type and locale information as necessary. See ResourceBundle.getBundle(String, Locale, ClassLoader) for the .properties file naming conventions. These files must be available in classpath for the webapp in order to be successfully located.

Parameters:

bundlePath - the path to the bundle's properties files.

Beadoc.attributedescription:

Set the path to the resource bundle's properties files. This can be a slash or dot delimited classpath. Valid values might be:

• com/foobar/resources/WebAppProperties
• com.foobar.resources.WebAppProperties

These are treated as equivalent values. The ResourceBundle class will handle appending the .properties file type and locale information as necessary. See ResourceBundle.getBundle(String, Locale, ClassLoader) for the .properties file naming conventions. These files must be available in classpath for the webapp in order to be successfully located.

Beadoc.attributesyntaxvalue:

string_bundlePath

Beadoc.databindable:

false

getBundlePath

public String getBundlePath()

Get the path to the resource bundle's properties files.

Returns:

the bundle path

doStartTag

public int doStartTag()

Start the JSP rendering lifecycle for this tag; it skips its body.

Specified by:

doStartTag in interface javax.servlet.jsp.tagext.Tag

Overrides:

doStartTag in class javax.servlet.jsp.tagext.BodyTagSupport

Returns:

Tag.SKIP_BODY

doEndTag

public int doEndTag()
             throws javax.servlet.jsp.JspException

Register a ResourceBundle that is available for the scope of this page. Errors raised during the execution of this tag will be reported in the page, which will continue rendering.

Specified by:

doEndTag in interface javax.servlet.jsp.tagext.Tag

Overrides:

doEndTag in class javax.servlet.jsp.tagext.BodyTagSupport

Returns:

Tag.EVAL_PAGE

Throws:

javax.servlet.jsp.JspException - if error conditions are encountered during this method which can not be reported in the page.

localRelease

protected void localRelease()

Reset all of the fields of this tag.

Overrides:

localRelease in class AbstractBaseTag