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 tools.gsf.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 * Returns the DimensionSetInstance for the site
34 *
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 *
43 * @param site name of the site
44 * @return the DimensionFilterInstance
45 */
46 public DimensionFilterInstance getDimensionFilter(String site);
47
48
49 /**
50 * Look up the translation for the asset specified, with the dimension filter.
51 * <p>
52 *
53 * @param id asset id of asset to look up
54 * @param filter the dimensionset to use
55 * @return AssetId of translation asset.
56 */
57 public AssetId findTranslation(final AssetId id, DimensionFilterInstance filter);
58
59 /**
60 * Look up the translation for the asset specified, in the locale specified.
61 * <p>
62 * If the desired translation is not available, null will be returned.
63 * <p>
64 * If a dimension set for the site has been configured that returns the
65 * asset other than the preferred locale, that is considered to be fine and
66 * not really the problem of the end user. In other words, a dimension set
67 * may dictate that a "backup" language can be returned to the user.
68 * <p>
69 * Null, however, is a valid option.
70 *
71 * @param c asset type of asset to look up
72 * @param cid asset id of asset to look up
73 * @param site name of site
74 * @param preferredLocaleDimensionId id of locale desired
75 * @return AssetId of translation asset.
76 */
77 public AssetId findTranslation(final String c, final String cid, final String site,
78 final String preferredLocaleDimensionId);
79
80 /**
81 * Look up the translation for the asset specified, in the locale specified.
82 * <p>
83 * If the desired translation is not available, null will be returned.
84 * <p>
85 * If a dimension set for the site has been configured that returns the
86 * asset other than the preferred locale, that is considered to be fine and
87 * not really the problem of the end user. In other words, a dimension set
88 * may dictate that a "backup" language can be returned to the user.
89 * <p>
90 * Null, however, is a valid option.
91 *
92 * @param id id of asset to look up
93 * @param site name of site
94 * @param preferredDimension id of locale desired
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 asset id
150 * @param preferredDimension id of preferred locale
151 * @param dimset dimension set instance
152 * @return assetid of translated asset.
153 * @throws IllegalStateException exception thrown if illegal state is reached
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 dimension 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 }