{scrollbar}

Tapestry IoC Configuration

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

Tapestry Configuration of Tapestry IOC services – both those provided by Tapestry and those you write yourself – are configured is done using Java, not XML.

One of the key concepts in Tapestry IoC is distributed configuration. The distributed part refers to the fact that any module may configure a service. Distributed configuration is the key feature of Tapestry IoC that supports extensibility and modularity.

...

Let's say you've written a bunch of different services, each of which does something specific for a particular type of file (identified by the file's extension), and each implements the same interface, which we'll call FileServicer. And now let's say you need a central service that selects the one of your FileServicer implementations based on a given file extension. You start by providing a service builder method:

  public static FileServiceDispatcher buildFileServicerDispatcher(Map<String,FileServicer> contributions)
  {
    return new FileServiceDispatcherImpl(contributions);
  } 

...

So where do the values come from? Your service contributor methods, methods whose names start with "contribute":

  public static void contributeFileServicerDispatcher(MappedConfiguration<String,FileServicer> configuration)
  {
    configuration.add("txt", new TextFileServicer());
    configuration.add("pdf", new PDFFileServicer());
  }  

Or, instead of instantiating those services ourselves, we could inject them:

  public static void contributeFileServicerDispatcher(MappedConfiguration<String,FileServicer> configuration,
  
    @InjectService("TextFileServicer") FileServicer textFileServicer,
    @InjectService("PDFFileServicer") FileServicer pdfFileServicer)
  {
    configuration.add("txt", textFileServicer);
    configuration.add("pdf", pdfFileServicer);
  }  

The extensibility comes from the fact that multiple modules may all contribute to the same service configuration:

  public static void contributeFileServicerDispatcher(MappedConfiguration<String,FileServicer> configuration)
  {
    configuration.add("doc", new WordFileServicer());
    configuration.add("ppt", new PowerPointFileServicer());
  }  

...

Naming conventions vs. Annotations

...

The following example is an annotation-based alternative for the contribution method above.

@Contribute(FileServiceDispatcher.class)
public static void arbitraryMethodName(MappedConfiguration<String,FileServicer> configuration)
{
    configuration.add("doc", new WordFileServicer());
    configuration.add("ppt", new PowerPointFileServicer());
}  

If you have several implementations of a service interface, you have to disambiguate the services. For this purpose the marker annotations should be placed on the contributor method.

@Contribute(FileServiceDispatcher.class)
@Red @Blue
public static void arbitraryMethodName(MappedConfiguration<String,FileServicer> configuration)
{
    configuration.add("doc", new WordFileServicer());
    configuration.add("ppt", new PowerPointFileServicer());
}

...

Note that it is possible for the same contribution method to be invoked to contribute to the configuration of multiple different services.

  @Contribute(FileServiceDispatcher.class)
  @Local
  public static void arbitraryMethodName(MappedConfiguration<String,FileServicer> configuration)
  {
    configuration.add("doc", new WordFileServicer());
    configuration.add("ppt", new PowerPointFileServicer());
  }  

...

For example, here's a kind of Startup service that needs some Runnable objects. It doesn't care what order the Runnable objects are executed in.

  public static Runnable buildStartup(final Collection<Runnable> configuration)
  {
    return new Runnable()
    {
      public void run()
      {
        for (Runnable contribution : configuration)
          contribution.run();
      }
    };
  }  

...

On the contribution side, a service contribution method sees a Configuration object:

  public static void contributeStartup(Configuration<Runnable> configuration)
  {
    configuration.add(new JMSStartup());
    configuration.add(new FileSystemStartup());
  }    

...

So, if we changed our Startup service to require a specific order for startup:

  public static Runnable buildStartup(final List<Runnable> configuration)
  {
    return new Runnable()
    {
      public void run()
      {
        for (Runnable contribution : configuration)
          contribution.run();
      }
    };
  }  

...

For our service contribution methods, we must provide a parameter of type OrderedConfiguration:

  public static void contributeStartup(OrderedConfiguration<Runnable> configuration)
  {
    configuration.add("JMS", new JMSStartup());
    configuration.add("FileSystem", new FileSystemStartup(), "after:CacheSetup");
  }    

...

Null values, once ordered, are edited out (the List passed to the service builder method does not include any nulls). Again, they are allowed as placeholders, for the actual contributed objects to organize themselves around.

Mapped Configurations

As discussed in the earlier examples, mapped configurations are also supported. The keys passed in must be unique. When conflicts occur, Tapestry will log warnings (identifying the source of the conflict, in terms of invoked methods), and ignore the conflicting value.

...

Configuration Overrides

...

In Tapestry 5.0, services that wanted to support this kind of override behavior had to implement it on an ad-hoc basis, such as ApplicationDefaults overriding FactoryDefaults. In many cases, that is still useful.

{scrollbar}