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/31 02:51:28 UTC
svn commit: r739488 - in
/labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma: basics/
basics/context/ basics/utils/ settings/
Author: simoneg
Date: Sat Jan 31 01:51:27 2009
New Revision: 739488
URL: http://svn.apache.org/viewvc?rev=739488&view=rev
Log:
LABS-285 : javadocs and ajdocs for foundation-basics
Removed:
labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/utils/SavingStack.java
Modified:
labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/DefaultCharSequence.java
labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/DefaultCharSequenceImpl.aj
labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/LocalizableString.java
labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/LocalizableStringWithSubject.java
labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/MagmaException.java
labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/AutoRegisterContextOwners.aj
labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/AutoSwitchContextOwner.aj
labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/ClassContextElement.java
labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/ContextElement.java
labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/ContextOwner.java
labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/MethodContextElement.java
labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/RunningContext.java
labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/StringContextElement.java
labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/SubRunningContext.java
labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/utils/AnnotationToInstance.java
labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/utils/GenericClass.java
labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/settings/Settings.java
labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/settings/SettingsHolder.java
Modified: labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/DefaultCharSequence.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/DefaultCharSequence.java?rev=739488&r1=739487&r2=739488&view=diff
==============================================================================
--- labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/DefaultCharSequence.java (original)
+++ labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/DefaultCharSequence.java Sat Jan 31 01:51:27 2009
@@ -1,5 +1,10 @@
package org.apache.magma.basics;
+/**
+ * Mock interface to infer default methods implementation to CharSequence subclasses.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public interface DefaultCharSequence extends CharSequence {
}
Modified: labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/DefaultCharSequenceImpl.aj
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/DefaultCharSequenceImpl.aj?rev=739488&r1=739487&r2=739488&view=diff
==============================================================================
--- labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/DefaultCharSequenceImpl.aj (original)
+++ labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/DefaultCharSequenceImpl.aj Sat Jan 31 01:51:27 2009
@@ -1,5 +1,10 @@
package org.apache.magma.basics;
+/**
+ * Default dummy implementations of CharSequence interface.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public aspect DefaultCharSequenceImpl {
public char DefaultCharSequence.charAt(int i) {
Modified: labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/LocalizableString.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/LocalizableString.java?rev=739488&r1=739487&r2=739488&view=diff
==============================================================================
--- labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/LocalizableString.java (original)
+++ labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/LocalizableString.java Sat Jan 31 01:51:27 2009
@@ -18,33 +18,57 @@
import java.text.MessageFormat;
-
+/**
+ * A way to format strings lazily and add additional behavior, like localization.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public class LocalizableString implements DefaultCharSequence {
private String message = null;
private Object[] args = null;
+ /**
+ * Creates a new instance.
+ * @param message The message string, can contain placeholders like {0}, {1} etc..
+ * @param arg Arguments to fill placeholders
+ */
public LocalizableString(String message, Object... arg) {
this.message = message;
this.args = arg;
}
+ /**
+ * @return Arguments of this localizable string
+ */
public Object[] getArgs() {
return args;
}
+ /**
+ * @param args Arguments of this localizable string
+ */
public void setArgs(Object[] args) {
this.args = args;
}
+ /**
+ * @return the raw message of this localizable string
+ */
public String getMessage() {
return message;
}
+ /**
+ * @param message the raw message of this localizable string, may contain placeholders like {0}, {1} etc..
+ */
public void setMessage(String message) {
this.message = message;
}
+ /**
+ * Formats the message, filling placeholders with arguments.
+ */
@Override
public String toString() {
if (this.args == null || this.args.length == 0) return this.message;
Modified: labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/LocalizableStringWithSubject.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/LocalizableStringWithSubject.java?rev=739488&r1=739487&r2=739488&view=diff
==============================================================================
--- labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/LocalizableStringWithSubject.java (original)
+++ labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/LocalizableStringWithSubject.java Sat Jan 31 01:51:27 2009
@@ -16,20 +16,38 @@
*/
package org.apache.magma.basics;
+/**
+ * Augments the {@link LocalizableString} adding a subject of the message.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public class LocalizableStringWithSubject extends LocalizableString {
private Object subject;
+ /**
+ * @param subject The subject of the message
+ * @param message The message string, can contain placeholders like {0}, {1} etc..
+ * @param arg Arguments to fill placeholders
+ */
public LocalizableStringWithSubject(Object subject, String message, Object[] arg) {
super(message, arg);
this.subject = subject;
}
+ /**
+ * Wraps an existing {@link LocalizableString} adding a subject.
+ * @param subject The subject of the message
+ * @param loc The {@link LocalizableString} to wrap
+ */
public LocalizableStringWithSubject(Object subject, LocalizableString loc) {
super(loc.getMessage(), loc.getArgs());
this.subject = subject;
}
+ /**
+ * @return the subject of this message
+ */
public Object getSubject() {
return subject;
}
Modified: labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/MagmaException.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/MagmaException.java?rev=739488&r1=739487&r2=739488&view=diff
==============================================================================
--- labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/MagmaException.java (original)
+++ labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/MagmaException.java Sat Jan 31 01:51:27 2009
@@ -21,6 +21,14 @@
import java.util.ArrayList;
import java.util.List;
+/**
+ * The base exception used in all Magma.
+ *
+ * This exception uses {@link LocalizableString}s for the message and support smart joining of multiple
+ * exceptions in a single exception.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public class MagmaException extends RuntimeException {
private List<LocalizableString> messages = null;
Modified: labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/AutoRegisterContextOwners.aj
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/AutoRegisterContextOwners.aj?rev=739488&r1=739487&r2=739488&view=diff
==============================================================================
--- labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/AutoRegisterContextOwners.aj (original)
+++ labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/AutoRegisterContextOwners.aj Sat Jan 31 01:51:27 2009
@@ -1,5 +1,10 @@
package org.apache.magma.basics.context;
+/**
+ * Automatically takes snapshots of the {@link RunningContext} when a new {@link ContextOwner} instance is created.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public aspect AutoRegisterContextOwners {
pointcut createdOwner(ContextOwner obj) : execution(ContextOwner+.new(..)) && this(obj);
Modified: labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/AutoSwitchContextOwner.aj
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/AutoSwitchContextOwner.aj?rev=739488&r1=739487&r2=739488&view=diff
==============================================================================
--- labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/AutoSwitchContextOwner.aj (original)
+++ labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/AutoSwitchContextOwner.aj Sat Jan 31 01:51:27 2009
@@ -1,5 +1,12 @@
package org.apache.magma.basics.context;
+/**
+ * Automatically switches to the snapshot taken for a particular {@link ContextOwner} when
+ * a method of the instance is called, and switches back when the method terminates execution,
+ * so that internal methods are executed in the correct snapshot.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public aspect AutoSwitchContextOwner {
declare precedence : AutoSwitchContextOwner, *;
Modified: labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/ClassContextElement.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/ClassContextElement.java?rev=739488&r1=739487&r2=739488&view=diff
==============================================================================
--- labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/ClassContextElement.java (original)
+++ labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/ClassContextElement.java Sat Jan 31 01:51:27 2009
@@ -1,5 +1,10 @@
package org.apache.magma.basics.context;
+/**
+ * A {@link ContextElement} wrapping a {@link Class}.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public class ClassContextElement implements ContextElement {
public Class<?> myclass = null;
Modified: labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/ContextElement.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/ContextElement.java?rev=739488&r1=739487&r2=739488&view=diff
==============================================================================
--- labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/ContextElement.java (original)
+++ labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/ContextElement.java Sat Jan 31 01:51:27 2009
@@ -1,5 +1,10 @@
package org.apache.magma.basics.context;
+/**
+ * Marker interface for objects that can be stored in the {@link SubRunningContext}.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public interface ContextElement {
}
Modified: labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/ContextOwner.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/ContextOwner.java?rev=739488&r1=739487&r2=739488&view=diff
==============================================================================
--- labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/ContextOwner.java (original)
+++ labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/ContextOwner.java Sat Jan 31 01:51:27 2009
@@ -1,6 +1,11 @@
package org.apache.magma.basics.context;
-
+/**
+ * Marker interface for objects that takes a snapshot of the {@link RunningContext} to retain
+ * the state in which they have been created.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public interface ContextOwner {
}
Modified: labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/MethodContextElement.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/MethodContextElement.java?rev=739488&r1=739487&r2=739488&view=diff
==============================================================================
--- labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/MethodContextElement.java (original)
+++ labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/MethodContextElement.java Sat Jan 31 01:51:27 2009
@@ -3,6 +3,11 @@
import java.lang.reflect.Method;
import java.util.Arrays;
+/**
+ * A {@link ContextElement} that wraps a method call.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public class MethodContextElement implements ContextElement {
private Method method = null;
Modified: labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/RunningContext.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/RunningContext.java?rev=739488&r1=739487&r2=739488&view=diff
==============================================================================
--- labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/RunningContext.java (original)
+++ labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/RunningContext.java Sat Jan 31 01:51:27 2009
@@ -6,6 +6,30 @@
import org.apache.magma.basics.MagmaException;
+/**
+ * The execution context.
+ *
+ * This class keeps the current execution state. Each package can contribute
+ * to this state saving here {@link ContextElement}s, and retrieving them where needed.
+ *
+ * This creates a transparent communication between packages, for example many packages
+ * can contribute I18nContextElement to participate in i18n decisions.
+ *
+ * Also, since the context can be polled on request, it makes most of the calculations lazy
+ * instead of pushing then eagerly. This gives more modularity and better performances in
+ * a number of systems, like relative URL calculations.
+ *
+ * Each thread has a single instance of this class. The current context is implemented in the
+ * {@link SubRunningContext} class, which is a {@link Stack} of {@link ContextElement}s.
+ *
+ * This class holds a stack of {@link SubRunningContext}s. This is necessary so that {@link ContextOwner}s
+ * can live in their own snapshots of the context.
+ *
+ * For this purpose, this class also holds {@link SubRunningContext}s which are snapshots (implemented
+ * as shallow copies) of the context at the moment the {@link ContextOwner} instances were created.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public class RunningContext {
private static ThreadLocal<RunningContext> runnings = new ThreadLocal<RunningContext>();
@@ -13,10 +37,17 @@
private Stack<SubRunningContext> currents = new Stack<SubRunningContext>();
private Map<ContextOwner, SubRunningContext> saveds = new HashMap<ContextOwner, SubRunningContext>();
+ /**
+ * Clean up this class at the end of a cycle.
+ */
public static void cleanup() {
runnings.set(null);
}
+ /**
+ * Retrieves the current {@link SubRunningContext}.
+ * @return The current context
+ */
public static SubRunningContext get() {
RunningContext context = runnings.get();
if (context == null) {
@@ -26,10 +57,17 @@
return context.currents.peek();
}
- public RunningContext() {
+ protected RunningContext() {
currents.push(new SubRunningContext());
}
+ /**
+ * Enters the snapshot for a {@link ContextOwner}. If no snapshot exist, it will be created.
+ * Until the {@link #exiting(ContextOwner)} method is called, the snapshot will be updated.
+ *
+ * It is possible to call this method multiple times, to support nested {@link ContextOwner}s.
+ * @param co the context owner we are entering.
+ */
public static void entering(ContextOwner co) {
RunningContext context = runnings.get();
SubRunningContext sr = context.saveds.get(co);
@@ -42,12 +80,21 @@
context.currents.push(sr);
}
+ /**
+ * Extis the snapshot of a {@link ContextOwner}, returning to the previous snapshot if more than one call to
+ * {@link #entering(ContextOwner)} was made, or to the normal flow.
+ * @param co The context owner we are exiting, used to check for leaks.
+ */
public static void exiting(ContextOwner co) {
RunningContext context = runnings.get();
SubRunningContext pop = context.currents.pop();
if (pop.getOwner() != co) throw new MagmaException("Running context disaligned, expecting {0} but got {1}", co, pop.getOwner());
}
+ /**
+ * Creates a snapshot for a given {@link ContextOwner}.
+ * @param co The context owner we are creating the snapshot for.
+ */
public static void createFor(ContextOwner co) {
RunningContext context = runnings.get();
if (!context.saveds.containsKey(co)) {
Modified: labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/StringContextElement.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/StringContextElement.java?rev=739488&r1=739487&r2=739488&view=diff
==============================================================================
--- labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/StringContextElement.java (original)
+++ labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/StringContextElement.java Sat Jan 31 01:51:27 2009
@@ -1,5 +1,10 @@
package org.apache.magma.basics.context;
+/**
+ * A {@link ContextElement} wrapping a plain {@link String}.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public class StringContextElement implements ContextElement {
public CharSequence mystring = null;
Modified: labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/SubRunningContext.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/SubRunningContext.java?rev=739488&r1=739487&r2=739488&view=diff
==============================================================================
--- labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/SubRunningContext.java (original)
+++ labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/context/SubRunningContext.java Sat Jan 31 01:51:27 2009
@@ -9,6 +9,12 @@
import org.apache.magma.basics.MagmaException;
import org.apache.magma.settings.Settings;
+/**
+ * A {@link Stack} of {@link ContextElement}s. This is the real implementation of the context.
+ * Multiple instances of this class are coordinated by the {@link RunningContext}.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public class SubRunningContext extends Stack<ContextElement> {
private ContextOwner owner;
@@ -16,12 +22,19 @@
protected SubRunningContext() {
}
+ /**
+ * Deprecates the normal {@link Stack#pop()}, the overridden pop methos should be used to check for leaks.
+ */
@Override
@Deprecated
public synchronized ContextElement pop() {
return super.pop();
}
+ /**
+ * Pops from the stack and checks that the {@link ContextElement} class is right, to avoid leaks.
+ * @param eleClass The class should be at the top of the {@link Stack}.
+ */
public synchronized void pop(Class<? extends ContextElement> eleClass) {
if (Settings.isProductionEnv()) {
super.pop();
@@ -35,6 +48,12 @@
}
}
+ /**
+ * Searches for {@link ContextElement}s on the stack of the given class or implementing the given interface.
+ * @param <SubElement> The {@link ContextElement} subclass or interface to search for.
+ * @param clazz The {@link ContextElement} subclass or interface to search for.
+ * @return A {@link List} of found {@link ContextElement}s.
+ */
@SuppressWarnings("unchecked")
public <SubElement extends ContextElement> List<SubElement> getElements(Class<SubElement> clazz) {
List<SubElement> ret = null;
@@ -49,35 +68,58 @@
return ret;
}
-
+ /**
+ * Shortcut method for popping a {@link StringContextElement} from the stack.
+ */
public void popString() {
pop(StringContextElement.class);
}
+ /**
+ * Shortcut method for popping a {@link ClassContextElement} from the stack.
+ */
public void popClass() {
pop(ClassContextElement.class);
}
+ /**
+ * Shortcut method for popping a {@link MethodContextElement} from the stack.
+ */
public void popMethod() {
pop(MethodContextElement.class);
}
+ /**
+ * Shortcut method for pushing a {@link ClassContextElement} on the stack.
+ */
public void push(Class<?> clazz) {
super.push(new ClassContextElement(clazz));
}
+ /**
+ * Shortcut method for pushing a {@link StringContextElement} on the stack.
+ */
public void push(String value) {
super.push(new StringContextElement(value));
}
+ /**
+ * Shortcut method for pushing a {@link MethodContextElement} on the stack.
+ */
public void push(Method method, Object... args) {
super.push(new MethodContextElement(method, args));
}
+ /**
+ * @return The {@link ContextOwner} of this instance if this is a snapshot.
+ */
public ContextOwner getOwner() {
return owner;
}
+ /**
+ * @param owner The {@link ContextOwner} of this instance if this is a snapshot.
+ */
public void setOwner(ContextOwner owner) {
this.owner = owner;
}
Modified: labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/utils/AnnotationToInstance.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/utils/AnnotationToInstance.java?rev=739488&r1=739487&r2=739488&view=diff
==============================================================================
--- labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/utils/AnnotationToInstance.java (original)
+++ labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/utils/AnnotationToInstance.java Sat Jan 31 01:51:27 2009
@@ -21,8 +21,18 @@
import java.lang.annotation.Annotation;
import java.lang.reflect.Method;
+/**
+ * Utility methods for parsing annotations.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public class AnnotationToInstance {
+ /**
+ * Transfers parameters from an annotation calling setters on a target instance.
+ * @param annotation The annotation to read from.
+ * @param instance The instance to write to.
+ */
public static void setup(Annotation annotation, Object instance) {
Class valclass = instance.getClass();
Method[] methods = annotation.annotationType().getMethods();
Modified: labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/utils/GenericClass.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/utils/GenericClass.java?rev=739488&r1=739487&r2=739488&view=diff
==============================================================================
--- labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/utils/GenericClass.java (original)
+++ labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/basics/utils/GenericClass.java Sat Jan 31 01:51:27 2009
@@ -32,6 +32,11 @@
import org.apache.magma.basics.MagmaException;
+/**
+ * A wrapper around reflection to resolve generics.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
// TODO there is vast space for caching and optimizations here!
public class GenericClass {
Modified: labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/settings/Settings.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/settings/Settings.java?rev=739488&r1=739487&r2=739488&view=diff
==============================================================================
--- labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/settings/Settings.java (original)
+++ labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/settings/Settings.java Sat Jan 31 01:51:27 2009
@@ -21,7 +21,36 @@
import java.net.URL;
import java.util.Enumeration;
import java.util.Map;
+import java.util.Properties;
+/**
+ * This class sets up and manages settings using a {@link SettingsHolder}.
+ *
+ * Settings in Magma are a bit more flexible than they usually are.
+ *
+ * First of all, a Magma program can run in different environments. Each environment is identified
+ * by a name. Then, all packages can provide some default properties. Moreover, each package can
+ * provide default properties for different environments.
+ *
+ * Obviously the user must be able to override and provide all the properties, and to do it
+ * in a simple way for different environments.
+ *
+ * To do this, this class loads from the classpath various resources in progressive order, so that
+ * each one overrides properties defined by the previous. All of them are in the META-INF resource directory.
+ *
+ * Given that the current environment is "devel", these resources are :
+ * <ul>
+ * <li>magma.default.properties : contains generic default properties for all environments</li>
+ * <li>magma.devel.default.properties : contains default properties for the "devel" environment</li>
+ * <li>magma.properties : contains specific project properties, common to all environments</li>
+ * <li>magma.devel.properties : contains specific project propertied for the "devel" environment</li>
+ * </ul>
+ *
+ * All property files must conform to the {@link Properties} format. Also the XML format can be used,
+ * in that case just add ".xml" to the file name.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public class Settings {
static SettingsHolder holder = new SettingsHolder();
@@ -32,16 +61,28 @@
static String environment = System.getProperty("magma.env", DEVEL_ENV);
+ /**
+ * Retrieves the value of a setting. If settings have not yet been loaded, they are loaded when needed.
+ * @param name The name of the setting property to retrieve.
+ * @return teh value of the setting, or null if not defined.
+ */
public static String get(String name) {
if (!holder.isInited()) init();
return holder.get(name);
}
+ /**
+ * Retrieves all the defined setting properties.
+ * @return A map with all the setting properties.
+ */
public static Map<String, String> getAll() {
if (!holder.isInited()) init();
return holder.getAll();
}
+ /**
+ * Loads the settings resources.
+ */
public static void init() {
String env = environment;
String prefix = null;
@@ -97,18 +138,31 @@
holder.inited();
}
+ /**
+ * @return The current environment name.
+ */
public static String getEnvironment() {
return environment;
}
+ /**
+ * Sets the current environment name.
+ * @param environment The environment name.
+ */
public static void setEnvironment(String environment) {
Settings.environment = environment;
}
+ /**
+ * @return True is current environment is considered a production environment, where optimizations are needed.
+ */
public static boolean isProductionEnv() {
return environment.equals(PRODUCTION_ENV);
}
+ /**
+ * @return True if current environment is considered a developement environment, where reloading is preferred.
+ */
public static boolean isDeveloperEnv() {
return environment.equals(DEVEL_ENV);
}
Modified: labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/settings/SettingsHolder.java
URL: http://svn.apache.org/viewvc/labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/settings/SettingsHolder.java?rev=739488&r1=739487&r2=739488&view=diff
==============================================================================
--- labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/settings/SettingsHolder.java (original)
+++ labs/magma/trunk/foundation-basics/src/main/java/org/apache/magma/settings/SettingsHolder.java Sat Jan 31 01:51:27 2009
@@ -21,9 +21,7 @@
import java.io.FileNotFoundException;
import java.io.IOException;
import java.io.InputStream;
-import java.io.InputStreamReader;
import java.net.URL;
-import java.nio.charset.Charset;
import java.util.Collections;
import java.util.InvalidPropertiesFormatException;
import java.util.Map;
@@ -31,6 +29,14 @@
import org.apache.magma.basics.MagmaException;
+/**
+ * This class manages settings and offer methods for easy oveeriding.
+ *
+ * Settings are implemented using java {@link Properties}. They are loaded with a progressive
+ * override strategy.
+ *
+ * @author Simone Gianni <si...@apache.org>
+ */
public class SettingsHolder {
private Properties properties = new Properties();
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@labs.apache.org
For additional commands, e-mail: commits-help@labs.apache.org