You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tapestry.apache.org by hl...@apache.org on 2007/03/11 01:39:29 UTC
svn commit: r516817 -
/tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/
Author: hlship
Date: Sat Mar 10 16:39:28 2007
New Revision: 516817
URL: http://svn.apache.org/viewvc?view=rev&rev=516817
Log:
TAPESTRY-1339: Update Tapestry IoC Documentation to remove references to private services and module ids.
Modified:
tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/case.apt
tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/coerce.apt
tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/command.apt
tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/configuration.apt
tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/decorator.apt
tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/index.apt
tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/module.apt
tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/order.apt
tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/pipeline.apt
tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/provider.apt
tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/service.apt
tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/strategy.apt
tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/symbols.apt
Modified: tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/case.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/case.apt?view=diff&rev=516817&r1=516816&r2=516817
==============================================================================
--- tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/case.apt (original)
+++ tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/case.apt Sat Mar 10 16:39:28 2007
@@ -18,7 +18,7 @@
[]
- Thus, <<<getService("foo.bar.Baz", Baz.class)>>> is preferred, but <<<getService("FOO.BAR.BAZ", Baz.class)>>> (or any variation thereof) will work just exactly as well. This also extends to other naming conventions,
+ Thus, <<<getService("fBaz", Baz.class)>>> is preferred, but <<<getService("BAZ", Baz.class)>>> (or any variation thereof) will work just exactly as well. This also extends to other naming conventions,
such as <<<contributeFoo>>> methods. It also applies to values inside annotations.
Just case is ignored --
Modified: tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/coerce.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/coerce.apt?view=diff&rev=516817&r1=516816&r2=516817
==============================================================================
--- tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/coerce.apt (original)
+++ tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/coerce.apt Sat Mar 10 16:39:28 2007
@@ -41,8 +41,7 @@
inform the TypeCoercer about this coercion.
+---+
- @Contribute("tapestry.ioc.TypeCoercer")
- public void contributeMoneyCoercion(Configuration<CoercionTuple> configuration)
+ public void contributeTypeCoercer(Configuration<CoercionTuple> configuration)
{
Coercion<BigDecimal, Money> coercion = new Coercion<BigDecimal, Money>()
{
Modified: tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/command.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/command.apt?view=diff&rev=516817&r1=516816&r2=516817
==============================================================================
--- tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/command.apt (original)
+++ tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/command.apt Sat Mar 10 16:39:28 2007
@@ -32,7 +32,7 @@
Because this pattern is used so often inside Tapestry, a built-in service exists
to create implementations of the pattern as needed. The
- {{{apidocs/org/apache/tapestry/ioc/services/ChainBuilder.html}tapestry.ioc.ChainBuilder}}
+ {{{apidocs/org/apache/tapestry/ioc/services/ChainBuilder.html}ChainBuilder}}
service takes care of all the work:
+----+
@@ -55,7 +55,7 @@
+----+
public static MyChainService buildMyChainService(List<MyChainService> commands,
- @InjectService("tapestry.ioc.ChainBuilder")
+ @InjectService("ChainBuilder")
ChainBuilder chainBuilder)
{
return chainBuilder.build(MyChainService.class, commands);
Modified: tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/configuration.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/configuration.apt?view=diff&rev=516817&r1=516816&r2=516817
==============================================================================
--- tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/configuration.apt (original)
+++ tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/configuration.apt Sat Mar 10 16:39:28 2007
@@ -53,7 +53,9 @@
+------+
@Contribute("FileServicerDispatcher")
public static void contributeFileServicers(MappedConfiguration<String,FileServicer> configuration,
+
@InjectService("TextFileServicer") FileServicer textFileServicer,
+
@InjectService("PDFFileServicer") FileServicer pdfFileServicer,
{
configuration.add("txt", textFileServicer);
@@ -61,13 +63,11 @@
}
+------+
- The <<extensibility>> comes from the fact that many different methods in all kinds
- of different module builder classes can make these contributions. So, another module
- might understand Microsoft Office formats:
+ The <<extensibility>> comes from the fact multiple modules may all contribute to the same
+ service configuration:
+------+
- @Contribute("some.module.FileServicerDispatcher")
- public static void contributeOfficeFileServicers(MappedConfiguration<String,FileServicer> configuration)
+ public static void contributeFileServicers(MappedConfiguration<String,FileServicer> configuration)
{
configuration.add("doc", new WordFileServicer());
configuration.add("ppt", new PowerPointFileServicer());
@@ -134,8 +134,7 @@
{{{apidocs/org/apache/tapestry/ioc/Configuration.html}Configuration}} object:
+------+
- @Contribute("some.module.Startup")
- public static void contributeStartups(Configuration<Runnable> configuration)
+ public static void contributeStartup(Configuration<Runnable> configuration)
{
configuration.add(new JMSStartup());
configuration.add(new FileSystemStartup());
@@ -194,21 +193,18 @@
{{{apidocs/org/apache/tapestry/ioc/OrderedConfiguration.html}OrderedConfiguration}}:
+------+
- @Contribute("some.module.Startup")
- public static void contributeStartups(OrderedConfiguration<Runnable> configuration)
+ public static void contributeStartup(OrderedConfiguration<Runnable> configuration)
{
configuration.add("JMS", new JMSStartup());
- configuration.add("FileSystem", new FileSystemStartup(), "after:*.CacheSetup");
+ configuration.add("FileSystem", new FileSystemStartup(), "after:CacheSetup");
}
+------+
- Often, you don't care about ordering, the first form of the add method is used then. The id value you
- provide will be prefixed with the contributing module's id. The ordering algorithm will find a spot for the
+ Often, you don't care about ordering, the first form of the add method is used then. The ordering algorithm will find a spot for the
object (here the JMSStartup instance) based on the constraints of other contributed objects.
For the "FileSystem" contribution, a constraint has been specified, indicating
- that FileSystem should be ordered after some other contribution named "CacheSetup"
- in an unspecified module (the "*" part). Any number of such
+ that FileSystem should be ordered after some other contribution named "CacheSetup". Any number of such
{{{order.html}ordering constraints}} may be specified (the add() method accepts
a variable number of arguments).
@@ -228,6 +224,11 @@
the conflict), and ignore the conflicting value.
The value may not be null.
+
+ <<TODO:>> It is planned that for mapped configurations where the key is String, a
+ {{{apidocs/org/apache/tapestry/ioc/util/CaseInsensitiveMap.html}CaseInsensitiveMap}}
+ will be used automatically, to help ensure that case insensitivity is automatic and pervasive. This has not yet been
+ implemented.
Injecting Resources
Modified: tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/decorator.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/decorator.apt?view=diff&rev=516817&r1=516816&r2=516817
==============================================================================
--- tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/decorator.apt (original)
+++ tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/decorator.apt Sat Mar 10 16:39:28 2007
@@ -57,10 +57,8 @@
+---------------------+
package org.example.myapp.services;
-import org.apache.tapestry.ioc.annotations.Id;
import org.apache.tapestry.ioc.services.LoggingDecorator;
-@Id("myapp")
public class MyAppModule
{
public static Indexer buildIndexer()
@@ -70,7 +68,8 @@
public static <T> T decorateIndexer(Class<T> serviceInterface, T delegate,
String serviceId, Log serviceLog,
- @InjectService("tapestry.ioc.LoggingDecorator")
+
+ @InjectService("LoggingDecorator")
LoggingDecorator decorator)
{
return decorator.build(serviceInterface, delegate, serviceId, serviceLog);
@@ -99,7 +98,7 @@
and an interceptor factory that generates logging interceptors.
The "heavy lifting" is provided by the factory, which will create a new interceptor
- that logs methods entry before delegating to the core service implementation. The interceptor
+ that logs method entry before delegating to the core service implementation. The interceptor
will also log method parameters, return values, and even log exceptions.
The return value of the method is the new interceptor. You may return null if your
@@ -112,14 +111,12 @@
+---------------------+
package org.example.myapp.services;
-import org.apache.tapestry.ioc.annotations.Id;
import org.apache.tapestry.ioc.services.LoggingDecorator;
-@Id("myapp")
public class MyAppModule
{
public static Indexer buildIndexer(Class serviceInterface, Log serviceLog,
- @InjectService("tapestry.ioc.LoggingDecorator")
+ @InjectService("LoggingDecorator")
LoggingInterceptorFactory decorator)
{
return decorator.build(serviceInterface, serviceLog, new IndexerImpl());
@@ -146,7 +143,7 @@
@Match("*")
public static <T> T decorateLogging(Class<T> serviceInterface, T delegate,
String serviceId, Log serviceLog,
- @InjectService("tapestry.ioc.LoggingDecorator")
+ @InjectService("LoggingDecorator")
LoggingDecorator decorator)
{
return decorator.build(serviceInterface, delegate, serviceId, serviceLog);
@@ -158,17 +155,21 @@
logging for your data access and business logic services, you might end up with
<<<@Match("Data*", "*Logic")>>> (based, of course, on how you name your services).
- For example, you might add <<<@Match("myapp.internal.*.*")>>> to match all services within
- any of your application's internal modules.
-
- Thus, <<<@Match("*.*")>>> is dangerous, because it will match every (public) service in every
+ As the precending example showed, a simple "glob" matching is supported, where a asterisk ('*')
+ may be used at the start or end of the match string to match any number of characters.
+ As elsewhere, matching is case insensitive.
+
+
+ Thus, <<<@Match("*")>>> is dangerous, because it will match every (public) service in every
module.
- <Note: It is not possible to decorate the services of the tapestry.ioc module.>
+ <Note: It is not possible to decorate the services of the TapestryIOCModule.>
<Note: Another idea will be other ways of matching services: base on inheritance of the
service interface and/or based on the presence of particular class annotations on the
- service interface.>
+ service interface. None of this has been implemented yet, and can readily be accompllished
+ inside the decorator method (which will return null if it decides the service doesn't
+ need decoration).>
Ordering of Decorators
@@ -185,10 +186,10 @@
+---------------------+
@Match("*")
- @Order("before:*.*")
+ @Order("before:*")
public static <T> T decorateLogging(Class<T> serviceInterface, T delegate,
String serviceId, Log serviceLog,
- @InjectService("tapestry.ioc.LoggingDecorator")
+ @InjectService("LoggingDecorator")
LoggingDecorator decorator)
{
return decorator.build(serviceInterface, delegate, serviceId, serviceLog);
@@ -196,14 +197,13 @@
+---------------------+
- "before:*.*" indicates that this decorator should come before any decorator in <any> module.
+ "before:*" indicates that this decorator should come before any decorator in <any> module.
- <<Note:>> the ordering of decorators is in terms of the <effect> desired. In the earlier
- example, the order of the effects is logging, then timing, then security, then transactions
- (then the core service implementation). Internally, the decorators are invoked
+ <<Note:>> the ordering of decorators is in terms of the <effect> desired.
+ Internally, the decorators are invoked
last to first (since each once receives the "next" interceptor as its delegate).
So the core service implementation is created (via a service builder method)
- and that is passed to the transaction decorator method. The interceptor created there
- is passed to the the security decorator, and so forth.
+ and that is passed to the last decorator method. The interceptor created there
+ is passed to the the next-to-last decorator method, and so forth.
Modified: tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/index.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/index.apt?view=diff&rev=516817&r1=516816&r2=516817
==============================================================================
--- tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/index.apt (original)
+++ tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/index.apt Sat Mar 10 16:39:28 2007
@@ -18,7 +18,7 @@
specifically for use as the IoC container for Tapestry 4. Tapestry 4 has met its goals for extensibility and configurability, largely
because of HiveMind's flexibility.
- Tapestry 5 extends on this, replacing HiveMind with a new container specifically build for Tapestry,
+ Tapestry 5 extends on this, replacing HiveMind with a new container specifically build for Tapestry 5,
designed for greater ease of use, expressiveness and performance. And it can be used seperately from the rest of Tapestry!
* Why Not Spring?
@@ -27,15 +27,10 @@
integrated {{{http://aspectj.org}AspectJ}} support, and a large number of libraries built on top of the container. Spring is an excellent
<application> container, but lacks a number of features necessary for a <framework> container:
- * Spring does not have the concept of a <namespace>. The names of beans are simple and unqualified, which could lead to naming conflicts.
-
* Spring beans can be wired together by name (or id), but it is not possible to introduce additional naming abstractions. Tapestry 4's
"infrastructure:" abstraction was the key to allowing easy spot overrides of internal Tapestry services without having to
duplicate the large web of interrelated services (nearly 200 in Tapestry 4.0).
-
- * Spring doesn't have a concept of <visibility>, whereby some service implementations are internal to a module (Spring doesn't
- have modules), which makes it easier to create service facades.
-
+
* Although Spring allows beans to be intercepted, it does so in the form of a new bean, leaving the un-intercepted bean visible
(and subject to misuse). HiveMind and Tapestry IoC "wrap" the service inside interceptors, preventing unintercepted access
to the core service implementation.
@@ -148,17 +143,14 @@
only be a single service per service interface, but in some situations, there may be many different services and service implementations
all sharing the same service interface.
- Services have a visibility: either public (the default) or private (only visible within the same module).
- Services are identified by a unique id, which combines an unqualified id for the service with the containing module's id (see below).
- Typically, a service id matches the name of the service interface.
+ Services are identified by a unique id. Typically, a service id matches the unqualified name of the service interface, but
+ this is simply a convention.
Services are aggregated into <<modules>>:
-
- * A module defines a <<module id>> that is used as a prefix when naming services within the module. This is very much equivalent
- to a Java package name. Module ids must be unique within the registry of modules.
-
- * A module is defined by a <<module builder>>, a specific class containing static or instance methods.
+
+ * A module is defined by a <<module builder>>, a specific class containing a mix of static or instance methods, used to define
+ services, decorate them (see below), or contribute to service configurations (again, more below).
* Methods of the module builder class define the services provided by the module,
and the same methods are responsible
@@ -169,7 +161,8 @@
The methods which define and construct services are called <<service builder methods>>.
The <<registry>> is the outside world's view of the modules and services. From the registry, it is possible to obtain
- a service, via its qualified id or by its service interface.
+ a service, via its unique id or by its service interface. Access by unique id is <caseless> (meaning, a match will be found
+ even the case of the search key doesn't match the case of the service itself).
Services may be <<decorated>> by <<service decorator methods>>. These methods create
@@ -187,10 +180,11 @@
to linked pairs of similarily named services and configurations. For Tapestry IoC, each service is allowed to have a single configuration,
which is normally sufficient.>
- Services are typically instantiated as needed. In this case, "need" translates to "when a method of the service is invoked".
- In nearly all cases, a service is represented (to the outside world, or to other services) as a <<proxy>> that implements
- the service interface. The first time a method is invoked on the proxy, the full service (implementation and interceptors) is
- constructed. This occurs in a completely <<thread-safe>> manner.
+ Services are instantiated as needed. In this case, "need" translates to "when a method of the service is invoked".
+ A service is represented (to the outside world, or to other services) as a <<proxy>> that implements
+ the service interface. The first time a method is invoked on the proxy, the full service (consisting of the core service implementation wrapped with any interceptors) is
+ constructed. This occurs in a completely <<thread-safe>> manner. Just-in-time instantiation allows for more complex, more finely grained networks of services, and improves
+ startup time.
Services define a <<lifecycle>> that controls when the service is constructed. The default lifecycle is <<singleton>>, meaning a single
global instance created as needed. Other lifecycles allow service implementations to be bound to the current thread (i.e., the current
Modified: tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/module.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/module.apt?view=diff&rev=516817&r1=516816&r2=516817
==============================================================================
--- tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/module.apt (original)
+++ tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/module.apt Sat Mar 10 16:39:28 2007
@@ -25,51 +25,25 @@
}
+-----------------------------------------------------------------------------------+
- By default, a module's id is the same as its package name (we'll see how to override
- that shortly). Here the module id will be org.example.myapp.services.
-
Any public method (static or instance) whose name starts with "build" is a service builder method, implicitly
defining a service within the module. Here we're defining a service around
the Indexer service interface (presumably also in the org.example.myapp.services
package).
- The service's unqualified id (the part after the module id) is derived from the method name.
- Here "build" was stripped off of "buildIndexer", leaving "Indexer". That's the unqualified id.
- Prefixing with the module id results in the fully qualfied id
- org.example.myapp.services.Indexer.
+ The service's unique id is derived from the method name.
+ Here "build" was stripped off of "buildIndexer", leaving "Indexer". This id is how
+ other services will refer to the Indexer service. Tapestry IoC is case insensitive; later we can
+ refer to this service as "indexer" or "INDEXER" or any variation thereof, and connect to
+ this service.
+
+ Service ids must be unique; if another module contributes a service with the id "Indexer"
+ (or any case variation thereof) a runtime exception will occur when the Registry is created.
We could extend this example by adding additional service builder methods, or by showing
how to inject dependencies. See {{{service.html#Injecting Dependencies}the service documentation}}
for more details.
-
-Overriding the Module id
-
- Adding an {{{apidocs/org/apache/tapestry/ioc/annotations/Id.html}@Id annnotation}}
- to the module builder class will control the module's id.
-
-+-----------------------------------------------------------------------------------+
-package org.example.myapp.services;
-
-import org.apache.tapestry.ioc.annotations.Id;
-
-@Id("myapp")
-public class MyAppModule
-{
- public static Indexer buildIndexer()
- {
- return new IndexerImpl();
- }
-}
-+-----------------------------------------------------------------------------------+
-
- This time, the module's id is "myapp" and the service's id is "myapp.Indexer".
-
- Remember that module ids must be unique, no other module builder class, even one
- in a different package, may declare the id "myapp", or runtime warnings or
- errors will occur.
-
-{Caching Services}
+{Cacheing Services}
You will often find yourself in the position of injecting the same services
into your service builder or service decorator methods repeatedly. This can be quite
@@ -90,6 +64,7 @@
public MyModule(
@Inject("service:JobScheduler")
JobScheduler scheduler,
+
@Inject("service:FileSystem")
FileSystem fileSystem)
{
@@ -115,15 +90,21 @@
In addition to injecting dependencies with the @InjectService and @Inject annotations,
you may also inject a number of <module> resources:
-
- * java.lang.String: the module id
-
- * org.apache.commons.logging.Log: log for the module
+
+ * org.apache.commons.logging.Log: log for the module (derived from the module's class name)
* {{{apidocs/org/apache/tapestry/ioc/ServiceLocator.html}ServiceLocator}}: access to other services
[]
+ Note that the fields are final: this is important. Tapestry IoC is thread-safe and you largely
+ never have to think about concurrency issues. But in a busy application, different services may be
+ built by different threads simultaneously. Each module builder class is instantiated at most once, and
+ making these fields final ensures that the values are available across multiple threads.
+ Refer to Brian Goetz's {{{http://www.javaconcurrencyinpractice.com/}Java Concurrency in Practice}}
+ for a more complete explantation of the relationship between final fields, constructors, and threads ...
+ or just trust us!
+
Care should be taken with this approach: in some circustances, you may force a situtation in which
the module constructor is dependent on itself. For example, if you invoke a method on any injected services
defined within the same module from the module builder's constructor,
@@ -199,7 +180,6 @@
exactly as if they were identified in the manifest. For example:
+----+
-@Id("tapestry.internal.services")
@SubModule(
{ InternalTransformModule.class })
public final class InternalModule
Modified: tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/order.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/order.apt?view=diff&rev=516817&r1=516816&r2=516817
==============================================================================
--- tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/order.apt (original)
+++ tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/order.apt Sat Mar 10 16:39:28 2007
@@ -34,8 +34,6 @@
Often a single contribution will have more than one constraint.
Constraint Types
-
- Constraint types can be "before" or "after".
Each constraint string begins with a prefix, "before:" or "after:", used to
identify the type of constraint.
@@ -52,15 +50,7 @@
appear at the start, or end, or both of the pattern, and will match zero or more
characters there. Thus you can have patterns such as "Data*" or "*Logic" or even "*User*".
- Patterns that do not contain a period ('.') character are <simple> patterns; simple patterns
- only match within their own module. When a period does exist, it is the seperator between
- the module id pattern and the service id pattern. When there is more than one period, it is
- the <last> period that is the divider (which makes sense, as unqualified service ids
- can't contain a period).
-
- Because a pattern with a period in it is really <two> patterns, you can create patterns like
- "app.internal*.*Data". This matches services whose id ends with "Data" inside modules whose id
- starts with "app.internal".
+ Matching is case insensitive.
Modified: tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/pipeline.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/pipeline.apt?view=diff&rev=516817&r1=516816&r2=516817
==============================================================================
--- tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/pipeline.apt (original)
+++ tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/pipeline.apt Sat Mar 10 16:39:28 2007
@@ -59,7 +59,7 @@
+-----+
The
- {{{apidocs/org/apache/tapestry/ioc/services/PipelineBuilder.html}tapestry.ioc.PipelineBuilder}}
+ {{{apidocs/org/apache/tapestry/ioc/services/PipelineBuilder.html}PipelineBuilder}}
service is useful for constructing pipelines. The service is often injected
into a service builder method, along with an ordered configuration of services.
@@ -73,7 +73,7 @@
+-----+
public static StringTransformService buildStringTransform(
- @InjectService("tapestry.ioc.PipelineBuilder")
+ @InjectService("PipelineBuilder")
PipelineBuilder builder,
List<StringTransformFilter> configuration,
Log serviceLog)
Modified: tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/provider.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/provider.apt?view=diff&rev=516817&r1=516816&r2=516817
==============================================================================
--- tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/provider.apt (original)
+++ tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/provider.apt Sat Mar 10 16:39:28 2007
@@ -17,25 +17,24 @@
understands the expression.
In practice, @InjectService("Foo") and @Inject("service:Foo") work identically,
- even with regards to the relative visibility of
- private services. Here, the provider prefix is "service" and the expression
+ Here, the provider prefix is "service" and the expression
is "Foo".
* service provider
As outlined above, the service provider interprets the expression as
- a service id, either fully qualified or local.
+ a service id.
* infrastructure provider
The tapestry module (provided by the {{{http://tapestry.apache.org/tapestry5/tapestry-core/}tapestry-core library}}) provides the
- {{{http://tapestry.apache.org/tapestry5/tapestry-core/guide/infrastructure.html}infrastructure}} object provider, which exists
- to provide shorter names for injecting services and to support overrides.
+ {{{http://tapestry.apache.org/tapestry5/tapestry-core/guide/infrastructure.html}infrastructure}} object provider, which to allow
+ for various forms of overrides.
* default provider
If the string does not contain a prefix, then the value is treated as a literal string.
- It will be coerced to the proper type (such as int or long).
+ It will be {{{coerce.html}coerced}} to the proper type (such as int or long).
Defining New Providers
@@ -47,8 +46,7 @@
Example:
+-----+
- @Contribution("tapestry.ioc.MasterObjectProvider")
- public void contributeMyProvider(MappedConfiguration<String,ObjectProvider> configuration)
+ public void contributeMasterObjectProvider(MappedConfiguration<String,ObjectProvider> configuration)
{
configuration.add("myprefix", new MyObjectProvider());
}
Modified: tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/service.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/service.apt?view=diff&rev=516817&r1=516816&r2=516817
==============================================================================
--- tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/service.apt (original)
+++ tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/service.apt Sat Mar 10 16:39:28 2007
@@ -20,7 +20,6 @@
import org.apache.tapestry.ioc.annotations.Id;
-@Id("myapp")
public class MyAppModule
{
public static Indexer buildIndexer()
@@ -31,7 +30,7 @@
+-----------------------------------------------------------------------------------+
Here the service interface is Indexer (presumably inside the org.example.myapp.services package,
- since there isn't an import). Tapestry doesn't know about the IndexerImpl class (the
+ since there isn't an import). Tapestry IoC doesn't know about the IndexerImpl class (the
service implementation of the Indexer service), but it does know
about the buildIndexer() method.
@@ -43,7 +42,9 @@
+-----------------------------------------------------------------------------------+
public static Indexer buildIndexer(@InjectService("JobScheduler")
- JobScheduler scheduler, @InjectService("FileSystem")
+ JobScheduler scheduler,
+
+ @InjectService("FileSystem")
FileSystem fileSystem)
{
IndexerImpl indexer = new IndexerImpl(fileSystem);
@@ -55,9 +56,8 @@
+-----------------------------------------------------------------------------------+
Here we've annotated the parameters of the service builder method to identify what
- service to inject for that parameter. We used unqualified ids ... these are the names
- of other services within the <same module>: there will be a buildJobScheduler()
- and a buildFileSystem() service builder methods as well.
+ service to inject for that parameter. It doesn't matter in which module
+ these services are defined, and whether the service builder methods are static or instance.
Note that we don't invoke those service builder methods ... we just "advertise" that we need
the named services. Tapestry IoC will provide the necessary proxies and, when we start to
@@ -65,9 +65,6 @@
interceptors and its dependencies, are ready to go. Again, this is done in a
thread-safe manner.
- If we used fully qualified service ids, such as "org.examples.myapps.jobs.JobScheduler",
- then we can access services from some other module entirely.
-
If you find yourself injecting the same dependencies into multiple service builder
(or service decorator) methods, you can
{{{module.html#Caching Services}cache dependency injections}} in your module, by defining
@@ -97,17 +94,6 @@
}
+-----------------------------------------------------------------------------------+
-Defining Visibility
-
- Normally, a service can be referenced from any other module, simply by providing a
- fully qualified service id.
-
- In some cases, it is desirable to mark a service a private, in which case, it is only
- visible within the same module.
-
- The {{{apidocs/org/apache/tapestry/ioc/annotations/Private.html}@Private annotation}} can
- be attached to a service builder method to indicate that the service in question is private.
-
Defining Service Lifecycle
Each service has a <lifecycle> that controls when the service implementation is instantiated.
@@ -133,6 +119,12 @@
As the first method is invoked, the service builder method is invoked, then any service
decorations occur. This construction process occurs only once.
+ You should be aware when writing services that your code must be thread safe; any service
+ you define could be invoked simulataneously by multiple threads. This is rarely an issue
+ in practice, since most services take input, use local variables, and invoke methods on other services,
+ without making use of non-final instance variables. The few instance variables
+ in a service implementation are usually references to other Tapestry IoC services.
+
* perthread
The perthread service lifecycle exists primarily to help multi-threaded servlet applications,
@@ -189,7 +181,7 @@
In addition to injecting services, Tapestry will key off of the parameter type to allow
other things to be injected.
- * java.lang.String: fully qualified service id for the service being created
+ * java.lang.String: unique id for the service
* org.apache.commons.logging.Log: to which service logging can occur
@@ -207,8 +199,12 @@
Example:
+-----------------------------------------------------------------------------------+
- public static Indexer buildIndexer(String serviceId, Log serviceLog, @InjectService("JobScheduler")
- JobScheduler scheduler, @InjectService("FileSystem")
+ public static Indexer buildIndexer(String serviceId, Log serviceLog,
+
+ @InjectService("JobScheduler")
+ JobScheduler scheduler,
+
+ @InjectService("FileSystem")
FileSystem fileSystem)
{
IndexerImpl indexer = new IndexerImpl(serviceLog, fileSystem);
@@ -227,6 +223,9 @@
id of service dependencies is known at build time), it is easier
to use the @InjectService annotation.
+ The Log's name (used when configuring logging settings for the service) consists of
+ the module class name and the service id seperated by a period, i.e. "org.example.myapp.MyModule.Indexer".
+
Automatic Dependency Resolution
When injecting another service, you may choose to not provide the @InjectService annotation.
@@ -235,12 +234,12 @@
from the parameter type). If it finds exactly one match, then the corresponding service will be
injected.
- If it finds more than one match, that's an error.
+ If there are no matches, or multiple matches, then a runtime exception is thrown.
Obviously, this is only useful when you can be sure that there's only one service in the entire registry
that implements the service interface. When you are building a framework for others to use, you should
not use this feature ... it's all too likely that some end-user application will create a second service
- with the same implementation and break your injections.
+ with the same service interface and break your injections.
On the other hand, if you are using Tapestry IoC as part of an application, then you can save yourself
a small amount of effort and maintenance by letting Tapestry automatically identify dependencies.
@@ -269,18 +268,19 @@
in the
{{{apidocs/org/apache/tapestry/ioc/services/TapestryIOCModule.html}TapestryIOCModule}} class.
-*----------------------------------+-----------------------------------------------------------------------------------------+
-| <<Service Id>> | <<Service Interface>> |
-*----------------------------------+-----------------------------------------------------------------------------------------+
-| tapestry.ioc.ClassFactory | {{{apidocs/org/apache/tapestry/ioc/services/ClassFactory.html}ClassFactory}} |
-*----------------------------------+-----------------------------------------------------------------------------------------+
-| tapestry.ioc.LogSource | {{{apidocs/org/apache/tapestry/ioc/LogSource.html}LogSource}} |
-*----------------------------------+-----------------------------------------------------------------------------------------+
-| tapestry.ioc.RegistryShutdownHub | {{{apidocs/org/apache/tapestry/ioc/RegistryShutdownHub.html}RegistryShutdownHub}} |
-*----------------------------------+-----------------------------------------------------------------------------------------+
-| tapestry.ioc.ThreadCleanupHub | {{{apidocs/org/apache/tapestry/ioc/services/ThreadCleanupHub.html}ThreadCleanupHub}} |
-*----------------------------------+-----------------------------------------------------------------------------------------+
+*---------------------+-----------------------------------------------------------------------------------------+
+| <<Service Id>> | <<Service Interface>> |
+*---------------------+-----------------------------------------------------------------------------------------+
+| ClassFactory | {{{apidocs/org/apache/tapestry/ioc/services/ClassFactory.html}ClassFactory}} |
+*---------------------+-----------------------------------------------------------------------------------------+
+| LogSource | {{{apidocs/org/apache/tapestry/ioc/LogSource.html}LogSource}} |
+*---------------------+-----------------------------------------------------------------------------------------+
+| RegistryShutdownHub | {{{apidocs/org/apache/tapestry/ioc/RegistryShutdownHub.html}RegistryShutdownHub}} |
+*---------------------+-----------------------------------------------------------------------------------------+
+| ThreadCleanupHub | {{{apidocs/org/apache/tapestry/ioc/services/ThreadCleanupHub.html}ThreadCleanupHub}} |
+*---------------------+-----------------------------------------------------------------------------------------+
+ Consult the JavaDoc for each of these services to identify under what circumstances you'll need to use them.
Mutually Dependant Services
Modified: tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/strategy.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/strategy.apt?view=diff&rev=516817&r1=516816&r2=516817
==============================================================================
--- tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/strategy.apt (original)
+++ tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/strategy.apt Sat Mar 10 16:39:28 2007
@@ -17,7 +17,7 @@
As a special case, the value null is search for as if it was an instance of the class void.
- The {{{apidocs/org/apache/tapestry/ioc/services/StrategyBuilder.html}tapestry.ioc.StrategyBuilder}} service creates a service implementation around a strategy registry.
+ The {{{apidocs/org/apache/tapestry/ioc/services/StrategyBuilder.html}StrategyBuilder}} service creates a service implementation around a strategy registry.
+---+
public interface StrategyBuilder
@@ -43,7 +43,7 @@
+---+
public static MyStrategyService buildMyStrategyService(Map<Class, MyStrategyService> configuration,
- @InjectService("tapestry.ioc.StrategyBuilder")
+ @InjectService("StrategyBuilder")
StrategyBuilder builder)
{
StategyRegistry<MyStrategyService> registry = StrategyRegistry.newInstance(MyStrategyService.class, configuration);
Modified: tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/symbols.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/symbols.apt?view=diff&rev=516817&r1=516816&r2=516817
==============================================================================
--- tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/symbols.apt (original)
+++ tapestry/tapestry5/tapestry-ioc/branches/hlship-20070309-simplifyioc/src/site/apt/symbols.apt Sat Mar 10 16:39:28 2007
@@ -18,16 +18,16 @@
For example:
+----+
- public static MyService buildMyService(@Inject("${mymodule.some-reference}") CollaboratorA collabA,
- @InjectService("${mymodule.some-service-id}") CollaboratorB collabB)
+ public static MyService buildMyService(@Inject("${some-reference}") CollaboratorA collabA,
+ @InjectService("${some-service-id}") CollaboratorB collabB)
{
return . . . ;
}
+---+
- Here, the first symbol is <<<mymodule.some-reference>>> whose value should be an
+ Here, the first symbol is <<<some-reference>>> whose value should be an
{{{provider.html}object reference}} such as <<<service:CollaboratorA>>>. The second symbol,
- <<<mymodule.some-service-id>>> is just a service id, such as <<<CollaboratorB>>>.
+ <<<some-service-id>>> is just a service id, such as <<<CollaboratorB>>>.
Although not shown here, it is possible to use multple symbols inside the string, or mix literal text with
symbols.
@@ -58,8 +58,7 @@
From the previous example:
+----+
- @Contribute("tapestry.ioc.ApplicationDefaults")
- public void contributeDefaults(MappedConfiguration<String, String> configuration)
+ public void contributeApplicationDefaults(MappedConfiguration<String, String> configuration)
{
configuration.add("mymodule.some-reference", "service:CollaboratorA");
configuration.add("mymodule.some-service-id", "CollaboratorB");
@@ -81,8 +80,7 @@
+----+
- @Contribute("tapestry.ioc.FactoryDefaults")
- public void contributeDefaults(MappedConfiguration<String, String> configuration)
+ 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");
@@ -99,8 +97,7 @@
illegal:
+----+
- @Contribute("tapestry.ioc.ApplicationDefaults")
- public void contributeOverrides(MappedConfiguration<String, String> configuration)
+ public void contributeApplicationDefaults(MappedConfiguration<String, String> configuration)
{
configuration.add("report.path", "${report.url}/report.cgi");
}