Author: hlship
Date: Mon Oct 27 17:24:08 2008
New Revision: 708408
URL: http://svn.apache.org/viewvc?rev=708408&view=rev
Log:
TAP5-41: Create a guide to create component libraries and documenting components
Added:
tapestry/tapestry5/trunk/src/site/apt/cookbook/lib.apt
tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/autoload.apt
Modified:
tapestry/tapestry5/trunk/quickstart/src/main/resources/archetype-resources/pom.xml
tapestry/tapestry5/trunk/src/site/apt/jboss.apt
tapestry/tapestry5/trunk/src/site/apt/struts.apt
tapestry/tapestry5/trunk/src/site/apt/tomcat.apt
tapestry/tapestry5/trunk/src/site/apt/upgrade4.apt
tapestry/tapestry5/trunk/src/site/fml/faq/general.fml
tapestry/tapestry5/trunk/src/site/site.xml
tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/module.apt
tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/run.apt
tapestry/tapestry5/trunk/tapestry-ioc/src/site/site.xml
Modified:
tapestry/tapestry5/trunk/quickstart/src/main/resources/archetype-resources/pom.xml
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/quickstart/src/main/resources/archetype-resources/pom.xml?rev=708408&r1=708407&r2=708408&view=diff
==============================================================================
---
tapestry/tapestry5/trunk/quickstart/src/main/resources/archetype-resources/pom.xml
(original)
+++
tapestry/tapestry5/trunk/quickstart/src/main/resources/archetype-resources/pom.xml
Mon Oct 27 17:24:08 2008
@@ -1,4 +1,5 @@
-<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/maven-v4_0_0.xsd";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xmlns="http://maven.apache.org/POM/4.0.0";>
+<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/maven-v4_0_0.xsd";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xmlns="http://maven.apache.org/POM/4.0.0";>
<modelVersion>4.0.0</modelVersion>
<groupId>${groupId}</groupId>
<artifactId>${artifactId}</artifactId>
@@ -51,21 +52,6 @@
</requestLog>
</configuration>
</plugin>
-
-
- <!-- This changes the WAR file packaging so that what would
normally go into WEB-INF/classes
- is instead packaged as WEB-INF/lib/${artifactId}.jar. This is
necessary for Tapestry
- to be able to search for page and component classes at startup.
Only
- certain application servers require this configuration, please
see the documentation
- at the Tapestry 5 project page
(http://tapestry.apache.org/tapestry5/). -->
-
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-war-plugin</artifactId>
- <configuration>
- <archiveClasses>true</archiveClasses>
- </configuration>
- </plugin>
</plugins>
</build>
Added: tapestry/tapestry5/trunk/src/site/apt/cookbook/lib.apt
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/src/site/apt/cookbook/lib.apt?rev=708408&view=auto
==============================================================================
--- tapestry/tapestry5/trunk/src/site/apt/cookbook/lib.apt (added)
+++ tapestry/tapestry5/trunk/src/site/apt/cookbook/lib.apt Mon Oct 27 17:24:08
2008
@@ -0,0 +1,251 @@
+ ---
+ Creating Component Libraries
+ ---
+
+Creating Component Libraries
+
+
+ Nearly every Tapestry application includes a least a couple of custom
components, specific to the application.
+ What's exciting about Tapestry is how easy it is to package components for
reuse across many applications ...
+ and the fact that applications using a component library need no special
configuration.
+
+ A Tapestry component library consists of components (as well as component
base class, pages and mixins). In
+ addition, a component library will have a module that can define new
services (needed by the components)
+ or configure other services present in Tapestry. Finally, components can be
packaged with
+ <assets>: resources such as images, stylesheets and JavaScript libraries
that need to be provided to the
+ client web browser.
+
+ We're going to create a somewhat insipid component that displays a large
happy face icon.
+
+ Tapestry doesn't mandate that you use any build system, but we'll assume for
the moment that you are using
+ Maven 2. In that case, you'll have a pom.xml file something like the
following:
+
+
+---
+<project>
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>org.example</groupId>
+ <artifactId>happylib</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <packaging>jar</packaging>
+ <name>happylib Tapestry 5 Library</name>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.tapestry</groupId>
+ <artifactId>tapestry-core</artifactId>
+ <version>${tapestry-release-version}</version>
+ </dependency>
+
+ <dependency>
+ <groupId>org.testng</groupId>
+ <artifactId>testng</artifactId>
+ <version>5.1</version>
+ <classifier>jdk15</classifier>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <configuration>
+ <source>1.5</source>
+ <target>1.5</target>
+ <optimize>true</optimize>
+ </configuration>
+ </plugin>
+
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-jar-plugin</artifactId>
+ <configuration>
+ <archive>
+ <manifestEntries>
+
<Tapestry-Module-Classes>org.example.happylib.services.HappyModule</Tapestry-Module-Classes>
+ </manifestEntries>
+ </archive>
+ </configuration>
+ </plugin>
+
+ </plugins>
+ </build>
+
+ <repositories>
+ <repository>
+ <id>codehaus.snapshots</id>
+ <url>http://snapshots.repository.codehaus.org</url>
+ </repository>
+ <repository>
+ <id>OpenQA_Release</id>
+ <name>OpenQA Release Repository</name>
+ <url>http://archiva.openqa.org/repository/releases/</url>
+ </repository>
+ </repositories>
+
+ <properties>
+ <tapestry-release-version>5.0.16</tapestry-release-version>
+ </properties>
+</project>
+---
+
+ We'll go into more detail about the relevant portions of this POM in the
later sections.
+
+Step 1: Choose a base package name
+
+ Just as with Tapestry applications, Tapestry component libraries should have
a <unique> base package name.
+ In this example, we'll use <<<org.examples.happylib>>>.
+
+ As with an application, we'll follow the conventions: we'll place the
module for this library
+ inside the services package, and place pages and components under their
respective packages.
+
+Step 2: Create your pages and/or components
+
+ Our component is very simple:
+
+----
+package org.example.happylib.components;
+
+import org.apache.tapestry5.Asset;
+import org.apache.tapestry5.MarkupWriter;
+import org.apache.tapestry5.annotations.Path;
+import org.apache.tapestry5.ioc.annotations.Inject;
+
+public class HappyIcon
+{
+ @Inject
+ @Path("happy.jpg")
+ private Asset happyIcon;
+
+ boolean beginRender(MarkupWriter writer)
+ {
+ writer.element("img", "src", happyIcon);
+ writer.end();
+
+ return false;
+ }
+}
+----
+
+ HappyIcon appears inside the components sub-package. The happyIcon field is
injected with the the Asset
+ for the file happy.jpg. The path specified with the @Path annotation is
relative to the HappyIcon.class file;
+ it should be stored in the project under
src/main/resources/org/example/happylib/components.
+
+ Tapestry ensures that asset can be accessed from the web browser; the src
attribute of the \<img\> tag
+ will be a URL that directly accesses the image file ... there's no need to
unpackage the happy.jpg file, it's
+ all handled by Tapestry.
+
+ This component renders out an img tag for the icon.
+
+ Often, a component library will have many different components, or even
pages.
+
+Step 3: Choose a virtual folder name
+
+ In Tapestry, components that have been packaged in a library are referenced
using a virtual folder name.
+ It's effectively as if the application had a new root-level folder
containing the components.
+
+ In our example, we'll use "happy" as the folder name. That means the
application will include the
+ HappyIcon component in the template as:
+
+ * <<<\<t:happy.happyicon\>>>> or <<<\<t:happy.icon\>>>>
+
+ * <<<\<img t:type="happy.happyicon"\>>>> or <<<\<img
t:type="happy.icon"\>>>>
+
+ []
+
+ Why "icon" vs. "happyicon"? Tapestry notices that the folder name, "happy"
is a prefix or suffix of the
+ class name ("HappyIcon") and creates an alias that strips off the prefix (or
suffix). To Tapestry, they are
+ completely identical.
+
+Step 4: Configure the virtual folder
+
+ Tapestry needs to know to where to search for your component class. This is
accomplished in your library's IoC module class, by
+ making a <contribution> to the ComponentClassResolver
{{{../../tapestry-ioc/configuration.html}service configuration}}.
+
+----
+package org.example.happylib.services;
+
+import org.apache.tapestry5.ioc.Configuration;
+import org.apache.tapestry5.services.LibraryMapping;
+
+public class HappyModule
+{
+ public static void
contributeComponentClassResolver(Configuration<LibraryMapping> configuration)
+ {
+ configuration.add(new LibraryMapping("happy", "org.example.happylib"));
+ }
+}
+----
+
+ The ComponentClassResolver service is responsible for mapping libraries to
packages; it takes as a contribution
+ a collection of these LibraryMapping objects. Every module may make its own
contribution to the ComponentClassResolver service,
+ mapping its own package to its own folder.
+
+ This module class is also where you would define new services that can be
accessed by your components (or other parts
+ of the application).
+
+ <<Note:>> it is possible to add a mapping for "core". "core" is the core
library for Tapestry components; all the built-in
+ Tapestry components (TextField, BeanEditForm, Grid, etc.) are actually in the
core library. All Tapestry does is search inside
+ the "core" library when it does find a component in the application.
Contributing an additional package as "core" simply extends the number of
+ packages searched for core components (it doesn't replace Tapestry's default
package, org.apache.tapestry5.corelib).
+ Adding to "core" is sometimes reasonable, if there is virtually no chance of
a naming conflict (via different modules contributing
+ packages to core with conflicting class names).
+
+Step 5: Configure the module to autoload
+
+ For Tapestry to {{{../../tapestry-ioc/autoload.html}autoload}} your module,
it is necessary to put an entry in the
+ JAR manifest. This is taken care of in the pom.xml above:
+
+----
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-jar-plugin</artifactId>
+ <configuration>
+ <archive>
+ <manifestEntries>
+
<Tapestry-Module-Classes>org.example.happylib.services.HappyModule</Tapestry-Module-Classes>
+ </manifestEntries>
+ </archive>
+ </configuration>
+ </plugin>
+
+----
+
+Step 6: Versioning Assets
+
+ Classpath assets, those packaged in JAR files (such as the happy.jpg asset)
are retrieved by the client web browser
+ using a URL that reflects the package name. Tapestry users
a special virtual folder, <<</assets>>>, under
+ the context folder for this purpose.
+
+ The image file here would exposed to the web browser via the URL
<<</happyapp/assets/org/example/happylib/components/happy.jpg>>> (this assumes
that
+ the application was deployed as happyapp.war).
+
+ Tapestry uses a far-future expiration date for classpath assets; this allows
browsers to aggresively cache
+ the file, but this causes a problem should a later version of the library
change the file.
+
+ To handle this problem, you should map your library assets to a versioned
folder. This can be accomplished using
+ another contribution from the HappyModule, this time to the
ClasspathAssetAliasManager service
+ whose configuration maps a virtual folder under neath /assets
+ to a package:
+
+
+----
+ public static void
contributeClasspathAssetAliasManager(MappedConfiguration<String, String>
configuration)
+ {
+ configuration.add("happylib/1.0", "org/example/happylib");
+ }
+----
+
+ With this in place, and the library and applications rebuilt and redeployed,
the URL for happy.jpg becomes
+ <<</happyapp/assets/happylib/1.0/components/happy.jpg>>>. This is shorter,
but also incorporates a version number ("1.0")
+ that can be changed in a later release.
+
+Conclusion
+
+ That's it! Autoloading plus the virtual folders for components and for
assets takes care of all the issues related
+ to components. Just build your JARs, setup the JAR Manifest, and drop them
into your applications.
+
+
+
Modified: tapestry/tapestry5/trunk/src/site/apt/jboss.apt
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/src/site/apt/jboss.apt?rev=708408&r1=708407&r2=708408&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/src/site/apt/jboss.apt (original)
+++ tapestry/tapestry5/trunk/src/site/apt/jboss.apt Mon Oct 27 17:24:08 2008
@@ -5,7 +5,4 @@
Deployment Notes: JBoss
JBoss's default servlet container is {{{tomcat.html}Tomcat}}, so deployment
notes for Tomcat apply to JBoss as well.
-
-* Logging
-
- TODO: Discuss logging configuration for JBoss.
\ No newline at end of file
+
\ No newline at end of file
Modified: tapestry/tapestry5/trunk/src/site/apt/struts.apt
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/src/site/apt/struts.apt?rev=708408&r1=708407&r2=708408&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/src/site/apt/struts.apt (original)
+++ tapestry/tapestry5/trunk/src/site/apt/struts.apt Mon Oct 27 17:24:08 2008
@@ -145,7 +145,7 @@
You don't have to worry about URLs. Incoming requests for Tapestry encode the
name of the page and the id of the component within the page, along with
other information,
into the URL for you. Your code never has to pick apart a URL, you create
- {{{tapestry-core/guide/event.html}event listening methods}} to know when the
user has clicked a link
+ {{{../guide/event.html}event handler methods}} to know when the user has
clicked a link
or submitted a form, or done something more interesting using Ajax.
Tapestry has the structure it needs
to build all necessary information into the URL, and unpack that information
in a later request.
Modified: tapestry/tapestry5/trunk/src/site/apt/tomcat.apt
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/src/site/apt/tomcat.apt?rev=708408&r1=708407&r2=708408&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/src/site/apt/tomcat.apt (original)
+++ tapestry/tapestry5/trunk/src/site/apt/tomcat.apt Mon Oct 27 17:24:08 2008
@@ -4,19 +4,9 @@
Deployment Notes: Tomcat
- Deploying Tapestry applications into {{{http://tomcat.apache.org/}Tomcat}}
is relatively easy, with one big caveat: you must not store your Tapestry
component classes under WEB-INF/classes.
-
- At startup, Tapestry needs to locate all your page and component classes, so
that it can match page names in request URLs to page classes. Due to the way
- Tomcat creates ClassLoaders, this information is not accessible to Tapestry.
-
- Fortunately, Maven has an option inside its war plugin,
-
{{{http://maven.apache.org/plugins/maven-war-plugin/war-mojo.html#archiveClasses}archiveClasses}},
that changes the packaging; instead of putting compiled
- classes and resource files in
- WEB-INF/classes, they are instead placed inside an additional JAR inside
WEB-INF/lib. This keeps Tapestry happy at runtime.
+ Deploying Tapestry applications into {{{http://tomcat.apache.org/}Tomcat}}
is (no longer) any different than deployment using
+ {{{jetty. html}Jetty}} (previously, Tomcat deployment required more effort).
- The {{{quickstart/}quickstart archetype}} configures your project's Maven
pom.xml file to make use of this
- option.
-
Tapestry 5 has been tested with Tomcat 5.5.20.
* index.html
@@ -25,7 +15,4 @@
for a base URL (just the context path).
By contrast, {{{jetty.html}Jetty}} favors the filter over the index.html
file.
-
-* Logging
-
- TODO: Discuss logging configuration for Tomcat.
\ No newline at end of file
+
\ No newline at end of file
Modified: tapestry/tapestry5/trunk/src/site/apt/upgrade4.apt
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/src/site/apt/upgrade4.apt?rev=708408&r1=708407&r2=708408&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/src/site/apt/upgrade4.apt (original)
+++ tapestry/tapestry5/trunk/src/site/apt/upgrade4.apt Mon Oct 27 17:24:08 2008
@@ -15,6 +15,4 @@
As part of
{{{https://issues.apache.org/jira/browse/TAPESTRY-2421}TAPESTRY-2421}}, we've
done
some judicous renaming so that Tapestry 4 and Tapestry 5 applications can run
inside the same WAR.
-
-
- More to come ...
\ No newline at end of file
+
\ No newline at end of file
Modified: tapestry/tapestry5/trunk/src/site/fml/faq/general.fml
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/src/site/fml/faq/general.fml?rev=708408&r1=708407&r2=708408&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/src/site/fml/faq/general.fml (original)
+++ tapestry/tapestry5/trunk/src/site/fml/faq/general.fml Mon Oct 27 17:24:08
2008
@@ -189,7 +189,7 @@
<pre>
private static final String LOGIN = "login";
- @OnEvent(value=Form.VALIDATE_FORM, component=LOGIN)
+ @OnEvent(value=EventConstants.VALIDATE_FORM,
component=LOGIN)
void validateUserCredentials()
{
...
@@ -197,7 +197,7 @@
</pre>
<p>
- This helps the compiler check your code for typos, and
mnimizes the difficult of change when
+ This helps the compiler check your code for typos, and
minimizes the difficult of change when
refactoring the names of components.
</p>
@@ -253,7 +253,7 @@
</faq>
- <faq>
+ <faq id="request-vs-servlet-request">
<question>
Why are there both Request and HttpServletRequest?
</question>
@@ -264,7 +264,7 @@
to the standard HttpServletRequest interface. It differs
in just a few ways, omitting
a number of unneeded methods, adding a couple
of methods (such as isXHR()) and changing how a few of the
existing methods
- operate. for example, getParameterNames() returns a sorted
List of Strings;
+ operate. For example, getParameterNames() returns a sorted
List of Strings;
HttpServletRequest returns an Enumeration, which is a very
dated approach.
</p>
@@ -277,5 +277,40 @@
</answer>
</faq>
+ <faq id="beaneditform-constructor-exception">
+ <question>
+ Why do I get an exception about invoking a constructor when I
use my bean with the
+ BeanEditForm component?
+ </question>
+ <answer>
+ <p>When you build a UI using BeanEditForm, the BeanEditForm
component needs a place
+ to store the data that is provided in the submission.
+ </p>
+ <p>If you don't provide a new instance, it will instantiate
one.</p>
+ <p>
+ The BeanEditForm component uses the same mechanism that is
used to instantiate
+ services in the Tapestry IoC container; it looks for the
constructor with the most
+ parameters, and tries to match each parameter to an IoC
service.
+ </p>
+ <p>
+ When you have a constructor like:
+ <code>public MyBean(String name, Date date)</code>,
+ Tapestry will try to inject the date parameter and find no
IoC service matches that type.
+ </p>
+ <p>
+ The solution is to put an @Inject annotation on the
constructor Tapestry
+ <em>should</em>
+ be
+ using (the default constructor, with no parameters).
+ </p>
+ <p>
+ Alternately, provide a handler for the prepareForSubmit
event, and store an instance
+ into the property connected to the BeanEditForm. The
BeanEditForm will see a non-null value and use
+ it,
+ therefore it will not get tripped up in terms of
instantiating an instance.
+ </p>
+ </answer>
+ </faq>
+
</part>
</faqs>
\ No newline at end of file
Modified: tapestry/tapestry5/trunk/src/site/site.xml
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/src/site/site.xml?rev=708408&r1=708407&r2=708408&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/src/site/site.xml (original)
+++ tapestry/tapestry5/trunk/src/site/site.xml Mon Oct 27 17:24:08 2008
@@ -42,8 +42,9 @@
<item name="Download"
href="http://tapestry.apache.org/download.html"/>
<item name="Release Notes" href="release-notes.html"/>
<item name="Component Reference" href="tapestry-core/ref/"/>
+ <item name="JavaDocs" href="apidocs/"/>
<item name="Nightly Docs"
href="http://tapestry.formos.com/nightly/tapestry5/"/>
- <item name="Issues"
href="https://issues.apache.org/jira/browse/TAPESTRY"/>
+ <item name="Issues"
href="https://issues.apache.org/jira/browse/TAP5"/>
<item name="FAQ" href="faq/general.html"/>
</menu>
@@ -104,6 +105,7 @@
<item name="Default Parameter"
href="cookbook/defaultparameter.html"/>
<item name="Exception Reporting" href="cookbook/exceptions.html"/>
<item name="Supporting Informal Parameters"
href="cookbook/informals.html"/>
+ <item name="Component Libraries" href="cookbook/lib.html"/>
</menu>
<menu name="Tapestry 5 Maven Support">
Added: tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/autoload.apt
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/autoload.apt?rev=708408&view=auto
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/autoload.apt (added)
+++ tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/autoload.apt Mon Oct 27
17:24:08 2008
@@ -0,0 +1,91 @@
+ ---
+ Autoloading Modules
+ ---
+
+Autoloading Modules
+
+ An important part of Tapestry IoC is the autoloading of modules; this allows
new features to be added to an application
+ just by "dropping in" a JAR that contains a module: the services in the
module are automatically integrated
+ into the overall service registry, along with any configuration or other
supporting code and resources.
+
+ An example of this is the {{{../tapestry-upload/index.html}tapestry-upload}}
library, which introduces
+ an Upload component, along with supporting services related to handling file
upload requests.
+
+ The core Tapestry IoC module is automatically included. When using the
Tapestry web framework, the core Tapestry module
+ is also included, as is an optional per-application module, plus any
autoloaded modules.
+
+ Module autoloading isn't 100% free ... you must tell Tapestry IoC where the
modules to load are located, which
+ can be done via a Manifest file entry, or via an annotation.
+
+JAR Manifest Entries
+
+ When setting up the registry, Tapestry can automatically locate modules
packaged into JARs.
+ It does this by searching for a particular global manifest entry.
+
+ The manifest entry name is "Tapestry-Module-Classes". The value is a
comma-separated list
+ of fully qualified class names of module builder classes (this allows a
single
+ JAR to contain multiple, related modules). Whitespace is ignored.
+
+ Example:
+
++-----------------------------------------------------------------------------------+
+Manifest-Version: 1.0
+Tapestry-Module-Classes: org.example.mylib.LibModule,
org.example.mylib.internal.InternalModule
++-----------------------------------------------------------------------------------+
+
+ If you are using Maven 2, then getting these entries into your JAR's manifest
+ is as simple as some configuration in your pom.xml:
+
++-----------------------------------------------------------------------------------+
+<project>
+ . . .
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-jar-plugin</artifactId>
+ <configuration>
+ <archive>
+ <manifestEntries>
+ <Tapestry-Module-Classes>org.example.mylib.LibModule,
+
org.example.mylib.internal.InternalModule</Tapestry-Module-Classes>
+ </manifestEntries>
+ </archive>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ . . .
+</project>
++-----------------------------------------------------------------------------------+
+
+
+ More details are provided in the
+ {{{http://maven.apache.org/guides/mini/guide-manifest.html}Maven Manifest
Guide}}.
+
+SubModule Annotation
+
+ Often, you will have several different modules working together that should
all be loaded
+ as a unit.
+
+ One approach is to update the module ids into the manifest, as shown in the
previous extension.
+
+ This can become tedious, and somewhat brittle in the face of refactorings
(such as renaming of classes
+ or packages).
+
+ A better alternative is the
+ {{{../apidocs/org/apache/tapestry5/ioc/annotations/[EMAIL PROTECTED]
annotation}}.
+
+ The value for this annotation is a list of <additional> classes to be
treated as module builder classes,
+ exactly as if they were identified in the manifest. For example:
+
++----+
[EMAIL PROTECTED](
+{ InternalTransformModule.class })
+public final class InternalModule
+{
+ . . .
++----+
+
+ In general, your should only need to identify a single module in the JAR
manifest, and make use of
+ @SubModule to pull in any additional module builder classes.
\ No newline at end of file
Modified: tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/module.apt
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/module.apt?rev=708408&r1=708407&r2=708408&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/module.apt (original)
+++ tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/module.apt Mon Oct 27
17:24:08 2008
@@ -178,78 +178,6 @@
Tapestry detects these scenarios and throws a runtime exception to prevent
an endless loop.
-{Autoloading modules}
-
- When setting up the registry, Tapestry can automatically locate modules
packaged into JARs.
- It does this by searching for a particular global manifest entry.
-
- The manifest entry name is "Tapestry-Module-Classes". The value is a
comma-separated list
- of fully qualified class names of module builder classes (this allows a
single
- JAR to contain multiple, related modules). Whitespace is ignored.
-
- Example:
-
-+-----------------------------------------------------------------------------------+
-Manifest-Version: 1.0
-Tapestry-Module-Classes: org.example.mylib.LibModule,
org.example.mylib.internal.InternalModule
-+-----------------------------------------------------------------------------------+
-
- If you are using Maven 2, then getting these entries into your JAR's manifest
- is as simple as some configuration in your pom.xml:
-
-+-----------------------------------------------------------------------------------+
-<project>
- . . .
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-jar-plugin</artifactId>
- <configuration>
- <archive>
- <manifestEntries>
- <Tapestry-Module-Classes>org.example.mylib.LibModule,
-
org.example.mylib.internal.InternalModule</Tapestry-Module-Classes>
- </manifestEntries>
- </archive>
- </configuration>
- </plugin>
- </plugins>
- </build>
- . . .
-</project>
-+-----------------------------------------------------------------------------------+
-
-
- More details are provided in the
- {{{http://maven.apache.org/guides/mini/guide-manifest.html}Maven Manifest
Guide}}.
-
-SubModule Annotation
-
- Often, you will have several different modules working together that should
all be loaded
- as a unit.
-
- One approach is to update the module ids into the manifest, as shown in the
previous extension.
-
- This can become tedious, and somewhat brittle in the face of refactorings
(such as renaming of classes
- or packages).
-
- A better alternative is the
- {{{../apidocs/org/apache/tapestry5/ioc/annotations/[EMAIL PROTECTED]
annotation}}.
-
- The value for this annotation is a list of <additional> classes to be
treated as module builder classes,
- exactly as if they were identified in the manifest. For example:
-
-+----+
[EMAIL PROTECTED](
-{ InternalTransformModule.class })
-public final class InternalModule
-{
- . . .
-+----+
-
- In general, your should only need to identify a single module in the JAR
manifest, and make use of
- @SubModule to pull in any additional module builder classes.
Module Builder Implementation Notes
Modified: tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/run.apt
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/run.apt?rev=708408&r1=708407&r2=708408&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/run.apt (original)
+++ tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/run.apt Mon Oct 27
17:24:08 2008
@@ -46,7 +46,7 @@
The default registry is available by invoking the static method
{{{../apidocs/org/apache/tapestry5/ioc/IOCUtilities.html#buildDefaultRegistry()}IOCUtilities.buildDefaultRegistry()}}.
This method builds a Registry using
- {{{module.html#Autoloading modules}autoloading logic}}, where modules to load
+ {{{autoload.html}autoloading logic}}, where modules to load
are identified via a JAR Manifest entry.
In addition, the JVM system property <<<tapestry.modules>>> (if specified)
is a list of additional
Modified: tapestry/tapestry5/trunk/tapestry-ioc/src/site/site.xml
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-ioc/src/site/site.xml?rev=708408&r1=708407&r2=708408&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-ioc/src/site/site.xml (original)
+++ tapestry/tapestry5/trunk/tapestry-ioc/src/site/site.xml Mon Oct 27 17:24:08
2008
@@ -49,6 +49,7 @@
<item name="Introduction" href="index.html"/>
<item name="Overview of Tapestry IoC" href="overview.html"/>
<item name="Modules" href="module.html"/>
+ <item name="Module Autoloading" href="autoload.html"/>
<item name="Services" href="service.html"/>
<item name="Decorators" href="decorator.html"/>
<item name="Configuration" href="configuration.html"/>
