Scrollbar |
---|
Symbols are named configuration settings for
Symbols
Tapestry IOC makes use of runtime-evaluated symbols to handle certains types of configuration tasks.-based services. Tapestry provides mechanisms for easy access to symbols from within such services.
Div | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
|
Syntax
The syntax of symbols is based on Ant expressions. That is, the name is surrounded by ${ and } characters:
Code Block |
---|
${some.symbol.name}
|
expression, that is, a leading $
{ before the symbol name, and a trailing }
after. The value on the inside is the symbol name. By convention, the symbol name is segmented with periods (for example, "tapestry.production-mode").
Built-in Symbols
The Configuration page lists most of the symbol names used by Tapestry's built-in services.
Using Symbols in your Services
Symbols These symbols are used inside the @Value and @InjectService annotations.
For example:
Code Block | ||||
---|---|---|---|---|
| ||||
public static MyService build(
@InjectService("${some-service-id}") Collaborator collab)
{
return . . . ;
} |
Here, the symbol name, some-service-id
is a service id, such as WackyCollaborator
.
Although not shown here, it is possible to use multple multiple 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:
Code Block | ||||
---|---|---|---|---|
| ||||
public class MyService implements MyServiceInterface { private boolean productionMode; public MyService(@Value("${tapestry.production-mode}") boolean productionMode, ...) { this.if (productionMode) = productionMode; { . . . |
Here Tapestry has coerced the "tapestry.production-mode" symbol to a boolean to be injected.
An alternate annotation, @SymbolAs an alternative, the @Symbol annotation, may be used:
Code Block | ||||
---|---|---|---|---|
| ||||
public class MyService implements MyServiceInterface { private boolean productionMode; public MyService(@Symbol(SymbolConstants.PRODUCTION_MODE) boolean productionMode, ...) { this.if (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.
Symbols in Component Classes and Templates
It's easy to use a symbol in a component class:
Code Block | ||
---|---|---|
| ||
@Inject
@Symbol(SymbolConstants.PRODUCTION_MODE)
private boolean productionMode;
. . .
void setupRender() {
if (productionMode) {
. . .
}
} |
You can even use them directly in a component template, using the "symbol" binding prefix:
Code Block | ||
---|---|---|
| ||
<t:if test="!symbol:tapestry.production-mode">
<p>WARNING: We're running in development mode (slower, and less secure)</p>
</t:if> |
Symbol Resolution
Symbols are resolved by the SymbolSource service. The SymbolSource service checks against an ordered list of SymbolProvider objects.
Additional You may employ additional symbol providers may be employed by contributing to the tapestry.ioc. SymbolSource service configuration, which is an ordered list of SymbolProviders.
By default, there are three providers:
SystemProperties Provider
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. SystemProperties is always checked first.
ApplicationDefaults Provider
Values not found as System Properties are searched for in the ApplicationDefaults. This service, ApplicationDefaults, may be configured using a mapped configuration to provide values.
From the previous example:
Code Block | ||||
---|---|---|---|---|
| ||||
public void contributeApplicationDefaults(MappedConfiguration<String, String> configuration)
{
configuration.add("some-service-id", "WackyCollaborator");
} |
FactoryDefaults Provider
The This is the same as ApplicationDefaults, but checked only if a value is not satisfied by SystemProperties or ApplicationDefaults.
...
FactoryDefaults is always checked last when resolving symbol names to symbol values.
Recursive Symbols
It is possible and valid to define one symbol in terms of one ore or more other symbols.
Code Block | ||||
---|---|---|---|---|
| ||||
public void contributeFactoryDefaults(MappedConfiguration<String, String> configuration)
{
configuration.add("report.url", "http://${report.host}:${report.port}/${report.path}");
configuration.add("report.host", "www.myreportsite.com");
configuration.add("report.port", "80");
configuration.add("report.path", "/report.cgi");
} |
The ordinary default for report.url
will be: http://www.myreportsite.com:80/report.cgi
.
However, this can be changed by making an overriding contribution to the ApplicationDefaults service configuration.
Tapestry checks that no symbol is directly or indirectly dependent on itself. For example, the following contribution is illegal:
Code Block | ||||
---|---|---|---|---|
| ||||
public void contributeApplicationDefaults(MappedConfiguration<String, String> configuration)
{
configuration.add("report.path", "${report.url}/report.cgi");
} |
When the report.url
is referenced, an exception will be thrown with the message: * Symbol 'report.path' is defined in terms of itself (report.path --> report.url --> report.path).*
Scrollbar |
---|