Skip to content

Commit

Permalink
SOLDER-38 document pre-servlet 3.0 config
Browse files Browse the repository at this point in the history 
- also made the gettingstarted chapter much more readable
  • Loading branch information
@mojavelinux
mojavelinux committed Dec 18, 2010
1 parent 9698957 commit d6edfa8
Showing 1 changed file with 129 additions and 49 deletions.
178 changes: 129 additions & 49 deletions docs/src/main/docbook/en-US/gettingstarted.xml
View file
Expand Up @@ -3,65 +3,145 @@

<chapter id="gettingstarted">
<title>Getting Started</title>

<para>
Getting started with Seam Solder is easy. If you are using Maven, then you can declare a dependency on Seam
Solder (<code>org.jboss.seam.solder:seam-solder:${seam.solder.version}</code>, make sure you have the JBoss
Maven repository enabled). Otherwise, add the jar to your compile time and runtime classpath.
Getting started with Seam Solder is easy. All you need to do is put the API and implementation JARs on the classpath
of your CDI application. The features provided by Seam Solder will be enabled automatically.
</para>

<para>
Most of Seam Solder has very few dependencies:
Some additional configuration, covered at the end of this chapter, is required if you are using a pre-Servlet 3.0
environment.
</para>

<section id="installation.maven-dependencies">
<title>Maven dependency configuration</title>
<para>
If you are using <ulink url="http://maven.apache.org/">Maven</ulink> as your build tool, first make sure you
have configured your build to use the <ulink
url="http://community.jboss.org/wiki/MavenGettingStarted-Users">JBoss Community repository</ulink>, where you
can find all the Seam artifacts. Then, add the following single dependency to your pom.xml file to get started
using Seam Solder:
</para>
<programlisting role="XML"><![CDATA[<dependency>
<groupId>org.jboss.seam.solder</groupId>
<artifactId>seam-solder</artifactId>
<version>${seam.solder.version}</version>
</dependency>]]></programlisting>
<para>
This artifact includes the combined API and implementation.
</para>
<tip>
<para>
Substitute the expression ${seam.solder.version} with the most recent or appropriate version of Seam Solder.
Alternatively, you can create a <ulink
href="http://www.sonatype.com/books/mvnref-book/reference/resource-filtering-sect-properties.html#resource-filtering-sect-user-defined">Maven
user-defined property</ulink> to satisfy this substitution so you can centrally manage the version.
</para>
</tip>
<para>
To be more strict, you can use the API at compile time and only include the implementation at runtime. This
protects you from inadvertantly depending on an implementation class.
</para>
<programlisting role="XML"><![CDATA[<dependency>
<groupId>org.jboss.seam.solder</groupId>
<artifactId>seam-solder-api</artifactId>
<version>${seam.solder.version}</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>org.jboss.seam.solder</groupId>
<artifactId>seam-solder-impl</artifactId>
<version>${seam.solder.version}</version>
<scope>runtime</scope>
</dependency>]]></programlisting>
<para>
In a Servlet 3.0 or Java EE 6 environment, <emphasis>your configuration is now complete!</emphasis>
</para>
</section>

<itemizedlist>
<listitem>
<code>javax.enterprise:cdi-api</code>
</listitem>
<listitem>
<code>org.slf4j:slf4j-api</code>
</listitem>
<listitem>
<code>org.jboss.logging:jboss-logging-api</code>
</listitem>
<listitem>
<code>javax.el:el-api</code>
</listitem>
<listitem>
<code>javax.inject:javax.inject</code>
</listitem>
</itemizedlist>

<tip>
<section id="gettingstarted.dependencies">
<title>Transitive dependencies</title>
<para>
The POM for Seam Solder specifies the versions required. If you are using Maven 3, you can easily import
the <code>dependencyManagement</code> into your POM by declaring the following in your
<code>depdendencyManagement</code> section:
Most of Seam Solder has very few dependencies, only one of which is not provided by Java EE 6:
</para>

<programlisting role="XML"><![CDATA[ <dependency>
<groupId>org.jboss.seam.solder</groupId>
<artifactId>seam-solder</artifactId>
<version>${seam.solder.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>]]></programlisting>
</tip>

<itemizedlist>
<listitem>
<code>javax.enterprise:cdi-api</code> (provided by Java EE 6)
</listitem>
<listitem>
<code>javax.inject:javax:inject</code> (provided by Java EE 6)
</listitem>
<listitem>
<code>javax.annotation:jsr250-api</code> (provided by Java EE 6)
</listitem>
<listitem>
<code>javax.interceptor:interceptor-api</code> (provided by Java EE 6)
</listitem>
<listitem>
<code>javax.el:el-api</code> (provided by Java EE 6)
</listitem>
<listitem>
<code>org.jboss.logging:jboss-logging</code>
</listitem>
</itemizedlist>

<tip>
<para>
The POM for Seam Solder specifies the versions required. If you are using Maven 3, you can easily import
the <code>dependencyManagement</code> into your POM by declaring the following in your
<code>depdendencyManagement</code> section:
</para>

<programlisting role="XML"><![CDATA[<dependency>
<groupId>org.jboss.seam.solder</groupId>
<artifactId>seam-solder-parent</artifactId>
<version>${seam.solder.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>]]></programlisting>
</tip>

<para>
Some features of Seam Solder require additional dependencies (which are declared optional, so will not be
added as transitive dependencies):
</para>

<variablelist>
<varlistentry>
<term><code>org.javassist:javassist</code></term>
<listitem>Service Handlers, Unwrapping Producer Methods</listitem>
</varlistentry>
<varlistentry>
<term><code>javax.servlet:servlet-api</code></term>
<listitem>Accessing resources from the Servlet Context</listitem>
</varlistentry>
</variablelist>
</section>

<section id="gettingstarted.pre-servlet-3">
<title>Pre-Servlet 3.0 configuration</title>
<para>
<emphasis>If you are using Java EE 5 or some other Servlet 2.5 container</emphasis>, then you need to manually
register a Servlet component in your application's web.xml to access resources from the Servlet Context.
</para>
<programlisting role="XML"><![CDATA[<listener>
<listener-class>org.jboss.seam.solder.resourceLoader.servlet.ResourceListener</listener-class>
</listener>]]></programlisting>

<para>
This registration happens automatically in a Servlet 3.0 environment through the use of a
/META-INF/web-fragment.xml included in the Solder implementation.
</para>
</section>

<para>
Some features of Seam Solder require additional dependencies (which are declared optional, so will not be
added as transitive dependencies):
You're all setup. It's time to dive into all the useful stuff that Seam Solder provides!
</para>

<variablelist>
<varlistentry>
<term><code>org.javassist:javassist</code></term>
<listitem>Service Handlers, Unwrapping Producer Methods</listitem>
</varlistentry>
<varlistentry>
<term><code>javax.servlet:servlet-api</code></term>
<listitem>Accessing resources from the Servlet Context</listitem>
</varlistentry>
</variablelist>

<!--
vim:et:ts=3:sw=3:tw=120
-->
</chapter>

0 comments on commit d6edfa8

Please sign in to comment.