svn commit: r709580 - /tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/symbols.apt

[hl...@apache.org]

Author: hlship
Date: Fri Oct 31 14:53:50 2008
New Revision: 709580

URL: http://svn.apache.org/viewvc?rev=709580&view=rev
Log:
TAP5-188: Document the need to use @Inject with @Value or @Symbol when the parameter/field type is String (to avoid injecting the service id)

Modified:
    tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/symbols.apt

Modified: tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/symbols.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/symbols.apt?rev=709580&r1=709579&r2=709580&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/symbols.apt (original)
+++ tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/symbols.apt Fri Oct 31 14:53:50 2008
@@ -30,6 +30,43 @@
      
   Although not shown here, it is possible to use multple symbols inside the string, or mix literal text with
   symbols.
+
+Injecting Values from Symbols
+
+  You may also inject symbol values.  For example, if you are interested in whether the application
+  is in production mode or developer mode:
+
+---
+public class MyService implements MyServiceInterface
+{
+  private boolean productionMode;
+
+  public MyService(@Value("${tapestry.production-mode}") boolean productionMode, ...)
+  {
+    this.productionMode = productionMode;
+    . . .
+----
+
+  Here Tapestry has {{{coerce.apt}coerced}} the "tapestry.production-mode" symbol to a boolean to be injected.
+
+  An alternate annotation, @Symbol, may be used:
+
+---
+public class MyService implements MyServiceInterface
+{
+  private boolean productionMode;
+
+  public MyService(@Symbol(SymbolConstants.PRODUCTION_MODE) boolean productionMode, ...)
+  {
+    this.productionMode = productionMode;
+    . . .
+----
+
+  This is very useful when a constant value is defined for the symbol; it means that the compiler can catch
+  a typo, rather than detecting it a runtime.
+    
+  <<Note:>> When injecting a symbol as a <string> into a service, you must use the @Inject annotation as well as @Value or @Symbol; otherwise
+  Tapestry will inject the service's service id.
   
 Symbol Resolution
 
@@ -47,7 +84,7 @@
 
   The first provider allows JVM System Properties to provide symbol values.  This allows the use
   of the <<java>> command's <<-D>> option to provide runtime overrides.  This is most often used
-  when testing code, rather than in production.
+  when testing code, rather than in production.       SystemProperties is always checked first.
   
 * ApplicationDefaults
 
@@ -71,6 +108,8 @@
   Libraries will typically set reasonable defaults as contributions to the FactoryDefaults service configuration.
   Individual applications may hard code overrides of those defaults using ApplicationDefaults.  Individual developers
   may override even those defaults by setting JVM System Properties.
+
+  FactoryDefaults is always checked last when resolving symbol names to symbol values.
   
 Recursive Symbols