Scrollbar |
---|
Symbols are named configuration settings for Tapestry IOC-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} |
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 Symbols page lists the symbol names used by Tapestry's built-in services.
...
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
.
...
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 { public MyService(@Value("${tapestry.production-mode}") boolean productionMode, ...) { if (productionMode) { . . . |
Here Tapestry has coerced the "tapestry.production-mode" symbol to a boolean to be injected.
As an alternative, the @Symbol annotation, may be used:
Code Block | ||||
---|---|---|---|---|
| ||||
public class MyService implements MyServiceInterface { public MyService(@Symbol(SymbolConstants.PRODUCTION_MODE) boolean productionMode, ...) { if (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.
...
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.
...
From the previous example:
Code Block | ||||
---|---|---|---|---|
| ||||
public void contributeApplicationDefaults(MappedConfiguration<String, String> configuration) { configuration.add("some-service-id", "WackyCollaborator"); } |
FactoryDefaults Provider
This is the same as ApplicationDefaults, but checked only if a value is not satisfied by SystemProperties or ApplicationDefaults.
...
It is possible and valid to define one symbol in terms of one 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
.
...
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 |
---|