1 /*
2 * Copyright 2008 FatWire Corporation. All Rights Reserved.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package com.fatwire.gst.foundation.facade.mda;
17
18 import com.fatwire.assetapi.data.AssetId;
19 import com.fatwire.mda.Dimension;
20 import com.fatwire.mda.DimensionFilterInstance;
21 import com.fatwire.mda.DimensionSetInstance;
22
23 /**
24 * Service to find translated assets and work with Dimensions, DimensionSets and DimensionFilters.
25 *
26 * @author Dolf Dijkstra
27 * @since Apr 19, 2011
28 */
29 public interface LocaleService {
30
31
32
33 /**
34 * Returns the DimensionSetInstance for the site
35 * @param site the name of the site
36 * @return the DimensionSetInstance for the site
37 */
38 public DimensionSetInstance locateDimensionSetInstanceForSite(String site);
39
40 /**
41 * Looks up the DimensionFilter based on the current browser settings and site configuration, as well as request parameters.
42 * @param site
43 * @return the DimensionFilterInstance
44 */
45 public DimensionFilterInstance getDimensionFilter(String site);
46
47
48 /**
49 * Look up the translation for the asset specified, with the dimension filter.
50 * <p/>
51 *
52 * @param id asset id of asset to look up
53 * @param filter the dimensionset to use
54 * @return AssetId of translation asset.
55 */
56 public AssetId findTranslation(final AssetId id, DimensionFilterInstance filter);
57
58 /**
59 * Look up the translation for the asset specified, in the locale specified.
60 * <p/>
61 * If the desired translation is not available, null will be returned.
62 * <p/>
63 * If a dimension set for the site has been configured that returns the
64 * asset other than the preferred locale, that is considered to be fine and
65 * not really the problem of the end user. In other words, a dimension set
66 * may dictate that a "backup" language can be returned to the user.
67 * <p/>
68 * Null, however, is a valid option.
69 *
70 * @param c asset type of asset to look up
71 * @param cid asset id of asset to look up
72 * @param site name of site
73 * @param preferredLocaleDimensionId id of locale desired
74 * @return AssetId of translation asset.
75 */
76 public AssetId findTranslation(final String c, final String cid, final String site,
77 final String preferredLocaleDimensionId);
78
79 /**
80 * Look up the translation for the asset specified, in the locale specified.
81 * <p/>
82 * If the desired translation is not available, null will be returned.
83 * <p/>
84 * If a dimension set for the site has been configured that returns the
85 * asset other than the preferred locale, that is considered to be fine and
86 * not really the problem of the end user. In other words, a dimension set
87 * may dictate that a "backup" language can be returned to the user.
88 * <p/>
89 * Null, however, is a valid option.
90 *
91 * @param id id of asset to look up
92 * @param site name of site
93 * @param preferredDimension id of locale desired
94 *
95 * @return AssetId of translation asset, or null if none is returned by the
96 * dimension set filter.
97 */
98
99 public AssetId findTranslation(final AssetId id, final String site, final long preferredDimension);
100
101 /**
102 * Look up the translation for the asset specified, in the locale specified.
103 * <p/>
104 * If the desired translation is not available, null will be returned.
105 * <p/>
106 * If a dimension set for the site has been configured that returns the
107 * asset other than the preferred locale, that is considered to be fine and
108 * not really the problem of the end user. In other words, a dimension set
109 * may dictate that a "backup" language can be returned to the user.
110 * <p/>
111 * Null, however, is a valid option.
112 *
113 * @param id id of asset to look up
114 * @param preferredDimension id of locale desired
115 * @param dimensionSetId dimension set to use to find the translation
116 * @return AssetId of translation asset, or null if none is returned by the
117 * dimension set filter.
118 */
119
120 public AssetId findTranslation(final AssetId id, final long preferredDimension, final long dimensionSetId);
121
122 /**
123 * Look up the translation for the asset specified, in the locale specified.
124 * <p/>
125 * If the desired translation is not available, null will be returned.
126 * <p/>
127 * If a dimension set has been configured that returns the asset other than
128 * the preferred locale, that is considered to be fine and not really the
129 * problem of the end user. In other words, a dimension set may dictate that
130 * a "backup" language can be returned to the user.
131 * <p/>
132 * Null, however, is a valid option.
133 *
134 * @param id id of asset to look up
135 * @param preferredDimension id of locale desired
136 * @param dimensionSetName the name of the dimension set to use to find the
137 * translation
138 * @return AssetId of translation asset, or null if none is returned by the
139 * dimension set filter. The id parameters is returned if the asset
140 * does not have a locale or if the locale is already of the
141 * preferredDimension
142 */
143
144 public AssetId findTranslation(final AssetId id, final long preferredDimension, final String dimensionSetName);
145
146 /**
147 * Finds the translation for the preferred dimension and dimensionset.
148 *
149 * @param id
150 * @param preferredDimension
151 * @param dimset
152 * @return assetid of translated asset.
153 * @throws IllegalStateException
154 */
155
156 public AssetId findTranslation(final AssetId id, final long preferredDimension, final DimensionSetInstance dimset);
157
158 /**
159 * Looksup the DimensionSetInstance for the given name.
160 *
161 * @param name
162 * @return the DimensionSetInstance by the provided name
163 */
164
165 public DimensionSetInstance getDimensionSet(final String name);
166
167 /**
168 * Return the dimension of the input asset that corresponds to its locale.
169 * If the asset does not have a locale set, returns null
170 *
171 * @param id asset
172 * @return locale dimension or null
173 */
174
175 public Dimension getLocaleForAsset(final AssetId id);
176
177 /**
178 * Get the id of the dimension asset for the name specified
179 *
180 * @param name dimension name, or locale like en_US
181 * @return dimension id, -1 is not found.
182 */
183
184 public long getDimensionIdForName(final String name);
185
186 /**
187 * Get the AssetId of the dimension asset for the name specified
188 *
189 * @param name dimension name, or locale like en_US
190 * @return dimension id, null if not found
191 */
192
193 public AssetId getDimensionAssetIdForName(final String name);
194
195 /**
196 * Get the AssetId of the dimension asset for the name specified
197 *
198 * @param name dimension name, or locale like en_US
199 * @return dimension id, null if not found
200 */
201
202 public Dimension getDimensionForName(final String name);
203
204 /**
205 * Shorthand function to get the name given a dimension ID specified.
206 *
207 * @param dimensionid ID of a locale. Note the dimension group is not
208 * verified
209 * @return dimension name, or locale name, like en_CA, null if not found
210 */
211
212 public String getNameForDimensionId(final long dimensionid);
213
214 }