Skip to content

Commit

Permalink
Remove "Run the example on Jetty from Eclipse" from docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@mkouba @jharting
mkouba authored and jharting committed Sep 20, 2013
1 parent 447fcb2 commit ea51fb4
Showing 1 changed file with 56 additions and 82 deletions.
138 changes: 56 additions & 82 deletions docs/reference/src/main/docbook/en-US/gettingstarted.xml
View file
Expand Up @@ -7,14 +7,14 @@
<para>
Weld comes with a number of examples. We recommend you start with <literal>examples/jsf/numberguess</literal>
and <literal>examples/jsf/translator</literal>. Numberguess is a web (war) example containing
only non-transactional managed beans. This example can be run on a wide range of servers, including JBoss
AS, GlassFish, Apache Tomcat, Jetty, Google App Engine, and any compliant Java EE 6 container.
only non-transactional managed beans. This example can be run on a wide range of servers, including JBoss
AS, GlassFish, Apache Tomcat, Jetty, Google App Engine, and any compliant Java EE 6 container.
Translator is an enterprise (ear) example that contains session beans. This example
must be run on JBoss AS 7 or better, GlassFish 3 or better, or any compliant Java EE 6 container.
</para>

<para>
Both examples use JSF 2.0 as the web framework and, as such, can be found in the <literal>examples/jsf</literal>
Both examples use JSF 2.0 as the web framework and, as such, can be found in the <literal>examples/jsf</literal>
directory of the Weld distribution.
</para>

Expand All @@ -24,7 +24,7 @@
<para>
To run the examples with the provided build scripts, you'll need the following:
</para>

<itemizedlist>
<listitem>
<para>the latest release of Weld, which contains the examples</para>
Expand All @@ -50,18 +50,18 @@
</itemizedlist>
</listitem>
</itemizedlist>

<para>
In the next few sections, you'll be using the Maven command (<literal>mvn</literal>) to invoke the Maven project file
in each example to compile, assemble and deploy the example to JBoss AS and, for the war example, Apache Tomcat.
You can also deploy the generated artifact (war or ear) to any other container that supports Java EE 6, such as
In the next few sections, you'll be using the Maven command (<literal>mvn</literal>) to invoke the Maven project file
in each example to compile, assemble and deploy the example to JBoss AS and, for the war example, Apache Tomcat.
You can also deploy the generated artifact (war or ear) to any other container that supports Java EE 6, such as
GlassFish 3.
</para>

<para>The sections below cover the steps for deploying with Maven in detail. Let's start with JBoss AS.</para>

</section>

<section id="jbossas">
<title>Deploying to JBoss AS</title>

Expand All @@ -70,14 +70,14 @@
7.0.0.Final</ulink> or above. The good news is
that there are no additional modifications you have to make to the server. It's ready to go!
</para>

<para>
After you have downloaded JBoss AS, extract it. (We recommended renaming the folder to include the
<literal>as</literal> qualifier so it's clear that it's the application server). You can move the extracted
folder anywhere you like. Wherever it lays to rest, that's what we'll call the JBoss AS installation
directory, or <literal>JBOSS_HOME</literal>.
</para>

<programlisting><![CDATA[$> unzip jboss-as-7.1.1.Final.zip
$> mv jboss-as-7.*/ jboss-as-7]]></programlisting>

Expand All @@ -94,12 +94,12 @@ $> mv jboss-as-7.*/ jboss-as-7]]></programlisting>
</para>

<para>
Switch to the <literal>examples/jsf/numberguess</literal> directory and execute the Maven
Switch to the <literal>examples/jsf/numberguess</literal> directory and execute the Maven
<literal>deploy</literal> target:
</para>

<programlisting><![CDATA[$> cd examples/jsf/numberguess
$> mvn jboss-as:run]]></programlisting>
$> mvn jboss-as:run]]></programlisting>

