You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@labs.apache.org by si...@apache.org on 2009/01/30 16:41:57 UTC
svn commit: r739310 - in
/labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n: ./
formatters/
Author: simoneg
Date: Fri Jan 30 15:41:56 2009
New Revision: 739310
URL: http://svn.apache.org/viewvc?rev=739310&view=rev
Log:
LABS-285 : javadocs and ajdocs for foundation-i18n
Modified:
labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/AddFormatterInPropertyInfo.aj
labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/AddFormattingInHandler.aj
labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/ContextMatrix.java
labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/CurrentLocale.java
labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/Format.java
labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/Formatter.java
labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/Formatters.java
labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/HookFormattingToHandler.aj
labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/I18nRenderingHelper.java
labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/LocaleHolder.java
labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/LocalizeLocalizableString.aj
labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/NilFormatter.java
labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/formatters/BooleanFormatter.java
labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/formatters/DateFormatter.java
labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/formatters/DoubleFormatter.java
labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/formatters/EnumFormatter.java
Modified: labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/AddFormatterInPropertyInfo.aj
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/AddFormatterInPropertyInfo.aj?rev=739310&r1=739309&r2=739310&view=diff
==============================================================================
--- labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/AddFormatterInPropertyInfo.aj (original)
+++ labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/AddFormatterInPropertyInfo.aj Fri Jan 30 15:41:56 2009
@@ -22,16 +22,29 @@
import org.apache.magma.beans.PropertyInfo;
+/**
+ * Adds {@link Formatter} property and utility methos into {@link PropertyInfo}.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public aspect AddFormatterInPropertyInfo {
declare precedence : AddFormatterInPropertyInfo, AddConverterInPropertyInfo;
private Formatter PropertyInfo.formatter = null;
+ /**
+ * @return the formatter assigned to this {@link PropertyInfo}.
+ */
public Formatter PropertyInfo.getFormatter() {
return this.formatter;
}
+ /**
+ * Parses annotations on a property getter to assign a {@link Formatter}
+ * @param info The property info being created
+ * @param desc The property descriptor being used
+ */
after(PropertyInfo info, PropertyDescriptor desc) :
execution(* PropertyInfo.init(PropertyDescriptor, Class)) && target(info) && args(desc,..) {
if (info.getType() == null) return;
@@ -54,6 +67,12 @@
}
}
+ /**
+ * Forces the {@link PropertyInfo#toString(Object)} method to use the {@link Formatter}.
+ * @param info The {@link PropertyInfo} on which the call is made.
+ * @param value The argument passed to the {@link PropertyInfo#toString(Object)} method.
+ * @return The formatted value if a formatter was assigned, the {@link PropertyInfo#toString(Object)} result otherwise.
+ */
String around(PropertyInfo info, Object value) :
execution(String PropertyInfo.toUser(Object)) &&
this(info) && args(value) {
Modified: labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/AddFormattingInHandler.aj
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/AddFormattingInHandler.aj?rev=739310&r1=739309&r2=739310&view=diff
==============================================================================
--- labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/AddFormattingInHandler.aj (original)
+++ labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/AddFormattingInHandler.aj Fri Jan 30 15:41:56 2009
@@ -26,11 +26,21 @@
import org.apache.magma.beans.PropertyInfo;
import org.apache.magma.conversion.ConversionException;
+/**
+ * Adds a layer to the {@link BeanHandler} to support formatted values retrieval and parsing.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public privileged aspect AddFormattingInHandler {
private Map<String,String> BeanHandler.formattedValues = new HashMap<String,String>();
private Set<String> BeanHandler.formattedExplicitlySet = new HashSet<String>();
+ /**
+ * Sets a value as a formatted string.
+ * @param field The field we are setting the value for.
+ * @param value The formatted value, it will be parsed by the formatter if assigned, otherwise normal processing will occur.
+ */
public void BeanHandler.setFormattedStringValue(String field, String value) {
PropertyInfo property = data.getProperty(field);
if (property == null) throw new MagmaException("Cannot find a property named {0} in class {1}", field, bean.getClass().getName());
@@ -43,12 +53,21 @@
formattedValues.put(field, value);
}
+ /**
+ * Sets all values as formatted strings.
+ * @param values A Map(field name : formatted value) with values to set.
+ */
public void BeanHandler.setFormattedStringValues(Map<String, String> values) {
for (Map.Entry<String, String> entry : values.entrySet()) {
setFormattedStringValue(entry.getKey(), entry.getValue());
}
}
+ /**
+ * Retrieves a value as a formatted string.
+ * @param field The field we are retrieving.
+ * @return the formatted value for the field if a {@link Formatter} has been assigned, the normal string converted value otherwise.
+ */
public String BeanHandler.getFormattedStringValue(String field) {
PropertyInfo property = data.getProperty(field);
if (property == null) throw new MagmaException("Cannot find a proprty named {0} in class {1}", field, bean.getClass().getName());
@@ -59,6 +78,9 @@
return formattedValues.get(field);
}
+ /**
+ * Rolls back all formatted values.
+ */
public void BeanHandler.rollbackFormattedStringValues() {
this.formattedValues.clear();
Set<String> names = this.data.getPropertyNames();
@@ -78,6 +100,9 @@
}
}
+ /**
+ * Commits all formatted values, triggering parsing.
+ */
public void BeanHandler.commitFormattedStringValues() {
ConversionException exc = null;
for (String name : formattedExplicitlySet) {
Modified: labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/ContextMatrix.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/ContextMatrix.java?rev=739310&r1=739309&r2=739310&view=diff
==============================================================================
--- labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/ContextMatrix.java (original)
+++ labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/ContextMatrix.java Fri Jan 30 15:41:56 2009
@@ -7,12 +7,23 @@
import org.apache.magma.basics.context.ContextElement;
import org.apache.magma.basics.context.RunningContext;
+import org.apache.magma.basics.context.SubRunningContext;
+/**
+ * Parses and holds an i18n key with its context match.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public class ContextMatrix {
private String[] parts;
private String value;
+ /**
+ * Builds the context
+ * @param key The key complete with context match
+ * @param value The translated value
+ */
public ContextMatrix(String key, String value) {
StringTokenizer stok = new StringTokenizer(key, ".");
List<String> parts = new ArrayList<String>();
@@ -23,10 +34,26 @@
this.value = value;
}
+ /**
+ * @return the last part of the key, which is the main discriminator
+ */
public String getMainDiscriminator() {
return parts[parts.length - 1];
}
+ /**
+ * Given a certain context, calculates the score of this key context match.
+ *
+ * This is used when there are more than one key for the same discriminator, like
+ * whe two keys like "person.name = Firstname" and "computer.name = System name" are present.
+ *
+ * The score is calculated counting the number of matches on the current context, and giving
+ * more points to later matches. This way two overlapping keys like "person.name = Name" and
+ * "form.person.name = Type your name" are properly given a relative value.
+ *
+ * @param mc The current context stack, this is usually a {@link SubRunningContext} instance.
+ * @return an integer value determining the score.
+ */
public int getScore(Stack<ContextElement> mc) {
//int maxscore = (mc.size() * (mc.size() + 1)) / 2;
int total = 0;
@@ -58,6 +85,9 @@
return 0;
}
+ /**
+ * @return The translation value
+ */
public String getValue() {
return value;
}
Modified: labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/CurrentLocale.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/CurrentLocale.java?rev=739310&r1=739309&r2=739310&view=diff
==============================================================================
--- labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/CurrentLocale.java (original)
+++ labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/CurrentLocale.java Fri Jan 30 15:41:56 2009
@@ -8,13 +8,21 @@
import org.apache.magma.basics.context.RunningContext;
import org.apache.magma.settings.Settings;
-
+/**
+ * Holds the current locale for a {@link Thread}.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public class CurrentLocale {
private static Map<Locale, LocaleHolder> holders = new HashMap<Locale, LocaleHolder>();
private static ThreadLocal<LocaleHolder> current = new ThreadLocal<LocaleHolder>();
+ /**
+ * Sets the current {@link Thread} locale.
+ * @param locale The locate to set.
+ */
public static void setLocale(Locale locale) {
LocaleHolder holder = holders.get(locale);
if (holder == null) {
@@ -32,12 +40,20 @@
current.set(holder);
}
+ /**
+ * Converts a string to its i18n translation, given the current locale and the {@link RunningContext}.
+ * @param string The string to translate
+ * @return the translated string
+ */
public static String convert(String string) {
LocaleHolder holder = current.get();
if (holder == null) return string;
return holder.getMessage(RunningContext.get(), string);
}
+ /**
+ * @return the current locale for this thread.
+ */
public static Locale getLocale() {
LocaleHolder holder = current.get();
if (holder == null) {
Modified: labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/Format.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/Format.java?rev=739310&r1=739309&r2=739310&view=diff
==============================================================================
--- labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/Format.java (original)
+++ labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/Format.java Fri Jan 30 15:41:56 2009
@@ -5,11 +5,24 @@
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+/**
+ * Annotation to place on properties (property getters) to specify a formatter.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Format {
+ /**
+ * The {@link Class} of the {@link Formatter} to use for this property.
+ */
public Class<? extends Formatter<?>> type() default NilFormatter.class;
+
+ /**
+ * A {@link Formatter} specific configuration string.
+ * See Formatter subclasses docs to know which formats they support.
+ */
public String format() default "default";
}
Modified: labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/Formatter.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/Formatter.java?rev=739310&r1=739309&r2=739310&view=diff
==============================================================================
--- labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/Formatter.java (original)
+++ labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/Formatter.java Fri Jan 30 15:41:56 2009
@@ -1,13 +1,58 @@
package org.apache.magma.i18n;
+import java.util.Date;
+
import org.apache.magma.conversion.Converter;
+import org.apache.magma.conversion.DateConverter;
+import org.apache.magma.i18n.formatters.DateFormatter;
+/**
+ * A Formatter converts a value to a String for human interaction.
+ *
+ * This differs from a {@link Converter} which is intended for machine-to-machine conversions.
+ *
+ * An example is formatting of a {@link Date} using the {@link DateFormatter}. While the
+ * {@link DateConverter} converts a Date to an ISO date string, which is perfect for machine-to-machine
+ * communication, we don't want a user to see a date in that format, instead we want to present a nice
+ * "Sun, 18th october" or the like, and have it in the proper format and language for the current user lcoale.
+ *
+ * That's what Formatters do.
+ *
+ * The formatter is also able to parse values expressed in the same way, so the user in out example will be
+ * able to write a date in his locale proper format and language.
+ *
+ *
+ * @author Simone Gianni <si...@apache.org>
+ * @param <T> The kind of values (like Date, Integer etc..) the formatter deals with.
+ */
public interface Formatter<T> extends Converter<T> {
+ /**
+ * Sets a formatter-specific, optional, "configuration" string.
+ *
+ * Depending on the formatter, this could be a pattern string, a way to select among different formats, or
+ * other ways to fine tune the format.
+ *
+ * @param format The "configuration" string.
+ */
public void setFormat(String format);
+ /**
+ * Builds the default, thread-safe, instance of a formatter for the specified class.
+ * @param clazz The class we need to format.
+ * @return a thead-safe, singleton instance of a formatter.
+ */
public Formatter<T> buildDefault(Class<? extends T> clazz);
+ /**
+ * If possible, tries to describe the current pattern being used by this formatter in a standard way.
+ *
+ * Wether this method returns a meaningful value, and in which format it is, depends on the formatter
+ * implementation. This is used to interface the formatter with other presentation components, for
+ * example with a javascript library client side that wants to know in which format a date should be
+ * to perform basic validation or display a client side calendar popup.
+ * @return A representation of the pattern used for formatting and parsing the values.
+ */
public String getPattern();
}
Modified: labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/Formatters.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/Formatters.java?rev=739310&r1=739309&r2=739310&view=diff
==============================================================================
--- labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/Formatters.java (original)
+++ labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/Formatters.java Fri Jan 30 15:41:56 2009
@@ -7,8 +7,19 @@
import sun.misc.Service;
+/**
+ * Utility methods (and extension points) to deal with {@link Formatter}s.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public class Formatters {
+ /**
+ * Sets up and configures the proper {@link Formatter} given an annotation and a type.
+ * @param ann The annotation used to annotate the property
+ * @param type The type of the property
+ * @return A {@link Formatter} subclass properly configured.
+ */
public static Formatter getFormatterFor(Format ann, Class<?> type) {
Class<? extends Formatter> formclass = ann.type();
Formatter ret = null;
@@ -27,10 +38,21 @@
return ret;
}
+ /**
+ * Configures the given formatter instance based on values found on the given annotation.
+ * @param annotation The annotation to use to configure the formatter.
+ * @param ret The formatter to configure.
+ */
public static void setupFormatter(Format annotation, Formatter ret) {
AnnotationToInstance.setup(annotation, ret);
}
+ /**
+ * Fetches the default implementation of a formatter for the given type.
+ * @param <T> The type
+ * @param type The class of the type.
+ * @return a default formatter for the given type.
+ */
public static <T> Formatter<T> getFormatterFor(Class<T> type) {
Class simpletype = MethodUtils.toNonPrimitiveClass(type);
Iterator providers = Service.providers(Formatter.class);
Modified: labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/HookFormattingToHandler.aj
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/HookFormattingToHandler.aj?rev=739310&r1=739309&r2=739310&view=diff
==============================================================================
--- labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/HookFormattingToHandler.aj (original)
+++ labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/HookFormattingToHandler.aj Fri Jan 30 15:41:56 2009
@@ -19,14 +19,28 @@
import org.apache.magma.beans.BeanHandler;
import org.apache.magma.conversion.HookConversionToHandler;
+/**
+ * Automates the calls to the methods defined in {@Link AddFormatterInPropertyInfo} when
+ * common methods of {@link BeanHandler} are called.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public aspect HookFormattingToHandler {
declare precedence : HookFormattingToHandler, HookConversionToHandler;
+ /**
+ * Synchronizes the rollback.
+ * @param handler The handler on which rollback was called.
+ */
after(BeanHandler handler) : execution(public void BeanHandler.rollback()) && this(handler) {
handler.rollbackFormattedStringValues();
}
+ /**
+ * Synchronizes the commit.
+ * @param handler The handler on which commit was called.
+ */
before(BeanHandler handler) : execution(public void BeanHandler.commit()) && this(handler) {
handler.commitFormattedStringValues();
}
Modified: labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/I18nRenderingHelper.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/I18nRenderingHelper.java?rev=739310&r1=739309&r2=739310&view=diff
==============================================================================
--- labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/I18nRenderingHelper.java (original)
+++ labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/I18nRenderingHelper.java Fri Jan 30 15:41:56 2009
@@ -5,16 +5,36 @@
import org.apache.magma.basics.LocalizableString;
import org.apache.magma.i18n.formatters.DateFormatter;
+/**
+ * A dumb helper to be passed to template engines so that template writes can translate and format stuff from there.
+ * @author Simone Gianni <si...@apache.org>
+ */
public class I18nRenderingHelper {
+ /**
+ * Translates the given message.
+ * @param message The message to translate
+ * @return the translated message
+ */
public String tr(String message) {
return new LocalizableString(message).toString();
}
+ /**
+ * Formats the given date correctly for the current locale
+ * @param date The date to format
+ * @return the formatted date
+ */
public String tr(Date date) {
return tr(date, "default");
}
+ /**
+ * Formats the given date correctly for the current locale, using the given format configuration
+ * @param date The date to format
+ * @param format The format to use, see {@link DateFormatter} docs
+ * @return the formatted date
+ */
public String tr(Date date, String format) {
DateFormatter df = new DateFormatter();
df.setFormat(format);
Modified: labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/LocaleHolder.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/LocaleHolder.java?rev=739310&r1=739309&r2=739310&view=diff
==============================================================================
--- labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/LocaleHolder.java (original)
+++ labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/LocaleHolder.java Fri Jan 30 15:41:56 2009
@@ -13,8 +13,17 @@
import java.util.Stack;
import org.apache.magma.basics.context.ContextElement;
+import org.apache.magma.basics.context.SubRunningContext;
import org.apache.magma.settings.SettingsHolder;
+/**
+ * Holds translation keys for a given locale.
+ *
+ * One instance on this class exists for each locale encountered by the system, and acts as a cache
+ * for i18n keys to minimize parsing in production.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public class LocaleHolder {
private Locale locale;
@@ -22,6 +31,10 @@
private Map<String, List<ContextMatrix>> firstLookup = new HashMap<String, List<ContextMatrix>>();
+ /**
+ * Creates an instance
+ * @param locale The locale this instance will be bound to.
+ */
public LocaleHolder(Locale locale) {
this.locale = locale;
initMessages();
@@ -76,6 +89,9 @@
}
}
+ /**
+ * Builds an inverted lookup table to speed up key resolution.
+ */
public void buildMatrix() {
Map<String, String> all = messages.getAll();
for (Map.Entry<String, String> entry : all.entrySet()) {
@@ -90,7 +106,15 @@
}
}
-
+ /**
+ * Gets the translation for the given string and the given context.
+ *
+ * The context is usually a {@link SubRunningContext} instance.
+ *
+ * @param ct A stack of elements representing the context.
+ * @param original The original string to translate.
+ * @return The translation or the original string if no translation found.
+ */
public String getMessage(Stack<ContextElement> ct, String original) {
String deh = normalize(original);
List<ContextMatrix> list = firstLookup.get(deh);
@@ -110,6 +134,18 @@
return winner.getValue();
}
+ /**
+ * Transforms a string into a key.
+ *
+ * This means :
+ * <ul>
+ * <li>Limiting it to 30 characters, appending a "+" followed by the length of the original string</li>
+ * <li>Replacing each "{" and "}" character with an underscore</li>
+ * <li>Removing any non alphanumeric character</li>
+ * </ul>
+ * @param original The message to convert to an i18n key
+ * @return the i18n key obtained from the message
+ */
public static String normalize(String original) {
StringBuffer sb = new StringBuffer(original.toLowerCase());
if (sb.length() > 30) {
@@ -129,6 +165,9 @@
return sb.toString();
}
+ /**
+ * @return The locale this instance is bound to.
+ */
public Locale getLocale() {
return locale;
}
Modified: labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/LocalizeLocalizableString.aj
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/LocalizeLocalizableString.aj?rev=739310&r1=739309&r2=739310&view=diff
==============================================================================
--- labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/LocalizeLocalizableString.aj (original)
+++ labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/LocalizeLocalizableString.aj Fri Jan 30 15:41:56 2009
@@ -3,8 +3,20 @@
import java.text.MessageFormat;
import org.apache.magma.basics.LocalizableString;
+/**
+ * Hooks the {@link LocalizableString#toString()} method so that it gets translated based on the current locale and context.
+ *
+ * The i18n translation can contain placeholders (like {1}, {2} etc..) to hold arguments.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public aspect LocalizeLocalizableString {
+ /**
+ * Intercepts the {@link LocalizableString#toString()} method to perform the translation.
+ * @param ls The {@link LocalizableString} to translate
+ * @return the translated message if found, the normal one otherwise.
+ */
String around(LocalizableString ls) : execution(String LocalizableString.toString()) && this(ls) {
String message = ls.getMessage();
message = CurrentLocale.convert(message);
Modified: labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/NilFormatter.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/NilFormatter.java?rev=739310&r1=739309&r2=739310&view=diff
==============================================================================
--- labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/NilFormatter.java (original)
+++ labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/NilFormatter.java Fri Jan 30 15:41:56 2009
@@ -2,6 +2,11 @@
import org.apache.magma.conversion.Converter;
+/**
+ * A do nothing {@link Formatter} implementation to use as default value where null is not permitted (like in annotations).
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public class NilFormatter implements Formatter<Object>{
public Formatter<Object> buildDefault(Class<? extends Object> clazz) {
Modified: labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/formatters/BooleanFormatter.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/formatters/BooleanFormatter.java?rev=739310&r1=739309&r2=739310&view=diff
==============================================================================
--- labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/formatters/BooleanFormatter.java (original)
+++ labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/formatters/BooleanFormatter.java Fri Jan 30 15:41:56 2009
@@ -4,6 +4,14 @@
import org.apache.magma.i18n.CurrentLocale;
import org.apache.magma.i18n.Formatter;
+/**
+ * Output only - Formatter for {@link Boolean} values, including also the boolean native type.
+ *
+ * This gives the opportunity to localize it with strings like Yes, Si, Oui etc.. for various languages, and also
+ * to format it differently based on context, like "Booked: not yet!" instead of "Booked: no".
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public class BooleanFormatter extends BooleanConverter implements Formatter<Boolean>{
Modified: labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/formatters/DateFormatter.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/formatters/DateFormatter.java?rev=739310&r1=739309&r2=739310&view=diff
==============================================================================
--- labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/formatters/DateFormatter.java (original)
+++ labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/formatters/DateFormatter.java Fri Jan 30 15:41:56 2009
@@ -13,6 +13,35 @@
import java.util.Date;
import java.util.Locale;
+/**
+ * Formats dates.
+ *
+ * The custom format is composed of two parts, separated by a comma (","). The first part is relative to the DATE part, which
+ * is day, month and year. The second part is optional and refers to the time part, namely hour, minutes, seconds and milliseconds.
+ *
+ * If the second part is not present, the time part will not be included in the output nor parsed in the input.
+ *
+ * Each part can take one of the following standard values :
+ * <dl>
+ * <dt>none</dt>
+ * <dd>Do not display pr parse that part</dd>
+ * <dt>short</dt>
+ * <dd>Display and parse using the {@link DateFormat#SHORT} format.</dd>
+ * <dt>full</dt>
+ * <dd>Display and parse using the {@link DateFormat#FULL} format.</dd>
+ * <dt>long</dt>
+ * <dd>Display and parse using the {@link DateFormat#LONG} format.</dd>
+ * <dt>medium</dt>
+ * <dd>Display and parse using the {@link DateFormat#MEDIUM} format.</dd>
+ * </dl>
+ *
+ * Using these default settings is recommended because they are context sensitive. That means that the short format for
+ * an Italian will be different than that for an Eglish or American of French user.
+ *
+ * Otherwise, each of the two parts can be a pattern string as specified by {@link SimpleDateFormat}.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public class DateFormatter extends DateConverter implements Formatter<Date> {
private String customFormat = "default";
@@ -77,6 +106,7 @@
this.customFormat = null;
this.dateFormat = checkForFormat(format);
if (dateFormat != -2) {
+ // TODO isn't this a bug? what if i specify "yyyy-MM-dd" without a trailing comma?
if (format.indexOf(',') != -1) {
format = format.substring(format.indexOf(',') + 1);
} else {
@@ -85,6 +115,7 @@
}
this.timeFormat = checkForFormat(format);
if (timeFormat != -2) {
+ // TODO isn't this a bug? what if i specify a custom time format using a standard date format?
if (format.indexOf(',') != -1) {
format = format.substring(format.indexOf(',') + 1);
} else {
@@ -135,6 +166,9 @@
return this.toString(new Date(1230764399999l)).length();
}
+ /**
+ * @return The date pattern used for formatting and parsed, in the format returned by {@link SimpleDateFormat#toPattern()}
+ */
public String getPattern() {
DateFormat formatter = getFormatter();
if (formatter instanceof SimpleDateFormat) {
Modified: labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/formatters/DoubleFormatter.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/formatters/DoubleFormatter.java?rev=739310&r1=739309&r2=739310&view=diff
==============================================================================
--- labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/formatters/DoubleFormatter.java (original)
+++ labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/formatters/DoubleFormatter.java Fri Jan 30 15:41:56 2009
@@ -15,6 +15,34 @@
import org.apache.magma.i18n.CurrentLocale;
import org.apache.magma.i18n.Formatter;
+/**
+ * Formats double values.
+ *
+ * If not format string is specified, the default java formatting is used, see {@link NumberFormat} for details.
+ *
+ * The format string can use three predefined settings :
+ * <dl>
+ * <dt>scientific</dt>
+ * <dd>Outputs and parses the scientific notation, like 0.05 being 5E-2</dd>
+ * <dt>percent</dt>
+ * <dd>Considers the double as a percentage. One is 100%, 0.5 if 50%, 2 id 200% etc..</dd>
+ * <dt>currency</dt>
+ * <dd>Considers the could as a currency. By default, the locale currency is used (Dollars for US, Euro for European countries etc..),
+ * which is not the best thing because most probably you are referring to a specific currency. You can specify the
+ * currency code (see the ISO-4217 for those codes) separating it with a dash, like "currency-EUR" for Euro.
+ * Java usually appends the the currency code to the formatted string, in a locale dependant way. For US people,
+ * 250 formatted with currency-EUR will result in 250.00 EUR, while for an Italian it will be 250,00 €.
+ * If you don't want this to be displayed, you can append an additional "-HIDDEN" at the end, like in
+ * "currency-EUR-HIDDEN".
+ * </dd>
+ * </dl>
+ *
+ * It is important to use the proper setting when dealing with money, cause we don't want users to see the same quantity in
+ * euros or dollars or a local currency depending on where they are connecting from, 200 dollars and 200 turkish liras are two very
+ * different amounts!
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public class DoubleFormatter extends DoubleConverter implements Formatter<Double> {
Modified: labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/formatters/EnumFormatter.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/formatters/EnumFormatter.java?rev=739310&r1=739309&r2=739310&view=diff
==============================================================================
--- labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/formatters/EnumFormatter.java (original)
+++ labs/magma/trunk/foundation-i18n/src/main/java/org/apache/magma/i18n/formatters/EnumFormatter.java Fri Jan 30 15:41:56 2009
@@ -5,6 +5,13 @@
import org.apache.magma.i18n.Formatter;
import org.apache.magma.i18n.LocaleHolder;
+/**
+ * Output only - Formats {@link Enum} values.
+ *
+ * This gives a way to properly customize and translate Enum values.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public class EnumFormatter extends EnumConverter implements Formatter<Enum> {
public EnumFormatter() {
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@labs.apache.org
For additional commands, e-mail: commits-help@labs.apache.org