Page History

{scrollbar}

{float:right|background=#eee}
{contentbylabel:title=Related Articles|showLabels=false|showSpace=false|space=@self|labels=configuration}
{float}

...

Symbols are named configuration settings for Tapestry IOC-based services. Tapestry provides mechanisms for easy access to symbols from within such services.

Syntax

The syntax of symbols is based on Ant expressions. That is, the name is surrounded by ${ and } characters:

${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 page lists most of the symbol names used by Tapestry's built-in services.

Using Symbols in your Services

...

For example:

  public static MyService build(
      @InjectService("${some-service-id}") Collaborator collab)
  {
    return . . . ;
  }

...

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
{
  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:

public class MyService implements MyServiceInterface
{
  public MyService(@Symbol(SymbolConstants.PRODUCTION_MODE) boolean productionMode, ...)
  {
    if (productionMode) {
      . . .

...

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:

  @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:

<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:

  public void contributeApplicationDefaults(MappedConfiguration<String, String> configuration)
  {
    configuration.add("some-service-id", "WackyCollaborator");
  }

...

It is possible and valid to define one symbol in terms of one or more other symbols.

  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:

  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).

...