<note>
<para>
Expand Down Expand Up @@ -159,9 +159,9 @@ $> mvn jboss-as:run]]></programlisting>
not really, but the stub is there for you to implement, at least. Good luck!) To try it out, switch to the
translator example directory and execute the deploy target:
</para>

<programlisting><![CDATA[$> cd examples/jsf/translator/ear
$> mvn jboss-as:run]]></programlisting>
$> mvn jboss-as:run]]></programlisting>

<note>
<para>
Expand All @@ -171,7 +171,7 @@ $> mvn jboss-as:run]]></programlisting>
</note>

<para>
Again, wait a few seconds for the application to deploy (if you're really bored, read the log messages), and
Again, wait a few seconds for the application to deploy (if you're really bored, read the log messages), and
visit <ulink url="http://localhost:8080/weld-translator">http://localhost:8080/weld-translator</ulink> to begin
pseudo-translating.
</para>
Expand All @@ -182,7 +182,7 @@ $> mvn jboss-as:run]]></programlisting>

<programlisting><![CDATA[$> cd examples/jsf/translator/ftest
$> mvn verify -Darquillian=jbossas-managed-7]]></programlisting>

</section>

<section id="glassfish">
Expand All @@ -203,19 +203,19 @@ $> mvn verify -Darquillian=jbossas-managed-7]]></programlisting>
</para>

<programlisting><![CDATA[$> chmod 755 glassfish-v3-unix.sh
$> ./glassfish-v3-unix.sh]]></programlisting>
$> ./glassfish-v3-unix.sh]]></programlisting>

<para>
On Windows you can just click on the executable. Follow the instructions in the installer. It will create a
single domain named <literal>domain1</literal>. You'll use that domain to deploy the example. We recommend that
you choose <literal>7070</literal> as the main HTTP port to avoid conflicts with a running instance of JBoss AS
you choose <literal>7070</literal> as the main HTTP port to avoid conflicts with a running instance of JBoss AS
(or Apache Tomcat).
</para>

<para>
Next, make sure the <literal>GLASSFISH_HOME</literal> environment variable is set to point to the GlassFish installation.
</para>

<para>
Now switch to the example directory again and create a new GlassFish domain for the example.
</para>
Expand All @@ -240,7 +240,7 @@ $> mvn glassfish:create-domain]]></programlisting>

<para>
There are alternative ways of,deploying applications to GlassFish either by using the <ulink url="http://localhost:4848">GlassFish Admin
Console</ulink> or the <literal>asadmin</literal> command.
Console</ulink> or the <literal>asadmin</literal> command.
</para>

<para>
Expand All @@ -250,22 +250,22 @@ $> mvn glassfish:create-domain]]></programlisting>
</para>

</section>

<section id="tomcat">
<title>Deploying to Apache Tomcat</title>

<para>
Servlet containers are not required to support Java EE services like CDI. However, you can use CDI in a
Servlet containers are not required to support Java EE services like CDI. However, you can use CDI in a
servlet container like Tomcat by embedding a standalone CDI implementation such as Weld.</para>

<para>
Weld comes with a servlet listener which bootstraps the CDI environment, registers the <literal>BeanManager</literal>
in JNDI and provides injection into servlets. Basically, it emulates some of the work done by the Java EE
Weld comes with a servlet listener which bootstraps the CDI environment, registers the <literal>BeanManager</literal>
in JNDI and provides injection into servlets. Basically, it emulates some of the work done by the Java EE
container. (But you don't get enterprise features such as session beans and container-managed transactions.)
</para>

<para>
Let's give the Weld servlet extension a spin on Apache Tomcat. First, you'll need to download Tomcat 6.0.18 or
Let's give the Weld servlet extension a spin on Apache Tomcat. First, you'll need to download Tomcat 6.0.18 or
later from <ulink url="http://tomcat.apache.org/download-60.cgi">tomcat.apache.org</ulink> and extract it.
</para>

Expand All @@ -274,31 +274,31 @@ $> mvn glassfish:create-domain]]></programlisting>
<para>
The Maven plugin communicates with Tomcat over HTTP, so it doesn't care where you have installed Tomcat.
However, the plugin configuration assumes you are running Tomcat in its default configuration, with a hostname
of localhost and port <literal>8080</literal>. The <literal>readme.txt</literal> file in the example directory
of localhost and port <literal>8080</literal>. The <literal>readme.txt</literal> file in the example directory
has information about how to modify the Maven settings to accommodate a different setup.
</para>

