Return-Path:
This Qualifier allows to use the DeltaSpike configuration mechanism
- * via simple injection. Example 1:
+ * This Qualifier allows simple injection of configuration properties through the DeltaSpike configuration
+ * mechanism.
+ *
+ * A default implementation is provided in DeltaSpike for basic String injection points:
*
* @Inject @ConfigProperty(name="locationId")
* private String locationId;
*
*
Example 2 (the type-safe alternative): + *
+ * It's possible to use config properties in a type-safe manner, which requires a custom producer: * *
- * @Target({ FIELD, METHOD }) + * @Target({FIELD, METHOD}) * @Retention(RUNTIME) * @ConfigProperty(name = "locationId") - * // alternative to null check in the producer: - * // @ConfigProperty(name = "locationId", defaultValue = "LOCATION_X") * @Qualifier - * public @interface Location - * { + * public @interface Location { * } *- * * - * Depending on the producer it's possible to use a String or a custom type like an enum at the injection point. - * - * With a String: *
* @Location * private String locationId; ** - * With a custom type: - *
- * @Inject - * @Location - * private LocationId locationId; - *- *
In any case a custom producer is needed. - * {@link org.apache.deltaspike.core.spi.config.BaseConfigPropertyProducer} can be used as an base for custom - * producers. - * Producer for the configured String: - *
+ ** @ApplicationScoped - * public class CustomConfigPropertyProducer extends BaseConfigPropertyProducer - * { + * public class CustomConfigPropertyProducer extends BaseConfigPropertyProducer { * @Produces * @Dependent * @Location - * public String produceLocationId(InjectionPoint injectionPoint) - * { + * public String produceLocationId(InjectionPoint injectionPoint) { * String configuredValue = getStringPropertyValue(injectionPoint); - * if (configuredValue == null) - * { + * if (configuredValue == null) { * return null; * } * return configuredValue; * } * } *+ * + *+ * Producers can be implemented to support other types of injection points: + *
+ * @Inject + * @Location + * private LocationId locationId; + ** - * Producer for a custom type: ** @ApplicationScoped - * public class CustomConfigPropertyProducer extends BaseConfigPropertyProducer - * { + * public class CustomConfigPropertyProducer extends BaseConfigPropertyProducer { * @Produces * @Dependent * @Location - * public LocationId produceLocationId(InjectionPoint injectionPoint) - * { + * public LocationId produceLocationId(InjectionPoint injectionPoint) { * String configuredValue = getStringPropertyValue(injectionPoint); - * if (configuredValue == null) - * { + * if (configuredValue == null) { * return null; * } * return LocationId.valueOf(configuredValue.trim().toUpperCase()); * } * } *- * + * + * For custom producer implementations, {@link org.apache.deltaspike.core.spi.config.BaseConfigPropertyProducer} can + * be used as the base class. + * * @see org.apache.deltaspike.core.api.config.ConfigResolver * @see org.apache.deltaspike.core.spi.config.BaseConfigPropertyProducer */ @@ -124,13 +111,13 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; public @interface ConfigProperty { /** - * This constant is a workaround for the java restriction that Annotation values - * cannot be set to null. Do not use this String in your configuration... + * This constant is a workaround for the java restriction that Annotation values cannot be set to null. Do not use + * this String in your configuration. */ String NULL = "org.apache.deltaspike.NullValueMarker"; /** - * Name/key of the property + * Name/key of the property. * @return name of the property */ @Nonbinding @@ -138,6 +125,7 @@ public @interface ConfigProperty /** * Optional default value. + * * @return the default value which should be used if no config value could be found */ @Nonbinding http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigResolver.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigResolver.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigResolver.java index ae37147..c70557b 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigResolver.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigResolver.java @@ -39,11 +39,20 @@ import org.apache.deltaspike.core.util.ProjectStageProducer; import org.apache.deltaspike.core.util.ServiceUtils; /** - *Resolve the configuration via their well defined ordinals.
+ * The main entry point to the DeltaSpike configuration mechanism. * - *You can provide your own lookup paths by implementing - * and registering additional {@link PropertyFileConfig} or + *
+ * Resolves configured values of properties by going through the list of configured {@link ConfigSource}s and using the + * one with the highest ordinal. If multiple {@link ConfigSource}s have the same ordinal, their order is undefined.
+ * + *+ * You can provide your own lookup paths by implementing and registering additional {@link PropertyFileConfig} or * {@link ConfigSource} or {@link ConfigSourceProvider} implementations.
+ * + *+ * The resolved configuration is also accessible by simple injection using the {@link ConfigProperty} qualifier.
+ * + * @see DeltaSpike Configuration Mechanism */ @Typed() public final class ConfigResolver @@ -96,7 +105,7 @@ public final class ConfigResolver } /** - * Clear all ConfigSources for the current ClassLoader + * Clear all ConfigSources for the current ClassLoader. */ public static synchronized void freeConfigSources() { @@ -104,9 +113,9 @@ public final class ConfigResolver } /** - * Add a {@link ConfigFilter} to the ConfigResolver. - * This will only affect the current WebApp - * (or more precisely the current ClassLoader and it's children). + * Add a {@link ConfigFilter} to the ConfigResolver. This will only affect the current WebApp (or more precisely the + * current ClassLoader and it's children). + * * @param configFilter */ public static void addConfigFilter(ConfigFilter configFilter) @@ -132,14 +141,14 @@ public final class ConfigResolver } /** - * Resolve the property value by going through the list of configured {@link ConfigSource}s - * and use the one with the highest priority. If no configured value has been found that - * way we will use the defaultValue. + * {@link #getPropertyValue(java.lang.String)} which returns the provided default value if no configured value can + * be found (null
or empty). * - * @param key the property key. - * @param defaultValue will be used if no configured value for the key could be found. - * @return the configured property value from the {@link ConfigSource} with the highest ordinal or - * the defaultValue if there is no value explicitly configured. + * @param key the property key + * @param defaultValue fallback value + * + * @return the configured property value from the {@link ConfigSource} with the highest ordinal or the defaultValue + * if there is no value explicitly configured */ public static String getPropertyValue(String key, String defaultValue) { @@ -149,12 +158,12 @@ public final class ConfigResolver } /** - * Resolve the property value by going through the list of configured {@link ConfigSource}s - * and use the one with the highest priority. + * Resolves the value configured for the given key. + * + * @param key the property key * - * @param key the property key. - * @return the configured property value from the {@link ConfigSource} with the highest ordinal or - * null if there is no configured value for it. + * @return the configured property value from the {@link ConfigSource} with the highest ordinal or null if there is + * no configured value for it */ public static String getPropertyValue(String key) { @@ -180,18 +189,22 @@ public final class ConfigResolver } /** - *Search for the configured value in all {@link ConfigSource}s and take the - * current {@link org.apache.deltaspike.core.api.projectstage.ProjectStage} - * into account.
+ * Resolves the value configured for the given key in the current + * {@link org.apache.deltaspike.core.api.projectstage.ProjectStage}. + * + *+ * First, it will search for a value configured for the given key suffixed with the current ProjectStage (e.g. + * 'myproject.myconfig.Production'), and in case this value is not found (null or empty), it will look up the given + * key without any suffix.
* - *It first will search if there is a configured value of the given key prefixed - * with the current ProjectStage (e.g. 'myproject.myconfig.Production') and if this didn't - * find anything it will lookup the given key without any prefix.
+ *+ * Attention This method must only be used after all ConfigSources got registered and it also must not be + * used to determine the ProjectStage itself.
* - *Attention This method must only be used after all ConfigSources - * got registered and it also must not be used to determine the ProjectStage itself.
* @param key - * @return the configured value or if non found the defaultValue + * + * @return the value configured for {@code. }, or just the configured value of + * {@code } if the project-stage-specific value is not found (null or empty) * */ public static String getProjectStageAwarePropertyValue(String key) @@ -207,10 +220,12 @@ public final class ConfigResolver return value; } /** - * {@link #getProjectStageAwarePropertyValue(String)} which returns the defaultValue - * if the property is null
or empty. + * {@link #getProjectStageAwarePropertyValue(String)} which returns the provided default value if no configured + * value can be found (null
or empty). + * * @param key - * @param defaultValue + * @param defaultValue fallback value + * * @return the configured value or if non found the defaultValue * */ @@ -222,37 +237,42 @@ public final class ConfigResolver } /** - *Search for the configured value in all {@link ConfigSource}s and take the - * current {@link org.apache.deltaspike.core.api.projectstage.ProjectStage} - * and the value configured for the given property into account.
- * - *The first step is to resolve the value of the given property. This will - * take the current ProjectStage into account. E.g. given the property is 'dbvendor' - * and the ProjectStage is 'UnitTest', the first lookup is - *
. - * If this value is not found then we will do a 2nd lookup for - *
- 'dbvendor.UnitTest'
+ * Resolves the value configured for the given key, parameterized by the current + * {@link org.apache.deltaspike.core.api.projectstage.ProjectStage} and by the value of a second property. * - *
- 'dbvendor'
If a value was found for the given property (e.g. dbvendor = 'mysql' - * then we will use this value to lookup in the following order until we - * found a non-null value. If there was no value found for the property - * we will only do the key+ProjectStage and key lookup. - * In the following sample 'dataSource' is used as key parameter: + *
+ * Example:
+ *
+ * Suppose the current ProjectStage is {@code UnitTest} and we are looking for the value of {@code datasource} + * parameterized by the configured {@code dbvendor}. + *+ * The first step is to resolve the value of the second property, {@code dbvendor}. This will also take the current + * ProjectStage into account. The following lookup is performed: + *
+ * and if this value is not found then we will do a 2nd lookup for + *
- dbvendor.UnitTest
* + *
- dbvendor
+ * If a value was found for the second property (e.g. dbvendor = 'mysql') then we will use its value for the main + * lookup. If no value is found for the parameterized key {@code
* + *. . }, we + * will do the {@code . }, then {@code . } and finally a {@code } + * lookup: * - *
*- 'datasource.mysql.UnitTest'
- *- 'datasource.mysql'
- *- 'datasource.UnitTest'
- *- 'datasource'
+ *- datasource.mysql.UnitTest
+ *- datasource.mysql
+ *- datasource.UnitTest
+ *- datasource
*+ * Attention This method must only be used after all ConfigSources got registered and it also must not be + * used to determine the ProjectStage itself.
* - *Attention This method must only be used after all ConfigSources - * got registered and it also must not be used to determine the ProjectStage itself.
* @param key - * @param property the property to look up first - * @return the configured value or if non found the defaultValue + * @param property the property to look up first and use as the parameter for the main lookup + * + * @return the configured value or null if no value is found for any of the key variants * */ public static String getPropertyAwarePropertyValue(String key, String property) @@ -274,15 +294,21 @@ public final class ConfigResolver return value; } - /* - *Attention This method must only be used after all ConfigSources - * got registered and it also must not be used to determine the ProjectStage itself.
+ /** + * {@link #getPropertyAwarePropertyValue(java.lang.String, java.lang.String)} which returns the provided default + * value if no configured value can be found (null
or empty). + * + *+ * Attention This method must only be used after all ConfigSources got registered and it also must not be + * used to determine the ProjectStage itself.
+ * * @param key - * @param property the property to look up first - * @param defaultValue + * @param property the property to look up first and use as the parameter for the main lookup + * @param defaultValue fallback value + * * @return the configured value or if non found the defaultValue * - */ + */ public static String getPropertyAwarePropertyValue(String key, String property, String defaultValue) { String value = getPropertyAwarePropertyValue(key, property); @@ -291,12 +317,12 @@ public final class ConfigResolver } /** - * Resolve all values for the given key, from all registered ConfigSources ordered by their - * ordinal value in ascending ways. If more {@link ConfigSource}s have the same ordinal, their - * order is undefined. + * Resolve all values for the given key. + * + * @param key + * + * @return a List of all found property values, sorted by their ordinal in ascending order * - * @param key under which configuration is stored - * @return List with all found property values, sorted in ascending order of their ordinal. * @see org.apache.deltaspike.core.spi.config.ConfigSource#getOrdinal() */ public static ListgetAllPropertyValues(String key) @@ -323,6 +349,13 @@ public final class ConfigResolver return result; } + /** + * Returns a Map of all properties from all scannable config sources. The values of the properties reflect the + * values that would be obtained by a call to {@link #getPropertyValue(java.lang.String)}, that is, the value of the + * property from the ConfigSource with the highest ordinal. + * + * @see ConfigSource#isScannable() + */ public static Map getAllProperties() { // must use a new list because Arrays.asList() is resistant to sorting on some JVMs: http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/DeltaSpikeConfig.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/DeltaSpikeConfig.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/DeltaSpikeConfig.java index 87ca2ce..3b51992 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/DeltaSpikeConfig.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/DeltaSpikeConfig.java @@ -21,18 +21,17 @@ package org.apache.deltaspike.core.api.config; import java.io.Serializable; /** - * Marker interface for all type-safe framework configs.
+ * Marker interface for all classes used for configuration of DeltaSpike itself. * - *All DeltaSpike Configuration objects implement this interface - * so they can be found more easily. There is no other + *
+ * All DeltaSpike configuration objects implement this interface so they can be found more easily. There is no other * functionality implied with this interface.
* - *DeltaSpike uses a Typesafe Configuration approach. - * Instead of writing a properties file or XML, you just implement - * one of the configuration interfaces which will then be picked up as - * CDI bean. If there is already a default configuration for - * some functionality in DeltaSpike, you can use @Specializes or - * @Alternative to change those.
+ *+ * DeltaSpike uses a type-safe configuration approach. Instead of writing a properties file or XML, you just + * implement one of the configuration interfaces which will then be picked up as a CDI bean. If there is already a + * default configuration for some functionality in DeltaSpike, you can use @Specializes or @Alternative to + * change those.
*/ public interface DeltaSpikeConfig extends Serializable { http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyFileConfig.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyFileConfig.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyFileConfig.java index 0d0a883..216ebe7 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyFileConfig.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyFileConfig.java @@ -19,29 +19,26 @@ package org.apache.deltaspike.core.api.config; /** - *If you implement this interface inside a Bean Archive - * (a JAR or ClassPath entry with a META-INF/beans.xml file), - * the property files with the given file name - * will be registered as {@link org.apache.deltaspike.core.spi.config.ConfigSource}s.
+ *+ * If you implement this interface inside a Bean Archive (a JAR or ClassPath entry with a META-INF/beans.xml file), the + * property files with the given file name will be registered as + * {@link org.apache.deltaspike.core.spi.config.ConfigSource}s.
* - *DeltaSpike will automatically pickup all the implementations - * during the {@link javax.enterprise.inject.spi.ProcessAnnotatedType} - * phase and create a new instance via reflection. Thus the - * implementations will need a non-private default constructor. - * There is no CDI injection being performed in those instances! - * The scope of the implementations will also be ignored as they will - * not get picked up as CDI beans.
+ *+ * DeltaSpike will automatically pick up all the implementations during the + * {@link javax.enterprise.inject.spi.ProcessAnnotatedType} phase and create a new instance via reflection. Thus the + * implementations will need a non-private default constructor. There is no CDI injection being performed in + * those instances! The scope of the implementations will also be ignored as they will not get picked up as CDI + * beans.
* - *Please note that the configuration will only be available - * after the boot is finished. This means that you cannot use - * this configuration inside a CDI Extension before the boot - * is finished!
+ *+ * Please note that the configuration will only be available after the boot is finished. This means that you cannot use + * this configuration inside a CDI Extension before the boot is finished!
*/ public interface PropertyFileConfig extends DeltaSpikeConfig { /** - * All the property files on the classpath which have this - * name will get picked up and registered as + * All the property files on the classpath which have this name will get picked up and registered as * {@link org.apache.deltaspike.core.spi.config.ConfigSource}s. * * @return the full file name (including path) of the property files to pick up. http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyLoader.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyLoader.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyLoader.java index ecd7291..eb777da 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyLoader.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyLoader.java @@ -35,13 +35,14 @@ import java.util.logging.Level; import java.util.logging.Logger; /** - *Utility class to load configuration properties via a list of - * artibrary property files by a well defined order.
+ * Utility class to load configuration properties via arbitrary property files in a well defined order. * - *This will also pick up property files which are post-fixed with - * a -$projectStage.properties
- *User configurations should start with 'configuration.ordinal' - * greater than 100.
+ *+ * This will also pick up property files with names suffixed with {@code -
+ *}, e.g. + * myconfig-Production.properties. + * User configurations should have {@code deltaspike_ordinal} as the first property, with a value greater than + * 100.
* */ public class PropertyLoader @@ -61,24 +62,25 @@ public class PropertyLoader } /** - *Look for all property files with the given name (e.g. 'myconfig.properties') in - * the classpath. Then load all properties files and sort them by their ascending - * configuration order and apply them in this order.
+ * Looks for all properties files with the given name in the classpath, loads them in ascending order determined by + * their ordinal and merges them. * - *The idea is to be able to 'override' properties by just providing - * a new properties file with the same name but a higher 'deltaspike_ordinal' - * than the old one.
+ *+ * The idea is to be able to override properties by just providing a new properties file with the same name but a + * higher 'deltaspike_ordinal' than the old one.
* - *If a property file defines no 'configuration.ordinal' property than a default - * value of {@link #CONFIGURATION_ORDINAL_DEFAULT_VALUE} is assumed. Any sensitive - * default which is provided by the system parsing for the configuration should - * have a 'configuration.ordinal' value lower than 10. In most cases a value of 1
+ *+ * If a property file defines no 'deltaspike_ordinal' property than a default value of + * {@link #CONFIGURATION_ORDINAL_DEFAULT_VALUE} is assumed. Any sensitive default which is provided by the system + * parsing for the configuration should have a 'deltaspike_ordinal' value lower than 10. In most cases a value of + * 1.
* - *If 2 property files have the same ordinal 'configuraiton.order' the outcome - * is not really defined. The Properties file which got found first will be - * processed first and thus get overwritten by the one found later.
+ *+ * If two property files have the same 'deltaspike_ordinal', their order is undefined. The Properties file which + * gets found first will be processed first and thus gets overwritten by the one found later.
* * @param propertyFileName the name of the properties file, without the extension '.properties' + * * @return the final property values */ public static synchronized Properties getProperties(String propertyFileName) @@ -205,7 +207,7 @@ public class PropertyLoader } /** - * Determine the 'configuration.ordinal' of the given properties. + * Determine the 'deltaspike_ordinal' of the given properties. * {@link #CONFIGURATION_ORDINAL_DEFAULT_VALUE} if * {@link ConfigSource#DELTASPIKE_ORDINAL} is not set in the * Properties file. http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/DefaultErrorView.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/DefaultErrorView.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/DefaultErrorView.java index 5305907..9bdf5c6 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/DefaultErrorView.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/DefaultErrorView.java @@ -20,11 +20,9 @@ package org.apache.deltaspike.core.api.config.view; /** * Abstract class which marks an error view. - * - * It's an abstract class instead of an interface, - * because you can use it for navigation (which is restricted to classes). - * (Since only the final page should be a class and for the rest it's recommended to use interfaces, - * it isn't a problem/restriction.) + * + * It's an abstract class instead of an interface, because it can be used for navigation (which is restricted to + * classes). */ public abstract class DefaultErrorView implements ViewConfig { http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewConfig.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewConfig.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewConfig.java index 66db48a..ab8a017 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewConfig.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewConfig.java @@ -19,8 +19,8 @@ package org.apache.deltaspike.core.api.config.view; /** - * Marker interface for type-safe view-config classes. - * Required for view-configs which represent a (logical) page and optional for the rest (e.g. folder-configs). + * Marker interface for type-safe view-config classes. Required for view-configs which represent a (logical) page and + * optional for the rest (e.g. folder-configs). */ public interface ViewConfig { http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewRef.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewRef.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewRef.java index 8c4a786..4634631 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewRef.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewRef.java @@ -35,7 +35,10 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Allows to reference a view-config + * A reference to a view-config, applied on a view-controller. The opposite direction of {@link ViewControllerRef}. + * + * ViewRef annotation instances are not present at runtime as metadata, they are instead transformed to + * ViewControllerRef instances during deployment. */ @Target({ TYPE, METHOD }) @@ -52,9 +55,9 @@ public @interface ViewRef } /** - * Specifies the pages via type-safe {@link ViewConfig}. + * Specifies the views to bind to the view-controller. * - * @return views which should be aware of the bean or observer + * @return {@link ViewConfig}s of views bound to the view-controller */ @Nonbinding Class extends ViewConfig>[] config(); http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/InitView.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/InitView.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/InitView.java index 4bb4e44..7764c1e 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/InitView.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/InitView.java @@ -26,8 +26,8 @@ import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * View-controller annotation for page-beans. - * Methods annotated with this annotation will be invoked as soon as a view has been initialized. + * Callback annotation for view-controllers. Methods annotated with this annotation will be invoked as soon as a view + * has been initialized. */ @Target(METHOD) @Retention(RUNTIME) http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PostRenderView.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PostRenderView.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PostRenderView.java index 6148759..a6b4f23 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PostRenderView.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PostRenderView.java @@ -26,8 +26,8 @@ import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * View-controller annotation for page-beans. - * Methods annotated with this annotation will be invoked after the view gets rendered. + * Callback annotation for view-controllers. Methods annotated with this annotation will be invoked after the view gets + * rendered. */ @Target(METHOD) @Retention(RUNTIME) http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreRenderView.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreRenderView.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreRenderView.java index 0bde410..baf8e68 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreRenderView.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreRenderView.java @@ -26,8 +26,8 @@ import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * View-controller annotation for page-beans. - * Methods annotated with this annotation will be invoked before the view gets rendered. + * Callback annotation for view-controllers. Methods annotated with this annotation will be invoked before the view gets + * rendered. */ @Target(METHOD) @Retention(RUNTIME) http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreViewAction.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreViewAction.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreViewAction.java index 0d835cb..8ced102 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreViewAction.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreViewAction.java @@ -26,9 +26,8 @@ import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * View-controller annotation for page-beans. - * Methods annotated with this annotation will be invoked before the method binding gets invoked. - * Usually only used for using a callback in the page-bean in parallel with 3rd party flow-engines + * Callback annotation for view-controllers. Methods annotated with this annotation will be invoked before the method + * binding gets invoked. Can be used as a callback in a view-controller in parallel with 3rd party flow-engines. */ @Target(METHOD) @Retention(RUNTIME) http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/ViewControllerRef.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/ViewControllerRef.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/ViewControllerRef.java index e107db1..a767e84 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/ViewControllerRef.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/ViewControllerRef.java @@ -18,11 +18,6 @@ */ package org.apache.deltaspike.core.api.config.view.controller; -/** - * Specifies one or more page-beans via the type-safe view-config. - * Such page beans support e.g. the view-controller annotations. - */ - import org.apache.deltaspike.core.api.config.view.metadata.SimpleCallbackDescriptor; import org.apache.deltaspike.core.api.config.view.metadata.ViewMetaData; import org.apache.deltaspike.core.spi.config.view.ConfigPreProcessor; @@ -36,6 +31,10 @@ import java.lang.annotation.Target; import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; +/** + * Specifies one or more view-controllers for the view-config which has this annotation applied. View-controllers can + * handle callbacks like {@link InitView}, {@link PreRenderView}, etc. + */ //don't use @Inherited @Target(TYPE) @Retention(RUNTIME) @@ -45,19 +44,17 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; public @interface ViewControllerRef { /** - * Class of the page-bean + * Class of the view-controller. * - * @return class of the page-bean + * @return class of the view-controller */ Class> value(); /** - * Currently not implemented - * - * - * Optional name of the page-bean + * Currently not implemented. + * Optional name of the view-controller. * - * @return name of the page-bean + * @return name of the view-controller */ //TODO String name() default ""; http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/Aggregated.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/Aggregated.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/Aggregated.java index c163219..a0c6aca 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/Aggregated.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/Aggregated.java @@ -26,20 +26,23 @@ import static java.lang.annotation.ElementType.ANNOTATION_TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * This annotation can be used to mark annotations as aggregated meta-data. - * Core just provides this annotation, but the concrete behaviour is defined by a concrete ConfigNodeConverter. - * E.g. DefaultConfigNodeConverter uses the result stored in ViewConfigNode#getInheritedMetaData to replace - * default- (/ null-) values of "higher" levels with custom values of "lower" levels, - * if #value is 'true'. + * Marks view-metadata annotations or their fields as aggregated metadata. That results in retention of multiple + * instances of such annotation per view instead of the metadata getting overriden by lower levels. + * + * Core just provides this annotation, but the concrete behaviour is defined by a concrete ConfigNodeConverter. E.g. + * DefaultConfigNodeConverter uses the result stored in + * {@link org.apache.deltaspike.core.spi.config.view.ViewConfigNode#getInheritedMetaData} to replace default- (/ null-) + * values of "higher" levels with custom values of "lower" levels, if #value is 'true'. */ -@Target({ ANNOTATION_TYPE }) //TODO re-visit and discuss method-level (for annotation-attributes) +//TODO re-visit and discuss method-level (for annotation-attributes) +@Target({ ANNOTATION_TYPE }) @Retention(RUNTIME) @Documented public @interface Aggregated { /** - * @return false to override the same meta-data type of the parent view-config and - * true to allow multiple instances of a meta-data per view + * @return false to override the same metadata type of the parent view-config, and true to allow multiple instances + * of a metadata per view */ boolean value(); } http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/CallbackDescriptor.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/CallbackDescriptor.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/CallbackDescriptor.java index cb7e1c8..848c5aa 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/CallbackDescriptor.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/CallbackDescriptor.java @@ -31,8 +31,8 @@ import java.util.List; import java.util.Map; /** - * Basic descriptor for a given class and callback-type. - * It finds and caches the method/s of the given class which are annotated with the given callback-type. + * Basic descriptor for a given class and callback type. It finds and caches the method(s) of the given class which are + * annotated with the given callback-type. */ public abstract class CallbackDescriptor { http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ConfigDescriptor.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ConfigDescriptor.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ConfigDescriptor.java index df4383b..401dfe5 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ConfigDescriptor.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ConfigDescriptor.java @@ -22,51 +22,60 @@ import java.lang.annotation.Annotation; import java.util.List; /** - * Base descriptor for all type-safe view-configs which represents the - * config-class and meta-data, callbacks,... provided by/bound to this class. + * Base descriptor for all type-safe view-configs which describes the config class, metadata, callbacks and other + * properties of a view-config. + * + * @paramclass of the view-config */ -public interface ConfigDescriptor +public interface ConfigDescriptor { Class extends CT> getConfigClass(); /** - * Meta-data which is configured for the entry. It allows to provide and resolve meta-data annotated - * with {@link ViewMetaData} + * Metadata configured for this view-config. Resolves {@link ViewMetaData}-annotated annotations which are inherited + * or directly present on the view-config class. * - * @return meta-data of the current entry + * @return metadata of this view-config */ List getMetaData(); /** - * Meta-data which is configured for the entry. It allows to provide and resolve meta-data annotated - * with {@link ViewMetaData} + * Metadata which is configured for this view-config. Resolves {@link ViewMetaData}-annotated annotations which are + * inherited or directly present on the view-config class. * * @param target target type - * @return custom meta-data for the given type of the current entry + * + * @return custom metadata for the given type of this view-config */ List getMetaData(Class target); /** - * Callbacks which are configured for the entry and bound to the given meta-data type. - * @param metaDataType type of the meta-data (e.g. PageBean.class) - * @return descriptor for the callback or null if there is no callback-method + * Callbacks which are configured for this view-config and bound to the given metadata type. + * + * @param metaDataType type of the metadata (e.g. ViewControllerRef.class) + * + * @return descriptor for the callback or null if there is no callback method */ CallbackDescriptor getCallbackDescriptor(Class extends Annotation> metaDataType); /** - * Callbacks which are configured for the entry and bound to the given meta-data type. - * @param metaDataType type of the meta-data (e.g. PageBean.class) + * Callbacks which are configured for this view-config and bound to the given metadata type. + * + * @param metaDataType type of the metadata (e.g. ViewControllerRef.class) * @param callbackType type of the callback (e.g. PreRenderView.class) + * * @return descriptor for the callback null if there is no callback-method */ CallbackDescriptor getCallbackDescriptor(Class extends Annotation> metaDataType, Class extends Annotation> callbackType); /** - * Callbacks which are configured for the entry and bound to the given meta-data type. - * @param metaDataType type of the meta-data (e.g. PageBean.class) - * @param executorType type of the executor which allows to get a typed result (e.g. Secured.Descriptor) - * @return descriptor for the callback which also allows to invoke it or null if there is no callback-method + * Callbacks which are configured for this view-config and bound to the given metadata type. + * + * @param metaDataType type of the metadata (e.g. ViewControllerRef.class) + * @param executorType type of the executor which returns a typed result (e.g. Secured.Descriptor) + * + * @return executable descriptor for the callback or null if there is no callback method */ @SuppressWarnings("rawtypes") //TODO > when major version is incremented @@ -74,11 +83,13 @@ public interface ConfigDescriptor Class extends T> executorType); /** - * Callbacks which are configured for the entry and bound to the given meta-data type. - * @param metaDataType type of the meta-data (e.g. PageBean.class) + * Callbacks which are configured for this view-config and bound to the given metadata type. + * + * @param metaDataType type of the metadata (e.g. ViewControllerRef.class) * @param callbackType type of the callback (e.g. PreRenderView.class) - * @param executorType type of the executor which allows to get a typed result (e.g. Secured.Descriptor) - * @return descriptor for the callback which also allows to invoke it or null if there is no callback-method + * @param executorType type of the executor which returns a typed result (e.g. Secured.Descriptor) + * + * @return executable descriptor for the callback or null if there is no callback method */ @SuppressWarnings("rawtypes") //TODO > when major version is incremented @@ -87,7 +98,8 @@ public interface ConfigDescriptor Class extends T> executorType); /** - * Returns the string representation of the resource represented by #getConfigClass + * Returns the string representation of the resource (page, folder) represented by this view-config. + * * @return relative path to the folder or page */ String getPath(); http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/DefaultCallback.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/DefaultCallback.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/DefaultCallback.java index b4acf5a..34b794a 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/DefaultCallback.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/DefaultCallback.java @@ -25,38 +25,44 @@ import java.lang.annotation.Target; import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.RetentionPolicy.RUNTIME; -@Target( METHOD ) -@Retention(RUNTIME) -@Documented - /** - * A ConfigDescriptor can contain CallbackDescriptors in general as well as ExecutableCallbackDescriptors. - * An ExecutableCallbackDescriptor can reference one or multiple callback-method/s. If there is only one callback type, - * it's possible to annotate it with @DefaultCallback. - * That allows to handle it in an easier fashion - * (= without providing a special marker (-annotation) for the target method). + * A ConfigDescriptor can contain CallbackDescriptors or ExecutableCallbackDescriptors. An ExecutableCallbackDescriptor + * can reference one or more callback method(s). If there is only one callback type, it's possible to annotate it with + * {@code @DefaultCallback}. That eliminates the need for a special marker annotation for the target method. + * + * If there are multiple callback types, it's necessary to use custom annotations as marker for the target method (e.g. + * see {@code @Secured} vs. {@code @ViewControllerRef}). * - * If there are multiple callback types, it's needed to use custom annotations as marker for the target method. - * (e.g. see @Secured vs. @ViewControllerBean) + * + * {@code + * ViewConfigDescriptor viewConfigDescriptor = viewConfigResolver.getViewConfigDescriptor(SomePage.class); * - * ViewConfigDescriptor viewConfigDescriptor = viewConfigResolver.getViewConfigDescriptor(PageConfig.class); * viewConfigDescriptor.getExecutableCallbackDescriptor( * Secured.class, Secured.Descriptor.class).execute(accessDecisionVoterContext); - * is short for + * }is short for + *+ * {@code * viewConfigDescriptor.getExecutableCallbackDescriptor( * Secured.class, DefaultCallback.class, Secured.Descriptor.class).execute(accessDecisionVoterContext); + * }* * whereas e.g. + *+ * {@code * viewConfigDescriptor.getExecutableCallbackDescriptor( - * ViewControllerBean.class, PreRenderView.class, ViewControllerBean.ViewControllerDescriptor.class).execute(); - * or just + * ViewControllerRef.class, PreRenderView.class, ViewControllerRef.Descriptor.class).execute(); + * }or just + *+ * {@code * viewConfigDescriptor.getExecutableCallbackDescriptor( - * ViewControllerBean.class, PreRenderView.class, SimpleCallbackDescriptor.class).execute(); - * - * are needed to call only @PreRenderView callbacks - * (and not the others like @InitView which are also bound to @ViewControllerBean) + * ViewControllerRef.class, PreRenderView.class, SimpleCallbackDescriptor.class).execute(); + * }are needed to call @PreRenderView callbacks specifically (instead of the others like @InitView which are also + * bound to @ViewControllerRef). */ //TODO find a better name -public @interface DefaultCallback +@Target( METHOD ) +@Retention(RUNTIME) +@Documented +public @interface DefaultCallback { } http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ExecutableCallbackDescriptor.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ExecutableCallbackDescriptor.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ExecutableCallbackDescriptor.java index 16c80b5..afa3bb5 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ExecutableCallbackDescriptor.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ExecutableCallbackDescriptor.java @@ -26,9 +26,9 @@ import java.util.ArrayList; import java.util.List; /** - * Specialized {@link CallbackDescriptor} - * which provides {@link #execute} only for concrete descriptors, but doesn't expose it (-> can't get used by accident). - * Concrete implementations can provide type-safe versions of it, but delegate the final execution to {@link #execute}. + * Specialized {@link CallbackDescriptor} which provides {@link #execute} only for concrete descriptors, but doesn't + * expose it (and can't get used by accident). Concrete implementations can provide type-safe versions of it, but + * delegate the final execution to {@link #execute}. * * @paramreturn type */ http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/InlineViewMetaData.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/InlineViewMetaData.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/InlineViewMetaData.java index 15e07ba..a157e5a 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/InlineViewMetaData.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/InlineViewMetaData.java @@ -28,6 +28,17 @@ import java.lang.annotation.Target; import static java.lang.annotation.ElementType.ANNOTATION_TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; +/** + * Provides the ability to apply metadata to a view-config "remotely" – from a + * different place than the view-config itself (and with different syntax and a different annotation). + * + * + * For example, the @ViewControllerRef (main) vs. @ViewRef (inline) – the @ViewControllerRef is applied + * directly on a view-config and references a view-controller, but there's also @ViewRef, which has the same purpose, + * but is applied in reverse – on a view-controller, referencing a view-config. + *
+ */ + @Target({ ANNOTATION_TYPE }) @Retention(RUNTIME) @Documented http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SimpleCallbackDescriptor.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SimpleCallbackDescriptor.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SimpleCallbackDescriptor.java index 81b828e..5d7ff6b 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SimpleCallbackDescriptor.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SimpleCallbackDescriptor.java @@ -22,8 +22,8 @@ import java.lang.annotation.Annotation; import java.util.List; /** - * {@link ExecutableCallbackDescriptor} for simple callback-methods without (supported) parameters, - * which exposes #execute without parameters. + * {@link ExecutableCallbackDescriptor} for simple callback methods without (supported) parameters, which exposes + * #execute without parameters. * * @paramreturn type */ http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SkipMetaDataMerge.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SkipMetaDataMerge.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SkipMetaDataMerge.java index acbf094..9e37d14 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SkipMetaDataMerge.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SkipMetaDataMerge.java @@ -25,13 +25,13 @@ import java.lang.annotation.Target; import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.RetentionPolicy.RUNTIME; +/** + * Disables metadata merging on attributes of @ViewMetaData annotations. Used in cases (e.g. @Folder#name) where it + * doesn't make sense to merge that part with inherited information. + */ @Target( METHOD ) @Retention(RUNTIME) @Documented - -/** - * In some cases (e.g. @Folder#name) it doesn't make sense to merge that part with inherited information. - */ public @interface SkipMetaDataMerge { } http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigDescriptor.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigDescriptor.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigDescriptor.java index 7a937f8..0a2fe9f 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigDescriptor.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigDescriptor.java @@ -21,17 +21,16 @@ package org.apache.deltaspike.core.api.config.view.metadata; import org.apache.deltaspike.core.api.config.view.ViewConfig; /** - * Descriptor which represents a concrete view (/page). + * Descriptor which represents a concrete view (page). */ public interface ViewConfigDescriptor extends ConfigDescriptor { /** - * View-ID of the current descriptor - * The default implementation returns the same as ConfigDescriptor#getPath. - * For the default implementation (and default integration with JSF) it's in place to provide a straightforward API. + * View ID of the current descriptor. The default implementation returns the same as ConfigDescriptor#getPath. For + * the default implementation (and default integration with JSF) it's in place to provide a straightforward API. * However, e.g. an integration for a different view technology can use it e.g. for a logical id. * - * @return current view-id + * @return current view ID */ String getViewId(); } http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigResolver.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigResolver.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigResolver.java index 82d2de7..514205c 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigResolver.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigResolver.java @@ -23,13 +23,13 @@ import org.apache.deltaspike.core.api.config.view.ViewConfig; import java.util.List; /** - * Resolver for view-configs + * Resolver of view-configs. * - * A {@link ConfigDescriptor} can be bound to any config-class (without required base-type). - * That's needed e.g. for folder-configs. Whereas {@link ViewConfigDescriptor}s only represent config-classes which - * inherit from {@link ViewConfig} which is required for all page-configs. + * A {@link ConfigDescriptor} can be bound to any config class (without required base type). That's needed e.g. for + * folder-configs. Whereas {@link ViewConfigDescriptor}s only represent classes which inherit from {@link ViewConfig} + * which is required for all view-configs. * - * Use {@link org.apache.deltaspike.core.spi.config.view.ViewConfigRoot} to configure a custom resolver. + * Use {@link org.apache.deltaspike.core.spi.config.view.ViewConfigRoot} to register a custom resolver. */ //TODO re-visit name since we also need ConfigDescriptor public interface ViewConfigResolver @@ -37,48 +37,51 @@ public interface ViewConfigResolver ConfigDescriptor> getConfigDescriptor(String path); /** - * Resolves the {@link ConfigDescriptor} for the given config-class + * Resolves the {@link ConfigDescriptor} for the given class. * - * @param configClass config-class (which usually represents a folder node) - * @return config-descriptor which represents the given config-class + * @param configClass config class which usually represents a folder node + * + * @return config descriptor which represents the given config class */ ConfigDescriptor> getConfigDescriptor(Class> configClass); //TODO re-visit name (depends on other discussions) /** - * Resolves all descriptors for folders + * Resolves all descriptors for folders. * - * @return all descriptors for the known view-configs + * @return all descriptors for the known folder-configs */ List > getConfigDescriptors(); /** - * Resolves the {@link ViewConfigDescriptor} for the given view-id + * Resolves the {@link ViewConfigDescriptor} for the given view-id. * * @param viewId view-id of the page - * @return view-config-descriptor which represents the given view-id, null otherwise + * + * @return view-config descriptor which represents the given view-id, null otherwise */ ViewConfigDescriptor getViewConfigDescriptor(String viewId); /** - * Resolves the {@link ViewConfigDescriptor} for the given view-config-class + * Resolves the {@link ViewConfigDescriptor} for the given view-config class. + * + * @param viewDefinitionClass view-config class of the page * - * @param viewDefinitionClass view-config-class of the page - * @return view-config-descriptor which represents the given view-config-class + * @return view-config descriptor which represents the given view-config class */ ViewConfigDescriptor getViewConfigDescriptor(Class extends ViewConfig> viewDefinitionClass); /** - * Resolves all descriptors for the known {@link ViewConfig}s + * Resolves all descriptors for the known {@link ViewConfig}s. * * @return all descriptors for the known view-configs */ List getViewConfigDescriptors(); /** - * Resolves the descriptor for the default-error page + * Resolves the descriptor for the default error page. * - * @return descriptor for the default-error page + * @return descriptor for the default error page */ ViewConfigDescriptor getDefaultErrorViewConfigDescriptor(); } http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewMetaData.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewMetaData.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewMetaData.java index 095d5f8..a1f16c9 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewMetaData.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewMetaData.java @@ -28,9 +28,11 @@ import static java.lang.annotation.ElementType.ANNOTATION_TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * This meta-annotation allows to create custom meta-data which can be used for view-configs. - * Per default meta-data of a lower level overrides meta-data on a higher level which has the same type. - * Can be customized via annotating the final annotation as a whole via @Aggregated(true) or only special fields of it. + * Meta-annotation for custom metadata which can be applied to view-configs. + * + * By default, metadata of a lower level overrides metadata of the same type from a higher level (cascading behaviour). + * This behaviour can be changed by annotating the target annotation (or only chosen fields of it) with + * {@code @Aggregated(true)}. */ @Target({ ANNOTATION_TYPE }) @Retention(RUNTIME) http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameter.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameter.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameter.java index 9b84ddf..fdecffc 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameter.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameter.java @@ -32,8 +32,9 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * This annotation can be used as interceptor for JSF action methods as an alternative for - * {@link org.apache.deltaspike.core.api.config.view.navigation.NavigationParameterContext}. + * Used on JSF action methods, this adds navigation parameters (key-value pairs) to the resulting navigation string. + * Alternatively, {@link org.apache.deltaspike.core.api.config.view.navigation.NavigationParameterContext} can be used + * to add the parameters. */ @Target({ METHOD, TYPE }) @Retention(RUNTIME) @@ -45,14 +46,14 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; public @interface NavigationParameter { /** - * Key of the parameter + * Key of the parameter. * * @return name of the key */ @Nonbinding String key(); /** - * Value or EL-Expression of the parameter + * Value of the parameter, a plain String or an EL expression. * * @return ref or expression */ @@ -64,7 +65,7 @@ public @interface NavigationParameter //TODO add special support for list-annotations (add value automatically) /** - * Allows to specify multiple parameters (@see ViewParameter) + * A container for multiple NavigationParameters. */ @ViewMetaData @Aggregated(true) @@ -72,7 +73,7 @@ public @interface NavigationParameter public static @interface List { /** - * 1-n parameters + * One or more navigation parameters. * * @return parameters */ http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameterContext.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameterContext.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameterContext.java index 207ad02..5efa3d0 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameterContext.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameterContext.java @@ -22,7 +22,7 @@ import java.io.Serializable; import java.util.Map; /** - * Can be used to add parameters dynamically to the final navigation string + * Can be used to add parameters dynamically to the final navigation string. */ public interface NavigationParameterContext extends Serializable { http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/ViewNavigationHandler.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/ViewNavigationHandler.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/ViewNavigationHandler.java index 80b8fd3..4c60eda 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/ViewNavigationHandler.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/ViewNavigationHandler.java @@ -21,14 +21,14 @@ package org.apache.deltaspike.core.api.config.view.navigation; import org.apache.deltaspike.core.api.config.view.ViewConfig; /** - * Allows to trigger manual navigation via the type-safe {@link ViewConfig} approach. + * A type-safe {@link ViewConfig}-based NavigationHandler wrapper. */ public interface ViewNavigationHandler { /** * Triggers navigation to the given view. * - * @param targetView the view which is the navigation target + * @param targetView the navigation target */ void navigateTo(Class extends ViewConfig> targetView); } http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/event/PreViewConfigNavigateEvent.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/event/PreViewConfigNavigateEvent.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/event/PreViewConfigNavigateEvent.java index 110cf61..c98af03 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/event/PreViewConfigNavigateEvent.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/event/PreViewConfigNavigateEvent.java @@ -21,8 +21,8 @@ package org.apache.deltaspike.core.api.config.view.navigation.event; import org.apache.deltaspike.core.api.config.view.ViewConfig; /** - * Event will be fired before the navigation (from and to a view-config based page) occurs. - * With {@link #navigateTo(Class)} it's possible to change the navigation target. + * This event is fired before a navigation from/to a view-config-based page occurs. With {@link #navigateTo(Class)} it's + * possible to change the navigation target. */ public class PreViewConfigNavigateEvent { @@ -30,7 +30,7 @@ public class PreViewConfigNavigateEvent private Class extends ViewConfig> toView; /** - * Constructor for creating the event for the given source and target view + * Constructor for creating the event for the given source and target view. * * @param fromView source-view * @param toView target-view @@ -62,7 +62,7 @@ public class PreViewConfigNavigateEvent } /** - * Allows to change the navigation target. + * Changes the navigation target. * * @param toView new navigation target */ http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/BeforeHandles.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/BeforeHandles.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/BeforeHandles.java index 8e7078a..707d457 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/BeforeHandles.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/BeforeHandles.java @@ -27,10 +27,15 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Marker annotation for a method to be considered an Exception Handler, handles the exception in the BEFORE - * traversal of the exception chain. Handlers are typically in the form of - * public void ... (@BeforeHandles ... CaughtException<...> ...)
methods. - * If a method has a return type, it is ignored. + * Marker annotation for a method to be considered an Exception Handler, handles the exception in the BEFORE traversal + * of the exception chain. + *+ * Handlers methods typically have this form:
+ *public void handle(@BeforeHandles @OptionalQualifier ExceptionEvent<TypeOfTheException> evt) + *. + * + * + * If a handler method has a return type, it is ignored. */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.PARAMETER) @@ -38,7 +43,8 @@ import java.lang.annotation.Target; public @interface BeforeHandles { /** - * Precedence relative to callbacks for the same type + * Precedence relative to callbacks for the same type. Handler with a higher ordinal is invoked before a handler + * with a lower ordinal. */ int ordinal() default 0; } http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandler.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandler.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandler.java index d706909..83a3e2f 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandler.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandler.java @@ -27,6 +27,9 @@ import java.lang.annotation.Target; /** * Marker for types containing Exception Handler methods. + * + * @see BeforeHandles + * @see Handles */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.TYPE) http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandlingFlow.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandlingFlow.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandlingFlow.java index e454e86..eef759d 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandlingFlow.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandlingFlow.java @@ -20,7 +20,7 @@ package org.apache.deltaspike.core.api.exception.control; /** - * Flow control enum. Used in the dispatcher to determine how to markHandled. + * Enum of exception handling states. Used in the dispatcher to determine how to markHandled. */ public enum ExceptionHandlingFlow { http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/HandlerMethod.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/HandlerMethod.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/HandlerMethod.java index d875b05..22d7c14 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/HandlerMethod.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/HandlerMethod.java @@ -27,7 +27,7 @@ import java.lang.reflect.Type; import java.util.Set; /** - * Meta data interface about an exception handler. It is the responsibility of the + * Metadata interface for an exception handler method. It is the responsibility of the * implementation to support {@link javax.enterprise.inject.spi.InjectionPoint}s and to * validate those {@link javax.enterprise.inject.spi.InjectionPoint}s. * @@ -59,7 +59,8 @@ public interface HandlerMethodvoid notify(ExceptionEvent event, BeanManager beanManager) throws Exception; /** - * Obtains the precedence of the handler, relative to other handlers for the same type. + * Obtains the precedence of the handler, relative to other handlers for the same type. Handler with a higher + * ordinal is invoked before a handler with a lower ordinal. */ int getOrdinal(); http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/Handles.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/Handles.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/Handles.java index 8d86160..d915bfc 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/Handles.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/Handles.java @@ -26,9 +26,15 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Marker annotation for a method to be considered an Exception Handler. Handlers are typically in the form of - * public void ... (@Handles ... CaughtException<...> ...)
methods. If a method has a return type, it is - * ignored. + * Marker annotation for a method to be considered an Exception Handler. + * + *+ * Handlers typically have this form: + *
+ * public void handle(@Handles @OptionalQualifier ExceptionEvent<TypeOfTheException> evt)+ * + * + * If a handler method has a return type, it is ignored. */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.PARAMETER) @@ -36,7 +42,8 @@ import java.lang.annotation.Target; public @interface Handles { /** - * Precedence relative to handlers for the same type + * Precedence relative to handlers for the same type. Handler with a higher ordinal is invoked before a handler with + * a lower ordinal. */ int ordinal() default 0; //TODO discuss Precedence } http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionEvent.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionEvent.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionEvent.java index c4a2402..42a6b60 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionEvent.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionEvent.java @@ -20,8 +20,8 @@ package org.apache.deltaspike.core.api.exception.control.event; /** - * Payload for an exception to be handled. Implementations of this interface should not expose internals and remain - * immutable for this contract. + * Payload for an exception to be handled. Implementations of this interface should not expose internals and should + * remain immutable. * * @paramException type this event represents */ http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionToCatchEvent.java ---------------------------------------------------------------------- diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionToCatchEvent.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionToCatchEvent.java index c134645..18b8fe6 100644 --- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionToCatchEvent.java +++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionToCatchEvent.java @@ -27,7 +27,7 @@ import java.util.HashSet; import java.util.Set; /** - * Entry point event into the Catch system. This object is nearly immutable, the only mutable portion + * Entry point event into the Exception Control system. This object is nearly immutable, the only mutable portion * is the handled flag. */ @SuppressWarnings("CdiManagedBeanInconsistencyInspection") @@ -84,9 +84,10 @@ public class ExceptionToCatchEvent implements Serializable } /** - * Test to see if the exception has been handled via Solder Catch. + * Test to see if the exception has already been processed by an + * {@link org.apache.deltaspike.core.api.exception.control.ExceptionHandler}. * - * @return test if the exception has been through Solder Catch handling. + * @return true if the exception has already been processed by a handler; false otherwise */ public boolean isHandled() {