summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorChristopher Frost2010-10-27 12:26:27 (EDT)
committer Glyn Normington2010-11-02 08:25:37 (EDT)
commit8044f10b30f7f0fa0b546aa3bab543354cb36f6a (patch)
tree478358bf45d975d38b887f63c50d01d9c3a05f8e
parentf7335d699a4657c655f45f27fbcfba8c10bdeefa (diff)
downloadorg.eclipse.virgo.documentation-8044f10b30f7f0fa0b546aa3bab543354cb36f6a.zip
org.eclipse.virgo.documentation-8044f10b30f7f0fa0b546aa3bab543354cb36f6a.tar.gz
org.eclipse.virgo.documentation-8044f10b30f7f0fa0b546aa3bab543354cb36f6a.tar.bz2
Second set of edits for the programmer gudie
-rw-r--r--programmer-guide/src/architecture.xml42
-rw-r--r--programmer-guide/src/developing-applications.xml161
-rw-r--r--programmer-guide/src/formtags-case-study.xml1199
-rw-r--r--programmer-guide/src/tooling.xml81
4 files changed, 747 insertions, 736 deletions
diff --git a/programmer-guide/src/architecture.xml b/programmer-guide/src/architecture.xml
index 70436d0..c765614 100644
--- a/programmer-guide/src/architecture.xml
+++ b/programmer-guide/src/architecture.xml
@@ -45,7 +45,7 @@
<para><link linkend="architecture-wars">Java EE WAR</link></para>
</listitem>
<listitem>
- <para><link linkend="architecture-war-rfc66">Web Bundles</link></para>
+ <para><link linkend="architecture-war-gemini">Web Bundles</link></para>
</listitem>
<listitem>
<para><link linkend="architecture-pars">PAR</link></para>
@@ -53,12 +53,14 @@
<listitem>
<para><link linkend="architecture-plans">Plans</link></para>
</listitem>
+ <listitem>
+ <para><link linkend="architecture-configurations">Configurations</link></para>
+ </listitem>
</orderedlist>
<para>
When you deploy an application to the @short.product.name@, each deployment artifact (e.g., a single bundle, WAR, PAR, or
- plan) passes through a deployment pipeline. This deployment pipeline supports the notion of personality-specific
- deployers which are responsible for processing an application with a certain personality (i.e., application type).
- The @bundle.version@ release of the @short.product.name@ natively supports personality-specific deployers analogous
+ plan) passes through a deployment pipeline. This deployment pipeline is responsible for processing applications of certain
+ types (i.e., application type). The @bundle.version@ release of the @short.product.name@ natively supports deployers analogous
to each of the aforementioned packaging options.
</para>
<para>
@@ -177,24 +179,23 @@
modularity and reduced overall footprint of your web applications.
</para>
</section>
- <section id="architecture-war-rfc66">
- <title>WARs and the OSGi Web Container (RFC66)</title>
+ <section id="architecture-war-gemini">
+ <title>WARs and the Gemini Web Container</title>
<para>
- @product.name@ fully supports the OSGi Web Container (RFC66) standard. In fact, the reference implementation for RFC66
- was developed by SpringSource from an offshoot of the original @short.product.name@ codebase. This RI is now fully integrated in
- @short.product.name@ as the basis of the support for web application deployment.
+ @product.name@ fully supports the OSGi Web Container standard. Using the reference implementation from Gemini Web that
+ was developed by SpringSource from an offshoot of the original @short.product.name@ codebase. This RI is now fully
+ integrated in @short.product.name@ as the basis of the support for web application deployment.
</para>
<para>
- The Web Container specification introduces the concept of a <emphasis>web bundle</emphasis>, which is a WAR that is also
- a bundle. The specification defines how WAR files are transformed into bundles automatically as needed.
+ The Web Container specification introduces the concept of a <emphasis>web application bundle</emphasis>, which is a WAR
+ that is also a bundle. The specification defines how WAR files are transformed into bundles automatically as needed.
</para>
<para>
- The Web Container specification is not yet publicly available, but you can find an introduction to the Web Container in
- blog entries written by the @short.product.name@ team
+ You can find an introduction to the Web Container in blog entries written by the @short.product.name@ team
<ulink url="http://blog.springsource.com/2009/05/27/introduction-to-the-osgi-web-container/">here</ulink>
and <ulink url="http://blog.springsource.com/2009/06/01/what-the-osgi-web-container-means-for-dm-server/">here</ulink>.
</para>
- <section id="architecture-war-rfc66-extensions">
+ <section id="architecture-war-gemini-extensions">
<title>Extensions to the Web Container</title>
<para>
@product.name@ provides a variety of extensions to the Web Container that allow you to construct sophisticated applications.
@@ -240,10 +241,10 @@
</section>
</section>
</section>
- <section id="architecture-web-modules">
+ <section id="architecture-web-bundles">
<title>Web Modules</title>
<para>
- Web Modules have been removed in favor of war files and web bundles following the OSGi Web Container specification.
+ Web Modules have been removed in favour of war files and web bundles following the OSGi Web Container specification.
We believe our users will benefit more from a standard model than one that is @short.product.name@-specific.
</para>
</section>
@@ -329,6 +330,15 @@
between plans as well as update individual parts of a plan without having to physically repackage (re-JAR) it.
</para>
</section>
+ <section id="architecture-configurations">
+ <title>Configurations</title>
+ <para>
+ A Configuration is simply a Java properties file. When deployed it will be recognised by the deployer and installed in to
+ <emphasis>Configuration Admin</emphasis> for later use by your applications. The name that it will be installed under or PID
+ (Properties Identification) will be the name of the properties file less any extension. How to consume configuration data
+ is discussed <link linkend="developing-applications-configuration-artifacts">later</link>.
+ </para>
+ </section>
</section>
<!-- ======================================================================= -->
diff --git a/programmer-guide/src/developing-applications.xml b/programmer-guide/src/developing-applications.xml
index ba5423c..95e73c3 100644
--- a/programmer-guide/src/developing-applications.xml
+++ b/programmer-guide/src/developing-applications.xml
@@ -116,11 +116,15 @@ Manifest-Version: 1.0
<title>Creating PARs and WARs</title>
<para>
The @product.name@ supports two OSGi-oriented ways of packaging applications: the PAR format
- and application modules (including personality-specific modules). The @short.product.name@ also supports three
+ and application bundles (including web bundles). The @short.product.name@ also supports three
distinct WAR deployment and packaging formats: standard Java EE WAR, Shared Libraries WAR, Shared Services WAR.
</para>
<para>
- The @short.product.name@ also supports plans as a way to describe an application. This method is similar to a PAR in that it encapsulates all the artifacts of an application as a single unit, but differs in that a plan simply lists the bundles in an XML file rather than packaging all the bundles in a single JAR file. The use of plans offers additional benefits to using PARs; for this reason, we recommend their use. For details, see <link linkend="developing-applications-plans">Creating Plans</link>.
+ The @short.product.name@ also supports plans as a way to describe an application. This method is similar to a PAR
+ in that it encapsulates all the artifacts of an application as a single unit, but differs in that a plan simply
+ lists the bundles in an XML file rather than packaging all the bundles in a single JAR file. The use of plans
+ offers additional benefits to using PARs; for this reason, we recommend their use. For details, see
+ <link linkend="developing-applications-plans">Creating Plans</link>.
</para>
<section id="developing-applications-packaging-par">
<title>PARs</title>
@@ -128,13 +132,13 @@ Manifest-Version: 1.0
An OSGi application is packaged as a JAR file, with extension <literal>.par</literal>. A PAR artifact offers several benefits:
<itemizedlist>
<listitem>A PAR file has an application name, version, symbolic name, and description.</listitem>
- <listitem>The modules of a PAR file are scoped so that they cannot
+ <listitem>The artifacts of a PAR file are scoped so that they cannot
be shared accidentally by other applications. The scope forms a boundary for automatic
propagation of load time weaving and bundle refresh.</listitem>
- <listitem>The modules of a PAR have their exported packages imported by the
+ <listitem>The artifacts of a PAR have their exported packages imported by the
synthetic context bundle which is used for thread context class loading. So,
for example, hibernate will be able to load classes of any of the exported
- packages of the modules in a PAR file using <code>Class.forName()</code> (or equivalent).</listitem>
+ packages of the artifacts in a PAR file using <code>Class.forName()</code> (or equivalent).</listitem>
<listitem>The PAR file is visible to management interfaces.</listitem>
<listitem>The PAR file can be undeployed and redeployed as a unit.</listitem>
</itemizedlist>
@@ -186,10 +190,10 @@ Manifest-Version: 1.0
<title>Web Modules</title>
<para>
As discussed earlier, Web Modules are no longer supported in @short.product.name@. Instead, we recommend that you
- use Shared Service WARs or Web Bundles that are compliant with the OSGi Web Container specification.
+ use Shared Service WARs or Web Application Bundles that are compliant with the OSGi Web Container specification.
</para>
<section id="developing-applications-packaging-web-module-to-war">
- <title>Migrating to a Web Bundle from a Web Module</title>
+ <title>Migrating to a Web Application Bundle from a Web Module</title>
<para>
To move from a Web Module to a Web Container-compliant Web Bundle you need to follow these four steps:
<orderedlist>
@@ -352,7 +356,7 @@ Manifest-Version: 1.0
<entry><literal>type</literal></entry>
<entry>Specifies the type of the artifact. Valid values are:
<itemizedlist>
- <listitem><code>bundle</code>: Specifies an OSGi bundle. Use this artifact type for WAR files. </listitem>
+ <listitem><code>bundle</code>: Specifies an OSGi bundle. Use this artifact type for WAR files and Web application bundles. </listitem>
<listitem><code>configuration</code>: Specifies that the artifact is a configuration file. Configuration files contain name/value pairs that set initial values for configuration properties of a bundle. </listitem>
<listitem><code>plan</code>: Specifies that the artifact is a plan. </listitem>
<listitem><code>par</code>: Specifies that the artifact is a PAR. </listitem>
@@ -385,8 +389,8 @@ Manifest-Version: 1.0
<para>When you create a plan, you use the <code>name</code> attribute of the <code>&lt;artifact&gt;</code> element to specify the name of all the plan&rsquo;s dependencies. This section describes how to determine the name of an artifact, which is not always obvious.</para>
<para>Use the following guidelines to determine the name of an artifact:</para>
<itemizedlist>
- <listitem><para><emphasis role="bold">Bundle</emphasis>: In this context, a <emphasis>bundle</emphasis> refers to a standard OSGi bundle as well as a Web application WAR file. The name of a bundle is the value of the <code>Bundle-SymbolicName</code> header in the <code>META-INF/MANIFEST.MF</code> file of the <code>*.jar</code> or <code>*.war</code> file. The following <code>MANIFEST.MF</code> snippet shows a bundle with name <code>com.springsource.exciting.app</code>:</para>
- <screen>Bundle-SymbolicName: com.springsource.exciting.app</screen>
+ <listitem><para><emphasis role="bold">Bundle</emphasis>: In this context, a <emphasis>bundle</emphasis> refers to a standard OSGi bundle as well as a Web application bundles and WAR file. The name of a bundle is the value of the <code>Bundle-SymbolicName</code> header in the <code>META-INF/MANIFEST.MF</code> file of the <code>*.jar</code> or <code>*.war</code> file. The following <code>MANIFEST.MF</code> snippet shows a bundle with name <code>com.springsource.exciting.app</code>:</para>
+ <screen>Bundle-SymbolicName: org.eclispe.virgo.exciting.app</screen>
<para>If the bundle does not contain a <code>META-INF/MANIFEST.MF</code> file, then the name of the bundle is its filename minus the <code>.jar</code> or <code>.war</code> extension.</para>
</listitem>
<listitem><para><emphasis role="bold">Configuration File</emphasis>: The name of a configuration file is its filename minus the <code>.properties</code> extension. </para></listitem>
@@ -397,7 +401,7 @@ Manifest-Version: 1.0
...</screen>
</listitem>
<listitem><para><emphasis role="bold">PAR</emphasis>: The name of a PAR is the value of the <code>Application-SymbolicName</code> header in the <code>META-INF/MANIFEST.MF</code> file of the <code>*.par</code> file. The following <code>MANIFEST.MF</code> snippet shows a PAR with name <code>com.springsource.my.par</code>:</para>
- <screen>Application-SymbolicName: com.springsource.my.par</screen>
+ <screen>Application-SymbolicName: org.eclipse.virgo.my.par</screen>
<para>If the PAR does not contain a <code>META-INF/MANIFEST.MF</code> file, then the name of the PAR is its filename minus the <code>.par</code> extension.</para>
</listitem>
</itemizedlist>
@@ -409,11 +413,11 @@ Manifest-Version: 1.0
Because a plan is a list of artifacts, rather than a physical file that contains the artifacts, there are a few additional steps you must perform before you deploy it to @short.product.name@.
</para>
<orderedlist>
- <listitem><para>Copy the artifacts that make up the plan to the <code>usr</code> repository, which by default is the <code>$DMS_HOME/repository/usr</code> directory, where <code>$DMS_HOME</code> refers to the top-level installation directory of @short.product.name@. Note that you might have configured the server differently; in which case, copy the artifacts to your custom repository directory.</para></listitem>
+ <listitem><para>Copy the artifacts that make up the plan to the <code>usr</code> repository, which by default is the <code>$SERVER_HOME/repository/usr</code> directory, where <code>$SERVER_HOME</code> refers to the top-level installation directory of @short.product.name@. Note that you might have configured the server differently; in which case, copy the artifacts to your custom repository directory.</para></listitem>
<listitem><para>Restart @short.product.name@.</para></listitem>
- <listitem><para>After the server has started, either use the Admin Console to deploy the plan, or manually deploy it by copying the plan&rsquo;s XML file into the <code>$DMS_HOME/pickup</code> directory. </para>
+ <listitem><para>After the server has started, either use the Admin Console to deploy the plan, or manually deploy it by copying the plan&rsquo;s XML file into the <code>$SERVER_HOME/pickup</code> directory. </para>
<para>This results in @short.product.name@ deploying the plan with the same semantics as a PAR file.</para></listitem>
- <listitem><para>To undeploy the plan, use the Admin Console, or simply delete it from the <code>$DMS_HOME/pickup</code> directory.</para></listitem>
+ <listitem><para>To undeploy the plan, use the Admin Console, or simply delete it from the <code>$SERVER_HOME/pickup</code> directory.</para></listitem>
</orderedlist>
</section>
@@ -544,7 +548,7 @@ password = secret</screen>
<section id="developing-applications-configuration-artifacts-app">
<title>Updating Your Application</title>
- <para>To update your application so that it "knows" about the configuration artifact, you update the application's Spring application context XML file, typically located in the <literal>WEB-INF</literal> directory.</para>
+ <para>To update your application so that it "knows" about the configuration artifact, you update the application's Spring application context XML file, typically located in the <literal>WEB-INF</literal> or <literal>META-INF/spring</literal> directories.</para>
<para>You use the <literal>&lt;context:property-placeholder&gt;</literal> element to specify that you want to use the @short.product.name@ mechanism for substituting values into bean properties. The <literal>properties-ref</literal> attribute of this element points to a <literal>&lt;osgi-compendium:cm-properties&gt;</literal> element which you use to specify the configuration artifact that contains the property values. You set the value of the <literal>persistent-id</literal> attribute of this element equal to the name of the configuration artifact, which is the name of the properties file <emphasis>minus</emphasis> the <literal>.properties</literal> extension. </para>
<para>The following sample Spring application context XMl file shows everything wired together; only relevant parts of the file are shown:</para>
@@ -610,37 +614,36 @@ password = secret</screen>
<!-- ======================================================================= -->
<section id="developing-applications-programmatic-access">
- <title>Programmatic Access to Personality-specific Features</title>
+ <title>Programmatic Access to The Deployer Pipeline</title>
<para>
- Module personalities typically provide automatic access to features
- specific to the personality via custom manifest headers or other
- configuration mechanisms. There may be situations, however, for which
- programmatic access to such features is desirable or necessary.
- This section describes how to programmatically access personality-specific
- features from application code in a module.
+ Typically access to features are provided automatically via custom
+ manifest headers or other configuration mechanisms. There may be situations,
+ however, for which programmatic access to such features is desirable or necessary.
+ This section describes how to programmatically access features from application
+ code in a bundle.
</para>
<section id="developing-applications-programmatic-access-web">
- <title>Programmatic Access to Web Personality Features</title>
+ <title>Programmatic Access to Web Features</title>
<section id="developing-applications-programmatic-access-web-application-context">
<title>Programmatic Access to the WebApplicationContext</title>
<para>
The @product.name@ automatically creates a <literal>WebApplicationContext</literal>
- for Web Bundles and WAR files. When used in conjuction with an
+ for Web application bundles and WAR files. When used in conjunction with an
an auto-configured Spring MVC <literal>DispatcherServlet</literal>,
there is generally no need to access the <literal>WebApplicationContext</literal>
programmatically, since all components of the web application are configured
within the scope of the <literal>WebApplicationContext</literal>
itself. However, if you wish to access the <literal>WebApplicationContext</literal>
you can do so via the web application&rsquo;s <literal>ServletContext</literal>.
- The Web Personality subsystem stores the bundle&rsquo;s
+ The Web subsystem stores the bundle&rsquo;s
<literal>WebApplicationContext</literal> in the ServletContext under
the attribute name "<literal>BSN-ApplicationContext</literal>", where
<literal>BSN</literal> is the <literal>Bundle-SymbolicName</literal>
- of your WAR or Web Bundle.
+ of your WAR or Web application bundle.
</para>
<para>
- Alternatively, since the Web Personality subsystem also stores the
+ Alternatively, since the Web subsystem also stores the
<literal>WebApplicationContext</literal> under the attribute name
with the value of the <literal>WebApplicationContext.ROOT_WEB_APPLICATION_CONTEXT_ATTRIBUTE</literal>
constant, you may choose to use Spring MVC&rsquo;s WebApplicationContextUtils&rsquo;
@@ -665,67 +668,63 @@ password = secret</screen>
</section>
</section>
- <section id="developing-applications-automatic-imports">
- <title>Automatic Imports</title>
+
+ <section id="developing-applications-automatic-imports-web">
+ <title>Automatic Imports for the Web subsystem</title>
<para>
The @product.name@ generates automatic package imports (i.e., via the
- <literal>Import-Package</literal> manifest header) for various
- module personalities. This section lists which packages are automatically
- generated for each personality.
+ <literal>Import-Package</literal> manifest header) for the web subsystem&rsquo;s
+ artifacts. This section lists which packages are automatically generated.
</para>
- <section id="developing-applications-automatic-imports-web">
- <title>Automatic Imports for the Web Personality</title>
-
- <para>
- All WARs, as required by the OSGi Web Container specification, and Web Bundles (see <link linkend="known-issues-web-bundle-default-headers">Default Web
- Application Bundle Headers</link>) will automatically import the following packages:
- </para>
-
- <itemizedlist>
- <listitem>
- <literal>javax.servlet;version="2.5"</literal>
- </listitem>
- <listitem>
- <literal>javax.servlet.http;version="2.5"</literal>
- </listitem>
- <listitem>
- <literal>javax.servlet.jsp";version="2.1"</literal>
- </listitem>
- <listitem>
- <literal>javax.servlet.jsp.el;version="2.1"</literal>
- </listitem>
- <listitem>
- <literal>javax.servlet.jsp.tagext;version="2.1"</literal>
- </listitem>
- <listitem>
- <literal>javax.el";version="1.0"</literal>
- </listitem>
- </itemizedlist>
+ <para>
+ All WARs, as required by the OSGi Web Container specification, and Web application bundles (see <link linkend="known-issues-web-bundle-default-headers">Default Web
+ Application Bundle Headers</link>) will automatically import the following packages:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <literal>javax.servlet;version="2.5"</literal>
+ </listitem>
+ <listitem>
+ <literal>javax.servlet.http;version="2.5"</literal>
+ </listitem>
+ <listitem>
+ <literal>javax.servlet.jsp";version="2.1"</literal>
+ </listitem>
+ <listitem>
+ <literal>javax.servlet.jsp.el;version="2.1"</literal>
+ </listitem>
+ <listitem>
+ <literal>javax.servlet.jsp.tagext;version="2.1"</literal>
+ </listitem>
+ <listitem>
+ <literal>javax.el";version="1.0"</literal>
+ </listitem>
+ </itemizedlist>
+ <para>
+ In addition to the above-described imports, @short.product.name@ will also
+ generate automatic imports for all of the packages that are exported by the system
+ bundle, unless an import for the package already exists in the artifact&rsquo;s manifest,
+ or the artifact contains the package, i.e. within <literal>WEB-INF/classes</literal>,
+ or in a jar file in <literal>WEB-INF/lib</literal>. When an import is generated, it
+ is versioned such that it exactly matches the version or versions of the package that
+ are exported from the system bundle. For example, a package that&rsquo;s exported only at
+ version <literal>1.0.0</literal> will generate an import with a version of
+ <literal>[1.0.0,1.0.0]</literal>, and a package that&rsquo;s exported at version
+ <literal>1.0.0</literal> and version <literal>2.0.0</literal> will generate an import
+ with a version of <literal>[1.0.0,2.0.0]</literal>.
+ </para>
+
+ <tip>
+ <title>System Bundle Package Exports</title>
<para>
- In addition to the above-described imports, @short.product.name@ will also
- generate automatic imports for all of the packages that are exported by the system
- bundle, unless an import for the package already exists in the artifact&rsquo;s manifest,
- or the artifact contains the package, i.e. within <literal>WEB-INF/classes</literal>,
- or in a jar file in <literal>WEB-INF/lib</literal>. When an import is generated, it
- is versioned such that it exactly matches the version or versions of the package that
- are exported from the system bundle. For example, a package that&rsquo;s exported only at
- version <literal>1.0.0</literal> will generate an import with a version of
- <literal>[1.0.0,1.0.0]</literal>, and a package that&rsquo;s exported at version
- <literal>1.0.0</literal> and version <literal>2.0.0</literal> will generate an import
- with a version of <literal>[1.0.0,2.0.0]</literal>.
+ For further details on which packages are exported by the
+ OSGi system bundle, consult the <filename>java6-server.profile</filename>
+ file located in the <literal>SERVER_HOME/lib</literal> directory.
</para>
-
- <tip>
- <title>System Bundle Package Exports</title>
- <para>
- For further details on which packages are exported by the
- OSGi system bundle, consult the <filename>java6-server.profile</filename>
- file located in the <literal>SERVER_HOME/lib</literal> directory.
- </para>
- </tip>
+ </tip>
- </section>
</section>
<section id="developing-applications-dependencies">
diff --git a/programmer-guide/src/formtags-case-study.xml b/programmer-guide/src/formtags-case-study.xml
index 8458958..6aa89ce 100644
--- a/programmer-guide/src/formtags-case-study.xml
+++ b/programmer-guide/src/formtags-case-study.xml
@@ -2,198 +2,199 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="formtags-case-study">
- <title>Case study: Migrating the Form Tags sample application</title>
- <titleabbrev>Migrating Form Tags</titleabbrev>
- <para>
- In this chapter we will walk through the steps needed to migrate the
- Form Tags sample application from a standard Java EE WAR to a fully OSGi
- compliant <emphasis>Shared Services WAR</emphasis> within a PAR.
- The migration involves four packaging and deployment formats:
- <orderedlist>
- <listitem>
- <para>
- <link linkend="formtags-case-study-war">Standard WAR</link>
- </para>
- </listitem>
- <listitem>
- <para>
- <link linkend="formtags-case-study-war-shared-libs">Shared Libraries WAR</link>
- </para>
- </listitem>
- <listitem>
- <para>
- <link linkend="formtags-case-study-war-shared-services">Shared Services WAR</link>
- </para>
- </listitem>
- <listitem>
- <para>
- <link linkend="formtags-case-study-par">PAR with a shared services WAR</link>
- </para>
- </listitem>
- </orderedlist>
- </para>
- <para>
- Each of these migration steps will produce a web application
- that can be deployed and run on the @short.product.name@.
- </para>
- <para>
- After summarising the process, an example <literal>plan</literal> is shown which is another way of packaging and deploying the application.
- </para>
- <para>
- The following image displays the directory structure you should have
- after installing the Form Tags sample. Note however that the release tag
- will typically resemble <literal>2.0.0.RELEASE</literal>.
- </para>
- <para><imagedata fileref="images/formtags-case-study-sample-layout.png" format="PNG"/></para>
- <para>
- The <literal>dist</literal> directory contains the distributables,
- and the <literal>projects</literal> directory contains the source code
- and build scripts.
- </para>
- <para>
- For simplicity, this chapter will focus on the distributables—which are built using Spring-Build—rather than
- on configuring a project in an IDE.
- <tip>
- Pre-packaged distributables are made available in the <literal>dist</literal> directory;
- however, if you would like to modify the samples or build them from scratch, you may
- do so using Spring-Build. Take a look at
- the <literal>README.TXT</literal> file in each of the folders under
- the <literal>projects</literal> directory in the
- Form Tags sample for instructions.
- </tip>
- </para>
- <section id="formtags-case-study-introduction">
- <title>Overview of the Form Tags Sample Application</title>
- <para>
- The sample that we will be using is the Form Tags show case sample
- which was provided with Spring 2.0. The Form Tags application has
- been removed from the official Spring 2.5.x distributions; however,
- since it is relatively simple but still contains enough ingredients
- to demonstrate the various considerations required during a migration,
- we have chosen to use it for these examples.
- </para>
- <para>
- The purpose of the Form Tags show case sample was to demonstrate how
- the Spring specific <literal>form:</literal> tags, released
- in Spring 2.0, make view development with JSPs and tag libraries easier.
- The Form Tags application consists of a single <literal>UserService</literal> which returns a list
- of <literal>Users</literal>. Furthermore, the application demonstrates how to list, view,
- and edit <literal>Users</literal> in a simple Spring MVC based web application using JSP
- and JSTL.
- </para>
- </section>
-
- <section id="formtags-case-study-war">
- <title>Form Tags WAR</title>
- <para>
- We begin with a standard WAR deployment.
- <note>
- The @product.name@ supports the standard Java EE WAR packaging
- and deployment format as a first-class citizen, and there are many
- benefits to deploying a standard WAR file on the @short.product.name@ including,
- but not limited to: tooling support, runtime error diagnostics, FFDC
- (first failure data capture), etc.
- In addition, support for standard WAR deployment provides an easy on-ramp
- for trying out the @product.name@ with existing web applications.
- </note>
- </para>
- <para>
- The following screen shot displays the directory structure of the
- Form Tags application using the standard WAR format. As you can see,
- there is no deviation from the standard structure and layout, and as
- you would expect, all of the web application&rsquo;s third-party dependencies
- (for example: Spring, Commons Logging) are packaged as JARs in
- <literal>WEB-INF/lib</literal>.
- </para>
- <para><imagedata fileref="images/formtags-case-study-exploded-war.png" format="PNG"/></para>
- <para>
- To deploy this application, simply copy <literal>dist/formtags-war-2.0.0.*.war</literal> to
- the <literal>SERVER_HOME/pickup</literal> directory for hot deployment.
- </para>
- <para>
- You should then see the @short.product.name@ produce console output similar to the following:
- </para>
- <note>
- <para>The console output has been reformatted to fit this document.</para>
- </note>
+ <title>Case study: Migrating the Form Tags sample application</title>
+ <titleabbrev>Migrating Form Tags</titleabbrev>
+ <para>
+ In this chapter we will walk through the steps needed to migrate the
+ Form Tags sample application from a standard Java EE WAR to a fully OSGi
+ compliant <emphasis>Shared Services WAR</emphasis> within a PAR.
+ The migration involves four packaging and deployment formats:
+ <orderedlist>
+ <listitem>
+ <para>
+ <link linkend="formtags-case-study-war">Standard WAR</link>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="formtags-case-study-war-shared-libs">Shared Libraries WAR</link>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="formtags-case-study-war-shared-services">Shared Services WAR</link>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="formtags-case-study-par">PAR with a shared services WAR</link>
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ <para>
+ Each of these migration steps will produce a web application
+ that can be deployed and run on the @short.product.name@.
+ </para>
+ <para>
+ After summarising the process, an example <literal>plan</literal> is shown which is another way of
+ packaging and deploying the application.
+ </para>
+ <para>
+ The following image displays the directory structure you should have
+ after installing the Form Tags sample. Note however that the release tag
+ will typically resemble <literal>2.0.0.RELEASE</literal>.
+ </para>
+ <para><imagedata fileref="images/formtags-case-study-sample-layout.png" format="PNG"/></para>
+ <para>
+ The <literal>dist</literal> directory contains the distributables,
+ and the <literal>projects</literal> directory contains the source code
+ and build scripts.
+ </para>
+ <para>
+ For simplicity, this chapter will focus on the distributables—which are built using Virgo-Build
+ rather than on configuring a project in an IDE.
+ <tip>
+ Pre-packaged distributables are made available in the <literal>dist</literal> directory;
+ however, if you would like to modify the samples or build them from scratch, you may
+ do so using Virgo-Build. Take a look at
+ the <literal>README.TXT</literal> file in each of the folders under
+ the <literal>projects</literal> directory in the
+ Form Tags sample for instructions.
+ </tip>
+ </para>
+ <section id="formtags-case-study-introduction">
+ <title>Overview of the Form Tags Sample Application</title>
+ <para>
+ The sample that we will be using is the Form Tags show case sample
+ which was provided with Spring 2.0. The Form Tags application has
+ been removed from the official Spring 2.5.x distributions; however,
+ since it is relatively simple but still contains enough ingredients
+ to demonstrate the various considerations required during a migration,
+ we have chosen to use it for these examples.
+ </para>
+ <para>
+ The purpose of the Form Tags show case sample was to demonstrate how
+ the Spring specific <literal>form:</literal> tags, released
+ in Spring 2.0, make view development with JSPs and tag libraries easier.
+ The Form Tags application consists of a single <literal>UserService</literal> which returns a list
+ of <literal>Users</literal>. Furthermore, the application demonstrates how to list, view,
+ and edit <literal>Users</literal> in a simple Spring MVC based web application using JSP
+ and JSTL.
+ </para>
+ </section>
+
+ <section id="formtags-case-study-war">
+ <title>Form Tags WAR</title>
+ <para>
+ We begin with a standard WAR deployment.
+ <note>
+ The @product.name@ supports the standard Java EE WAR packaging
+ and deployment format as a first-class citizen, and there are many
+ benefits to deploying a standard WAR file on the @short.product.name@ including,
+ but not limited to: tooling support, runtime error diagnostics, FFDC
+ (first failure data capture), etc.
+ In addition, support for standard WAR deployment provides an easy on-ramp
+ for trying out the @product.name@ with existing web applications.
+ </note>
+ </para>
+ <para>
+ The following screen shot displays the directory structure of the
+ Form Tags application using the standard WAR format. As you can see,
+ there is no deviation from the standard structure and layout, and as
+ you would expect, all of the web application&rsquo;s third-party dependencies
+ (for example: Spring, Commons Logging) are packaged as JARs in
+ <literal>WEB-INF/lib</literal>.
+ </para>
+ <para><imagedata fileref="images/formtags-case-study-exploded-war.png" format="PNG"/></para>
+ <para>
+ To deploy this application, simply copy <literal>dist/formtags-war-2.0.0.*.war</literal> to
+ the <literal>SERVER_HOME/pickup</literal> directory for hot deployment.
+ </para>
+ <para>
+ You should then see the @short.product.name@ produce console output similar to the following:
+ </para>
+ <note>
+ <para>The console output has been reformatted to fit this document.</para>
+ </note>
<programlisting>
[2009-07-01 14:54:45.135] fs-watcher
- &lt;SPDE0048I&gt; Processing 'CREATED' event for file 'formtags-war-2.0.0.RELEASE.war'.
+ &lt;SPDE0048I&gt; Processing 'CREATED' event for file 'formtags-war-2.0.0.RELEASE.war'.
[2009-07-01 14:54:45.797] fs-watcher
- &lt;SPDE0010I&gt; Deployment of 'formtags-war-2.0.0.RELEASE.war' version '0' completed.
+ &lt;SPDE0010I&gt; Deployment of 'formtags-war-2.0.0.RELEASE.war' version '0' completed.
[2009-07-01 14:54:45.797] Thread-20
- &lt;SPWE0000I&gt; Starting web bundle '/formtags-war-2.0.0.RELEASE'.
+ &lt;SPWE0000I&gt; Starting web bundle '/formtags-war-2.0.0.RELEASE'.
[2009-07-01 14:54:46.380] Thread-20
- &lt;SPWE0001I&gt; Started web bundle '/formtags-war-2.0.0.RELEASE'.
+ &lt;SPWE0001I&gt; Started web bundle '/formtags-war-2.0.0.RELEASE'.
</programlisting>
- <para>
- Navigate to <literal>http://localhost:8080/</literal> plus the web application context path,
- which in the above case is
- <literal>formtags-war-2.0.0.RELEASE</literal>. Thus navigating to
- <literal>http://localhost:8080/formtags-war-2.0.0.RELEASE</literal>
- should render the sample application&rsquo;s welcome page, as displayed in the screen
- shot below.
- <tip>
- For WARs, the default web context path is the name of the WAR file
- without the <literal>.war</literal> extension. You can optionally
- specify a context path using the <literal>Web-ContextPath</literal> bundle
- manifest header, which will be described in further detail later.
- </tip>
- </para>
- <para>
- <imagedata fileref="images/formtags-case-study-war-webpage.png" format="PNG" />
- </para>
- </section>
+ <para>
+ Navigate to <literal>http://localhost:8080/</literal> plus the web application context path,
+ which in the above case is
+ <literal>formtags-war-2.0.0.RELEASE</literal>. Thus navigating to
+ <literal>http://localhost:8080/formtags-war-2.0.0.RELEASE</literal>
+ should render the sample application&rsquo;s welcome page, as displayed in the screen
+ shot below.
+ <tip>
+ For WARs, the default web context path is the name of the WAR file
+ without the <literal>.war</literal> extension. You can optionally
+ specify a context path using the <literal>Web-ContextPath</literal> bundle
+ manifest header, which will be described in further detail later.
+ </tip>
+ </para>
+ <para>
+ <imagedata fileref="images/formtags-case-study-war-webpage.png" format="PNG" />
+ </para>
+ </section>
- <section id="formtags-case-study-war-shared-libs">
- <title>Form Tags Shared Libraries WAR</title>
- <para>
- As mentioned above, a standard WAR file typically packages of all its required
- dependencies in <literal>WEB-INF/lib</literal>. The servlet container will
- then add all of the JARs in <literal>WEB-INF/lib</literal> to the application&rsquo;s
- classpath.
- </para>
- <para>
- The first step of the migration towards benefiting from an OSGi
- container is to retrieve the dependencies from the @short.product.name@&rsquo;s bundle
- repository at runtime. This can significantly reduce the time it takes to build
- and deploy the application. It also enables the enforcement of policies
- regarding the use of third-party libraries.
- </para>
- <para>
- The way in which dependencies are declared in an OSGi environment is
- via manifest headers in a bundle&rsquo;s <literal>/META-INF/MANIFEST.MF</literal>.
- As mentioned in <xref linkend="developing-applications"/>, there are
- three ways of expressing dependencies: <literal>Import-Package</literal>,
- <literal>Import-Bundle</literal> and <literal>Import-Library</literal>.
- </para>
- <para>
- The Form Tags application uses JSTL standard tag libraries.
- Thus, you need to choose a JSTL provider, for example the
- Apache implementation which comes with the @short.product.name@. To use the
- Apache implementation of JSTL, you need to express your dependency
- as outlined in the following manifest listing.
- Because it is a single bundle, <literal>Import-Bundle</literal> is
- the simplest and therefore preferred manifest header to use.
- </para>
- <para>
- The Form Tags application requires commons-logging and Spring.
- It would be very painful to have to list all the Spring packages one by one.
- Equally, considering the number of bundles that make up the
- Spring framework, it would be verbose to list each bundle. Therefore
- <literal>Import-Library</literal> is the preferred approach
- for expressing the dependency on the Spring framework.
- </para>
- <tip>
- <para>
- How do you determine the name of a library definition provided
- by the @product.name@?
- Use the <ulink url="http://www.springsource.com/repository">@ebr@</ulink>.
- </para>
- </tip>
- <para>
- Examine the <literal>/META-INF/MANIFEST.MF</literal> in
- <literal>/dist/formtags-shared-libs-*.war</literal>:
+ <section id="formtags-case-study-war-shared-libs">
+ <title>Form Tags Shared Libraries WAR</title>
+ <para>
+ As mentioned above, a standard WAR file typically packages of all its required
+ dependencies in <literal>WEB-INF/lib</literal>. The servlet container will
+ then add all of the JARs in <literal>WEB-INF/lib</literal> to the application&rsquo;s
+ classpath.
+ </para>
+ <para>
+ The first step of the migration towards benefiting from an OSGi
+ container is to retrieve the dependencies from the @short.product.name@&rsquo;s bundle
+ repository at runtime. This can significantly reduce the time it takes to build
+ and deploy the application. It also enables the enforcement of policies
+ regarding the use of third-party libraries.
+ </para>
+ <para>
+ The way in which dependencies are declared in an OSGi environment is
+ via manifest headers in a bundle&rsquo;s <literal>/META-INF/MANIFEST.MF</literal>.
+ As mentioned in <xref linkend="developing-applications"/>, there are
+ three ways of expressing dependencies: <literal>Import-Package</literal>,
+ <literal>Import-Bundle</literal> and <literal>Import-Library</literal>.
+ </para>
+ <para>
+ The Form Tags application uses JSTL standard tag libraries.
+ Thus, you need to choose a JSTL provider, for example the
+ Apache implementation which comes with the @short.product.name@. To use the
+ Apache implementation of JSTL, you need to express your dependency
+ as outlined in the following manifest listing.
+ Because it is a single bundle, <literal>Import-Bundle</literal> is
+ the simplest and therefore preferred manifest header to use.
+ </para>
+ <para>
+ The Form Tags application requires commons-logging and Spring.
+ It would be very painful to have to list all the Spring packages one by one.
+ Equally, considering the number of bundles that make up the
+ Spring framework, it would be verbose to list each bundle. Therefore
+ <literal>Import-Library</literal> is the preferred approach
+ for expressing the dependency on the Spring framework.
+ </para>
+ <tip>
+ <para>
+ How do you determine the name of a library definition provided
+ by the @product.name@?
+ Use the <ulink url="http://www.springsource.com/repository">@ebr@</ulink>.
+ </para>
+ </tip>
+ <para>
+ Examine the <literal>/META-INF/MANIFEST.MF</literal> in
+ <literal>/dist/formtags-shared-libs-*.war</literal>:
<programlisting>
Manifest-Version: 1.0
Ant-Version: Apache Ant 1.7.0
@@ -204,62 +205,62 @@ Bundle-SymbolicName: org.springframework.showcase.formtags-shared-libs
<emphasis role="bold">Import-Bundle</emphasis>: com.springsource.org.apache.taglibs.standard;version="1
.1.2"
</programlisting>
- You can see the <literal>Import-Library</literal> and <literal>Import-Bundle</literal>
- directives that instruct the @short.product.name@ to add the appropriate package imports to the bundle
- classpath used by this WAR file.
- </para>
- <para>
- Deploying the shared libraries WAR onto the @short.product.name@ should result
- in console output similar to the following:
- </para>
- <note>
- <para>The console output has been reformatted to fit this document.</para>
- </note>
+ You can see the <literal>Import-Library</literal> and <literal>Import-Bundle</literal>
+ directives that instruct the @short.product.name@ to add the appropriate package imports to the bundle
+ classpath used by this WAR file.
+ </para>
+ <para>
+ Deploying the shared libraries WAR onto the @short.product.name@ should result
+ in console output similar to the following:
+ </para>
+ <note>
+ <para>The console output has been reformatted to fit this document.</para>
+ </note>
<programlisting>
[2009-07-01 15:00:14.953] fs-watcher
- &lt;SPDE0048I&gt; Processing 'CREATED' event for file 'formtags-shared-libs-2.0.0.RELEASE.war'.
+ &lt;SPDE0048I&gt; Processing 'CREATED' event for file 'formtags-shared-libs-2.0.0.RELEASE.war'.
[2009-07-01 15:00:15.363] fs-watcher
- &lt;SPDE0010I&gt; Deployment of 'org.springframework.showcase.formtags_shared_libs' version '2' completed.
+ &lt;SPDE0010I&gt; Deployment of 'org.springframework.showcase.formtags_shared_libs' version '2' completed.
[2009-07-01 15:00:15.364] Thread-20
- &lt;SPWE0000I&gt; Starting web bundle '/formtags-shared-libs-2.0.0.RELEASE'.
+ &lt;SPWE0000I&gt; Starting web bundle '/formtags-shared-libs-2.0.0.RELEASE'.
[2009-07-01 15:00:15.816] Thread-20
- &lt;SPWE0001I&gt; Started web bundle '/formtags-shared-libs-2.0.0.RELEASE'.
+ &lt;SPWE0001I&gt; Started web bundle '/formtags-shared-libs-2.0.0.RELEASE'.
</programlisting>
- <para>
- Navigating to <literal>http://localhost:8080/formtags-shared-libs-BUILDTAG</literal>
- should render the welcome page. Note that for the pre-packaged distributable,
- the <literal>BUILDTAG</literal> should be similar to <literal>2.0.0.RELEASE</literal>;
- whereas, for a local build the <literal>-BUILDTAG</literal> may be completely
- omitted. Please consult the console output, web-based admin console, or log
- to determine the exact context path under which the web application has been deployed.
- </para>
- </section>
-
- <section id="formtags-case-study-war-shared-services">
- <title>Form Tags Shared Services WAR</title>
- <para>
- The next step in the migration is to deploy the services as a separate
- OSGi bundle which the WAR then references.
- The Form Tags sample has a single service <literal>UserManager</literal>.
- </para>
- <para>
- This scenario has two separate deployables, the <literal>service</literal> bundle and the WAR file.
- The following image shows the two separate source trees:
- </para>
- <para>
- <imagedata fileref="images/formtags-case-study-shared-services-eclipse.png" format="PNG"/>
- <note>Note that the WAR does not contain the <literal>.domain</literal> or
- <literal>.service</literal> packages as these will be imported from the separate service bundle.
- </note>
- </para>
- <section id="formtags-case-study-war-shared-services-service">
- <title>The Service Bundle</title>
- <para>
- The responsibility of the first bundle (<literal>formtags-shared-services-service</literal>)
- is to provide the API of the formtags service. This includes both the
- domain and the service API. In the same way that imports are defined
- in the <literal>/META-INF/MANIFEST.MF</literal>, so are exports.
- The following is the <literal>/META-INF/MANIFEST.MF</literal> listing from the service bundle.
+ <para>
+ Navigating to <literal>http://localhost:8080/formtags-shared-libs-BUILDTAG</literal>
+ should render the welcome page. Note that for the pre-packaged distributable,
+ the <literal>BUILDTAG</literal> should be similar to <literal>2.0.0.RELEASE</literal>;
+ whereas, for a local build the <literal>-BUILDTAG</literal> may be completely
+ omitted. Please consult the console output, web-based admin console, or log
+ to determine the exact context path under which the web application has been deployed.
+ </para>
+ </section>
+
+ <section id="formtags-case-study-war-shared-services">
+ <title>Form Tags Shared Services WAR</title>
+ <para>
+ The next step in the migration is to deploy the services as a separate
+ OSGi bundle which the WAR then references.
+ The Form Tags sample has a single service <literal>UserManager</literal>.
+ </para>
+ <para>
+ This scenario has two separate deployables, the <literal>service</literal> bundle and the WAR file.
+ The following image shows the two separate source trees:
+ </para>
+ <para>
+ <imagedata fileref="images/formtags-case-study-shared-services-eclipse.png" format="PNG"/>
+ <note>Note that the WAR does not contain the <literal>.domain</literal> or
+ <literal>.service</literal> packages as these will be imported from the separate service bundle.
+ </note>
+ </para>
+ <section id="formtags-case-study-war-shared-services-service">
+ <title>The Service Bundle</title>
+ <para>
+ The responsibility of the first bundle (<literal>formtags-shared-services-service</literal>)
+ is to provide the API of the formtags service. This includes both the
+ domain and the service API. In the same way that imports are defined
+ in the <literal>/META-INF/MANIFEST.MF</literal>, so are exports.
+ The following is the <literal>/META-INF/MANIFEST.MF</literal> listing from the service bundle.
<programlisting>
Manifest-Version: 1.0
Ant-Version: Apache Ant 1.7.0
@@ -271,113 +272,113 @@ Bundle-SymbolicName: org.springframework.showcase.formtags.service-shared-servic
ngframework.showcase.formtags.domain
Import-Library: org.springframework.spring;version="[2.5.4,3.1.0)"
</programlisting>
- </para>
- <para>
- The symbolic name of this bundle is
- <literal>org.springframework.showcase.formtags.service-shared-services</literal>.
- Note that the name of the bundle typically describes the package
- that the bundle primarily exports.
- If you take a look at the <literal>repository/bundles/ext</literal> in the @short.product.name@
- directory, you&rsquo;ll see that names are almost always indicative of the contents of the bundle.
- For this example, however, we have also appended
- &quot;<literal>-shared-services</literal>&quot;
- in order to avoid possible clashes with other bundle symbolic names.
- You will see later that the PAR also contains a service bundle.
- <note>
- In OSGi, the combination of <literal>Bundle-SymbolicName</literal>
- and <literal>Bundle-Version</literal> is used to uniquely identify
- a bundle within the OSGi container. Furthermore, when you deploy
- a bundle to the @product.name@, for example via the <literal>pickup</literal>
- directory, a bundle&rsquo;s filename is also used to uniquely identify it for
- the purpose of supporting <emphasis>hot deployment</emphasis> via
- the file system.
- </note>
- </para>
- <para>
- As well as exporting types (i.e. the domain classes and service
- API), the service bundle also publishes an implementation of the
- <literal>UserManager</literal>. The actual implementation is
- <literal>StubUserManager</literal>; however, that should remain an
- implementation detail of this bundle.
- </para>
- <para>
- The fact that this bundle publishes a service is not captured in
- the <literal>/META-INF/MANIFEST.MF</literal>, as it is a Spring-DM concept.
- The following image is of <literal>src/main/resources/spring</literal>.
- </para>
- <para><imagedata fileref="images/formtags-case-study-shared-services-service-resources.png" format="PNG"/></para>
- <para>
- As you can see there are two Spring configuration files: <literal>module-context.xml</literal> and
- <literal>osgi-context.xml</literal>.
- <tip>
- These names are abitrary; however, they follow an informal convention:
- <literal>module-context.xml</literal> typically bootstraps the Spring context
- (usually delegating to smaller fine grained context files inside another directory), whilst
- <literal>osgi-context.xml</literal> contains all the OSGi service exports and references.
- </tip>
- The following is a listing of <literal>module-context.xml</literal>.
+ </para>
+ <para>
+ The symbolic name of this bundle is
+ <literal>org.springframework.showcase.formtags.service-shared-services</literal>.
+ Note that the name of the bundle typically describes the package
+ that the bundle primarily exports.
+ If you take a look at the <literal>repository/bundles/ext</literal> in the @short.product.name@
+ directory, you&rsquo;ll see that names are almost always indicative of the contents of the bundle.
+ For this example, however, we have also appended
+ &quot;<literal>-shared-services</literal>&quot;
+ in order to avoid possible clashes with other bundle symbolic names.
+ You will see later that the PAR also contains a service bundle.
+ <note>
+ In OSGi, the combination of <literal>Bundle-SymbolicName</literal>
+ and <literal>Bundle-Version</literal> is used to uniquely identify
+ a bundle within the OSGi container. Furthermore, when you deploy
+ a bundle to the @product.name@, for example via the <literal>pickup</literal>
+ directory, a bundle&rsquo;s filename is also used to uniquely identify it for
+ the purpose of supporting <emphasis>hot deployment</emphasis> via
+ the file system.
+ </note>
+ </para>
+ <para>
+ As well as exporting types (i.e. the domain classes and service
+ API), the service bundle also publishes an implementation of the
+ <literal>UserManager</literal>. The actual implementation is
+ <literal>StubUserManager</literal>; however, that should remain an
+ implementation detail of this bundle.
+ </para>
+ <para>
+ The fact that this bundle publishes a service is not captured in
+ the <literal>/META-INF/MANIFEST.MF</literal>, as it is a Spring-DM concept.
+ The following image is of <literal>src/main/resources/spring</literal>.
+ </para>
+ <para><imagedata fileref="images/formtags-case-study-shared-services-service-resources.png" format="PNG"/></para>
+ <para>
+ As you can see there are two Spring configuration files: <literal>module-context.xml</literal> and
+ <literal>osgi-context.xml</literal>.
+ <tip>
+ These names are abitrary; however, they follow an informal convention:
+ <literal>module-context.xml</literal> typically bootstraps the Spring context
+ (usually delegating to smaller fine grained context files inside another directory), whilst
+ <literal>osgi-context.xml</literal> contains all the OSGi service exports and references.
+ </tip>
+ The following is a listing of <literal>module-context.xml</literal>.
<programlisting language="xml">
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
-
+
&lt;beans xmlns="http://www.springframework.org/schema/beans"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="
- http://www.springframework.org/schema/beans
- http://www.springframework.org/schema/beans/spring-beans-2.5.xsd"&gt;
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ http://www.springframework.org/schema/beans
+ http://www.springframework.org/schema/beans/spring-beans-2.5.xsd"&gt;
- &lt;bean id="userManager"
- class="org.springframework.showcase.formtags.service.internal.StubUserManager"/&gt;
+ &lt;bean id="userManager"
+ class="org.springframework.showcase.formtags.service.internal.StubUserManager"/&gt;
&lt;/beans&gt;
</programlisting>
- As you can see, this simply defines a bean called <literal>userManager</literal>.
- The following is a listing of <literal>osgi-context.xml</literal>.
+ As you can see, this simply defines a bean called <literal>userManager</literal>.
+ The following is a listing of <literal>osgi-context.xml</literal>.
<programlisting language="xml">
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;beans:beans
- xmlns="http://www.springframework.org/schema/osgi"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xmlns:beans="http://www.springframework.org/schema/beans"
- xsi:schemaLocation="http://www.springframework.org/schema/osgi
- http://www.springframework.org/schema/osgi/spring-osgi.xsd
- http://www.springframework.org/schema/beans
- http://www.springframework.org/schema/beans/spring-beans.xsd"&gt;
+ xmlns="http://www.springframework.org/schema/osgi"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns:beans="http://www.springframework.org/schema/beans"
+ xsi:schemaLocation="http://www.springframework.org/schema/osgi
+ http://www.springframework.org/schema/osgi/spring-osgi.xsd
+ http://www.springframework.org/schema/beans
+ http://www.springframework.org/schema/beans/spring-beans.xsd"&gt;
+
+ &lt;service ref="userManager"
+ interface="org.springframework.showcase.formtags.service.UserManager"/&gt;
- &lt;service ref="userManager"
- interface="org.springframework.showcase.formtags.service.UserManager"/&gt;
-
&lt;/beans:beans&gt;
</programlisting>
- This single bean definition exports the <literal>userManager</literal>
- defined in <literal>module-context.xml</literal> to the
- OSGi service registry and makes it available under the public
- <literal>org.springframework.showcase.formtags.service.UserManager</literal> API.
- </para>
- <para>
- The service bundle should now be ready to deploy on the @short.product.name@.
- So copy <literal>/dist/formtags-shared-services-services*</literal>
- to the <literal>SERVER_HOME/pickup</literal> directory.
- Output similar to the following should appear in the @short.product.name@&rsquo;s console:
- </para>
- <note>
- <para>The console output has been reformatted to fit this document.</para>
- </note>
+ This single bean definition exports the <literal>userManager</literal>
+ defined in <literal>module-context.xml</literal> to the
+ OSGi service registry and makes it available under the public
+ <literal>org.springframework.showcase.formtags.service.UserManager</literal> API.
+ </para>
+ <para>
+ The service bundle should now be ready to deploy on the @short.product.name@.
+ So copy <literal>/dist/formtags-shared-services-services*</literal>
+ to the <literal>SERVER_HOME/pickup</literal> directory.
+ Output similar to the following should appear in the @short.product.name@&rsquo;s console:
+ </para>
+ <note>
+ <para>The console output has been reformatted to fit this document.</para>
+ </note>
<programlisting>
[2009-07-01 15:05:03.511] fs-watcher
- &lt;SPDE0048I&gt; Processing 'CREATED' event for file 'formtags-shared-services-service-2.0.0.RELEASE.jar'.
+ &lt;SPDE0048I&gt; Processing 'CREATED' event for file 'formtags-shared-services-service-2.0.0.RELEASE.jar'.
[2009-07-01 15:05:03.688] fs-watcher
- &lt;SPDE0010I&gt; Deployment of 'org.springframework.showcase.formtags.service_shared_services' version '2.0.0.RELEASE' completed.
+ &lt;SPDE0010I&gt; Deployment of 'org.springframework.showcase.formtags.service_shared_services' version '2.0.0.RELEASE' completed.
</programlisting>
- </section>
- <section id="formtags-case-study-war-shared-services-war">
- <title>Accessing the Service and Types from the WAR</title>
- <para>
- The WAR file now needs to access the types and service exported
- by the service bundle. The following listing is the WAR&rsquo;s
- <literal>/META-INF/MANIFEST.MF</literal> which imports the types
- exported by the service bundle. The <literal>Import-Bundle</literal>
- statement has also been extended to import <literal>org.springframework.osgi.core</literal>,
- which is necessary in order to load an OSGi-enabled <literal>WebApplicationContext</literal>.
+ </section>
+ <section id="formtags-case-study-war-shared-services-war">
+ <title>Accessing the Service and Types from the WAR</title>
+ <para>
+ The WAR file now needs to access the types and service exported
+ by the service bundle. The following listing is the WAR&rsquo;s
+ <literal>/META-INF/MANIFEST.MF</literal> which imports the types
+ exported by the service bundle. The <literal>Import-Bundle</literal>
+ statement has also been extended to import <literal>org.springframework.osgi.core</literal>,
+ which is necessary in order to load an OSGi-enabled <literal>WebApplicationContext</literal>.
<programlisting>
Manifest-Version: 1.0
Ant-Version: Apache Ant 1.7.0
@@ -391,306 +392,300 @@ Import-Library: org.springframework.spring;version="[2.5.4,3.1.0)"
Import-Bundle: com.springsource.org.apache.taglibs.standard;version="1
.1.2",<emphasis role="bold">org.springframework.osgi.core</emphasis>
</programlisting>
- </para>
- <para>
- In addition to importing the exported types of the service bundle,
- the WAR must also obtain a reference to the <literal>UserManager</literal>
- published by the service bundle. The following image shows the directory
- structure of the Shared Services WAR.
- </para>
- <para><imagedata fileref="images/formtags-case-study-shared-services-war-resources.png" format="PNG"/></para>
- <para>
- As you can see in the above image, the Form Tags Shared Services WAR&rsquo;s
- <literal>/WEB-INF/web.xml</literal> directory contains a standard <literal>web.xml</literal>
- deployment descriptor, <literal>applicationContext.xml</literal> which defines the configuration
- for the <emphasis>root</emphasis> <literal>WebApplicationContext</literal>, and
- <literal>formtags-servlet.xml</literal> which defines the configuration specific to the
- configured <emphasis>formtags</emphasis> <literal>DispatcherServlet</literal>.
- </para>
- <para>
- As is typical for Spring MVC based web applications, you configure a <literal>ContextLoaderListener</literal>
- in <literal>web.xml</literal> to load your root <literal>WebApplicationContext</literal>; however, to enable your
- <literal>WebApplicationContext</literal> to be able to reference services from the OSGi Service Registry,
- you must explicitly set the <literal>contextClass</literal> Servlet context parameter to the fully qualified
- class name of a <literal>ConfigurableWebApplicationContext</literal> which is OSGi-enabled. When deploying
- Shared Services WARs to the @product.name@, you should use
- <literal>org.eclipse.virgo.web.dm.ServerOsgiBundleXmlWebApplicationContext</literal>. This will
- then enable the use of Spring-DM&rsquo;s <literal>&lt;reference ... /&gt;</literal> within your root
- <literal>WebApplicationContext</literal> (i.e., in <literal>applicationContext.xml</literal>).
- The following listing is an excerpt from <literal>/WEB-INF/web.xml</literal>.
- </para>
+ </para>
+ <para>
+ In addition to importing the exported types of the service bundle,
+ the WAR must also obtain a reference to the <literal>UserManager</literal>
+ published by the service bundle. The following image shows the directory
+ structure of the Shared Services WAR.
+ </para>
+ <para><imagedata fileref="images/formtags-case-study-shared-services-war-resources.png" format="PNG"/></para>
+ <para>
+ As you can see in the above image, the Form Tags Shared Services WAR&rsquo;s
+ <literal>/WEB-INF/web.xml</literal> directory contains a standard <literal>web.xml</literal>
+ deployment descriptor, <literal>applicationContext.xml</literal> which defines the configuration
+ for the <emphasis>root</emphasis> <literal>WebApplicationContext</literal>, and
+ <literal>formtags-servlet.xml</literal> which defines the configuration specific to the
+ configured <emphasis>formtags</emphasis> <literal>DispatcherServlet</literal>.
+ </para>
+ <para>
+ As is typical for Spring MVC based web applications, you configure a <literal>ContextLoaderListener</literal>
+ in <literal>web.xml</literal> to load your root <literal>WebApplicationContext</literal>; however, to enable your
+ <literal>WebApplicationContext</literal> to be able to reference services from the OSGi Service Registry,
+ you must explicitly set the <literal>contextClass</literal> Servlet context parameter to the fully qualified
+ class name of a <literal>ConfigurableWebApplicationContext</literal> which is OSGi-enabled. When deploying
+ Shared Services WARs to the @product.name@, you should use
+ <literal>org.eclipse.virgo.web.dm.ServerOsgiBundleXmlWebApplicationContext</literal>. This will
+ then enable the use of Spring-DM&rsquo;s <literal>&lt;reference ... /&gt;</literal> within your root
+ <literal>WebApplicationContext</literal> (i.e., in <literal>applicationContext.xml</literal>).
+ The following listing is an excerpt from <literal>/WEB-INF/web.xml</literal>.
+ </para>
<programlisting language="xml"><![CDATA[
- <context-param>
- <param-name>contextClass</param-name>
- <param-value>org.eclipse.virgo.web.dm.ServerOsgiBundleXmlWebApplicationContext</param-value>
- </context-param>
+ <context-param>
+ <param-name>contextClass</param-name>
+ <param-value>org.eclipse.virgo.web.dm.ServerOsgiBundleXmlWebApplicationContext</param-value>
+ </context-param>
- <listener>
- <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
- </listener>
+ <listener>
+ <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
+ </listener>
]]></programlisting>
- <para>
- The Form Tags Shared Services WAR contains a <literal>/WEB-INF/applicationContext.xml</literal>
- file which is the default configuration location used to create the <emphasis>root</emphasis>
- <literal>WebApplicationContext</literal> for Spring MVC&rsquo;s <literal>ContextLoaderListener</literal>.
- <note>
- As already mentioned, in the OSGi world, bundle configuration
- takes place in the root <literal>/META-INF/</literal> directory.
- Typically Spring-DM powered configuration files will live
- there as well (e.g., in <literal>/META-INF/spring/*.xml</literal>).
- In a WAR, however, the root <literal>WebApplicationContext</literal>
- loaded by <literal>ContextLoaderListener</literal> and the <literal>DispatcherServlet&rsquo;s</literal>
- application context typically live in <literal>/WEB-INF/</literal>.
- </note>
- The following is the listing of the WAR&rsquo;s <literal>/WEB-INF/applicationContext.xml</literal>.
+ <para>
+ The Form Tags Shared Services WAR contains a <literal>/WEB-INF/applicationContext.xml</literal>
+ file which is the default configuration location used to create the <emphasis>root</emphasis>
+ <literal>WebApplicationContext</literal> for Spring MVC&rsquo;s <literal>ContextLoaderListener</literal>.
+ <note>
+ As already mentioned, in the OSGi world, bundle configuration
+ takes place in the root <literal>/META-INF/</literal> directory.
+ Typically Spring-DM powered configuration files will live
+ there as well (e.g., in <literal>/META-INF/spring/*.xml</literal>).
+ In a WAR, however, the root <literal>WebApplicationContext</literal>
+ loaded by <literal>ContextLoaderListener</literal> and the <literal>DispatcherServlet&rsquo;s</literal>
+ application context typically live in <literal>/WEB-INF/</literal>.
+ </note>
+ The following is the listing of the WAR&rsquo;s <literal>/WEB-INF/applicationContext.xml</literal>.
<programlisting language="xml">
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;beans:beans
xmlns="http://www.springframework.org/schema/osgi"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:beans="http://www.springframework.org/schema/beans"
- xsi:schemaLocation="http://www.springframework.org/schema/osgi
- http://www.springframework.org/schema/osgi/spring-osgi.xsd
- http://www.springframework.org/schema/beans
- http://www.springframework.org/schema/beans/spring-beans.xsd"&gt;
+ xsi:schemaLocation="http://www.springframework.org/schema/osgi
+ http://www.springframework.org/schema/osgi/spring-osgi.xsd
+ http://www.springframework.org/schema/beans
+ http://www.springframework.org/schema/beans/spring-beans.xsd"&gt;
+
+ &lt;reference id="userManager"
+ interface="org.springframework.showcase.formtags.service.UserManager"/&gt;
- &lt;reference id="userManager"
- interface="org.springframework.showcase.formtags.service.UserManager"/&gt;
-
&lt;/beans:beans&gt;
</programlisting>
- The single bean declaration is retrieving a service that implements
- the <literal>org.springframework.showcase.formtags.service.UserManager</literal>
- API from the OSGi Service Registry.
- <tip>
- You might have been expecting a reference to the service bundle,
- but that isn&rsquo;t how OSGi works. OSGi provides a service
- registry, and this bean definition is accessing a service in that
- registry that meets the specified restriction (i.e. implements
- the specified interface). This leads to a very loosely coupled
- programming model: the WAR really doesn&rsquo;t care where the implementation
- comes from.
- </tip>
- <tip>
- What happens if there is no service at runtime?
- What if there are multiple services that match the criteria?
- Spring-DM provides a lot of configuration options, including
- whether or not the reference is <emphasis>mandatory</emphasis>,
- how long to wait for a service reference, etc. Please consult the
- <ulink url="http://www.springframework.org/osgi/">Spring Dynamic Modules for OSGi</ulink>
- home page for further information.
- </tip>
- <para>
- One of the benefits of programming to interfaces is that you are
- decoupled from the actual implementation; Spring-DM provides a proxy. This
- has enormous benefits including the ability to dynamically refresh individual bundles without
- cascading that refresh to unrelated bundles.
- </para>
- </para>
- <para>
- To deploy the WAR, copy <literal>/dist/formtags-shared-services-war*</literal>
- to the <literal>SERVER_HOME/pickup</literal> directory.
- You should then see console output similar to the following:
- </para>
- <note>
- <para>The console output has been reformatted to fit this document.</para>
- </note>
+ The single bean declaration is retrieving a service that implements
+ the <literal>org.springframework.showcase.formtags.service.UserManager</literal>
+ API from the OSGi Service Registry.
+ <tip>
+ You might have been expecting a reference to the service bundle,
+ but that isn&rsquo;t how OSGi works. OSGi provides a service
+ registry, and this bean definition is accessing a service in that
+ registry that meets the specified restriction (i.e. implements
+ the specified interface). This leads to a very loosely coupled
+ programming model: the WAR really doesn&rsquo;t care where the implementation
+ comes from.
+ </tip>
+ <tip>
+ What happens if there is no service at runtime?
+ What if there are multiple services that match the criteria?
+ Spring-DM provides a lot of configuration options, including
+ whether or not the reference is <emphasis>mandatory</emphasis>,
+ how long to wait for a service reference, etc. Please consult the
+ <ulink url="http://www.springframework.org/osgi/">Spring Dynamic Modules for OSGi</ulink>
+ home page for further information.
+ </tip>
+ <para>
+ One of the benefits of programming to interfaces is that you are
+ decoupled from the actual implementation; Spring-DM provides a proxy. This
+ has enormous benefits including the ability to dynamically refresh individual bundles without
+ cascading that refresh to unrelated bundles.
+ </para>
+ </para>
+ <para>
+ To deploy the WAR, copy <literal>/dist/formtags-shared-services-war*</literal>
+ to the <literal>SERVER_HOME/pickup</literal> directory.
+ You should then see console output similar to the following:
+ </para>
+ <note>
+ <para>The console output has been reformatted to fit this document.</para>
+ </note>
<programlisting>
[2009-07-01 15:09:19.819] fs-watcher
- &lt;SPDE0048I&gt; Processing 'CREATED' event for file 'formtags-shared-services-war-2.0.0.RELEASE.war'.
+ &lt;SPDE0048I&gt; Processing 'CREATED' event for file 'formtags-shared-services-war-2.0.0.RELEASE.war'.
[2009-07-01 15:09:20.167] fs-watcher
- &lt;SPDE0010I&gt; Deployment of 'org.springframework.showcase.formtags.web_shared_services' version '2' completed.
+ &lt;SPDE0010I&gt; Deployment of 'org.springframework.showcase.formtags.web_shared_services' version '2' completed.
[2009-07-01 15:09:20.168] Thread-20
- &lt;SPWE0000I&gt; Starting web bundle '/formtags-shared-services-war-2.0.0.RELEASE'.
+ &lt;SPWE0000I&gt; Starting web bundle '/formtags-shared-services-war-2.0.0.RELEASE'.
[2009-07-01 15:09:20.647] Thread-20
&lt;SPWE0001I&gt; Started web bundle '/formtags-shared-services-war-2.0.0.RELEASE'.
</programlisting>
- Navigating to the appropriate link should render the welcome page.
- </section>
- </section>
-
- <section id="formtags-case-study-par">
- <title>Form Tags PAR</title>
- <para>
- The final step in the migration is that of a full blown
- OSGi application with web support. The @product.name@ introduces a
- new packaging and deployment format: the PAR.
-
- A PAR is a standard JAR with a &quot;<literal>.par</literal>&quot;
- file extension which contains all of the modules of your
- application (e.g., service, domain, and infrastructure bundles
- as well as a WAR for web applications) in a single deployment unit.
- Moreover, a PAR defines both a physical and logical application boundary.
- </para>
- <para>
- The PAR sample is comprised of four directories, as shown below.
- </para>
- <para><imagedata fileref="images/formtags-case-study-par-sample.png" format="PNG"/></para>
- <para>
- The <literal>formtags-par</literal> directory is a build project that
- understands how to create the PAR from its constituent bundles.
- </para>
- <section id="formtags-case-study-par-granularity">
- <title>Granularity of the PAR</title>
- <para>
- Achieving the appropriate level of granularity for your OSGi
- application is more of an art than a science. It helps to look
- at the different requirements:
- <table id="formtags-case-study-par-granularity-drivers-table" colsep="1" frame="all" rowsep="1">
- <title>Granularity drivers</title>
- <tgroup cols="2">
- <colspec colwidth="2*" />
- <colspec colwidth="3*" />
- <thead>
- <row>
- <entry>Requirement</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>Domain/Technical Layering</entry>
- <entry>
- Applications can be split either by domain (i.e.,
- by use case or <emphasis>vertically</emphasis>) or
- by their technical layers (i.e., <emphasis>horizontally</emphasis>).
- Since the Form Tags application essentially has only
- a single use case, the bundles are split by technical layering
- (i.e., domain, service, and web).
- </entry>
- </row>
- <row>
- <entry>Refreshability</entry>
- <entry>
- A major benefit of OSGi is that of refreshability: if one bundle
- is changed, only bundles that have a dependency upon
- the exported types need to be refreshed. This has a high impact
- on development time costs as well as production
- costs. However, this can lead to lots of smaller, fine grained
- bundles. An example of this granularity would be to
- separate out the service API and implementation into two different
- bundles. This means that a change in the implementation
- wouldn&rsquo;t require any other bundles to be refreshed.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- Ultimately the right level of granularity will depend upon your particular application and team.
- <note>
- This topic will be revisited in greater detail later in the
- Programmer Guide in a chapter covering how to build a PAR from
- scratch.
- </note>
- </para>
- </section>
- <section id="formtags-case-study-par-domain-and-service">
- <title>Domain and Service Bundles</title>
- <para>
- The service bundle is identical (except for the <literal>Bundle-SymbolicName</literal>) to that
- in the shared-services variation of the sample.
- The PAR has also separated out the domain classes into their own bundle.
- When layering by technical considerations, it is again
- somewhat of an unofficial convention to have a
- <literal>.domain</literal> bundle.
- </para>
- </section>
- <section id="formtags-case-study-par-par">
- <title>Constructing the PAR</title>
- <para>
- Finally we need to construct the PAR itself.
- The following are the contents of the exploded PAR.
- </para>
- <para><imagedata fileref="images/formtags-case-study-par-exploded.png" format="PNG"/></para>
- <para>
- You can see that the PAR itself doesn&rsquo;t contain any resources or
- Java classes: it simply packages together a related set of bundles
- as a single, logical unit.
- </para>
- <para>
- The PAR does however, contain its own <literal>/META-INF/MANIFEST.MF</literal>.
+ Navigating to the appropriate link should render the welcome page.
+ </section>
+ </section>
+
+ <section id="formtags-case-study-par">
+ <title>Form Tags PAR</title>
+ <para>
+ The final step in the migration is that of a full blown
+ OSGi application with web support. The @product.name@ introduces a
+ new packaging and deployment format: the PAR.
+
+ A PAR is a standard JAR with a &quot;<literal>.par</literal>&quot;
+ file extension which contains all of the modules of your
+ application (e.g., service, domain, and infrastructure bundles
+ as well as a WAR for web applications) in a single deployment unit.
+ Moreover, a PAR defines both a physical and logical application boundary.
+ </para>
+ <para>
+ The PAR sample is comprised of four directories, as shown below.
+ </para>
+ <para><imagedata fileref="images/formtags-case-study-par-sample.png" format="PNG"/></para>
+ <para>
+ The <literal>formtags-par</literal> directory is a build project that
+ understands how to create the PAR from its constituent bundles.
+ </para>
+ <section id="formtags-case-study-par-granularity">
+ <title>Granularity of the PAR</title>
+ <para>
+ Achieving the appropriate level of granularity for your OSGi
+ application is more of an art than a science. It helps to look
+ at the different requirements:
+ <table id="formtags-case-study-par-granularity-drivers-table" colsep="1" frame="all" rowsep="1">
+ <title>Granularity drivers</title>
+ <tgroup cols="2">
+ <colspec colwidth="2*" />
+ <colspec colwidth="3*" />
+ <thead>
+ <row>
+ <entry>Requirement</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Domain/Technical Layering</entry>
+ <entry>
+ Applications can be split either by domain (i.e.,
+ by use case or <emphasis>vertically</emphasis>) or
+ by their technical layers (i.e., <emphasis>horizontally</emphasis>).
+ Since the Form Tags application essentially has only
+ a single use case, the bundles are split by technical layering
+ (i.e., domain, service, and web).
+ </entry>
+ </row>
+ <row>
+ <entry>Refreshability</entry>
+ <entry>
+ A major benefit of OSGi is that of refreshability: if one bundle
+ is changed, only bundles that have a dependency upon
+ the exported types need to be refreshed. This has a high impact
+ on development time costs as well as production
+ costs. However, this can lead to lots of smaller, fine grained
+ bundles. An example of this granularity would be to
+ separate out the service API and implementation into two different
+ bundles. This means that a change in the implementation
+ wouldn&rsquo;t require any other bundles to be refreshed.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ Ultimately the right level of granularity will depend upon your particular application and team.
+ </para>
+ </section>
+ <section id="formtags-case-study-par-domain-and-service">
+ <title>Domain and Service Bundles</title>
+ <para>
+ The service bundle is identical (except for the <literal>Bundle-SymbolicName</literal>) to that
+ in the shared-services variation of the sample.
+ The PAR has also separated out the domain classes into their own bundle.
+ When layering by technical considerations, it is again
+ somewhat of an unofficial convention to have a
+ <literal>.domain</literal> bundle.
+ </para>
+ </section>
+ <section id="formtags-case-study-par-par">
+ <title>Constructing the PAR</title>
+ <para>
+ Finally we need to construct the PAR itself.
+ The following are the contents of the exploded PAR.
+ </para>
+ <para><imagedata fileref="images/formtags-case-study-par-exploded.png" format="PNG"/></para>
+ <para>
+ You can see that the PAR itself doesn&rsquo;t contain any resources or
+ Java classes: it simply packages together a related set of bundles
+ as a single, logical unit.
+ </para>
+ <para>
+ The PAR does however, contain its own <literal>/META-INF/MANIFEST.MF</literal>.
<programlisting>
Manifest-Version: 1.0
Application-SymbolicName: org.springframework.showcase.formtags-par
Application-Version: 1.0.0
Application-Name: FormTags Showcase Application (PAR)
</programlisting>
- For more information on the contents of the PAR&rsquo;s
- <literal>/META-INF/MANIFEST.MF</literal>, please consult
- <xref linkend="developing-applications"/>.
- </para>
- <para>
- You can now deploy the PAR on the @short.product.name@, for example by copying
- <literal>/dist/formtags-par*.par</literal> to the @short.product.name@&rsquo;s
- <literal>pickup</literal> directory.
- You should then see console output similar to the following:
- </para>
- <note>
- <para>The console output has been reformatted to fit this document.</para>
- </note>
+ For more information on the contents of the PAR&rsquo;s
+ <literal>/META-INF/MANIFEST.MF</literal>, please consult
+ <xref linkend="developing-applications"/>.
+ </para>
+ <para>
+ You can now deploy the PAR on the @short.product.name@, for example by copying
+ <literal>/dist/formtags-par*.par</literal> to the @short.product.name@&rsquo;s
+ <literal>pickup</literal> directory.
+ You should then see console output similar to the following:
+ </para>
+ <note>
+ <para>The console output has been reformatted to fit this document.</para>
+ </note>
<programlisting>
[2009-07-01 15:13:43.306] fs-watcher
- &lt;SPDE0048I&gt; Processing 'CREATED' event for file 'formtags-par-2.0.0.RELEASE.par'.
+ &lt;SPDE0048I&gt; Processing 'CREATED' event for file 'formtags-par-2.0.0.RELEASE.par'.
[2009-07-01 15:13:44.060] fs-watcher
- &lt;SPDE0010I&gt; Deployment of 'formtags-par' version '2.0.0.RELEASE' completed.
+ &lt;SPDE0010I&gt; Deployment of 'formtags-par' version '2.0.0.RELEASE' completed.
[2009-07-01 15:13:44.068] Thread-20
- &lt;SPWE0000I&gt; Starting web bundle '/formtags-par'.
+ &lt;SPWE0000I&gt; Starting web bundle '/formtags-par'.
[2009-07-01 15:13:45.212] Thread-20
- &lt;SPWE0001I&gt; Started web bundle '/formtags-par'.
+ &lt;SPWE0001I&gt; Started web bundle '/formtags-par'.
</programlisting>
- <para>
- Navigate to <ulink url="http://localhost:8080/formtags-par" /> to see the welcome page.
- </para>
- <tip>
- Note that the web application&rsquo;s context path is explicitly defined via the
- <literal>Web-ContextPath</literal> manifest header in
- <literal>/META-INF/MANIFEST.MF</literal> of the web module within
- the PAR.
- </tip>
- </section>
- </section>
- <section id="formtags-case-study-summary">
- <title>Summary of the Form Tags Migration</title>
- <para>
- The @product.name@ provides out-of-the-box support for deploying
- standard Java EE WAR files. In addition support for
- <emphasis>Shared Libraries</emphasis> and <emphasis>Shared Services</emphasis>
- WAR formats provides a logical migration path away from standard,
- monolithic WARs toward OSGi-enable Web applications. The PAR packaging
- and deployment format enables truly fine-grained, loosely-coupled, and
- efficient application development. In general, the migration steps
- presented in this chapter are fairly straightforward, but developers
- should set aside time for some up-front design of the bundles themselves.
- </para>
- <para>
- It is recommended that you take another sample application or
- indeed your own small application and go through this migration
- process yourself. This will help you better understand the concepts and
- principles at work. In addition, it is highly recommended that you
- familiarize yourself with the Eclipse-based
- <emphasis>@product.name@ Tools</emphasis> support which is discussed in
- <xref linkend="tooling" />.
- </para>
- </section>
-
- <section id="formtags-case-study-as-plan">
- <title>Form Tags as a plan</title>
- <para>
- Plans (see <xref linkend="developing-applications-plans"/>)
- allow us to package and deploy the Form Tags application in a more flexible way.
- Instead of packaging all the bundles of the application into a single PAR file, each bundle can be placed in the repository
- and referred to in a <emphasis>plan</emphasis>.
- </para>
- <para>
+ <para>
+ Navigate to <ulink url="http://localhost:8080/formtags-par" /> to see the welcome page.
+ </para>
+ <tip>
+ Note that the web application&rsquo;s context path is explicitly defined via the
+ <literal>Web-ContextPath</literal> manifest header in <literal>/META-INF/MANIFEST.MF</literal>
+ of the Web application bundle within the PAR.
+ </tip>
+ </section>
+ </section>
+ <section id="formtags-case-study-summary">
+ <title>Summary of the Form Tags Migration</title>
+ <para>
+ The @product.name@ provides out-of-the-box support for deploying
+ standard Java EE WAR files. In addition support for
+ <emphasis>Shared Libraries</emphasis> and <emphasis>Shared Services</emphasis>
+ WAR formats provides a logical migration path away from standard,
+ monolithic WARs toward OSGi-enable Web applications. The PAR packaging
+ and deployment format enables truly fine-grained, loosely-coupled, and
+ efficient application development. In general, the migration steps
+ presented in this chapter are fairly straightforward, but developers
+ should set aside time for some up-front design of the bundles themselves.
+ </para>
+ <para>
+ It is recommended that you take another sample application or
+ indeed your own small application and go through this migration
+ process yourself. This will help you better understand the concepts and
+ principles at work. In addition, it is highly recommended that you
+ familiarize yourself with the Eclipse-based
+ <emphasis>@product.name@ Tools</emphasis> support which is discussed in
+ <xref linkend="tooling" />.
+ </para>
+ </section>
+
+ <section id="formtags-case-study-as-plan">
+ <title>Form Tags as a plan</title>
+ <para>
+ Plans (see <xref linkend="developing-applications-plans"/>)
+ allow us to package and deploy the Form Tags application in a more flexible way.
+ Instead of packaging all the bundles of the application into a single PAR file, each bundle can be placed in the repository
+ and referred to in a <emphasis>plan</emphasis>.
+ </para>
+ <para>
The bundles to be placed in a repository in the chain (for example, <literal>repository/usr</literal>) are:
<programlisting>org.springframework.showcase.formtags.domain-2.0.0.RELEASE.jar
org.springframework.showcase.formtags.service-2.0.0.RELEASE.jar
org.springframework.showcase.formtags.web-2.0.0.RELEASE.war
</programlisting>
- which are just those files which were part of the PAR.
- </para>
- <para>
- Here is the contents of a suitable plan file for the Form Tags example:
+ which are just those files which were part of the PAR.
+ </para>
+ <para>
+ Here is the contents of a suitable plan file for the Form Tags example:
<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<plan name="formtags.plan" version="2.0.0" scoped="true" atomic="true"
xmlns="http://www.eclipse.org/virgo/schema/plan"
@@ -699,20 +694,20 @@ org.springframework.showcase.formtags.web-2.0.0.RELEASE.war
http://www.eclipse.org/virgo/schema/plan
http://www.eclipse.org/virgo/schema/plan/eclipse-virgo-plan.xsd">
- <artifact type="bundle" name="org.springframework.showcase.formtags.domain_par" version="[2.0,2.1)"/>
- <artifact type="bundle" name="org.springframework.showcase.formtags.service_par" version="[2.0,2.1)"/>
- <artifact type="war" name="org.springframework.showcase.formtags.web_par" version="[2.0,2.1)"/>
+ <artifact type="bundle" name="org.springframework.showcase.formtags.domain_par" version="[2.0,2.1)"/>
+ <artifact type="bundle" name="org.springframework.showcase.formtags.service_par" version="[2.0,2.1)"/>
+ <artifact type="bundle" name="org.springframework.showcase.formtags.web_par" version="[2.0,2.1)"/>
</plan>]]></programlisting>
- where we have chosen to use any of the artifacts in the version range [2.0,2.1).
- This plan (as a file called, for example, <literal>formtags.plan</literal>)
- can be deployed in any of the normal ways (for example, dropped in
+ where we have chosen to use any of the artifacts in the version range [2.0,2.1).
+ This plan (as a file called, for example, <literal>formtags.plan</literal>)
+ can be deployed in any of the normal ways (for example, dropped in
the <literal>pickup</literal> directory).
- </para>
- <para>
- When the plan is deployed, the artifacts it references are installed from the repository and deployed in the order given in the plan file.
- Because this plan is scoped and atomic, the collection is given an application scope and is started and stopped as a single unit.
- </para>
- </section>
-
+ </para>
+ <para>
+ When the plan is deployed, the artifacts it references are installed from the repository and deployed in the order given in the plan file.
+ Because this plan is scoped and atomic, the collection is given an application scope and is started and stopped as a single unit.
+ </para>
+ </section>
+
</chapter>
diff --git a/programmer-guide/src/tooling.xml b/programmer-guide/src/tooling.xml
index 289faa0..4106f39 100644
--- a/programmer-guide/src/tooling.xml
+++ b/programmer-guide/src/tooling.xml
@@ -6,8 +6,7 @@
<para>
SpringSource provides a set of plug-ins for the Eclipse IDE that streamline the development
lifecycle of OSGi bundles and PAR applications. The @product.name@ Tools build on top
- of the Eclipse Web Tools Project (WTP) and Spring IDE, the open-source Spring development
- tool set.
+ of the Eclipse Web Tools Project (WTP).
</para>
<para>
The @product.name@ Tools support the creation of new OSGi bundle and PAR projects within Eclipse, and the
@@ -19,7 +18,7 @@
<para>
Currently the Tools support Eclipse 3.5 and Eclipse 3.6 with the corresponding version of WTP. Downloading and
unzipping the <ulink url="http://www.eclipse.org/downloads/">Eclipse IDE for Java EE Developers</ulink> is the
- easiest way to start.
+ easiest way to start.
</para>
<para>
You may like to change the Eclipse launcher options to increase the values of <literal>-XX:MaxPermSize</literal>,
@@ -43,7 +42,7 @@
</listitem>
<listitem>
<para>
- <literal>http://dist.springsource.com/milestone/TOOLS/update/e3.6/</literal>
+ <literal>http://dist.springsource.com/milestone/TOOLS/update/e3.6/</literal> (recommended at the time of writing)
</para>
</listitem>
<listitem>
@@ -67,7 +66,7 @@
<section id="tooling-running">
<title>Running a @product.name@ instance within Eclipse</title>
<para>
- After installing the Tools from the update site outlined in the previous section, you
+ After installing the Tools from the update site outlined in the previous section, you
will be able to configure an instance of the @short.product.name@ inside Eclipse.
</para>
<para>
@@ -80,7 +79,7 @@
<guimenuitem>Servers</guimenuitem>
</menuchoice>).
You can now right-click in the view and select "<menuchoice><guimenu>New</guimenu><guimenuitem>Server</guimenuitem></menuchoice>".
- This will bring up a "New Server" dialog. Select "@product.name@ v2.0 Server"
+ This will bring up a "New Server" dialog. Select "@product.name@ v2.1 Server"
in the "Virgo" category and click "<guibutton>Next</guibutton>".
</para>
<para>
@@ -92,7 +91,7 @@
entry in the Servers view.
</para>
<para>
- To start, stop, and debug the created @product.name@ instance use the toolbar or the context
+ To start, stop, and debug the created @product.name@ instance use the toolbar or the context
menu actions of the Servers view.
</para>
<para>
@@ -103,7 +102,7 @@
<title>Bundle and Library Provisioning</title>
<para>
After successful configuration of an instance of the @product.name@ in Eclipse you can use
- the Repository Browser to very easily install bundles and libraries from the remote
+ the Repository Browser to very easily install bundles and libraries from the remote
SpringSource Enterprise Bundle Repository.
</para>
<para>
@@ -117,26 +116,26 @@
</para>
<para>
The left section of the Repository Browser allows the user to run searches against the
- @ebr@ and displays matching results. The search can
+ @ebr@ and displays matching results. The search can
take parts of bundle symbolic names, class or package names and allows wildcards such as
- &lsquo;?&rsquo; and &lsquo;*&rsquo;. By selecting the checkbox left to a matching bundle and/or library and clicking
- the "Download" button it is very easy to install new bundles in the @product.name@. For your
- convenience JARs containing the bundle source code can be automatically downloaded as well.
+ &lsquo;?&rsquo; and &lsquo;*&rsquo;. By selecting the checkbox left to a matching bundle and/or library and clicking
+ the "Download" button it is very easy to install new bundles in the @product.name@. For your
+ convenience JARs containing the bundle source code can be automatically downloaded as well.
</para>
<para>
Clicking the "Download" button will trigger an Eclipse background job that will download
- the selected repository artifacts and -- if desired -- the source JARs one after another.
+ the selected repository artifacts and -- if desired -- the source JARs one after another.
</para>
<para>
The section on the right displays the currently installed bundles and libraries. Bundles
with available sources are visually marked. You can very easily download missing source
- JARs by using the "Install Sources" button.
+ JARs by using the "Install Sources" button.
</para>
</section>
<section id="tooling-config">
<title>Setting up Eclipse Projects</title>
<para>
- The @product.name@ supports different deployment units as discussed earlier in this guide. The
+ The @product.name@ supports different deployment units as discussed earlier in this guide. The
Tools define specific project types to support the development of OSGi and PAR projects.
</para>
<section id="tooling-config-creating-new-projects">
@@ -144,13 +143,13 @@
<para>
There are two New Project Wizards available within Eclipse that allow for creating
new OSGi bundle and PAR projects. The projects created by the wizards are deployable
- to the integrated @short.product.name@ instance without requiring any additional steps.
+ to the integrated @short.product.name@ instance without requiring any additional steps.
</para>
<para>
<imagedata fileref="images/tooling-new-project-wizards.png" format="PNG" />
</para>
<para>
- Those wizards create the required <code>MANIFEST.MF</code> file and appropriate manifest
+ Those wizards create the required <code>MANIFEST.MF</code> file and appropriate manifest
headers.
</para>
</section>
@@ -158,7 +157,7 @@
<title>Migrating existing Java Projects</title>
<para>
To migrate an existing Java Project to be used with the @short.product.name@, the Tools
- provide a migration action that adds the required meta data to the project.
+ provide a migration action that adds the required meta data to the project.
The migration will not change your project&rsquo;s source layout.
</para>
<para>
@@ -166,33 +165,41 @@
"<menuchoice><guimenu>Spring Tools</guimenu><guimenuitem>Convert to OSGi bundle project</guimenuitem></menuchoice>".
</para>
</section>
+ <section id="tooling-config-creating-plan-projects">
+ <title>Creating Plan Projects</title>
+ <para>
+ This is done by creating a new <emphasis>faceted</emphasis> project and then applying the OSGi Plan facet.
+ This will give you access to features such as content completion when editing <literal>.plan</literal> files
+ and deployment to configured servers from within the IDE.
+ </para>
+ </section>
</section>
<section id="tooling-developing" >
<title>Developing OSGi Bundles</title>
<para>
- The Tools provide functionality that makes developing OSGi bundles,
- especially the editing of MANIFEST.MF files, easier.
+ The Tools provide functionality that makes developing OSGi bundles,
+ especially the editing of MANIFEST.MF files, easier.
</para>
<section id="tooling-developing-resolving-bundle-dependencies">
<title>Resolving Bundle Dependencies</title>
<para>
- While working with OSGi bundles, one of the most interesting and challenging aspects is defining
- the package, bundle, and library imports in the manifest and then keeping this in sync
- with your compile classpath either in Ant and Maven or Eclipse. In most cases you would typically
- be required to manually set up the Eclipse classpath. Ultimately, the Eclipse compile
+ While working with OSGi bundles, one of the most interesting and challenging aspects is defining
+ the package, bundle, and library imports in the manifest and then keeping this in sync
+ with your compile classpath either in Ant and Maven or Eclipse. In most cases you would typically
+ be required to manually set up the Eclipse classpath. Ultimately, the Eclipse compile
classpath is still different from the bundle runtime classpath, as normally an entire
JAR file is being made available on the Eclipse classpath but not necessarily at runtime
- due to the explicit visibility rules defined in <code>Import-Package</code> headers.
+ due to the explicit visibility rules defined in <code>Import-Package</code> headers.
</para>
<para>
- The Tools address this problem by providing an Eclipse classpath container that
+ The Tools address this problem by providing an Eclipse classpath container that
uses an @product.name@-specific dependency resolution mechanism. This classpath
container makes resolved dependencies available on the project&rsquo;s classpath but allows
- only access to those package that are imported explicitly (e.g., via <code>Import-Package</code>)
+ only access to those package that are imported explicitly (e.g., via <code>Import-Package</code>)
or implicitly by using <code>Import-Library</code> or <code>Import-Bundle</code>.
</para>
<para>
- To use the automatic dependency resolution, an OSGi bundle or PAR project needs to be
+ To use the automatic dependency resolution, an OSGi bundle or PAR project needs to be
targeted to a configured @product.name@ instance. This can be done from the project&rsquo;s
preferences by selecting the runtime on the "Targeted Runtimes" preference page.
</para>
@@ -206,13 +213,13 @@
<imagedata fileref="images/tooling-classpath.png" format="PNG" />
</para>
<para>
- After targeting the project or PAR you will see a "Bundle Dependencies" classpath
- container in your Java project. It is now safe to remove any manually configured classpath
+ After targeting the project or PAR you will see a "Bundle Dependencies" classpath
+ container in your Java project. It is now safe to remove any manually configured classpath
entries.
</para>
<para>
The classpath container will automatically attach Java source code to the classpath
- entries by looking for source JARs next to the binary JARs in the @product.name@&rsquo;s
+ entries by looking for source JARs next to the binary JARs in the @product.name@&rsquo;s
repository. You can also manually override the source code attachment by using the
properties dialog on a single JAR entry. This manual attachment will always override
the convention-based attachment.
@@ -225,7 +232,7 @@
edit MANIFEST.MF files. The editor understands the @product.name@ specific headers
like <code>Import-Library</code> and <code>Import-Bundle</code> and provides content
assist features while editing source code. Furthermore a Eclipse Form-based UI is also
- available.
+ available.
</para>
<para>
To open the Bundle Manifest Editor right click a MANIFEST.MF file and select "Bundle
@@ -243,8 +250,8 @@
</para>
<para>
The content assist proposals in the source tab as well as in the UI-based tabs are
- resolved from the bundle and library repository of an installed and configured
- @product.name@. Therefore it is important to target the project or PAR to a specific
+ resolved from the bundle and library repository of an installed and configured
+ @product.name@. Therefore it is important to target the project or PAR to a specific
@short.product.name@ instance to indicate to the tooling which bundle repository to use.
</para>
<para>
@@ -260,7 +267,7 @@
<para>
The Dependencies tab of the Bundle Manifest Editor enables the user to easily download
and install bundles and libraries from the @ebr@
- by using the "Download..." buttons next to the "Import Bundle" and "Import Library"
+ by using the "Download..." buttons next to the "Import Bundle" and "Import Library"
sections.
</para>
</section>
@@ -287,14 +294,14 @@
</para>
</note>
<para>
- Once an application is deployed on the @product.name@ the tooling support will automatically
+ Once an application is deployed on the @product.name@ the tooling support will automatically
pick up any change to source files -- for example, Java and XML context files -- and refresh the
deployed application on the @short.product.name@.
</para>
<para>
The wait time between a change and the actual refresh can be configured
in the configuration editor of the runtime. To bring up that editor,
- double-click on the configured @product.name@ instance in the Servers view.
+ double-click on the configured @product.name@ instance in the Servers view.
</para>
</section>
</chapter>