<para>
To allow Maven to communicate with Tomcat over HTTP, edit the <literal>conf/tomcat-users.xml</literal> file in
To allow Maven to communicate with Tomcat over HTTP, edit the <literal>conf/tomcat-users.xml</literal> file in
your Tomcat installation and add the following line:
</para>

<programlisting role="XML"><![CDATA[<user username="admin" password="" roles="manager"/>]]></programlisting>
<programlisting role="XML"><![CDATA[<user username="admin" password="" roles="manager"/>]]></programlisting>

<para>
Next, start Tomcat. You can either start Tomcat from a Linux shell:
</para>

<programlisting><![CDATA[$> cd /path/to/apache-tomcat-6
$> ./bin/start.sh]]></programlisting>
$> ./bin/start.sh]]></programlisting>

<para>
a Windows command window:
</para>

<programlisting><![CDATA[$> cd c:\path\to\apache-tomcat-6\bin
$> start]]></programlisting>
$> start]]></programlisting>

<para>
or you can start the server using an IDE, like Eclipse.
</para>
Expand All @@ -317,11 +317,11 @@ $> mvn compile war:exploded tomcat:exploded -Ptomcat]]></programlisting>
<para>
Once the application is deployed, you can redeploy it using this command:
</para>
<programlisting><![CDATA[$> mvn tomcat:redeploy -Ptomcat]]></programlisting>

<programlisting><![CDATA[$> mvn tomcat:redeploy -Ptomcat]]></programlisting>

<para>
The <literal>-Ptomcat</literal> argument activates the <literal>tomcat</literal> profile defined in the Maven POM
The <literal>-Ptomcat</literal> argument activates the <literal>tomcat</literal> profile defined in the Maven POM
(<literal>pom.xml</literal>). Among other things, this profile activates the Tomcat plugin.
</para>

Expand All @@ -330,7 +330,7 @@ $> mvn compile war:exploded tomcat:exploded -Ptomcat]]></programlisting>
application in an embedded Tomcat 6 container:
</para>

<programlisting><![CDATA[$> mvn war:inplace tomcat:run -Ptomcat]]></programlisting>
<programlisting><![CDATA[$> mvn war:inplace tomcat:run -Ptomcat]]></programlisting>

<para>
The advantage of using the embedded server is that changes to assets in <literal>src/main/webapp</literal> take effect
Expand All @@ -339,13 +339,13 @@ $> mvn compile war:exploded tomcat:exploded -Ptomcat]]></programlisting>
build:
</para>

<programlisting><![CDATA[$> mvn compile war:inplace -Ptomcat]]></programlisting>
<programlisting><![CDATA[$> mvn compile war:inplace -Ptomcat]]></programlisting>

<para>
Finally, you can run the functional tests:
</para>

<programlisting><![CDATA[$> mvn verify -Darquillian=tomcat-embedded-6 -Ptomcat]]></programlisting>
<programlisting><![CDATA[$> mvn verify -Darquillian=tomcat-embedded-6 -Ptomcat]]></programlisting>

<para>
There are several other Maven goals that you can use if you are hacking on the example, which are documented in
Expand Down Expand Up @@ -373,22 +373,22 @@ $> mvn compile war:exploded tomcat:exploded -Ptomcat]]></programlisting>
</para>

