aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorSteve Powell2010-10-27 12:33:16 (EDT)
committerGlyn Normington2010-11-02 08:20:42 (EDT)
commit6a02d6b39d02b14096677bbfe3a74343c9ca0b24 (patch)
treeb334e224c001b942fba356d0ce75531734e6a588
parent5c05f3f42485c7f79f39507d3b14c2eb6fb473f8 (diff)
downloadorg.eclipse.virgo.documentation-6a02d6b39d02b14096677bbfe3a74343c9ca0b24.zip
org.eclipse.virgo.documentation-6a02d6b39d02b14096677bbfe3a74343c9ca0b24.tar.gz
org.eclipse.virgo.documentation-6a02d6b39d02b14096677bbfe3a74343c9ca0b24.tar.bz2
Frontmatter and Installation sections of Getting Started -- update to Version 2.1.0.RELEASE
-rw-r--r--getting-started/filters.properties19
-rw-r--r--getting-started/src/automated-build.xml9
-rw-r--r--getting-started/src/concepts.xml119
-rw-r--r--getting-started/src/installing-greenpages.xml2
-rw-r--r--getting-started/src/installing.xml53
-rw-r--r--getting-started/src/virgo-getting-started.xml2
6 files changed, 82 insertions, 122 deletions
diff --git a/getting-started/filters.properties b/getting-started/filters.properties
index 656c65c..ceedb71 100644
--- a/getting-started/filters.properties
+++ b/getting-started/filters.properties
@@ -15,12 +15,14 @@ webserv.zip.file=virgo-web-server-@webserv.version@.zip
sts=SpringSource Tool Suite
sts.short=STS
-sts.version=2.5.0
-sts.zip.file.windows=springsource-tool-suite-@sts.version@-e3.4-win32.zip
-#sts.zip.file.unix=springsource-tool-suite-@sts.version@-e3.4-linux-gtk.tar.gz
-#sts.zip.file.linux.32=springsource-tool-suite-@sts.version@-e3.4-linux-gtk.tar.gz
-#sts.zip.file.linux.64=springsource-tool-suite-@sts.version@-e3.4-linux-gtk-x86_64.tar.gz
-#sts.zip.file.mac=springsource-tool-suite-@sts.version@-e3.4-macosx-carbon.tar.gz
+sts.version.number=2.5.0
+sts.version=@sts.version.number@.RC1
+sts.eclipse.base.version=e3.6.1
+sts.zip.file.windows=springsource-tool-suite-@sts.version@-@sts.eclipse.base.version@-win32.zip
+#sts.zip.file.unix=springsource-tool-suite-@sts.version@-@sts.eclipse.base.version@-linux-gtk.tar.gz
+#sts.zip.file.linux.32=springsource-tool-suite-@sts.version@-@sts.eclipse.base.version@-linux-gtk.tar.gz
+#sts.zip.file.linux.64=springsource-tool-suite-@sts.version@-@sts.eclipse.base.version@-linux-gtk-x86_64.tar.gz
+#sts.zip.file.mac=springsource-tool-suite-@sts.version@-@sts.eclipse.base.version@-macosx-carbon.tar.gz
sts.download=http://www.springsource.com/products/springsource-tool-suite-download
dmst=@s2@ Tools
@@ -28,12 +30,13 @@ dmst.update=http://www.springsource.com/milestone/e3.5
greenpages=GreenPages
#The url and version for greenpages is finalised
-greenpages.version=2.1.0.M01
+greenpages.version.number=2.3.0
+greenpages.version=@greenpages.version.number@.RELEASE
greenpages.download.url=http://eclipse.org/virgo/documentation/
greenpages.zip.file=greenpages-@greenpages.version@.zip
greenpages.expanded.dir=greenpages-@greenpages.version@
-app.version.number=2.1.0
+app.version.number=2.3.0
app.version=@app.version.number@.RELEASE
spring.framework=Spring Framework
diff --git a/getting-started/src/automated-build.xml b/getting-started/src/automated-build.xml
index 0431734..8542794 100644
--- a/getting-started/src/automated-build.xml
+++ b/getting-started/src/automated-build.xml
@@ -113,7 +113,7 @@
</project>]]>
</programlisting>
ensuring that the version numbers are consistent
- (for example, <literal>2.0.0.RELEASE</literal> might be <literal>2.0.1.SNAPSHOT</literal>
+ (for example, <literal>@app.version@</literal> might be <literal>@app.version.number@</literal>
depending on which version of <literal>greenpages</literal> being developed).
</para>
@@ -188,7 +188,7 @@
</para>
<para>
This command will now complete successfully and build a PAR into <filename>target/</filename>:
-<programlisting><![CDATA[ [INFO] Scanning for projects...
+<programlisting>[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building GreenPages PAR
[INFO] task-segment: [clean, package]
@@ -196,7 +196,7 @@
[INFO] [clean:clean {execution: default-clean}]
[INFO] [resources:resources {execution: default-resources}]
[INFO] [par:par {execution: default-par}]
- [INFO] Assembling Artifacts for PAR '…/start/greenpages/target/greenpages-2.0.1.SNAPSHOT.par'
+ [INFO] Assembling Artifacts for PAR '…/start/greenpages/target/greenpages-@greenpages.version@.par'
[INFO] Added 'greenpages.app.jar'
[INFO] Added 'greenpages.jpa.jar'
[INFO] Added 'greenpages.db.jar'
@@ -205,8 +205,7 @@
[INFO] Ignored project with non-bundle packaging: [par]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
- [INFO] ------------------------------------------------------------------------]]>
-</programlisting>
+ [INFO] ------------------------------------------------------------------------</programlisting>
Proceed to the next step.
</para>
</section>
diff --git a/getting-started/src/concepts.xml b/getting-started/src/concepts.xml
index 7624f13..3084ff5 100644
--- a/getting-started/src/concepts.xml
+++ b/getting-started/src/concepts.xml
@@ -7,11 +7,15 @@
<title>Concepts</title>
-<para>@virgo@ @webserv@ is a Java application server composed of a
-collection of modules which supports applications which are also composed of a
-collection of modules.
-These may be traditional Java web applications packaged as Web ARchive (<literal>.war</literal>)
-files as well as other modular applications.</para>
+<para>
+ @virgo@ @webserv@ is a Java application server composed of a
+ collection of modules which supports applications which are also composed of a
+ collection of modules.
+ These may be traditional Java web applications packaged as Web ARchive (<literal>.war</literal>)
+ files as well as other modular applications.
+ Modules may be shared between applications and multiple versions of modules
+ can co-exist.
+</para>
<para>This chapter introduces concepts
necessary for developing @webserv@ applications.
@@ -33,18 +37,21 @@ A module <emphasis>imports</emphasis> a package to use the corresponding program
another module.</para>
<para>
-Representing a program as a collection of modules makes it easier for the
-programmer to manage it and modify it and for teams of programmers to divide
-responsibilities between themselves.
-A module is similar to a Java class in this respect. Rules similar to those for
-organising data and programs into classes can be applied
-to organising applications into modules.</para>
-
-<para>An industry consortium known as the
-<emphasis>OSGi Alliance</emphasis> (see <xref linkend="further.resources.projects"/>) develops OSGi
-specifications, reference implementations, and compliance tests.
-@virgo@ @webserv@ is built on the Equinox OSGi framework which is also
-the reference implementation for the OSGi framework specification.</para>
+ Representing a program as a collection of modules makes it easier for the
+ programmer to manage it and modify it and for teams of programmers to divide
+ responsibilities between themselves.
+ A module is similar to a Java class in this respect. Design principles similar to those for
+ organising data and programs into classes can be applied
+ to organising applications into modules.
+</para>
+
+<para>
+ An industry consortium known as the
+ <emphasis>OSGi Alliance</emphasis> (see <xref linkend="further.resources.projects"/>) develops OSGi
+ specifications, reference implementations, and compliance tests.
+ @virgo@ @webserv@ is built on the Equinox OSGi framework which is also
+ the reference implementation for the OSGi framework specification.
+</para>
<!--========================================================================-->
<section>
@@ -52,7 +59,7 @@ the reference implementation for the OSGi framework specification.</para>
<title>Bundles</title>
<para>Modules in OSGi are known as <emphasis>bundles</emphasis>.
-Each bundle conforms to the JAR file format and
+Each bundle is stored in a file which conforms to the JAR file format and
can contain Java classes, a manifest (in <literal>META-INF/MANIFEST.MF</literal>),
and further resource files.</para>
@@ -102,7 +109,7 @@ can be <emphasis>satisfied</emphasis> before the bundle runs. This process is kn
loading.
In OSGi, bundles and their packages do not appear on the application classpath.
Instead, each bundle has a class loader which loads its own classes and loads classes belonging to each of its
-imported packages by deferring to the bundle class loader that exported the package.</para>
+imported packages by deferring to the bundle class loader that exports the package.</para>
</section>
@@ -116,10 +123,10 @@ first of all <emphasis>install</emphasis>ed and will be in the INSTALLED state.
If a request is made to <emphasis>start</emphasis> the bundle, the OSGi framework <emphasis>resolve</emphasis>s the bundle
and, if resolution was successful, will subsequently move the bundle to the ACTIVE state.
If a request is made to <emphasis>stop</emphasis> the bundle, the OSGi framework will move the
-bundle back to the INSTALLED state. A request may then be made to <emphasis>uninstall</emphasis>
+bundle back to the RESOLVED state. A request may then be made to <emphasis>uninstall</emphasis>
the bundle.</para>
-<para>While the bundle is INSTALLED or ACTIVE, it may be <emphasis>updated</emphasis> to pick up
+<para>While the bundle is INSTALLED, ACTIVE or RESOLVED, it may be <emphasis>updated</emphasis> to pick up
some changes. These changes are not detected by bundles which were depending
on the bundle before it was updated.
A <quote>refresh packages</quote> operation may be performed to ripple the
@@ -149,7 +156,7 @@ This diagram shows some more of the intermediate states of a bundle not describe
to a registry managed by the OSGi framework. Other bundles running in
the same OSGi framework can then find and use those services. Services
are typically instances of some shared Java interface. A bundle which
-provides a service need not export the package containing the
+provides a service need not then export the package containing the
<emphasis>implementation</emphasis>
class of the service.
</para>
@@ -175,7 +182,7 @@ class SomeImpl implements SomeInterface {
then publish this instance (as an instance of the interface <literal>SomeInterface</literal>).
</para>
-<para>OSGi publishes a number of standard services. For example, the
+<para>An OSGi framework publishes a number of standard services. For example, the
<emphasis>Package Admin</emphasis> service provides the <quote>refresh packages</quote> life cycle operation
mentioned above.</para>
@@ -189,8 +196,11 @@ but it is much simpler to use Spring DM to accomplish this. (See <xref linkend="
<title>Versioning</title>
-<para>OSGi allows different versions of bundles, packages, and several other entities, to co-exist
-and provides some mechanisms for managing these versions.</para>
+<para>
+ OSGi allows different versions of bundles, packages, and several
+ other entities, to co-exist in the same framework
+ and provides some mechanisms for managing these versions.
+</para>
<section>
@@ -239,7 +249,7 @@ including all higher versions.</para>
denotes that version and only that version.</para></listitem>
<listitem><para>A <quote>half-open</quote> range, such as
<literal>[1.2,2)</literal>, which has an inclusive lower limit
-and an exclusive upper limit, denoting version <literal>1.2.0</literal> and any version later than this, up
+and an exclusive upper limit, denoting version <literal>1.2.0</literal> and any version after this, up
to, <emphasis>but not including</emphasis>, version <literal>2.0.0</literal>.
</para></listitem>
<listitem><para>An <quote>unbounded</quote> version range, such as <literal>1.2</literal>, which
@@ -378,10 +388,11 @@ using descriptions written in XML.
<para>The XML descriptions reside in files with extension <literal>.xml</literal> in the
bundle&rsquo;s <literal>META-INF/spring</literal> sub-directory.</para>
-<para>To publish a service, an <literal>&lt;osgi:service&gt;</literal> tag is used, specifying the
-implementation class of the service and the interface class to be used.
-Spring DM constructs an instance of the implementation class like any other
-Spring bean and then publishes that instance in the OSGi service registry under the interface when the bundle is started.
+<para>
+ To publish a service, an <literal>&lt;osgi:service&gt;</literal> tag is used, specifying the
+ implementation class of the service and the interface class to be used.
+ Spring DM constructs an instance of the implementation class and
+ publishes that instance in the OSGi service registry under the interface when the bundle is started.
</para>
<para>To consume a service, an <literal>&lt;osgi:reference&gt;</literal> tag is used and the
@@ -402,21 +413,14 @@ and closes the bundle&rsquo;s application contexts.
Web Server turns off damping of a service proxy while the proxy&rsquo;s application context
is being closed.</para>
-<para>Note that, at the time of writing, Spring DM is in the process of being contributed to Eclipse
-as the Gemini Blueprint service.</para>
+<para>(Spring DM has been contributed to Eclipse as the <emphasis>Gemini Blueprint</emphasis> project.)</para>
</section>
<!--========================================================================-->
-<section id="concepts.dmserver">
+<section id="concepts.grouping">
-<title>@webserv@ concepts</title>
-
-<para>Several @webserv@ concepts are essential for developing an application.</para>
-
-<section>
-
-<title>PAR files</title>
+<title>Grouping bundles in @webserv@</title>
<para>@webserv@ provides a way of grouping together a collection
of OSGi bundles which comprise a single application.
@@ -429,39 +433,16 @@ inside the PAR file may depend on packages and services outside the PAR file,
but bundles outside the PAR file may not depend on packages and services
provided by the PAR file.</para>
-<para>@virgo@ also provides another way of grouping bundles and other artifacts into an application: plans.
-A plan is a XML file listing a collection of artifacts. This Guide makes no further reference to plans.</para>
+<para>@virgo@ also provides the plan artifact as another way of grouping bundles and other artifacts into an application.
+A <emphasis>plan</emphasis> is a file (in XML format) listing a collection of artifacts.
+This Guide makes no further reference to plans.
+See <xref linkend="further.resources.documentation"/> for a link to more @virgo@ documentation.</para>
-</section>
-
-<section>
-
-<title>Deployment</title>
-
-<para>PAR files or individual bundles are <emphasis>deployed</emphasis> into @webserv@ by dropping them into a <quote>pickup</quote>
+<para>PAR files (or individual bundles) are <emphasis>deployed</emphasis> into @webserv@ by dropping them into a <quote>pickup</quote>
directory or using the Administration Console web application provided with @webserv@.
-During deployment, the bundle or bundles are installed into OSGi, resolved together, and then started together.</para>
+During deployment, the bundles in the PAR file are installed into OSGi, resolved together, and then started together.</para>
</section>
-<section>
-
-<title>Personalities</title>
-
-<para>@webserv@ supports multiple application programming models known as <emphasis>personalities</emphasis>.
-Each bundle of an application has a personality. For example, a bundle providing a servlet has the
-<emphasis>web</emphasis> personality. Bundles which provide packages and services using the OSGi and Spring
-DM programming models have the <emphasis>bundle</emphasis> personality.</para>
-
-<para>When a bundle is deployed into @webserv@, personality-specific transformations
-are applied to the bundle&rsquo;s contents, including its manifest, and the bundle is made available for use in
-a personality-specific way.
-For example, a bundle with the web personality has some package imports added to its manifest and its servlet is automatically
-made available
-for dispatching from HTTP requests.</para>
-
-</section>
-
-</section>
</chapter>
diff --git a/getting-started/src/installing-greenpages.xml b/getting-started/src/installing-greenpages.xml
index e67012d..8c7dc2d 100644
--- a/getting-started/src/installing-greenpages.xml
+++ b/getting-started/src/installing-greenpages.xml
@@ -475,7 +475,7 @@ prompt> del greenpages-solution-@app.version@.par</programlisting>
<listitem>
<para>
Verify that @greenpages@ is started correctly by checking for
- <code>&lt;DE0005I&gt; Started par 'greenpages' version '2.0.1'.</code> in the Console window.
+ <code>&lt;DE0005I&gt; Started par 'greenpages' version '@greenpages.version.number@'.</code> in the Console window.
<mediaobject>
<imageobject role="fo">
<imagedata fileref="images/installing-greenpages/success.png" format="PNG" align="center" width="16cm"/>
diff --git a/getting-started/src/installing.xml b/getting-started/src/installing.xml
index a611170..004d554 100644
--- a/getting-started/src/installing.xml
+++ b/getting-started/src/installing.xml
@@ -6,9 +6,10 @@
<para>
Before developing an application with @webserv@, it is essential to install <emphasis>@webserv@</emphasis>,
-the Eclipse <emphasis>Integrated Development Environment</emphasis> (IDE), the
-Eclipse-based <emphasis>@sts@</emphasis> (@sts.short@), and a build system integrated with Eclipse.
-The build system used here is <emphasis>@maven.full@</emphasis>.
+an <emphasis>Integrated Development Environment</emphasis> (IDE), and a build system integrated with Eclipse.
+The IDE used here is the
+Eclipse-based <emphasis>@sts@</emphasis> (@sts.short@), and
+the build system used here is <emphasis>@maven.full@</emphasis>.
</para>
<para>@sts.short@ is supplied as a fully configured Eclipse IDE, with @virgo@ @webserv@ and @maven@ plugins built-in.</para>
@@ -16,18 +17,18 @@ The build system used here is <emphasis>@maven.full@</emphasis>.
<title>Pre-requisites</title>
<para>
-Before proceeding, ensure that a Java<trademark class="trade"/> Standard Edition Development Kit
+Before proceeding, ensure that a Java<trademark class="trade"/> Standard Edition Development Kit (JDK)
for Java 6 or later is installed and that the <literal>JAVA_HOME</literal> environment variable
-is set to the correct value.
+is set to the root directory of the JDK.
(<emphasis>A Java Runtime Environment (JRE) alone is not sufficient,
a development kit is necessary to use the facilities in @sts.short@.</emphasis>)
</para>
<para>
To verify this, issue the command <literal>"%JAVA_HOME%"\bin\java -version</literal> from
-a command prompt on Windows or <literal>$JAVA_HOME/bin/java -version</literal> from a terminal window on UNIX
+a command prompt on Windows (or <literal>$JAVA_HOME/bin/java -version</literal> from a terminal window on UNIX)
and ensure that the command completes successfully and reports
-a Java version <literal>1.6.x</literal> (denoting Java 6) or greater.
+a Java version <literal>1.6.</literal><emphasis>x</emphasis> (denoting Java 6) or greater.
</para>
<para>
@@ -36,7 +37,7 @@ extracting files from zip archives.
If the <literal>jar</literal> command is unavailable, download and install a suitable zip program
such as <literal>7zip</literal>, <literal>gzip</literal>, or <literal>WinZip</literal>.
This is most relevant for Windows operating systems where the inbuilt zip extraction utility may
-mishandle long pathnames.
+not handle long pathnames correctly.
</para>
</section>
@@ -144,7 +145,7 @@ Thread-2 &lt;UR0001I&gt; User region ready. </programlisting
<para>
The @sts@ (@sts.short@) is a development environment based on Eclipse that
-needs to be configured with
+is already configured with
<!--comes configured with all-->
the plugins needed to
work with @webserv@ and OSGi.
@@ -176,7 +177,7 @@ prompt> "%JAVA_HOME%"\bin\jar xf \<emphasis>full…path…to</emphasis>\@sts.zip
</para>
<para>
-To verify the installation, run the <literal>eclipse.exe</literal> executable in the unzipped directory
+To verify the installation, run the <literal>eclipse.exe</literal> (or <literal>sts.exe</literal>) executable in the unzipped directory
and check that @sts.short@ displays a welcome panel.
The first time there may be a short delay due to the initial set-up of indexes.
</para>
@@ -193,7 +194,7 @@ system, simply move the unpacked directory to the chosen location.)
</para>
<para>
-To verify the installation, run the @sts.short@ executable (<literal>Eclipse.app</literal> on Mac OS X)
+To verify the installation, run the @sts.short@ executable (<literal>STS.app</literal> on Mac OS X)
in the unpacked directory and check that @sts.short@ displays a welcome panel.
The first time there may be a short delay due to the initial set-up of indexes.
</para>
@@ -203,37 +204,13 @@ The first time there may be a short delay due to the initial set-up of indexes.
</section>
<section>
-
- <title>Adding the @virgo@ tools plugins</title>
-
- <para>
- After installing and starting @sts.short@, click <emphasis role="bold">Help > Install New Software...</emphasis>
- and add the @dmst@ tools update site (@dmst.update@). Install the @s2@ dm Server Tools which include the tools for @virgo@.
- When prompted, restart Eclipse.
- </para>
-
-</section>
-
-<section>
<title>Note about Java versions in @sts.short@</title>
<para>
- @sts@ runs on Eclipse using Java Version 1.5, and @webserv@ requires Java Version 1.6.
+ @sts@ runs on Eclipse using Java Version 1.6, and @webserv@ requires Java Version 1.6.
The @greenpages@ application built here also requires Java Version 1.6.
- Alter the default Java compiler settings in @sts.short@ before proceeding:
+ You should not need to alter the default Java compiler settings in @sts.short@ before proceeding.
</para>
-<orderedlist>
- <listitem><para>In @sts@, click <emphasis role="bold">Window > Preferences</emphasis> from the menu.</para></listitem>
- <listitem><para>In the <emphasis role="bold">Preferences</emphasis> window, click <emphasis role="bold">Java > Compiler</emphasis> in the left panel.</para></listitem>
- <listitem><para>In the right panel, set the <emphasis role="bold">Compiler compliance level</emphasis> to <literal>1.6</literal>.</para></listitem>
- <listitem><para>Click <emphasis role="bold">Apply</emphasis>. You will get a message asking if you want a full rebuild; click <emphasis role="bold">Yes</emphasis>. The rebuild should take very little time to complete. </para>
- <para>You might also see a message similar to the following on the settings panel: <emphasis><quote>When selecting 1.6 compliance, make sure to have a compatible JRE installed and activated (currently 1.5).</quote></emphasis>
- A link to <emphasis>Configure</emphasis> this will appear.
- Select this link to open the <emphasis>Java--Installed JREs</emphasis> panel. If not already selected, choose a JRE suitable for Java Version 1.6.x (for example <code>JVM 1.6.0</code>).</para>
- </listitem>
- <listitem><para>Click <emphasis role="bold">OK</emphasis>.</para></listitem>
-</orderedlist>
-
</section>
</section>
@@ -243,7 +220,7 @@ The first time there may be a short delay due to the initial set-up of indexes.
<para>
<emphasis>@maven.full@</emphasis>, or @maven@ for short, is a software project management and comprehension tool
which uses a central <emphasis>Project Object Model</emphasis> (POM) to manage a project&rsquo;s build, reporting
-and documentation generation. The POM files (<literal>pom.xml</literal>) are included in the projects for
+and documentation generation. POM files (<literal>pom.xml</literal>) are included in the projects for
@greenpages@.
</para>
diff --git a/getting-started/src/virgo-getting-started.xml b/getting-started/src/virgo-getting-started.xml
index 8fb8b0b..2fa483e 100644
--- a/getting-started/src/virgo-getting-started.xml
+++ b/getting-started/src/virgo-getting-started.xml
@@ -6,7 +6,7 @@
<!-- The book title has any trademark and registered trademark symbols literally inserted, since the normal
escape doesn't appear to work on pdf output. This solution works on all output formats, now that
the input text is assumed to be Unicode. -->
- <title>Creating an application with the @virgo@ @webserv@</title>
+ <title>Creating an application with EclipseRT @virgo@ @webserv@</title>
<titleabbrev>Creating @greenpages@</titleabbrev>
<subtitle>@greenpages@: a demonstration</subtitle>
<!--