org.apache.cocoon.matching
Class LocaleMatcher

java.lang.Object
  org.apache.avalon.framework.logger.AbstractLogEnabled
      org.apache.cocoon.matching.LocaleMatcher

All Implemented Interfaces:

Disposable, Component, Configurable, LogEnabled, Serviceable, ThreadSafe, Matcher

public class LocaleMatcher
extends AbstractLogEnabled
implements Matcher, ThreadSafe, Serviceable, Configurable, Disposable

A matcher that locates and identifies to the pipeline a source document to be used as the content for an i18n site, based upon a locale provided in a range of ways.

Configuration

A sample configuration (given in the <map:matchers> section of the sitemap) is given below. This configuration shows default values.

   <map:matcher name="i18n" src="org.apache.cocoon.matching.LocaleMatcher">
     <locale-attribute>locale</locale-attribute>
     <negotiate>false</negotiate>
     <use-locale>true</use-locale>
     <use-locales>false</use-locales>
     <use-blank-locale>true</use-blank-locale>
     <default-locale language="en" country="US"/>
     <store-in-request>false<store-in-request>
     <create-session>false<create-session>
     <store-in-session>false<store-in-session>
     <store-in-cookie>false<store-in-cookie>
   </map:matcher>
 

Above configuration parameters mean:

• locale-attribute specifies the name of the request parameter / session attribute / cookie that is to be used as a locale (defaults to locale)
• negotiate specifies whether matcher should check that resource exists. If set to true, matcher will look for the locale till matching resource is found. If no resource found even with default or blank locale, matcher will not match.
• use-locale specifies whether the primary locale provided by the user agent (or server default, is no locale passed by the agent) is to be used
• use-locales specifies whether each locale provided by the user agent should be tested in turn (makes sense only when negotiate is set to true)
• default-locale specifies the default locale to be used when none matches any of the previous ones.
• use-blank-locale specifies whether a file should be looked for without a locale in its filename or filepath (e.g. after looking for index.en.html, try index.html) if none matches any of the previous locales.
• store-in-request specifies whether found locale should be stored as request attribute.
• create-session specifies whether session should be created when storing found locale as session attribute.
• store-in-session specifies whether found locale should be stored as session attribute.
• store-in-cookie specifies whether found locale should be stored as cookie.

Usage

This matcher will be used in a pipeline like so:

   <map:match pattern="*.html">
     <map:match type="i18n" pattern="xml/{1}.*.xml">
       <map:generate src="{source}"/>
       ...
     </map:match>
   </map:match>
 

* in the pattern identifies the place where locale should be inserted. In case of a blank locale, if character before and after * is the same (like in example above), duplicate will be removed (xml/{1}.*.xml becomes xml/{1}.xml).

Locale Identification

Locales will be tested in following order:

• Locale provided as a request parameter
• Locale provided as a session attribute
• Locale provided as a cookie
• Locale provided using a sitemap parameter
  (<map:parameter name="locale" value="{1}"/> style parameter within the <map:match> node)
• Locale provided by the user agent, or server default, if use-locale is set to true
• Locales provided by the user agent, if use-locales is set to true.
• The default locale, if specified in the matcher's configuration
• Resources with no defined locale (blank locale)

If negotiate mode is set to true, a source will be looked up using each locale. Where the full locale (language, country, variant) doesn't match, it will fall back first to language and country, and then just language, before moving on to the next locale.

If negotiate mode is set to false (default), first found locale will be returned.

Sitemap Variables

Once a matching locale has been found, the following sitemap variables will be available to sitemap elements contained within the matcher:

• {source}: The URI of the source that matched
• {locale}: The locale that matched that resource
• {matched-locale}: The part of the locale that matched the resource
• {language}: The language of the matching resource
• {country}: The country of the matching resource
• {variant}: The variant of the matching resource

Since:

2.1.6

Version:

CVS $Id: LocaleMatcher.html 1304258 2012-03-23 10:09:27Z ilgrosso $

Author:

Upayavira, Vadim Gritsenko

Field Summary

Fields inherited from interface org.apache.cocoon.matching.Matcher

ROLE

Constructor Summary

LocaleMatcher()

Method Summary

void	configure(Configuration config)
void	dispose()
Map	match(String pattern, Map objectModel, Parameters parameters) Matches the pattern against some Request values and returns a Map object with replacements for wildcards contained in the pattern.
void	service(ServiceManager manager)

Methods inherited from class org.apache.avalon.framework.logger.AbstractLogEnabled

enableLogging, getLogger, setupLogger, setupLogger, setupLogger

Methods inherited from class java.lang.Object

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

Constructor Detail

LocaleMatcher

public LocaleMatcher()

Method Detail

service

public void service(ServiceManager manager)
             throws ServiceException

Specified by:

service in interface Serviceable

Throws:

ServiceException

configure

public void configure(Configuration config)

Specified by:

configure in interface Configurable

dispose

public void dispose()

Specified by:

dispose in interface Disposable

match

public Map match(String pattern,
                 Map objectModel,
                 Parameters parameters)
          throws PatternException

Description copied from interface: Matcher

Matches the pattern against some Request values and returns a Map object with replacements for wildcards contained in the pattern.

Specified by:

match in interface Matcher

Parameters:

pattern - The pattern to match against. Depending on the implementation the pattern can contain wildcards or regular expressions.

objectModel - The Map with object of the calling environment which can be used to select values this matchers matches against.

Returns:

Map The returned Map object with replacements for wildcards/regular-expressions contained in the pattern. If the return value is null there was no match.

Throws:

PatternException