<para>
The Maven POM (<literal>pom.xml</literal>) includes a profile named <literal>jetty</literal> that activates the
The Maven POM (<literal>pom.xml</literal>) includes a profile named <literal>jetty</literal> that activates the
Maven Jetty plugin, which you can use
to start Jetty in embedded mode and deploy the application in place. You don't need anything else installed
except to have the Maven command (<literal>mvn</literal>) on your path. The rest will be downloaded from the
except to have the Maven command (<literal>mvn</literal>) on your path. The rest will be downloaded from the
internet when the
build is run.
</para>

<para>
To run the <literal>weld-numberguess</literal> example on Jetty, switch to the example directory and execute
the <literal>inplace</literal> goal of the Maven war plugin followed by the <literal>run</literal> goal of
the <literal>inplace</literal> goal of the Maven war plugin followed by the <literal>run</literal> goal of
the Maven Jetty plugin with the <literal>jetty</literal> profile enabled, as follows:
</para>

<programlisting><![CDATA[$> cd examples/jsf/numberguess
$> mvn war:inplace jetty:run -Pjetty]]></programlisting>
$> mvn war:inplace jetty:run -Pjetty]]></programlisting>

<para>
The log output of Jetty will be shown in the console. Once Jetty reports that the application has deployed, you
Expand All @@ -398,45 +398,19 @@ $> mvn war:inplace jetty:run -Pjetty]]></programlisting>
</para>

<para>
Any changes to assets in <literal>src/main/webapp</literal> take effect immediately. If a change to a webapp
configuration file is made, the application may automatically redeploy. The redeploy behavior can be fined-tuned
in the plugin configuration. If you make a change to a classpath resource, you need to execute a build and the
Any changes to assets in <literal>src/main/webapp</literal> take effect immediately. If a change to a webapp
configuration file is made, the application may automatically redeploy. The redeploy behavior can be fined-tuned
in the plugin configuration. If you make a change to a classpath resource, you need to execute a build and the
<literal>inplace</literal> goal of the Maven war plugin, again with the <literal>jetty</literal> profile enabled.
</para>

<programlisting><![CDATA[$> mvn compile war:inplace -Pjetty]]></programlisting>

<para>
The <literal>war:inplace</literal> goal copies the compiled classes and jars inside <literal>src/main/webapp</literal>,
under <literal>WEB-INF/classes</literal> and <literal>WEB-INF/lib</literal>, respectively, mixing source and compiled
files. However, the build does work around these temporary files by excluding them from the packaged war and cleaning
them during the Maven clean phase.
</para>

<para>
You have two options if you want to run the example on Jetty from the IDE. You can either install the
m2eclipse[link] plugin and run the goals as described above. Your other option is to start the Jetty container
from a Java application.
</para>

<para>
First, initialize the Eclipse project:
</para>

<programlisting><![CDATA[$> mvn clean eclipse:clean eclipse:eclipse -Pjetty-ide]]></programlisting>

<para>
Next, assemble all the necessary resources under <literal>src/main/webapp</literal>:
</para>

<programlisting><![CDATA[$> mvn war:inplace -Pjetty-ide]]></programlisting>
<programlisting><![CDATA[$> mvn compile war:inplace -Pjetty]]></programlisting>

<para>
Now, you are ready to run the server in Eclipse. Import the project into your Eclipse workspace using "Import
Existing Project into Workspace. Then, find the start class in <literal>src/jetty/java</literal> and run its
main method as a Java Application. Jetty will launch. You can view the application at the following local URL: <ulink
url="http://localhost:8080">http://localhost:8080</ulink>. Pay particular attention to the port in the URL and
the lack of a trailing context path.
The <literal>war:inplace</literal> goal copies the compiled classes and jars inside <literal>src/main/webapp</literal>,
under <literal>WEB-INF/classes</literal> and <literal>WEB-INF/lib</literal>, respectively, mixing source and compiled
files. However, the build does work around these temporary files by excluding them from the packaged war and cleaning
them during the Maven clean phase.
</para>

<para>
Expand Down

0 comments on commit ea51fb4

Please sign in to comment.