Author: tchemit Date: 2008-07-28 12:19:43 +0000 (Mon, 28 Jul 2008) New Revision: 931 Added: trunk/commandline/commandline-core/src/main/java/org/codelutin/option/ContextKey.java trunk/commandline/commandline-core/src/main/java/org/codelutin/option/ContextKeyImpl.java Modified: trunk/commandline/commandline-core/src/main/java/org/codelutin/option/AbstractContext.java trunk/commandline/commandline-core/src/main/java/org/codelutin/option/Context.java Log: javadoc mise en place d'un context dynamique Modified: trunk/commandline/commandline-core/src/main/java/org/codelutin/option/AbstractContext.java =================================================================== --- trunk/commandline/commandline-core/src/main/java/org/codelutin/option/AbstractContext.java 2008-07-27 10:36:26 UTC (rev 930) +++ trunk/commandline/commandline-core/src/main/java/org/codelutin/option/AbstractContext.java 2008-07-28 12:19:43 UTC (rev 931) @@ -73,6 +73,9 @@ /** le timestamp de d�marrage de l'application */ protected final long startingTime; + /** le dictionnaire de valeurs suppl�mentaires */ + protected final java.util.Map<String, Object> extraValues; + protected AbstractContext(Class<P> parserClass, Class<? extends Config>... configs) throws Exception { startingTime = System.nanoTime(); String home = System.getProperty("user.home"); @@ -98,6 +101,9 @@ for (ConfigKey configKey : getConfigKeys()) { this.configs[i++] = configKey.instanciateConfig(); } + + extraValues = new java.util.TreeMap<String, Object>(); + } protected AbstractContext(Class<P> parserClass) throws Exception { @@ -122,6 +128,7 @@ for (ConfigKey configKey : getConfigKeys()) { this.configs[i++] = configKey.instanciateConfig(); } + extraValues = new java.util.TreeMap<String, Object>(); } public void init(String[] args) throws Exception { @@ -380,4 +387,36 @@ visitor.enterConfig(configKey); } } + + public <T> void addContextValue(ContextKey<T> key, T value) { + String strKey = key.getKey(); + if (!extraValues.containsKey(strKey)) { + extraValues.put(strKey, value); + } + if (log.isWarnEnabled()) { + log.warn("on existing value for key " + key); + } + extraValues.put(strKey, value); + } + + public <T> void removeContextValue(ContextKey<T> key) { + String strKey = key.getKey(); + if (extraValues.containsKey(strKey)) { + extraValues.remove(strKey); + } + } + + public void removeAllContextValues() { + extraValues.clear(); + } + + @SuppressWarnings({"unchecked"}) + public <T> T getContextValue(ContextKey<T> key) { + String strKey = key.getKey(); + if (!extraValues.containsKey(strKey)) { + //TODO Should throw an exception + return null; + } + return (T) extraValues.get(strKey); + } } \ No newline at end of file Modified: trunk/commandline/commandline-core/src/main/java/org/codelutin/option/Context.java =================================================================== --- trunk/commandline/commandline-core/src/main/java/org/codelutin/option/Context.java 2008-07-27 10:36:26 UTC (rev 930) +++ trunk/commandline/commandline-core/src/main/java/org/codelutin/option/Context.java 2008-07-28 12:19:43 UTC (rev 931) @@ -18,60 +18,233 @@ import java.io.IOException; import java.util.List; -/** @author chemit */ +/** + * Contract of an application context. + * <p/> + * The context box an {@link OptionParser}, some {@link Config}. + * <p/> + * A context can also have dynamic entries (see the XXXContextValue(s) method). + * + * @author chemit + */ public interface Context<P extends OptionParser> extends ContextVisitable { + /** + * Init the context (says init the parser and the config) + * + * @param args arguments passed to application + * @throws Exception if any pb while initialisation. + */ void init(String[] args) throws Exception; + /** @return the starting time of the context (says when the context is instanciated) */ long getStartingTime(); + /** @return the delay elasped from {@link #getStartingTime()} to now */ long getElapsedTime(); + /** @return the delay elasped from {@link #getStartingTime()} to now as a String representation */ String getElapsedTimeAsString(); /** initialisation i18n apr�s init du parser et des configs. */ void initI18n(); - /** @return la configuration principale de l'application */ + /** + * Accessor of the main configuration of context. + * + * @return la configuration principale de l'application + */ Config getMainConfig(); + /** @return the boxed {@link OptionParser} */ P getParser(); + /** + * @param key the given key of config + * @return the config registred given his key + */ <C extends Config> C getConfig(ConfigKey<C> key); + /** + * Accessor of the flag <code>quit</code>. + * <p/> + * The <code>quit</code> is computed while firing the options given to application. + * + * @return <ocde>true</code> if we should stop application, <code>false</code> otherwise. + */ boolean isQuit(); + /** + * Accessor of the flag <code>useUI</code>. + * <p/> + * The <code>useUI</code> flag tells us if we can use UI in the application. + * + * @return <code>true</code> if we can use UI in the application, <code>false</code> otherwise. + */ boolean isUseUI(); + /** + * Accessor of the flag <code>launchUI</code>. + * <p/> + * The <code>launchUI</code> flag tells us if we should launch the main UI of the application, after the init. + * <p/> + * This flag can be changed by options fired + * + * @return <code>true</code> if we should launch main UI after init, <code>false</code> otherwise. + */ boolean isLaunchUI(); + /** + * Accessor of the flag <code>firstLaunch</code>. + * <p/> + * The <code>firstLaunch</code> determines if this is the first time the application is launched (says no + * configuration file was found) + * + * @return <code>true</code> if no config file was found, <code>false</code> otheriwse. + */ boolean isFirstLaunch(); + /** + * Mutator of the flag <code>quit</code> + * + * @param quit the new value of the flag <code>quit</code> + */ void setQuit(boolean quit); + /** + * Mutator of the flag <code>launchUI</code> + * + * @param launchUI the new value of the flag <code>launchUI</code> + */ void setLaunchUI(boolean launchUI); + /** + * Mutator of the flag <code>firstLaunch</code> + * + * @param firstLaunch the new value of the flag <code>firstLaunch</code> + */ void setFirstLaunch(boolean firstLaunch); + /** + * Try to save the configurations boxed by context. + * <p/> + * All configuration are saved in the same file given by the method {@link #getSource()}. + * + * @throws IOException if IO pb while saving + * @throws IllegalStateException TODO + */ void save() throws IOException, IllegalStateException; + /** + * Try to save the configurations boxed by the context. + * <p/> + * If any problem appears, no exception will be trhown. + * <p/> + * <b>Note : this is a weak method, since no exception is thrown...</b> + */ void saveSafely(); + /** + * Mutator of the configuration file + * + * @param source the new file to use to store on disk the configurations boxed by context. + */ void setSource(File source); + /** + * Accessor of the configuration file to store configurations + * + * @return the file where configurations boxed by context are stored. + */ File getSource(); + /** + * Accessor of all configuration's key known by the context. + * + * @return the list of {@link org.codelutin.option.ConfigKey} known by the context. + */ List<ConfigKey<?>> getConfigKeys(); + /** + * Accessor of all configurations boxed by the context. + * + * @return the list of all configurations boxed by the context. + */ Config[] getConfigs(); + /** + * Accessor of a typed configuration's key given his string representation key. + * <p/> + * This method is used when we do not knwon the real implementation of a configuration key. + * <p/> + * For example, there is always a <code>main</code> config in a context, so we can access the configKey using this + * method in a generic code. + * <p/> + * <b>Note : Use this code as less as possible, when you don't have access to real implementation of the context.</b> + * + * @param key the string representation of a key of configuration + * @return the typed configuration key given his string representation + */ ConfigKey<?> getConfigKey(String key); + /** + * Accessor of a boxed configuration using the configuration key (as a string representation). + * <p/> + * The configuration is searched via his method {@link org.codelutin.option.Config#getCategory()} + * <p/> + * <b>Note : use this method only if you do not know the real implementation of context (for example in a + * generic code)</b> + * + * @param key the string representaiotn of a key configuration researched + * @return the configuration boxed in context, or <code>null</code> if no matching configuration is found. + */ Config getConfig(String key); - @SuppressWarnings({"unchecked"}) - <C extends Config> void registerConfig(Class<? extends C> aClass); + /** + * Register in the context a new configuration, given his implementation class. + * + * @param aClass the config class implementation + */ + <C extends Config> void registerConfig(Class<? extends C> aClass); + @Override void accept(ContextVisitor visitor); + /** + * Dispose the context (says dispose the application), with possibility to reload it when <code>reload</code> has + * <code>true</code> value. + * <p/> + * For example, when we wants to change langue of an application, all uis has to be dispose then reloead, so you + * can use this method for the purpose. + * + * @param reload <code>true</code> if context is reload after disposing it, <ocde>false</code> otherwise. + */ void dispose(boolean reload); + + /** + * Add to the context a dynamic entry given his typed key and his real value. + * <p/> + * <b>Note : if an previously entry was in context, it will be override by the new value.</b> + * + * @param key the context typed entry key + * @param value the context entry value + */ + <T> void addContextValue(ContextKey<T> key, T value); + + /** + * Remove ffrom the context the dynamic entry + * + * @param key the context typed entry key + */ + <T> void removeContextValue(ContextKey<T> key); + + /** Remove from context, all dynamic entries. */ + void removeAllContextValues(); + + /** + * Accessor of a dynamic entry in the context given his type entry key. + * + * @param key the given typed entry key + * @return the value of the dynamic entry + */ + <T> T getContextValue(ContextKey<T> key); } Added: trunk/commandline/commandline-core/src/main/java/org/codelutin/option/ContextKey.java =================================================================== --- trunk/commandline/commandline-core/src/main/java/org/codelutin/option/ContextKey.java (rev 0) +++ trunk/commandline/commandline-core/src/main/java/org/codelutin/option/ContextKey.java 2008-07-28 12:19:43 UTC (rev 931) @@ -0,0 +1,34 @@ +/** + * # #% Copyright (C) 2008 Code Lutin, Tony Chemit + * This program is free software; you + * can redistribute it and/or modify it under the terms of the GNU General + * Public License as published by the Free Software Foundation; either version 2 + * of the License, or (at your option) any later version. This program is + * distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; + * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + * PARTICULAR PURPOSE. See the GNU General Public License for more details. You + * should have received a copy of the GNU General Public License along with this + * program; if not, write to the Free Software Foundation, Inc., 59 Temple Place + * - Suite 330, Boston, MA 02111-1307, USA. + * # #% + */ +package org.codelutin.option; + +/** + * Contract of a key in the context. + * <p/> + * The {@link #getKey()} returns the string value of the key. + * <p/> + * The {link #getValueType()} returns the type of the value. + * <p/> + * To obtain the real value of this key for a given context, use the method {@link Context#getContextValue(ContextKey)} + * + * @author chemit + */ +public interface ContextKey<T> { + + String getKey(); + + Class<T> getValueType(); + +} Added: trunk/commandline/commandline-core/src/main/java/org/codelutin/option/ContextKeyImpl.java =================================================================== --- trunk/commandline/commandline-core/src/main/java/org/codelutin/option/ContextKeyImpl.java (rev 0) +++ trunk/commandline/commandline-core/src/main/java/org/codelutin/option/ContextKeyImpl.java 2008-07-28 12:19:43 UTC (rev 931) @@ -0,0 +1,57 @@ +/** + * # #% Copyright (C) 2008 Code Lutin, Tony Chemit + * This program is free software; you + * can redistribute it and/or modify it under the terms of the GNU General + * Public License as published by the Free Software Foundation; either version 2 + * of the License, or (at your option) any later version. This program is + * distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; + * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + * PARTICULAR PURPOSE. See the GNU General Public License for more details. You + * should have received a copy of the GNU General Public License along with this + * program; if not, write to the Free Software Foundation, Inc., 59 Temple Place + * - Suite 330, Boston, MA 02111-1307, USA. + * # #% + */ +package org.codelutin.option; + +/** + * A simple implementation of {@link ContextKey}. + * <p/> + * This object has an invariant {@link #key} which defines the {@link #equals(Object)} methods (and of course the + * {@link #hashCode()} one too!). + * + * @author chemit + */ +public class ContextKeyImpl<T> implements ContextKey<T> { + + final protected String key; + final protected Class<T> valueType; + + public ContextKeyImpl(String key, Class<T> valueType) { + this.key = key; + this.valueType = valueType; + } + + public String getKey() { + return key; + } + + public Class<T> getValueType() { + return valueType; + } + + @Override + public String toString() { + return super.toString() + "<key:" + key + ", type:" + valueType + ">"; + } + + @Override + public boolean equals(Object o) { + return this == o || o instanceof ContextKeyImpl && key.equals(((ContextKeyImpl) o).key); + } + + @Override + public int hashCode() { + return key.hashCode(); + } +}