com.day.cq.wcm.api.LanguageManager Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of aem-sdk-api Show documentation
Show all versions of aem-sdk-api Show documentation
The Adobe Experience Manager SDK
/*
* Copyright 1997-2008 Day Management AG
* Barfuesserplatz 6, 4001 Basel, Switzerland
* All Rights Reserved.
*
* This software is the confidential and proprietary information of
* Day Management AG, ("Confidential Information"). You shall not
* disclose such Confidential Information and shall use it only in
* accordance with the terms of the license agreement you entered into
* with Day.
*/
package com.day.cq.wcm.api;
import com.day.cq.commons.Language;
import com.day.cq.commons.jcr.JcrConstants;
import org.apache.sling.api.resource.Resource;
import org.apache.sling.api.resource.ResourceResolver;
import org.osgi.annotation.versioning.ProviderType;
import javax.annotation.Nullable;
import java.util.Collection;
import java.util.Locale;
import java.util.Map;
/**
* Provides a service for content languages. Note that this has nothing to do
* with the i18n of the WCM itself.
*/
@ProviderType
public interface LanguageManager {
/**
* relative path of the language property of a hierarchy node.
*/
static final String ISO_PROP_NAME = NameConstants.NN_CONTENT + "/" + JcrConstants.JCR_LANGUAGE;
/**
* relative path of the language root property of a hierarchy node.
*/
static final String IS_LANGUAGE_ROOT_PROP_NAME = NameConstants.NN_CONTENT + "/" + "cq:isLanguageRoot";
/**
* Returns the country iso code for the given locale. if the country is not
* already defined in the locale a configured default value is returned.
* If no iso code exists, an empty string is returned.
*
* @param language the language locale to retrieve the country from
* @return a country iso code or ""
*/
String getIsoCountry(Locale language);
/**
* Returns a map of language information for each
* language filled with information if respective hierarchy or content exists
* for that language.
*
* @param resolver resource resolver
* @param path path to check
* @return map of information or null if the given path does not
* reside on or below a language root.
*
* @see com.day.cq.commons.LanguageUtil#getLanguageRoot(String)
*
* @deprecated use {@link #getAdjacentLanguageInfo(ResourceResolver, String)} instead
*/
Map getAdjacentInfo(ResourceResolver resolver, String path);
/**
* Returns a map of language information for each
* language filled with information if respective hierarchy or content exists
* for that language.
*
* @param resolver resource resolver
* @param path path to check
* @return map of information or null if the given path does not
* reside on or below a language root.
*
* @see com.day.cq.commons.LanguageUtil#getLanguageRoot(String)
*
* @since 5.4
*/
Map getAdjacentLanguageInfo(ResourceResolver resolver, String path);
/**
* Returns the language for the given resource.
* Note that this method only uses the path names for the determination of
* the language.
*
* @param res resource
* @return the locale or null if not determinable
*/
Locale getLanguage(Resource res);
/**
* Returns the language for the given resource.
* Note that this method only uses the path names for the determination of
* the language.
*
* @param res resource
* @return the locale or null if not determinable
*
* @since 5.4
*/
Language getCqLanguage(Resource res);
/**
* Returns the language for the given resource. The path of the resource
* is analyzed to find a matching iso code. If no iso code can be found,
* null is returned unless respectContent is
* true. then the resources ancestors (including the given)
* one is searched for a {@link #ISO_PROP_NAME} property.
*
* @param res resource
* @param respectContent if false only the path is analyzed
* @return the locale or null if not determinable
*
* @since 5.4
*/
Locale getLanguage(Resource res, boolean respectContent);
/**
* Returns the language for the given resource. The path of the resource
* is analyzed to find a matching iso code. If no iso code can be found,
* null is returned unless respectContent is
* true. then the resources ancestors (including the given)
* one is searched for a {@link #ISO_PROP_NAME} property.
*
* @param res resource
* @param respectContent if false only the path is analyzed
* @return the locale or null if not determinable
*
* @since 5.4
*/
Language getCqLanguage(Resource res, boolean respectContent);
/**
* Returns the language root page for the given resource.
* Note that currently only the path names are respected for the
* determination of the language.
* @param res resource
* @return the language root page or null if not determinable
*/
Page getLanguageRoot(Resource res);
/**
* Returns the language root page for the given resource. If
* {@code respectContent} is {@code true}, then the resources ancestors (including
* the given one) are searched for a {@link #IS_LANGUAGE_ROOT_PROP_NAME}
* property. If the property is {@code true}, {@link #ISO_PROP_NAME}
* is used to determine language root. If the {@link #IS_LANGUAGE_ROOT_PROP_NAME}
* property is {@code false} or the {@link #ISO_PROP_NAME} property is not
* found or {@code respectContent} is {@code false}, the path of the
* resource is analyzed to find a matching iso code. If no iso code can be found,
* {@code null} is returned.
*
* @param res resource
* @param respectContent if {@code false} only the path is analyzed
* @return the language root page or {@code null} if not determinable
*
* @since 6.4
*/
@Nullable Page getLanguageRoot(Resource res, boolean respectContent);
/**
* Returns the language root resource for the given resource.
* Note that currently only the path names are respected for the
* determination of the language.
* @param res the resource
* @return the language root resource or null if not determinable
*/
Resource getLanguageRootResource(Resource res);
/**
* Returns the language root resource for the given resource. If
* {@code respectContent} are {@code true}, then the resources ancestors (including
* the given one) is searched for a {@link #IS_LANGUAGE_ROOT_PROP_NAME}
* property. If the property is {@code true}, {@link #ISO_PROP_NAME}
* is used to determine language root. If the {@link #IS_LANGUAGE_ROOT_PROP_NAME}
* property is {@code false} or the {@link #ISO_PROP_NAME} property is not
* found or {@code respectContent} is {@code false}, the path of the
* resource is analyzed to find a matching iso code. If no iso code can be found,
* {@code null} is returned.
*
* @param res the resource
* @param respectContent if {@code false} only the path is analyzed
* @return the language root resource or {@code null} if not determinable
*
* @since 6.4
*/
@Nullable public Resource getLanguageRootResource(Resource res, boolean respectContent);
/**
* Returns a collection of root languages for the given page. Note that
* only the path names are respected for the determination of the language.
*
* @param resolver resource resolver
* @param path path of the current page
* @return collection of root languages
*
* @deprecated use {@link #getCqLanguages(ResourceResolver, String)} instead.
*/
Collection getLanguages(ResourceResolver resolver, String path);
/**
* Returns a collection of root languages for the given page. Note that
* only the path names are respected for the determination of the language.
*
* @param resolver resource resolver
* @param path path of the current page
* @return collection of root languages
*
* @since 5.4
*/
Collection getCqLanguages(ResourceResolver resolver, String path);
/**
* Returns a collection of language root pages for the given page. Note that
* only the path names are respected for the determination of the language.
*
* @param resolver resource resolver
* @param path path of the current page
* @return collection of language root paths
*/
Collection getLanguageRoots(ResourceResolver resolver, String path);
/**
* Returns a collection of {@link Resource} objects which act as language roots for the resource at the given path.
*
* @param resolver a {@link ResourceResolver} used to access the repository
* @param path the path of the current page
* @return a collection of language root resources
*/
Collection getLanguageRootResources(ResourceResolver resolver, String path);
/**
* Returns a collection of {@link Resource} objects which act as language
* roots for the resource at the given path. For example, consider the
* following structure where language roots would be searched a level up or down.
*
*
* /content/example/language-masters
* +-- en
* +-- emea
* | +-- de
* | +-- fr
* +-- apac
* | +-- ko
* | +-- zh-cn
*
*
* If {@code respectContent} is {@code true}, then the resources ancestors (including the
* given one) are searched for a {@link #IS_LANGUAGE_ROOT_PROP_NAME} property. If the
* property is {@code true}, {@link #ISO_PROP_NAME} is used to determine language root.
* If the {@link #IS_LANGUAGE_ROOT_PROP_NAME} property is {@code false} or the
* {@link #ISO_PROP_NAME} property is not found or {@code respectContent} is {@code false},
* the path of the resource is analyzed to find a matching iso code. Implementation may
* choose to optimize for certain type of hierarchies.
*
* @param resolver a {@link ResourceResolver} used to access the repository
* @param path the path of the current page
* @param respectContent if {@code false} only the path is analyzed
* @return a collection of language root resources
*
* @since 6.4
*/
Collection getLanguageRootResources(ResourceResolver resolver, String path, boolean respectContent);
/**
* Compares language trees using the language of the page at the given path
* as main language.
* @param resolver resource resolved
* @param path path to resource to start from
* @return the tree information
*/
public Tree compareLanguageTrees(ResourceResolver resolver, String path);
/**
* Encapsulates information about language specific existences of resources
* in a tree.
*/
interface Tree {
/**
* Returns the root path of the tree
* @return the root path of the tree
*/
String getRoot();
/**
* Returns a collection of all languages covered by this tree
* @return collection of languages
*
* @deprecated use {@link #getCqLanguages()} instead
*/
Collection getLanguages();
/**
* Returns a collection of all languages covered by this tree
* @return collection of languages
*
* @since 5.4
*/
Collection getCqLanguages();
/**
* Returns an collection of nodes.
* @return the nodes
*/
Collection getNodes();
}
/**
* Denotes a node in the tree.
*/
interface TreeNode {
/**
* Returns the relative path of the node.
* @return the relative path
*/
String getRelativePath();
/**
* Returns the info for the given locale or null if the
* locale is not part of the language collection returned by
* {@link Tree#getLanguages()}.
*
* @param locale the locale
* @return info or null
*
* @deprecated use {@link #getInfo(Language)} instead
*/
Info getInfo(Locale locale);
/**
* Returns the info for the given locale or null if the
* locale is not part of the language collection returned by
* {@link Tree#getCqLanguages()}.
*
* @param locale the locale
* @return info or null
*
* @since 5.4
*/
Info getInfo(Language locale);
}
/**
* Information about a resource in a language tree.
*/
interface Info {
/**
* Returns the path
* @return the path
*/
String getPath();
/**
* Checks if the resource exists at the given path.
* @return true if the resource exists at the given path
*/
boolean exists();
/**
* Checks if the resource has content at the given path
* @return true if the resource has content at the given path
*/
boolean hasContent();
/**
* Returns the last modification date of the resource
* @return the last modification date or 0
*/
long getLastModified();
}
}