[CONF] Apache Tapestry IoC - configuration
IoC - configuration Page moved by Bob Harner From: Apache Tapestry Tapestry IoC Configuration To: Apache Tapestry Redirects Children moved Change Notification Preferences View Online
[CONF] Apache Tapestry IoC - configuration
IoC - configuration Page added by Bob Harner This page has moved to Tapestry IoC Configuration Change Notification Preferences View Online
[CONF] Apache Tapestry IoC - configuration
IoC - configuration
Page edited by Bob Harner
Comment:
Fixed syntax error in example; reordered intro paragraphs for clarity and flow; fixed "override" link
Changes (22)
h1. Tapestry IoC Configurations
One of the key concepts on Tapestry IoC is _distributed configuration_. This is a concept borrowed from the Eclipse Plugin API and evidenced in Apache HiveMind prior to Tapestry 5 IoC.
Tapestry services -- both those provided by Tapestry and those you write yourself -- are configured using Java, not XML.
So ... nice term, what does it mean?
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.
Distributed configuration is the key feature of Tapestry IoC that supports _extensibility_ and _modularity_.
Modules configure a service by _contributing_ to service configurations. This seems esoteric, but is quite handy, and is best explained by an example.
The distributed part refers to the fact that _any module_ may make _contributions_ to any services configuration.
Lets say youve written a bunch of different services, each of which does something specific for a particular type of file (identified by the files extension), and each implements the same interface, which well call FileServicer. And now lets 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|Defining Tapestry IOC Services#serviceBuilderMethod]:
This seems esoteric, but is quite handy, and is best explained by example. Say you are building a service that, say, maps a file extension to an interface called FileServicer. Theres a bunch of different services, all implementing the FileServicer interface, across many different modules, each doing something specific for a particular type of file (identified by the files extension). A central service uses this configuration to select a particular FileService interface:
{code:java} public static FileServiceDispatcher buildFileServicerDispatcher(MapString,FileServicer contributions)
...
In order to provide a value for the contribution parameter, Tapestry will _collect_ contributions from service contribution methods. It will ensure that the keys and values match the generic types shown (String for the key, FileServicer for the value). The map will be assembled and passed into the service builder method, and from there, into the FileServiceDispatcherImpl constructor.
So where do the values come from? Service Your service contributor methods, methods that whose names start with contribute:
{code:java}
...
} {code}
Like service builder and service decorator methods, we can inject services if we like:
Or, instead of instantiating those services ourselves, we could [inject|IoC - injection] them:
{code:java}
...
@InjectService(TextFileServicer) FileServicer textFileServicer,
@InjectService(PDFFileServicer) FileServicer pdfFileServicer,)
{ configuration.add(txt, textFileServicer);
...
* There is no longer a linkage between the contribution method name and the service id, which is much more refactoring safe: if you change the service interface name, or the id of the service, your method will still be invoked when using @Contribute.
* It makes it much easier for an [override|cookbook/override.html] [override|#overrides] of the service to get the configuration intended for the original service.
The following example is an annotation-based alternative for the contribution method above.
{code:java}
...
{code}
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.
{code:java}
...
There are three different styles of configurations (with matching contributions):
* Unordered Collection. *Unordered Collection* -- Contributions are simply added in and order is not important.
* Ordered List. *Ordered List* -- Contributions are provided as an ordered list. Contributions must establish the order by giving each contributed object a unique id, by
[CONF] Apache Tapestry IoC - configuration
IoC - configuration
Page edited by Bob Harner
Comment:
Fixed most broken links, some misspelllings
Changes (18)
...
} {code}
The *extensibility* comes from the fact that multiple modules may all contribute to the same service configuration:
{code:java}
...
Now the FileServicerDispatcher builder method gets a Map with at least four entries in it.
Because Tapestry IoC is highly dynamic (it scans the visible JAR manifest files to identify module classes), the FileServicerDispatcher service may be in one module, and the other contributing modules (such as the one that contributes the Office file services) may be written at a much later date. With no change to the FileServicerDispatcher service or its module class, the new services plug into the overall solution, simply by having their JARs on the runtime classpath.
h1. Naming conventions vs. Annotations
...
{since:since=5.2}{since}
If you prefer annotations over naming conventions you can use the [Contribute|#apidocsorgapachetapestry5iocannotationsContribute.html] @[Contribute|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Contribute.html] annotation. As of version 5.2 this annotation that may be placed on a contributor method of a module instead of starting the methods name with contribute. The value of the annotation is the type of the service to contribute into.
The primary reasons to use @Contribute and marker annotations is twofold:
...
{code}
In this example, the method will only be invoked when constructing a service configuration where the service itself has both the Red and Blue marker annotations. Tapestry knows which annotations are marker annotations, and which marker annotations apply to the service, via the [Marker|#apidocsorgapachetapestry5iocannotationsMarker.html] @[Marker|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Marker.html] annotation on the service implementation.
If the special [Local|#apidocsorgapachetapestry5iocannotationsLocal.html] @[Local|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Local.html] annotation is present, then contribution is made only to the configuration of a service being constructed in the same module.
It is not impossible that the same contribution method will be invoked to contribute to the configuration of multiple different services.
...
Here we dont even need a separate class for the implementation, we use a inner class for the implementation. The point is, the configuration is provided to the builder method, which passes it along to the implementation of the service.
On the contribution side, a service contribution method sees a [Configuration|#apidocsorgapachetapestry5iocConfiguration.html] [Configuration|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/Configuration.html] object:
{code:java}
...
}{code}
The Configuration interface defines just a single method: {{add()}}. This is very intentional: the only thing you can do is add new items. If we passed in a Collection, you might be tempted to check it for values, or remove them ... but that flys in the face of the fact that the order of execution of these service contribution methods is entirely unknown.
For readability (if Java any longer supports that concept), weve parameterized the configuration parameter of the method, constraining it to instances of java.lang.Runnable, so as to match the corresponding parameter. This is optional, but often very helpful. In any case, attempting to contribute an object that doesnt extend or implement the type (Runnable) will result in a runtime warning (and the value will be ignored).
...
Ordered lists are much more common. With an ordered list, the contributions are sorted into a proper order before being provided to the service builder method.
Again, the order in which service contribution methods are invoked is unknown. Therefore, the order in which objects are added to the configuration is not known. Instead, we enforce an order on the items _after_ all the contributions have been added. As with [service decorators|#decorator.html], decorators|IoC - decorator], we set the order by giving each contributed object a unique id, and identifying (by id) which items must preceded it in the list, and which must follow.
So, if we changed our Startup service to require a specific order for startup:
...
Notice that the service builder method is
[CONF] Apache Tapestry IoC - configuration
IoC - configuration
Page edited by Christophe Cordenier
Changes (2)
...
h1. Naming conventions vs. Annotations
{info:title=Since 5.2}{info}
{since:since=5.2}{since}
If you prefer annotations over naming conventions you can use the [Contribute|#apidocsorgapachetapestry5iocannotationsContribute.html] annotation. As of version 5.2 this annotation that may be placed on a contributor method of a module instead of starting the methods name with contribute. The value of the annotation is the type of the service to contribute into.
...
Full Content
Tapestry IoC Configurations
One of the key concepts on Tapestry IoC is distributed configuration. This is a concept borrowed from the Eclipse Plugin API and evidenced in Apache HiveMind prior to Tapestry 5 IoC.
So ... nice term, what does it mean?
Distributed configuration is the key feature of Tapestry IoC that supports extensibility and modularity.
The distributed part refers to the fact that any module may make contributions to any service's configuration.
This seems esoteric, but is quite handy, and is best explained by example.
Say you are building a service that, say, maps a file extension to an interface called FileServicer. There's a bunch of different services, all implementing the FileServicer interface, across many different modules, each doing something specific for a particular type of file (identified by the file's extension).
A central service uses this configuration to select a particular FileService interface:
public static FileServiceDispatcher buildFileServicerDispatcher(MapString,FileServicer contributions)
{
return new FileServiceDispatcherImpl(contributions);
}
In order to provide a value for the contribution parameter, Tapestry will collect contributions from service contribution methods. It will ensure that the keys and values match the generic types shown (String for the key, FileServicer for the value). The map will be assembled and passed into the service builder method, and from there, into the FileServiceDispatcherImpl constructor.
So where do the values come from? Service contributor methods, methods that start with "contribute":
public static void contributeFileServicerDispatcher(MappedConfigurationString,FileServicer configuration)
{
configuration.add("txt", new TextFileServicer());
configuration.add("pdf", new PDFFileServicer());
}
Like service builder and service decorator methods, we can inject services if we like:
public static void contributeFileServicerDispatcher(MappedConfigurationString,FileServicer configuration,
@InjectService("TextFileServicer") FileServicer textFileServicer,
@InjectService("PDFFileServicer") FileServicer pdfFileServicer,
{
configuration.add("txt", textFileServicer);
configuration.add("pdf", pdfFileServicer);
}
The extensibility comes from the fact multiple modules may all contribute to the same service configuration:
public static void contributeFileServicerDispatcher(MappedConfigurationString,FileServicer configuration)
{
configuration.add("doc", new WordFileServicer());
configuration.add("ppt", new PowerPointFileServicer());
}
Now the FileServicerDispatcher builder method gets a Map with at least four entries in it.
Because Tapestry IoC is highly dynamic (it scans the visible JAR manifest files to identify module classes), the FileServicerDispatcher service may be in one module, and the other contributing modules (such as the one that contributes the Office file services) may be written at a much later date. With no change to the FileServicerDispatcher service or its module class, the new services "plug into" the overall solution, simply by having their JAR's on runtime classpath.
Naming conventions vs. Annotations
Added in 5.2
If you prefer annotations over naming conventions you can use the Contribute annotation. As of version 5.2 this annotation that may be placed on a contributor method of a module instead of starting the methods name with "contribute". The value of the annotation is the type of the service to contribute into.
The primary reasons to use @Contribute and marker annotations is twofold:
There is no longer a linkage between the contribution method name and the service id, which is much more refactoring safe: if you change the service interface name, or the id of the service, your method will still be invoked when using @Contribute.
It makes it much easier for an override|cookbook/override.html of the service to get the configuration intended for the original service.
The following example is an alternative for the contribution method above.
@Contribute(FileServiceDispatcher.class)
public static void
[CONF] Apache Tapestry IoC - configuration
IoC - configuration
Page edited by Christophe Cordenier
Changes (1)
...
h1. Naming conventions vs. Annotations
{info:title=Since 5.2}{info}
If you prefer annotations over naming conventions you can use the [Contribute|#apidocsorgapachetapestry5iocannotationsContribute.html] annotation. As of version 5.2 this annotation that may be placed on a contributor method of a module instead of starting the methods name with contribute. The value of the annotation is the type of the service to contribute into.
...
Full Content
Tapestry IoC Configurations
One of the key concepts on Tapestry IoC is distributed configuration. This is a concept borrowed from the Eclipse Plugin API and evidenced in Apache HiveMind prior to Tapestry 5 IoC.
So ... nice term, what does it mean?
Distributed configuration is the key feature of Tapestry IoC that supports extensibility and modularity.
The distributed part refers to the fact that any module may make contributions to any service's configuration.
This seems esoteric, but is quite handy, and is best explained by example.
Say you are building a service that, say, maps a file extension to an interface called FileServicer. There's a bunch of different services, all implementing the FileServicer interface, across many different modules, each doing something specific for a particular type of file (identified by the file's extension).
A central service uses this configuration to select a particular FileService interface:
public static FileServiceDispatcher buildFileServicerDispatcher(MapString,FileServicer contributions)
{
return new FileServiceDispatcherImpl(contributions);
}
In order to provide a value for the contribution parameter, Tapestry will collect contributions from service contribution methods. It will ensure that the keys and values match the generic types shown (String for the key, FileServicer for the value). The map will be assembled and passed into the service builder method, and from there, into the FileServiceDispatcherImpl constructor.
So where do the values come from? Service contributor methods, methods that start with "contribute":
public static void contributeFileServicerDispatcher(MappedConfigurationString,FileServicer configuration)
{
configuration.add("txt", new TextFileServicer());
configuration.add("pdf", new PDFFileServicer());
}
Like service builder and service decorator methods, we can inject services if we like:
public static void contributeFileServicerDispatcher(MappedConfigurationString,FileServicer configuration,
@InjectService("TextFileServicer") FileServicer textFileServicer,
@InjectService("PDFFileServicer") FileServicer pdfFileServicer,
{
configuration.add("txt", textFileServicer);
configuration.add("pdf", pdfFileServicer);
}
The extensibility comes from the fact multiple modules may all contribute to the same service configuration:
public static void contributeFileServicerDispatcher(MappedConfigurationString,FileServicer configuration)
{
configuration.add("doc", new WordFileServicer());
configuration.add("ppt", new PowerPointFileServicer());
}
Now the FileServicerDispatcher builder method gets a Map with at least four entries in it.
Because Tapestry IoC is highly dynamic (it scans the visible JAR manifest files to identify module classes), the FileServicerDispatcher service may be in one module, and the other contributing modules (such as the one that contributes the Office file services) may be written at a much later date. With no change to the FileServicerDispatcher service or its module class, the new services "plug into" the overall solution, simply by having their JAR's on runtime classpath.
Naming conventions vs. Annotations
Since 5.2
If you prefer annotations over naming conventions you can use the Contribute annotation. As of version 5.2 this annotation that may be placed on a contributor method of a module instead of starting the methods name with "contribute". The value of the annotation is the type of the service to contribute into.
The primary reasons to use @Contribute and marker annotations is twofold:
There is no longer a linkage between the contribution method name and the service id, which is much more refactoring safe: if you change the service interface name, or the id of the service, your method will still be invoked when using @Contribute.
It makes it much easier for an override|cookbook/override.html of the service to get the configuration intended for the original service.
The following example is an alternative for the contribution method above.
@Contribute(FileServiceDispatcher.class)
public static void
[CONF] Apache Tapestry IoC - configuration
IoC - configuration Page moved by Ulrich Stärk From: Apache Tapestry To: Apache Tapestry IoC Children moved Change Notification Preferences View Online
